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 路由注释 与变更记录。仅涉及注释、文档与字符串改动，无业务逻辑变更。
65 lines
2.9 KiB
Go
65 lines
2.9 KiB
Go
# service.xpcool.com — 个人多客户端后端服务
|
||
|
||
GoFrame v2 单体应用，为 mini / h5 / app 多端提供后端服务，并附带完整的后台管理体系。
|
||
|
||
核心业务：用户认证（JWT）、看房数据（小区/房源/成交/预售证）、招聘考试聚合、
|
||
站内通知、服务器安全日志；后台管理（RBAC 菜单权限 + 操作审计）。
|
||
|
||
> 面向 AI 助手的项目上下文见 [`AGENTS.md`](./AGENTS.md)；每次变更的结构化记录见
|
||
> [`docs/change-log/`](./docs/change-log/)；目录树见 [`PROJECT_STRUCTURE.md`](./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`，然后运行：
|
||
|
||
```powershell
|
||
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`）不兜底，配置缺失显性报错。
|
||
|
||
## 构建与测试
|
||
|
||
```powershell
|
||
go build ./...
|
||
go test ./...
|
||
```
|