@chongyan/autospec 1.0.1 → 1.0.2

package/knowledge/09-templates/01-architecture-design.md

@@ -0,0 +1,494 @@
+# 架构设计：{项目/系统名}
+
+> **版本**: v1.0
+> **模板来源**: 软件工程架构设计最佳实践、ANSI/ISO/IEC/IEEE 42010 标准、C4 模型、结构化设计方法
+> **适用范围**: 所有类型的软件系统架构设计
+> **生成模式**: 两步生成法（大纲→详设）、架构愿景 → 逻辑架构 → 物理架构 → 技术决策
+
+---
+
+## 1. 架构愿景
+
+### 1.1 系统概述
+
+| 字段 | 值 |
+|------|-----|
+| 系统名称 | |
+| 系统类型 | 单体/微服务/分布式/Serverless |
+| 主要功能 | |
+| 目标用户 | |
+| 预期规模 | 用户量/数据量/并发量 |
+
+### 1.2 架构目标
+
+| 目标 | 说明 | 优先级 | 衡量指标 |
+|------|------|--------|---------|
+| 性能 | | P0/P1/P2 | 响应时间<ms, QPS |
+| 可用性 | | P0/P1/P2 | 99.9%/99.99% |
+| 可扩展性 | | P0/P1/P2 | 水平扩展能力 |
+| 安全性 | | P0/P1/P2 | 安全合规等级 |
+| 可维护性 | | P0/P1/P2 | 代码复杂度、文档完整度 |
+
+### 1.3 架构约束
+
+| 约束类型 | 约束描述 | 来源 | 影响 |
+|---------|---------|------|------|
+| 技术约束 | 如：必须使用 Java 17 | 团队技术栈 | 技术选型 |
+| 业务约束 | 如：必须支持多租户 | 业务需求 | 架构设计 |
+| 合规约束 | 如：数据本地化存储 | 法规要求 | 部署架构 |
+
+---
+
+## 2. 系统上下文
+
+### 2.1 系统上下文图
+
+```mermaid
+C4Context
+    Person(user, "用户", "系统使用者")
+    System_Boundary(system, "系统边界") {
+        System(system_name, "系统名称", "系统描述")
+    }
+    Ext_Boundary(ext, "外部系统") {
+        System_Ext(ext_system, "外部系统", "依赖的第三方系统")
+    }
+    Rel(user, system_name, "使用")
+    Rel(system_name, ext_system, "调用")
+```
+
+### 2.2 外部依赖
+
+| 依赖名称 | 类型 | 用途 | 依赖方式 | SLA |
+|---------|------|------|---------|-----|
+| | 数据库/消息队列/缓存/API | | 同步/异步 | 99.9% |
+
+### 2.3 服务依赖关系
+
+> 本节描述项目间的服务调用关系，适用于微服务架构或多系统项目。
+
+#### 2.3.1 项目依赖图
+
+```mermaid
+graph LR
+    project_a -->|RPC| project_b
+    project_a -->|HTTP| external_service
+```
+
+#### 2.3.2 项目间依赖
+
+| 调用方 | 被调用方 | 类型 | 服务 | 说明 |
+|--------|----------|------|------|------|
+| {from} | {to} | rpc/http/mq | {services} | {description} |
+
+#### 2.3.3 外部服务依赖
+
+| 项目 | 外部服务 | 类型 | 用途 | 配置项 |
+|------|----------|------|------|--------|
+| {project} | {service} | rpc/http | {purpose} | {config_key} |
+
+#### 2.3.4 消息队列依赖
+
+| Topic | 生产者 | 消费者 | 说明 |
+|-------|--------|--------|------|
+| {topic} | {producer} | {consumer} | {description} |
+
+---
+
+## 3. 逻辑架构
+
+### 3.1 逻辑分层
+
+```mermaid
+graph TB
+    subgraph "展示层"
+        A1[Web 端]
+        A2[移动端]
+        A3[API 网关]
+    end
+
+    subgraph "业务层"
+        B1[业务服务 A]
+        B2[业务服务 B]
+        B3[业务服务 C]
+    end
+
+    subgraph "数据层"
+        C1[数据库]
+        C2[缓存]
+        C3[消息队列]
+    end
+
+    A1 --> A3
+    A2 --> A3
+    A3 --> B1
+    A3 --> B2
+    B1 --> C1
+    B1 --> C2
+    B2 --> C3
+```
+
+### 3.2 模块划分
+
+| 模块名称 | 职责 | 包含组件 | 接口定义 |
+|---------|------|---------|---------|
+| | | | |
+
+### 3.3 核心流程
+
+```mermaid
+sequenceDiagram
+    participant A as 组件 A
+    participant B as 组件 B
+    participant C as 组件 C
+
+    A->>B: 请求
+    B->>C: 处理
+    C-->>B: 结果
+    B-->>A: 响应
+```
+
+---
+
+## 4. 物理架构
+
+### 4.1 部署架构
+
+```mermaid
+graph TB
+    subgraph "可用区 A"
+        A1[节点 A1]
+        A2[节点 A2]
+    end
+
+    subgraph "可用区 B"
+        B1[节点 B1]
+        B2[节点 B2]
+    end
+
+    LB[负载均衡] --> A1
+    LB --> A2
+    LB --> B1
+    LB --> B2
+```
+
+### 4.2 基础设施
+
+| 资源类型 | 规格 | 数量 | 用途 |
+|---------|------|------|------|
+| 计算节点 | | | |
+| 数据库 | | | |
+| 缓存 | | | |
+| 消息队列 | | | |
+
+---
+
+## 5. 技术选型
+
+### 5.1 技术栈
+
+| 层级 | 技术 | 版本 | 选型理由 | 替代方案 |
+|------|------|------|---------|---------|
+| 前端 | | | | |
+| 后端 | | | | |
+| 数据库 | | | | |
+| 中间件 | | | | |
+
+### 5.2 关键技术决策
+
+| 决策项 | 选项 A | 选项 B | 选择 | 理由 |
+|-------|-------|-------|------|------|
+| | | | | |
+
+---
+
+## 6. 架构质量
+
+### 6.1 性能设计
+
+| 场景 | 目标 | 策略 |
+|------|------|------|
+| 读操作 | | 缓存/索引/分页 |
+| 写操作 | | 异步/批量/限流 |
+| 查询 | | 搜索引擎/预计算 |
+
+### 6.2 可用性设计
+
+| 风险 | 影响 | 缓解措施 |
+|------|------|---------|
+| 单点故障 | | 冗余部署/自动切换 |
+| 数据丢失 | | 备份/复制 |
+| 服务雪崩 | | 熔断/降级/限流 |
+
+### 6.3 安全设计
+
+| 风险 | 防护措施 |
+|------|---------|
+| 认证 | JWT/OAuth2/SSO |
+| 授权 | RBAC/ABAC |
+| 数据安全 | 加密/脱敏 |
+
+---
+
+## 7. 架构演进
+
+### 7.1 版本规划
+
+| 版本 | 时间 | 目标 | 关键特性 |
+|------|------|------|---------|
+| v1.0 | | MVP | |
+| v2.0 | | 扩展 | |
+
+### 7.2 技术债务
+
+| 债务项 | 原因 | 影响 | 偿还计划 |
+|-------|------|------|---------|
+| | | | |
+
+---
+
+## 8. 设计方法（两步生成法）
+
+### 8.1 概述
+
+采用两步生成法进行设计文档编写：
+
+```
+Phase 1 (大纲)          Phase 2 (详设)
+    ↓                       ↓
+功能点列表            逐个功能点写详设
+全部标记 - [ ]          每完成一个打钩 - [x]
+    ↓                       ↓
+用户确认方向           进度可视化
+```
+
+### 8.2 Phase 1: 大纲生成
+
+**输出**：功能点列表（待确认）
+
+```markdown
+### 3.2 功能点列表
+- [ ] **FP-01**: {功能点 1 名称} - {简要描述}
+- [ ] **FP-02**: {功能点 2 名称} - {简要描述}
+- [ ] **FP-03**: {功能点 3 名称} - {简要描述}
+```
+
+**优势**：
+- 用户先确认大纲方向，避免整体返工
+- 可中断：完成部分可直接使用
+- 进度可视化：用户随时知道完成度
+
+### 8.3 Phase 2: 逐个细化
+
+**输出**：每个功能点的详细设计
+
+```markdown
+#### 3.2.1 FP-01: {功能点 1 名称}
+- [x] 完成
+
+**概述**: {功能点的业务目标和实现思路}
+
+**流程图**:
+```mermaid
+sequenceDiagram
+    participant U as 用户/上游
+    participant S as 本系统
+    participant D as 下游系统
+
+    U->>S: 1. 请求描述
+    S->>D: 2. 调用下游
+    D-->>S: 3. 返回结果
+    S-->>U: 4. 响应
+```
+
+**职责**:
+- 输入：{入参}
+- 处理：{处理逻辑}
+- 输出：{输出结果}
+
+**异常处理**:
+- {异常 1}: {处理方式}
+- {异常 2}: {处理方式}
+```
+
+---
+
+## 9. 领域模型设计
+
+### 9.1 领域模型图
+
+使用 Mermaid classDiagram 描述领域模型：
+
+```mermaid
+classDiagram
+    class Order {
+        +Long orderId
+        +String userId
+        +OrderStatus status
+        +Money amount
+        +confirm()
+        +cancel()
+    }
+    class OrderStatus {
+        <<enumeration>>
+        INIT
+        PAYING
+        SUCCESS
+        CANCELLED
+    }
+    Order --> OrderStatus
+```
+
+### 9.2 状态机设计
+
+使用 Mermaid stateDiagram 描述状态流转：
+
+```mermaid
+stateDiagram-v2
+    [*] --> INIT: 创建订单
+    INIT --> PAYING: 发起支付
+    PAYING --> SUCCESS: 支付成功
+    PAYING --> CANCELLED: 支付失败/超时
+    CANCELLED --> [*]
+    SUCCESS --> [*]
+```
+
+### 9.3 数据库设计
+
+使用 Mermaid erDiagram 描述数据模型：
+
+```mermaid
+erDiagram
+    USER ||--o{ ORDER : places
+    ORDER ||--|{ ORDER_ITEM : contains
+    PRODUCT ||--o{ ORDER_ITEM : included_in
+```
+
+---
+
+## 10. 多系统架构设计
+
+### 10.1 设计文档组织
+
+```
+requirements/{业务域}/{需求}/
+├── proposal.md              # 整体需求提案
+└── design/
+    ├── overview.md          # 整体架构设计
+    ├── backend.md           # 后端系统设计
+    ├── frontend.md          # 前端系统设计
+    ├── ai.md                # AI/模型设计（如需要）
+    └── data.md              # 数据管道设计（如需要）
+```
+
+### 10.2 设计顺序
+
+**有依赖关系的系统**：
+1. 先设计被依赖的系统（如后端 API）
+2. 再设计调用方系统（如前端、移动端）
+
+**可并行的系统**：
+1. 先定义契约（API Schema、数据 Schema）
+2. 各系统基于契约并行设计
+
+### 10.3 跨系统设计检查
+
+- [ ] 系统间接口定义清晰
+- [ ] 数据一致性方案明确
+- [ ] 超时/重试/降级策略一致
+- [ ] 错误码定义统一
+- [ ] 监控指标对齐
+
+---
+
+## 11. 设计原则
+
+### 11.1 描述方法职责，不平铺实现代码
+
+**错误示例**：直接贴代码实现
+
+**正确示例**：
+```markdown
+**职责**: 接收订单创建请求，校验参数后创建订单记录
+
+**输入**: OrderRequest (userId, productId, amount)
+
+**处理**:
+1. 参数校验（非空、格式、业务规则）
+2. 用户存在性校验
+3. 库存预占
+4. 创建订单记录，状态为"待支付"
+5. 发送订单创建事件
+
+**输出**: Order (orderId, status, createTime)
+
+**异常**:
+- IllegalArgumentException: 参数校验失败
+- UserNotFoundException: 用户不存在
+- StockNotEnoughException: 库存不足
+```
+
+### 11.2 功能点职责不重叠
+
+确保每个功能点职责单一，不重复描述同一逻辑。
+
+### 11.3 开关/配置只加必要的
+
+- 能由调用方控制的不在本系统加开关
+- 新增配置必须有明确的业务场景
+- 避免过度配置导致维护成本
+
+### 11.4 共享组件/依赖库变更说明
+
+涉及共享组件（SPI/Facade/依赖库）模型变更时，必须说明：
+
+| 字段 | 说明 |
+|------|------|
+| Maven 坐标 | groupId:artifactId |
+| 当前版本 | 当前使用的版本 |
+| 升级版本 | 计划升级的版本 |
+| 变更内容 | 具体变更了什么 |
+| 需升级的系统 | 哪些系统需要同步升级 |
+
+---
+
+## 12. 附录
+
+### 12.1 术语表
+
+| 术语 | 定义 |
+|------|------|
+| | |
+
+### 12.2 设计质量检查清单
+
+**Phase 1 检查点**：
+- [ ] 项目背景填写完整
+- [ ] 业务用例图从 proposal 正确提取
+- [ ] 功能点列表完整，覆盖 proposal 所有功能
+- [ ] 功能点命名清晰，职责单一
+- [ ] 详细设计章节占位符正确
+
+**Phase 2 检查点**：
+- [ ] 所有功能点已标记为 `[x]` 完成
+- [ ] 每个功能点都有详细设计内容
+- [ ] 流程图可正常渲染
+- [ ] 与 proposal.md 业务流程一致
+- [ ] 遵循系统架构规范
+
+**设计原则检查**：
+- [ ] 无实现代码平铺（方法设计只描述职责、入参、输出）
+- [ ] 功能点职责不重叠（无多个功能点重复描述同一逻辑）
+- [ ] 开关/配置无过度设计
+- [ ] 新增配置与项目已有配置声明方式一致
+- [ ] 共享组件/依赖库模型变更已说明版本升级方案
+
+### 12.3 参考资料
+
+- [API 设计模板](./02-api-design.md)
+- [数据库设计模板](./03-database-design.md)
+
+---
+
+**维护者**: 项目团队
+**进化分区**: 受控区
+**关联文档**: `knowledge/09-templates/02-api-design.md`, `knowledge/09-templates/03-database-design.md`