4b3c00270f
Some checks failed
Build and Deploy (service.xpcool.com) / build-and-deploy (push) Failing after 31s
将 api 层校验规则提示语、service 层 gerror.Wrap 与 response.Error 错误信息、panic 未注册提示统一改为中文，并同步中文化 cmd 路由注释 与变更记录。仅涉及注释、文档与字符串改动，无业务逻辑变更。
70 lines
4.6 KiB
Go
70 lines
4.6 KiB
Go
# 变更日志 — 2026-09-13
|
||
|
||
## 请求
|
||
|
||
对整个项目做一次整理：更新陈旧的文档，凡能用中文的地方（注释、文档、提示语、错误信息）一律中文化。
|
||
|
||
## 变更
|
||
|
||
### 文档
|
||
|
||
- `README.MD` — **重写**。原文为英文且路由信息陈旧（写的是 `/api/v1`）。现改为中文，并修正为实际的三组路由
|
||
（`/api/service/open`、`/api/service/user`、`/api/service/admin`），补充分层约定、RBAC 权限映射机制、
|
||
`gf gen dao` 生成流程、本地启动方式（`.env.dev` / GoLand 运行配置）、构建测试命令。
|
||
- `PROJECT_STRUCTURE.md` — **重写**。原文为英文且目录树过时（缺 house / recruitment / notice / job / serversecurity
|
||
等模块）。现改为中文，并按实际结构补全 `api/`、`internal/`、`docs/`、`manifest/` 各层说明，
|
||
标注「部分模块 entity/do/dao 为手写，勿被生成命令覆盖」这一关键事实。
|
||
- `hack/hack.mk`、`hack/hack-cli.mk` — 构建脚本注释全部中文化。
|
||
|
||
### 源码注释与提示
|
||
|
||
- `common/doc.go`、`common/tools/doc.go` — 工具清单由英文改为中文，规则说明中文化。
|
||
- `common/tools/ip/ip.go` — `IsInternal` / `ToLong` 注释中文化。
|
||
- `main.go` — MySQL 驱动引入注释中文化。
|
||
- `internal/cmd/cmd.go` — 路由分组注册处的英文注释中文化（open / user / admin 三处）。
|
||
- `api/user/login/login.go` — 补充中文包文档，说明该包当前无端点、登录已收敛至 `api/user/auth`。
|
||
|
||
### 校验与错误提示中文化
|
||
|
||
- **API 层校验消息**（`v:"...#提示"` 中文提示）：
|
||
`api/user/auth/auth.go`（登录方式、终端类型）、`api/open/tools/md5`、`api/open/tools/random`、
|
||
`api/admin/system/menu_manage`（type）、`api/admin/admin/admin`（密码长度）。
|
||
- **service 层错误上下文与用户提示**（`gerror.Wrap` / `response.Error`），共涉及 19 个文件、逾 90 处：
|
||
- `service/admin/admin/admin`、`service/admin/admin/login`、`service/admin/system/{role,menu,menu_manage,login_log}`
|
||
- `service/user/auth`
|
||
- `service/house/{community,listing,dashboard,transaction,presale}`
|
||
- `service/notice`、`service/job`、`service/serversecurity`
|
||
- `service/recruitment/{recruitment,crawler}`
|
||
- `internal/library/jwt/jwt.go`、`internal/controller/admin/admin.go`
|
||
- 模式统一：`gerror.Wrap(err, "query list")` → `gerror.Wrap(err, "查询列表失败")`；
|
||
用户可见提示如 `"username or password incorrect"` → `"用户名或密码错误"`。
|
||
- 各 service 的 `panic("Xxx implementation not registered")` → `panic("Xxx 实现未注册")`。
|
||
|
||
### 变更记录
|
||
|
||
- 新增 `docs/change-log/2026-09-13.md`（本文）。
|
||
- `.workbuddy/memory/CHANGELOG.md` 顶部追加当日条目。
|
||
|
||
## 决策与理由
|
||
|
||
- **`README.MD` / `PROJECT_STRUCTURE.md` 采用重写而非增量修补**：两份文档原文均为英文，
|
||
且路由前缀、目录树与当前代码差异过大（路由从 `/api/v1` 演进为 `/api/service/*` 三分组；
|
||
新增 house/recruitment/notice/job/serversecurity 五大模块），增量改会造成前后矛盾，故整体重写。
|
||
- **生成代码（`internal/model/entity`、`internal/model/do`、`internal/dao`）的英文注释保持原样**：
|
||
这些文件由 `gf gen dao` 生成，头部含 `DO NOT EDIT` 标记，手工中文化会在下次生成时被覆盖，
|
||
反而制造噪音。符合 AGENTS.md「生成代码禁止手改」的约定。
|
||
- **错误信息中文化的范围界定**：
|
||
- 用户可见提示（`response.Error`）必须中文——直接展示给前端/用户；
|
||
- 内部错误上下文（`gerror.Wrap` 的 message）也一并中文——便于运维/日志排查时统一语义；
|
||
- 日志文案（`g.Log().Errorf` 等）同步中文，保持日志可读性一致。
|
||
- **保留英文的技术标识不动**：HTTP 方法名、SQL 关键字、表名/列名、字段名、`cron` 表达式、
|
||
第三方接口名（Bark / pushplus）、`panic` 中的类型名等属于技术符号，翻译反而降低可检索性。
|
||
|
||
## 待办与风险
|
||
|
||
- 本次仅做「文档整理 + 中文化」，**未改变任何业务逻辑**；所有改动均为注释、文档与字符串字面量。
|
||
- `go build ./...` 因当前环境无法访问 `proxy.golang.org`（模块下载超时）未能完整跑通；
|
||
已用 `read_lints` 对改动目录做静态检查，未发现语法/类型错误。
|
||
建议在有网络的环境执行一次 `go build ./...` 做最终确认。
|
||
- 后续新增代码请遵循「中文注释」约定；`gf gen dao` 重新生成后，entity/do/dao 的英文注释属预期现象，无需处理。
|