# 生产目录结构

```text
service.xpcool.com/
├── api/                         # HTTP 契约与 Swagger 元数据（按业务分组）
│   ├── admin/                   # /api/service/admin - 管理端 API（AdminAuth + 权限码）
│   │   ├── admin/               #   管理员账号 CRUD、登录/资料/权限码/刷新/登出
│   │   └── system/              #   登录日志、菜单路由、菜单管理、角色
│   ├── house/                   # /api/service/admin - 看房模块（小区/房源/看板/成交/预售证）
│   ├── recruitment/             # /api/service/admin - 招聘考试聚合模块
│   ├── notice/                  # /api/service/admin - 站内通知（渠道/规则/日志）
│   ├── job/                     # /api/service/admin - 自动任务（任务/日志）
│   ├── serversecurity/          # 服务器安全日志（open 上报 + admin 查询/统计）
│   ├── user/                    # /api/service/user - 用户端认证（登录/刷新）
│   └── open/                    # /api/service/open - 开放接口（公开、无鉴权）
│       └── tools/               #   工具子功能契约，每子功能一目录：tools/<name>/<name>.go
├── common/                      # 公共可复用模块（不依赖 internal/）
│   └── tools/                   #   工具集：md5、cryptox、uuid、random、timex、
│                                #   convertx、strx、slicex、ip、filex
├── internal/
│   ├── cmd/                     # 启动引导、环境变量注入、路由分组注册
│   ├── consts/                  # 业务错误码与常量
│   ├── controller/              # API→service 适配层（不写业务；含 open/ 开放接口实现）
│   ├── service/                 # 领域用例（业务逻辑直接写这里，不用 logic/）
│   ├── dao/                     # 数据访问（gf gen dao 生成 + 部分手写，禁止手改生成物）
│   │   └── internal/            #   生成代码内部实现
│   ├── model/
│   │   ├── entity/              #   数据库实体（生成 + 部分手写）
│   │   ├── do/                  #   Data Object（写库必须用 DO）
│   │   ├── dto/                 #   服务边界入参/出参
│   │   └── vo/                  #   API 视图模型
│   ├── middleware/              # 路由中间件：Recover、CORS、认证、全量加密
│   ├── library/                 # jwt / crypto(RSA+AES) / iploc / page / response 基础件
│   └── table/                   # 表列名常量（手写维护，供代码引用列名）
├── docs/
│   ├── house-system-design.md   # 看房系统总设计文档
│   └── change-log/              # 每次请求与变更的记录（AI 上下文记忆，随 git 提交）
├── manifest/
│   ├── config/                  # config.dev/test/prod.yaml（config.yaml 不入库）
│   ├── sql/                     # 有序 MySQL 迁移脚本（含 recruitment/ 子模块）
│   ├── deploy/                  # kustomize 部署清单
│   ├── docker/                  # Docker 构建上下文
│   ├── i18n/                    # 国际化资源
│   └── protobuf/                # protobuf 定义
├── deploy/
│   └── Dockerfile               # 生产容器镜像（alpine 最小运行时）
├── hack/                        # gf CLI 配置与 Makefile 片段
└── utility/                     # （预留）跨切面辅助
```

`dao`、`model/do`、`model/entity` 由迁移脚本生成，保证与 MySQL 结构不漂移；
但招聘 / 通知 / 自动任务 / 服务器安全日志等模块的部分结构为手写，改动时勿被生成命令覆盖。
控制器不访问 DAO，只有 service 可以。

面向 AI 助手的约定与上下文记忆体系见 [`AGENTS.md`](./AGENTS.md)。