OneSystem

Imported from zhurongbo111/OneSystem (AGENTS.md). Install upstream with npx skills add zhurongbo111/OneSystem. Copyright stays with the author.

AGENTS.md — 项目总体规则

本文件是项目总体规则（总则），AI 会话自动全文加载。 职责划分：本文件是工程约定的唯一事实源；各功能的 specs/<feature>/ 规格是功能需求的唯一事实源。规格与本文件冲突时以规格为准，但应提示用户核对规格是否有误。 专项规则（frontend / backend 等）只写本文件的落地细节，不重复总则条款；确需引用时标注章节（如 AGENTS.md §4.5 / §6）。总则与专项规则如有出入，以本文件为准并提示核对。 前端/后端的具体实现约定不在本文件，分别见：

• 后端规则：.codebuddy/rules/backend/RULE.mdc（开发 backend/ 时应用）
• 前端规则：.codebuddy/rules/frontend/RULE.mdc（开发 frontend/ 时应用）

实现新功能时：先读 specs/<feature>/ 规格，再按需加载对应端的规则文件。

1. 项目概述

2. 规格驱动开发（SDD）

2.1 规格目录

specs/
  <feature-name>/        # kebab-case 命名，与功能一一对应
    requirement.md       # 需求规格：背景、目标、功能点、验收标准
    design.md            # 设计规格：API 设计、数据模型、前端交互、技术决策
    tasks.md             # 任务清单：可勾选（- [ ]）的任务项

2.2 工作流（强制）

1. 需求先行：任何功能（含小改动）必须先创建或更新 specs/<feature>/requirement.md。
2. 设计：需求确认后写 design.md；新增/变更的接口、数据库改动、前端页面必须在此定义。
3. 任务拆分：设计确认后拆分为 tasks.md 中可勾选的任务项。
4. 实现：严格按 tasks.md 顺序实现；执行每个任务前先重读规格相关章节。
5. 勾选：任务完成后在 tasks.md 勾选；全部完成即功能完成。
6. 变更：开发中需求变化，先改规格、再改代码；禁止绕过规格直接改代码。

2.3 规则

• 规格是功能的唯一事实源，代码必须始终与规格一致。
• AI 实现功能前必须先读 specs/<feature>/ 三个文件；规格缺失时先提示补规格，不直接写代码。
• 规格文件命名、结构遵循 2.1，不得随意新增其他层级。

3. 目录结构

.
├── AGENTS.md              # 总体规则（本文件）
├── .codebuddy/rules/      # 专项规则（frontend / backend 等）
├── specs/                 # 功能规格
├── frontend/              # 前端项目
└── backend/               # 后端项目

frontend/、backend/ 内部结构分别在各自规则文件中定义。

4. API 契约（前后端共同遵守）

4.1 统一响应

所有接口统一返回：

{ "code": 0, "message": "success", "data": {} }

• code = 0 表示成功；非 0 一律为错误，前端统一提示 message。
• 前端请求封装统一解包 data，业务代码只处理数据本身。

4.2 错误码

业务错误码扩展在各功能 design.md 中定义，禁止随手新增。

4.3 分页

分页接口使用 Query 参数 page（从 1 起）、pageSize；data 结构：

{ "items": [], "total": 0, "page": 1, "pageSize": 20 }

4.4 命名与序列化

• 资源用名词复数，如 /api/users；不使用动词作资源路径。
• 后端 JSON 序列化采用 camelCase，与前端 DTO 类型一一对应。

4.5 认证（JWT）

• 登录成功后由后端签发 JWT；前端后续请求统一携带 Authorization: Bearer <token> 请求头。
• 后端全局校验 token（登录等白名单接口除外）；校验失败统一返回 code: 40100。
• token 过期 / 失效：前端统一处理 40100，清除本地凭证并跳转登录页。
• 签发与校验实现见后端规则；token 存储与携带见前端规则。

5. 通用编码约定（前后端共同遵守）

• 提交信息使用 Conventional Commits：feat|fix|docs|refactor|test|chore(scope): 描述。
• 异常处理：禁止吞异常；错误日志必须包含上下文（含 traceId）。
• 语言：代码标识符使用英文；注释与文档使用中文。

6. 测试策略（总述）

• 后端：单元测试（xUnit），重点覆盖 Handler 业务逻辑，细则见后端规则。
• 前端：不单写单元测试；集成测试用 Playwright e2e 自动化（frontend 下 npm run test:e2e，直连 dev 后端、不打 mock），细则见前端规则。
• 前端 e2e 覆盖（强制）：凡涉及前端改动的功能，交付前必须有 e2e 用例覆盖改动的用户可感知行为；无 e2e 覆盖视为未完成，不得勾选对应 tasks.md 任务。
• 前后端改动须跑相关测试（强制）：功能同时涉及前后端改动时，交付前必须后端 dotnet test 与前端 npm run test:e2e 都跑通；只改一端时至少跑被改动端的测试。测试未通过不得声明功能完成。

7. 环境与可观测性

• 环境目前只分 dev（开发）/ prod（生产）两个，后续按需扩展。
• 配置原则：非敏感配置放配置文件并按环境区分；敏感配置（数据库连接串、JWT 密钥等）只从环境变量读取，禁止硬编码、禁止入库。
• 可观测性：后端集成 OpenTelemetry（Tracing + Metrics），日志使用 NLog 对接默认 ILogger<T> 框架，细则见后端规则。

8. Git 分支与提交

8.1 分支模型（轻量）

• 同一时间只在一个分支上开发，避免长期并行分支。
• 合并方式使用普通 merge 或 squash merge（团队统一，后续 CI/CD 建立后由合并流程强制）。
• 禁止直接在 main 上开发、禁止 force push、禁止改写已推送的历史。

8.2 提交规范

• 提交信息遵循 Conventional Commits（见第 5 节）；scope 使用 frontend / backend 或具体模块名。
• 规格文件变更单独提交：docs(specs): ...。

9. 专项规则索引

10. 待补充清单（确认后逐项并入本文件）

• CI/CD 与部署方式（暂不考虑，后续更新）