@chongyan/autospec 1.0.2 → 1.0.4

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

@@ -1,494 +0,0 @@
-# 架构设计：{项目/系统名}
-
-> **版本**: 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`