Dev architecture

架构设计

把需求文档变成可以直接开工的技术方案。核心产出是两份文档：架构设计（给人看的决策记录）和 API 契约（前后端共同遵守的接口协议）。

前置检查

1. 读取 docs/dev/01-requirements.md。不存在则询问用户：是补跑 /dev-requirements，还是口头给出需求由你现场整理简版。
2. 检查项目现状：是全新项目还是在现有代码库上加功能？现有项目必须先摸清既有技术栈（读 package.json / pom.xml / go.mod / requirements.txt 等），新功能默认沿用现有栈，不引入平行技术。

开工前对齐（必须）

前置检查完成后，先向用户汇报：读到的需求要点、初步选型方向、本阶段将产出的两份文档（架构设计 + API 契约）。用户明确同意后才开始设计；有分歧的选型先用 AskUserQuestion 定下来再动笔。

商量必须自带默认推荐：每个选型都给出你建议的方案并标注「推荐」+一句理由（AskUserQuestion 推荐项放第一位），用户确认或改选即可，不许只抛开放式问题。

工作流程

1. 技术选型

全新项目才需要完整选型。原则：

• 用户量级和团队规模决定复杂度上限——内部工具/中小项目默认单体 + 单库，不上微服务、不上消息队列，除非需求文档里有明确依据。
• 选用户熟悉的、社区成熟的，不选"最新最酷"的。
• 有部署环境约束（内网/信创/国产数据库）时选型必须先过这一关。
• 关键选型（框架、数据库、部署方式）如有多个合理选项，用 AskUserQuestion 让用户拍板，每个选项讲清 trade-off。

2. 输出架构文档

写入 docs/dev/02-architecture.md：

# 架构设计：<项目名>

> 版本：v1.0 | 日期：<今天> | 对应需求：01-requirements.md v1.0

## 1. 技术栈
| 层 | 选型 | 版本 | 选择理由（一句话） |
|----|------|------|--------------------|

## 2. 系统结构
Mermaid 图：模块/服务划分 + 依赖方向 + 外部系统。

## 3. 模块划分
每个模块：职责、对外暴露什么、依赖谁。模块间只能通过声明的接口交互。

## 4. 数据模型
Mermaid ER 图 + 表清单（表名/核心字段/索引/关系）。
命名规范：表名、字段名、软删除/时间戳约定。

## 5. 关键流程
对 P0 需求里最复杂的 1-3 个场景画时序图（Mermaid sequenceDiagram）。

## 6. 部署方案
开发/生产环境拓扑，端口规划，配置管理方式（env 文件约定）。

## 7. 风险与决策记录
- 已知风险 + 缓解方案
- 重要决策：选了什么、放弃了什么、为什么（防止日后翻案无据可查）

3. 输出 API 契约

写入 docs/dev/03-api-contract.md。这是前后端的合同，后端按它实现，前端按它开发，联调时以它裁决分歧。

# API 契约：<项目名>

> 版本：v1.0 | 状态标记：📝 设计中 / ✅ 后端已实现 / 🔗 已联调

## 全局约定
- Base URL：`/api/v1`
- 认证方式：<JWT Header / Cookie / ...>
- 统一响应结构：
  ```json
  { "code": 0, "message": "ok", "data": {} }

• 错误码表：code 含义、HTTP 状态码对应关系
• 分页约定：请求参数（page/pageSize）与响应结构（list/total）
• 时间格式、金额单位、枚举值大小写等易吵架的细节

接口清单

#	方法	路径	说明	对应需求	状态
1	POST	/auth/login	登录	REQ-001	📝

接口详情

每个接口：请求参数（名称/类型/必填/校验规则）、响应示例（真实形状的 JSON，不写 "..."）、 错误情况（哪些输入返回哪个错误码）。

### 4. 评审与交接

1. 向用户汇报核心决策：技术栈一览 + 模块图 + 接口清单，请用户确认或调整。
2. 确认后提示：**下一步运行 `/dev-backend` 开始后端实现**。

## 原则

- 每个设计决策都要能回溯到需求文档的某一条，需求里没有的能力不要"顺手"设计进去。
- API 契约里的响应示例必须是真实形状的完整 JSON——前端会照着它写类型定义。
- 架构文档写"为什么"，代码写"是什么"；文档里不粘贴大段将要写的代码。
- 现有项目改造时，先画"现状图"再画"目标图"，标出迁移路径。