更新

AGENT.md

@@ -0,0 +1,119 @@
+# 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 是细则源头）