AGENTS.md

基本要求

写代码不要猜；先阅读相关代码、配置、迁移和调用链，再做修改。
不要回退用户或其他 agent 已经做过的改动。
后台后端不使用 .env；所有本地和环境配置都通过 configs/config.yaml 或同格式 YAML 配置文件管理。
修改后端代码后，至少执行 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。

模块拆分规则

每一层都要有模块边界：路由、Handler、Service、Repository 都要按业务域拆分。
模块内每个相关功能尽量一个文件；文件过重时继续按功能拆分，例如：
- user_create.go
- user_status.go
- role_permission.go
- role_data_scope.go
Handler 不直接访问 repository.Store；Handler 只能调用本模块 Service 或少量 shared 工具。
Service 承载业务规则、权限数据范围、密码处理、导出任务等业务流程。
Repository 只做数据访问、事务和查询条件，不放 HTTP 或响应逻辑。
跨模块复用必须谨慎；确实通用的能力放 internal/modules/shared，不要让模块互相直接依赖业务实现。

配置与环境

配置使用 YAML，默认入口是 configs/config.yaml。
environment、jwt_secret、mysql_auto_migrate、bootstrap、Redis、Jobs 都必须从配置读取。
非 local/dev 环境禁止：
- 默认 JWT secret。
- 默认 bootstrap 密码。
- 开启 mysql_auto_migrate。
本地启动命令：

go run ./cmd/server -config configs/config.yaml

显式执行 bootstrap：

go run ./cmd/server -config configs/config.yaml -bootstrap

数据库与迁移

表结构变更优先写 SQL migration，不要只依赖 GORM AutoMigrate。
migration 文件按数字前缀递增，例如 005_xxx.sql。
已执行的 migration 不要修改内容；需要变更时新增 migration。
本地数据库是 hyapp_admin，由启动入口按配置 DSN 创建。

权限、审计与任务

功能权限通过中间件校验，权限码需要同步到默认权限种子。
数据权限通过 admin_data_scopes 保存，涉及后台数据查询时要在 Service/Repository 链路执行过滤。
写操作需要审计；显式审计使用 shared.OperationLog，兜底审计由 middleware 处理。
异步任务使用 DB 租约和 Redis 锁，导出产物写入配置的 jobs.artifact_dir。
新增任务类型时，需要补齐创建接口、runner handler、重试/失败结果和产物策略。
区域创建和区域启用/禁用是后台管理能力，实现在 hyapp-admin-server，不要为此新增 user-service RPC 或把后台开关逻辑下沉到 app 后端服务。
国家创建和国家启用/禁用是后台管理后端能力，实现在 hyapp-admin-server，不要为这些后台动作新增 user-service RPC 或 user-service 业务逻辑。
后台创建 BD Leader 按目标用户当前 users.region_id 创建；admin-server 只负责权限和审计，不传 regionId，user-service 在关系创建事务里读取目标用户区域并写入 bd_leader_profiles.region_id，不要在创建 BD Leader 时顺手修改用户区域。
hyapp.local/api 是唯一允许直接依赖的 app 后端契约 module；不要 import hyapp/services/*、hyapp/internal/* 或 hyapp/pkg/*。
运营管理/全服通知只能调用 activityv1.MessageInboxService.CreateFanoutJob 创建异步 fanout 命令；admin-server 不直接写 activity-service 数据表，也不能在 HTTP 请求里同步遍历用户发系统/活动消息。
全服通知菜单 code 固定为 operation-full-server-notice，权限固定为 full-server-notice:view 和 full-server-notice:send；新增 UI、OpenAPI、种子权限和路由时必须保持这些 code 一致。

验证

常规验证：

gofmt -w <changed-go-files>
go test ./...

涉及启动、配置、迁移、Redis、任务或路由注入时，还需要本地启动并检查：

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

5.8 KiB Raw Blame History Unescape Escape