# 变更日志 — 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 的英文注释属预期现象，无需处理。