# K12Study Agent 工程规范

本文件是所有自动化 agent（Claude Code / Cursor / Copilot 等）在本仓库工作时必须遵守的项目级规范。
细则源文件位于 `.agents/skills/*/SKILL.md`，本文件是汇总入口，改动时两处保持一致。

---

## 1. 统一响应体契约（API Response）

来源：`.agents/skills/k12-api-response-standard/SKILL.md`

### 适用场景
- 新增或改造后端 API
- 改动前端 / 小程序请求层
- 修复“后端已报错但前端当成功处理”的联调问题

### 契约
响应体结构固定为 `code / message / data / traceId` 四字段。
- 成功：`code === 0`
- 业务失败：`code !== 0`，前端必须抛错并使用 `message` 透出
- `traceId` 必须保留用于链路追踪

### 强制项
1. 后端 Controller 与全局异常处理统一返回 `ApiResponse`（位于 `common-api`）
2. 前端 `frontend/src/utils/http.ts`、小程序 `app/src/utils/request.js` 必须同时校验 HTTP 状态码与业务 `code`
3. 新接口落地时同步检查类型声明与调用方解包方式，避免重复定义结构
4. 同步更新 `docs/architecture/api-design.md` 中响应体约定

### 禁止项
- 禁止字段重命名（如 `message` → `msg`）
- 禁止去掉 `traceId`

---

## 2. RESTful 接口风格

来源：`.agents/skills/k12-restful-api-style/SKILL.md`

### 适用场景
- 新增 API 设计
- 旧接口路径改造（如 `current-user`、`*/tree`）
- 同步网关白名单与客户端调用路径

### 设计规则
- 路径优先使用资源名（名词），不是动作名
- 集合资源使用复数：`/users`、`/departments`、`/classes`
- “当前用户”使用语义路径：`/users/current`
- 树形结构通过资源路径表达：`/areas`、`/tenants`、`/departments`
- 统一入口前缀：`/api/*`，不得更改

### 强制项
1. Controller 使用 RESTful 主路径
2. 改路径必须同步更新：前端 API、小程序 API、网关白名单、`docs/architecture/api-design.md`、`docs/architecture/logical-view.md`
3. Feign 契约（`apis/api-*/remote/*RemoteApi.java`）与 Controller 路径必须一致；启动时 `FeignContractValidator` 会校验

### 禁止项
- **旧接口不兼容，禁止保留/恢复兼容别名**
- 禁止动词化路径（如 `/getUser`、`/doLogin`）

---

## 3. 注释头规范

来源：`.agents/skills/k12-comment-header-standard/SKILL.md`

### 适用场景
- 任务涉及 `global.code-snippets`、`.fileheader/fileheader.config.yaml`
- 用户要求统一文件头 / 函数注释规范
- `@author` 对齐 git `user.name`

### 强制项
1. 以 `git config user.name` 为 `@author` 基线（当前：**wangys**）
2. 更新 `global.code-snippets` 中 `FileHeader` 与 `Method` 的 author 默认值
3. 使用 `turbo-file-header` 的项目须检查 `.fileheader/fileheader.config.yaml` 的 `@author`
4. 修改后验证 JSON / YAML 可解析
5. 保留字段顺序：`description / filename / author / copyright / since`

### 禁止项
- 不在此规范下修改业务逻辑代码

---

## 4. 前端导入别名规范

来源：`.agents/skills/k12-frontend-import-alias/SKILL.md`

### 适用场景
- 修改 `frontend/src` 下任意 `ts/tsx/js` 文件
- 新增组件、页面、路由、API、store、utils 模块
- 代码评审指出存在 `../`、`../../` 上跳导入

### 强制项
1. 跨目录导入统一使用 `@/` 别名路径（例如 `@/api`、`@/pages`、`@/utils`）。
2. 禁止使用 `../`、`../../` 等上跳相对导入。
3. 禁止使用以 `/` 开头的模块导入路径（如 `from "/utils/http"`）。
4. 同目录导入允许使用 `./`（例如 `./index.scss`）。
5. 改动后执行 `pnpm --dir frontend build` 验证。

### 禁止项
- 禁止新增任何 `../`、`../../` 或以 `/` 开头的导入写法。

---

## 5. Feign 契约与微服务边界（补充）

> 非 skills 原有条款，但属于本仓库架构约束，agent 工作时必须遵守。

- `apis/api-*` 模块只放 DTO + `@FeignClient` 接口 + 路径常量 + `FallbackFactory`，**不得**依赖 service / jdbc / redis
- 新业务模块同时做 Provider + Consumer 时引 `common-feign`，自动启用 `@EnableFeignClients(basePackages="com.k12study.api")` + OkHttp + Authorization 透传 + 启动契约自检
- 微服务模式通过 Nacos（`spring-cloud-starter-alibaba-nacos-discovery`）寻址，单体 / 本地联调通过 `k12study.remote.<module>.url` 走直连 URL 兜底
- 熔断降级统一返回 `ApiResponse.failure(503, reason)`，前端按标准响应体处理

---

## 6. Agent 协作约定

- 任务拆解与进度跟踪优先使用 `TaskCreate / TaskUpdate`，而不是把进度写进 memory
- 任何对本文件、`.agents/skills/*`、`docs/architecture/*` 的改动都必须在同一次提交中同步
- 本文件若与 `.agents/skills/*/SKILL.md` 冲突，以 SKILL.md 为准（SKILL.md 是细则源头）