# 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 ./...
```