107 lines
5.3 KiB
Markdown
107 lines
5.3 KiB
Markdown
# AGENTS.md
|
||
|
||
## 基本要求
|
||
|
||
1. 写代码不要猜；先阅读相关代码、配置、迁移和调用链，再做修改。
|
||
2. 不要回退用户或其他 agent 已经做过的改动。
|
||
3. 后台后端不使用 `.env`；所有本地和环境配置都通过 `configs/config.yaml` 或同格式 YAML 配置文件管理。
|
||
4. 修改后端代码后，至少执行 `gofmt` 和 `go test ./...`。
|
||
|
||
## 项目定位
|
||
|
||
`hyapp-admin-server` 是 HYApp 后台管理系统后端，当前位于 `hyapp-server/server/admin`，并作为 workspace 内的独立 Go module 运行。
|
||
|
||
- 本地 MySQL、Redis 与 app 后端对齐。
|
||
- 后台服务使用独立数据库 `hyapp_admin`。
|
||
- app 后端集成代码放在 `internal/integration` 或对应业务模块内，不要把 app 业务逻辑混进后台管理模块。
|
||
- 后台相关文档统一写在本 module 的 `docs` 目录。
|
||
|
||
## 架构约定
|
||
|
||
项目采用模块化单体，按业务模块组织代码：
|
||
|
||
- `cmd/server`：启动入口、配置加载、依赖组装。
|
||
- `configs`：YAML 配置。
|
||
- `migrations`：版本化 SQL migration。
|
||
- `internal/modules/<module>/routes.go`：模块路由注册。
|
||
- `internal/modules/<module>/handler.go`：HTTP 参数解析、响应适配。
|
||
- `internal/modules/<module>/service.go`：模块业务逻辑。
|
||
- `internal/modules/<module>/request.go`：模块请求结构。
|
||
- `internal/modules/<module>/response.go`：模块响应 DTO 或展示转换。
|
||
- `internal/modules/shared`：跨模块共享的薄工具，如当前操作者、分页参数、审计事件、通用 DTO。
|
||
- `internal/repository`：数据库读写，按业务能力拆文件。
|
||
- `internal/response`：统一响应协议，按 body、codes、page、success、error 拆文件。
|
||
- `internal/service`：只保留 JWT/AuthService 等跨模块基础能力。
|
||
- `internal/platform`：后台服务自有的基础设施适配，例如 COS 上传、后台对象 ID 等。
|
||
|
||
新增后台功能时，优先在对应 `internal/modules/<module>` 内补齐 `routes / handler / service / request / response`。不要把新业务继续塞回中心化 handler 或中心化 service。
|
||
|
||
## 模块拆分规则
|
||
|
||
1. 每一层都要有模块边界：路由、Handler、Service、Repository 都要按业务域拆分。
|
||
2. 模块内每个相关功能尽量一个文件；文件过重时继续按功能拆分，例如：
|
||
- `user_create.go`
|
||
- `user_status.go`
|
||
- `role_permission.go`
|
||
- `role_data_scope.go`
|
||
3. Handler 不直接访问 `repository.Store`；Handler 只能调用本模块 Service 或少量 shared 工具。
|
||
4. Service 承载业务规则、权限数据范围、密码处理、导出任务等业务流程。
|
||
5. Repository 只做数据访问、事务和查询条件，不放 HTTP 或响应逻辑。
|
||
6. 跨模块复用必须谨慎；确实通用的能力放 `internal/modules/shared`，不要让模块互相直接依赖业务实现。
|
||
|
||
## 配置与环境
|
||
|
||
1. 配置使用 YAML，默认入口是 `configs/config.yaml`。
|
||
2. `environment`、`jwt_secret`、`mysql_auto_migrate`、`bootstrap`、Redis、Jobs 都必须从配置读取。
|
||
3. 非 `local/dev` 环境禁止：
|
||
- 默认 JWT secret。
|
||
- 默认 bootstrap 密码。
|
||
- 开启 `mysql_auto_migrate`。
|
||
4. 本地启动命令：
|
||
|
||
```bash
|
||
go run ./cmd/server -config configs/config.yaml
|
||
```
|
||
|
||
显式执行 bootstrap：
|
||
|
||
```bash
|
||
go run ./cmd/server -config configs/config.yaml -bootstrap
|
||
```
|
||
|
||
## 数据库与迁移
|
||
|
||
1. 表结构变更优先写 SQL migration，不要只依赖 GORM `AutoMigrate`。
|
||
2. migration 文件按数字前缀递增，例如 `005_xxx.sql`。
|
||
3. 已执行的 migration 不要修改内容；需要变更时新增 migration。
|
||
4. 本地数据库是 `hyapp_admin`，由启动入口按配置 DSN 创建。
|
||
|
||
## 权限、审计与任务
|
||
|
||
1. 功能权限通过中间件校验，权限码需要同步到默认权限种子。
|
||
2. 数据权限通过 `admin_data_scopes` 保存，涉及后台数据查询时要在 Service/Repository 链路执行过滤。
|
||
3. 写操作需要审计；显式审计使用 `shared.OperationLog`，兜底审计由 middleware 处理。
|
||
4. 异步任务使用 DB 租约和 Redis 锁，导出产物写入配置的 `jobs.artifact_dir`。
|
||
5. 新增任务类型时，需要补齐创建接口、runner handler、重试/失败结果和产物策略。
|
||
6. 区域创建和区域启用/禁用是后台管理能力，实现在 `hyapp-admin-server`，不要为此新增 user-service RPC 或把后台开关逻辑下沉到 app 后端服务。
|
||
7. 国家创建和国家启用/禁用是后台管理后端能力，实现在 `hyapp-admin-server`，不要为这些后台动作新增 user-service RPC 或 user-service 业务逻辑。
|
||
8. 后台创建 BD Leader 必须传后台选择的 `regionId`；admin-server 负责权限和审计，user-service 在关系创建事务里更新目标用户 `users.region_id`，不要在 admin-server 里用 GetUser 做“用户原区域必须一致”的拒绝。
|
||
9. `hyapp.local/api` 是唯一允许直接依赖的 app 后端契约 module；不要 import `hyapp/services/*`、`hyapp/internal/*` 或 `hyapp/pkg/*`。
|
||
|
||
## 验证
|
||
|
||
常规验证：
|
||
|
||
```bash
|
||
gofmt -w <changed-go-files>
|
||
go test ./...
|
||
```
|
||
|
||
涉及启动、配置、迁移、Redis、任务或路由注入时，还需要本地启动并检查：
|
||
|
||
```bash
|
||
go run ./cmd/server -config configs/config.yaml
|
||
curl -sS http://127.0.0.1:13100/healthz
|
||
curl -sS http://127.0.0.1:13100/readyz
|
||
```
|