120 lines
4.8 KiB
Markdown
120 lines
4.8 KiB
Markdown
|
# 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 是细则源头）
|