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 路由注释 与变更记录。仅涉及注释、文档与字符串改动，无业务逻辑变更。 |
||
|---|---|---|
| .gitea/workflows | ||
| .workbuddy/memory | ||
| api | ||
| common | ||
| deploy | ||
| docs | ||
| hack | ||
| internal | ||
| manifest | ||
| resource | ||
| utility | ||
| .gitattributes | ||
| .gitignore | ||
| AGENTS.md | ||
| go.mod | ||
| go.sum | ||
| main.go | ||
| Makefile | ||
| PROJECT_STRUCTURE.md | ||
| README.MD | ||
service.xpcool.com — 个人多客户端后端服务
GoFrame v2 单体应用，为 mini / h5 / app 多端提供后端服务，并附带完整的后台管理体系。
核心业务：用户认证（JWT）、看房数据（小区/房源/成交/预售证）、招聘考试聚合、 站内通知、服务器安全日志；后台管理（RBAC 菜单权限 + 操作审计）。
面向 AI 助手的项目上下文见
AGENTS.md；每次变更的结构化记录见docs/change-log/；目录树见PROJECT_STRUCTURE.md。
分层约定
调用链强制为 api → internal/controller → internal/service → internal/dao → internal/model(entity/do)。
controller只做 API 到 service 的适配，不碰 dao；- 跨层出入参走
internal/model/dto与internal/model/vo，API 类型与 entity 不得越界； - 数据库操作必须用 DO 对象（
internal/model/do），禁止g.Map； - 错误一律用
gerror（保留堆栈），响应统一走internal/library/response。
路由分组
三组路由在 internal/cmd/cmd.go 中注册：
| 前缀 | 用途 | 鉴权 |
|---|---|---|
/api/service/open |
开放接口（前端直接调用） | 公开，无鉴权 |
/api/service/user |
用户端接口 | 登录公开，其余走 UserAuth |
/api/service/admin |
管理端接口 | AdminAuth + 按「方法+路径」自动匹配权限码 |
管理端权限由后端从 admin_menu（type=2 行，path 存 "METHOD /路径"）反查，
前端无需传 X-Permission；未配置映射的接口一律拒绝。
数据库模型生成
先在 MySQL 上执行 manifest/sql/ 下的迁移脚本，再设置 DB_DSN，然后运行：
gf gen dao -p internal -g default -gt -c
该命令是 internal/dao、internal/model/do、internal/model/entity 的唯一来源，生成物禁止手改。
注意：部分模块（招聘、通知、自动任务、服务器安全日志）的表结构为手写 entity/do/dao，
未走 gf gen，改动时请勿用生成命令覆盖。
本地启动
环境变量按 GF_GCFG_FILE 切换配置文件（config.dev.yaml / config.test.yaml / config.prod.yaml）。
- 终端：
source .env.dev && go run main.go（.env.dev不入库，保存本地 DSN 与密钥）。 - GoLand：运行配置
.run/service-dev.run.xml（项目级，重载项目后自动识别） 已注入GF_GCFG_FILE/DB_DSN/JWT_SECRET，在运行下拉框中选择即可。 该文件含数据库口令，已加入.gitignore。
开发环境下，若 ${DB_DSN} / ${RECRUITMENT_DB_DSN} / ${JWT_SECRET} 占位符未被环境变量注入，
injectEnv 会回填本地默认值，保证「零配置可启动」；生产（GF_GCFG_ENV=prod）不兜底，配置缺失显性报错。
构建与测试
go build ./...
go test ./...