# 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 按目标用户当前 `users.region_id` 创建；admin-server 只负责权限和审计，不传 `regionId`，user-service 在关系创建事务里读取目标用户区域并写入 `bd_leader_profiles.region_id`，不要在创建 BD Leader 时顺手修改用户区域。
9. `hyapp.local/api` 是唯一允许直接依赖的 app 后端契约 module；不要 import `hyapp/services/*`、`hyapp/internal/*` 或 `hyapp/pkg/*`。
10. 运营管理/全服通知只能调用 `activityv1.MessageInboxService.CreateFanoutJob` 创建异步 fanout 命令；admin-server 不直接写 activity-service 数据表，也不能在 HTTP 请求里同步遍历用户发系统/活动消息。
11. 全服通知菜单 code 固定为 `operation-full-server-notice`，权限固定为 `full-server-notice:view` 和 `full-server-notice:send`；新增 UI、OpenAPI、种子权限和路由时必须保持这些 code 一致。

## 验证

常规验证：

```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
```