# <!-- 由 BMAD™ Core 驱动 -->
template:
  id: architecture-template-v2
  name: 架构文档
  version: 2.0
  output:
    format: markdown
    filename: docs/architecture.md
    title: "{{project_name}} 架构文档"

workflow:
  mode: interactive
  elicitation: advanced-elicitation

sections:
  - id: introduction
    title: 引言
    instruction: |
      如果可用，请在开始前审查任何提供的相关文档以收集所有相关背景。如果至少找不到docs/prd.md，请询问用户哪些文档将为架构提供基础。
    sections:
      - id: intro-content
        content: |
          本文档概述了{{project_name}}的整体项目架构，包括后端系统、共享服务和非UI特定的问题。其主要目标是作为AI驱动开发的指导性架构蓝图，确保所选模式和技术的一致性和遵守。

          **与前端架构的关系：**
          如果项目包含重要的用户界面，则单独的前端架构文档将详细说明特定于前端的设计，并且必须与本文档结合使用。此处记录的核心技术栈选择（参见“技术栈”）对整个项目（包括任何前端组件）都是决定性的。
      - id: starter-template
        title: 入门模板或现有项目
        instruction: |
          在继续进行架构设计之前，请检查项目是否基于入门模板或现有代码库：

          1. 审查PRD和头脑风暴简报中是否提及：
          - 入门模板（例如，Create React App、Next.js、Vue CLI、Angular CLI等）
          - 用作基础的现有项目或代码库
          - 样板项目或脚手架工具
          - 要克隆或改编的以前的项目

          2. 如果提及了入门模板或现有项目：
          - 要求用户通过以下方法之一提供访问权限：
            - 指向入门模板文档的链接
            - 上传/附加项目文件（对于小项目）
            - 共享项目存储库的链接（GitHub、GitLab等）
          - 分析入门/现有项目以了解：
            - 预配置的技术栈和版本
            - 项目结构和组织模式
            - 内置脚本和工具
            - 现有的架构模式和约定
            - 入门模板施加的任何限制或约束
          - 使用此分析来为您的架构决策提供信息并与之保持一致

          3. 如果未提及入门模板但这是一个绿地项目：
          - 根据技术栈偏好建议合适的入门模板
          - 解释其好处（更快的设置、最佳实践、社区支持）
          - 让用户决定是否使用

          4. 如果用户确认不使用入门模板：
          - 从头开始进行架构设计
          - 注意所有工具和配置都需要手动设置

          在继续进行架构设计之前，在此处记录决定。如果没有，只需说N/A
        elicit: true
      - id: changelog
        title: 变更日志
        type: table
        columns: [日期, 版本, 描述, 作者]
        instruction: 跟踪文档版本和变更

  - id: high-level-architecture
    title: 高层架构
    instruction: |
      本节包含多个小节，它们构成了架构的基础。请一次性呈现所有小节。
    elicit: true
    sections:
      - id: technical-summary
        title: 技术摘要
        instruction: |
          提供一段简短的段落（3-5句）概述：
          - 系统的整体架构风格
          - 关键组件及其关系
          - 主要技术选择
          - 使用的核心架构模式
          - 回顾PRD目标以及此架构如何支持它们
      - id: high-level-overview
        title: 高层概览
        instruction: |
          根据PRD的技术假设部分，描述：

          1. 主要的架构风格（例如，单体、微服务、无服务器、事件驱动）
          2. PRD中的存储库结构决策（单体仓库/多仓库）
          3. PRD中的服务架构决策
          4. 概念层面上的主要用户交互流程或数据流
          5. 关键架构决策及其理由
      - id: project-diagram
        title: 高层项目图
        type: mermaid
        mermaid_type: graph
        instruction: |
          创建一个Mermaid图来可视化高层架构。考虑：
          - 系统边界
          - 主要组件/服务
          - 数据流方向
          - 外部集成
          - 用户入口点

      - id: architectural-patterns
        title: 架构和设计模式
        instruction: |
          列出将指导架构的关键高层模式。对于每个模式：

          1. 如果存在多个选项，则呈现2-3个可行的选项
          2. 提供带有明确理由的您的建议
          3. 在最终确定前获得用户确认
          4. 这些模式应与PRD的技术假设和项目目标保持一致

          要考虑的常见模式：
          - 架构风格模式（无服务器、事件驱动、微服务、CQRS、六边形）
          - 代码组织模式（依赖注入、存储库、模块、工厂）
          - 数据模式（事件溯源、Saga、每个服务一个数据库）
          - 通信模式（REST、GraphQL、消息队列、发布/订阅）
        template: "- **{{pattern_name}}:** {{pattern_description}} - _理由:_ {{rationale}}"
        examples:
          - "**无服务器架构：** 使用AWS Lambda进行计算 - _理由:_ 符合PRD对成本优化和自动扩展的要求"
          - "**存储库模式：** 抽象数据访问逻辑 - _理由:_ 实现测试和未来数据库迁移的灵活性"
          - "**事件驱动通信：** 使用SNS/SQS进行服务解耦 - _理由:_ 支持异步处理和系统弹性"

  - id: tech-stack
    title: 技术栈
    instruction: |
      这是决定性的技术选择部分。与用户合作做出具体选择：

      1. 审查PRD技术假设和来自{root}/data/technical-preferences.yaml或附加的technical-preferences的任何偏好
      2. 对于每个类别，呈现2-3个带有优缺点的可行选项
      3. 根据项目需求提出明确的建议
      4. 为每个选择获得明确的用户批准
      5. 记录确切的版本（避免使用“最新” - 固定特定版本）
      6. 此表是唯一的真实来源 - 所有其他文档都必须引用这些选择

      要最终确定的关键决策 - 在显示表格之前，确保您了解或询问用户 - 如果他们不确定任何内容，请告知用户您也可以提供带有理由的建议：

      - 入门模板（如果有）
      - 语言和运行时及其确切版本
      - 框架和库/包
      - 云提供商和关键服务选择
      - 数据库和存储解决方案 - 如果不清楚，则根据项目建议sql或nosql或其他类型，并根据云提供商提供建议
      - 开发工具

      渲染表格时，确保用户了解此部分选择的重要性，还应查找与任何内容的差距或分歧，如果不清楚列表中为什么会有某些内容，请要求澄清，并立即征求反馈 - 此声明和选项应在允许用户输入之前全部渲染并提示。
    elicit: true
    sections:
      - id: cloud-infrastructure
        title: 云基础设施
        template: |
          - **提供商：** {{cloud_provider}}
          - **关键服务：** {{core_services_list}}
          - **部署区域：** {{regions}}
      - id: technology-stack-table
        title: 技术栈表
        type: table
        columns: [类别, 技术, 版本, 目的, 理由]
        instruction: 用所有相关技术填充技术栈表
        examples:
          - "| **语言** | TypeScript | 5.3.3 | 主要开发语言 | 强类型，优秀的工具，团队专业知识 |"
          - "| **运行时** | Node.js | 20.11.0 | JavaScript运行时 | LTS版本，性能稳定，生态系统广泛 |"
          - "| **框架** | NestJS | 10.3.2 | 后端框架 | 企业级，良好的DI，符合团队模式 |"

  - id: data-models
    title: 数据模型
    instruction: |
      定义核心数据模型/实体：

      1. 审查PRD需求并识别关键业务实体
      2. 对于每个模型，解释其目的和关系
      3. 包括关键属性和数据类型
      4. 显示模型之间的关系
      5. 与用户讨论设计决策

      在转向数据库模式之前创建一个清晰的概念模型。
    elicit: true
    repeatable: true
    sections:
      - id: model
        title: "{{model_name}}"
        template: |
          **目的：** {{model_purpose}}

          **关键属性：**
          - {{attribute_1}}: {{type_1}} - {{description_1}}
          - {{attribute_2}}: {{type_2}} - {{description_2}}

          **关系：**
          - {{relationship_1}}
          - {{relationship_2}}

  - id: components
    title: 组件
    instruction: |
      基于上述的架构模式、技术栈和数据模型：

      1. 识别主要的逻辑组件/服务及其职责
      2. 考虑PRD中的存储库结构（单体仓库/多仓库）
      3. 定义组件之间清晰的边界和接口
      4. 对于每个组件，指定：
      - 主要职责
      - 暴露的关键接口/API
      - 对其他组件的依赖
      - 基于技术栈选择的技术细节

      5. 在有帮助的地方创建组件图
    elicit: true
    sections:
      - id: component-list
        repeatable: true
        title: "{{component_name}}"
        template: |
          **职责：** {{component_description}}

          **关键接口：**
          - {{interface_1}}
          - {{interface_2}}

          **依赖：** {{dependencies}}

          **技术栈：** {{component_tech_details}}
      - id: component-diagrams
        title: 组件图
        type: mermaid
        instruction: |
          创建Mermaid图来可视化组件关系。选项：
          - 用于高层视图的C4容器图
          - 用于详细内部结构的组件图
          - 用于复杂交互的序列图
          选择最合适的以求清晰

  - id: external-apis
    title: 外部API
    condition: 项目需要外部API集成
    instruction: |
      对于每个外部服务集成：

      1. 根据PRD需求和组件设计识别所需的API
      2. 如果文档URL未知，请向用户询问具体信息
      3. 记录身份验证方法和安全考虑
      4. 列出将使用的特定端点
      5. 注意任何速率限制或使用约束

      如果不需要外部API，请明确说明并跳到下一节。
    elicit: true
    repeatable: true
    sections:
      - id: api
        title: "{{api_name}} API"
        template: |
          - **目的：** {{api_purpose}}
          - **文档：** {{api_docs_url}}
          - **基本URL：** {{api_base_url}}
          - **身份验证：** {{auth_method}}
          - **速率限制：** {{rate_limits}}

          **使用的关键端点：**
          - `{{method}} {{endpoint_path}}` - {{endpoint_purpose}}

          **集成说明：** {{integration_considerations}}

  - id: core-workflows
    title: 核心工作流
    type: mermaid
    mermaid_type: sequence
    instruction: |
      使用序列图说明关键系统工作流：

      1. 从PRD中识别关键用户旅程
      2. 显示包括外部API在内的组件交互
      3. 包括错误处理路径
      4. 记录异步操作
      5. 根据需要创建高层和详细的图表

      专注于阐明架构决策或复杂交互的工作流。
    elicit: true

  - id: rest-api-spec
    title: REST API规范
    condition: 项目包含REST API
    type: code
    language: yaml
    instruction: |
      如果项目包含REST API：

      1. 创建一个OpenAPI 3.0规范
      2. 包括来自史诗/故事的所有端点
      3. 根据数据模型定义请求/响应模式
      4. 记录身份验证要求
      5. 包括示例请求/响应

      使用YAML格式以提高可读性。如果没有REST API，则跳过此部分。
    elicit: true
    template: |
      openapi: 3.0.0
      info:
        title: {{api_title}}
        version: {{api_version}}
        description: {{api_description}}
      servers:
        - url: {{server_url}}
          description: {{server_description}}

  - id: database-schema
    title: 数据库模式
    instruction: |
      将概念数据模型转换为具体的数据库模式：

      1. 使用技术栈中选择的数据库类型
      2. 使用适当的表示法创建模式定义
      3. 包括索引、约束和关系
      4. 考虑性能和可扩展性
      5. 对于NoSQL，显示文档结构

      以适合数据库类型的格式呈现模式（SQL DDL、JSON模式等）
    elicit: true

  - id: source-tree
    title: 源代码树
    type: code
    language: plaintext
    instruction: |
      创建一个反映以下内容的项目文件夹结构：

      1. 所选的存储库结构（单体仓库/多仓库）
      2. 服务架构（单体/微服务/无服务器）
      3. 所选的技术栈和语言
      4. 上述的组件组织
      5. 所选框架的最佳实践
      6. 清晰的关注点分离

      根据项目需求调整结构。对于单体仓库，显示服务分离。对于无服务器，显示函数组织。包括特定于语言的约定。
    elicit: true
    examples:
      - |
        project-root/
        ├── packages/
        │   ├── api/                    # 后端API服务
        │   ├── web/                    # 前端应用程序
        │   ├── shared/                 # 共享工具/类型
        │   └── infrastructure/         # IaC定义
        ├── scripts/                    # 单体仓库管理脚本
        └── package.json                # 带有工作区的根package.json

  - id: infrastructure-deployment
    title: 基础设施和部署
    instruction: |
      定义部署架构和实践：

      1. 使用技术栈中选择的IaC工具
      2. 选择适合架构的部署策略
      3. 定义环境和晋升流程
      4. 建立回滚程序
      5. 考虑安全性、监控和成本优化

      获取用户对部署偏好和CI/CD工具选择的输入。
    elicit: true
    sections:
      - id: infrastructure-as-code
        title: 基础设施即代码
        template: |
          - **工具：** {{iac_tool}} {{version}}
          - **位置：** `{{iac_directory}}`
          - **方法：** {{iac_approach}}
      - id: deployment-strategy
        title: 部署策略
        template: |
          - **策略：** {{deployment_strategy}}
          - **CI/CD平台：** {{cicd_platform}}
          - **管道配置：** `{{pipeline_config_location}}`
      - id: environments
        title: 环境
        repeatable: true
        template: "- **{{env_name}}:** {{env_purpose}} - {{env_details}}"
      - id: promotion-flow
        title: 环境晋升流程
        type: code
        language: text
        template: "{{promotion_flow_diagram}}"
      - id: rollback-strategy
        title: 回滚策略
        template: |
          - **主要方法：** {{rollback_method}}
          - **触发条件：** {{rollback_triggers}}
          - **恢复时间目标：** {{rto}}

  - id: error-handling-strategy
    title: 错误处理策略
    instruction: |
      定义全面的错误处理方法：

      1. 为技术栈中的语言/框架选择合适的模式
      2. 定义日志记录标准和工具
      3. 建立错误类别和处理规则
      4. 考虑可观察性和调试需求
      5. 确保安全（日志中不含敏感数据）

      本节指导AI和人类开发人员进行一致的错误处理。
    elicit: true
    sections:
      - id: general-approach
        title: 通用方法
        template: |
          - **错误模型：** {{error_model}}
          - **异常层次结构：** {{exception_structure}}
          - **错误传播：** {{propagation_rules}}
      - id: logging-standards
        title: 日志记录标准
        template: |
          - **库：** {{logging_library}} {{version}}
          - **格式：** {{log_format}}
          - **级别：** {{log_levels_definition}}
          - **所需上下文：**
            - 关联ID：{{correlation_id_format}}
            - 服务上下文：{{service_context}}
            - 用户上下文：{{user_context_rules}}
      - id: error-patterns
        title: 错误处理模式
        sections:
          - id: external-api-errors
            title: 外部API错误
            template: |
              - **重试策略：** {{retry_strategy}}
              - **断路器：** {{circuit_breaker_config}}
              - **超时配置：** {{timeout_settings}}
              - **错误转换：** {{error_mapping_rules}}
          - id: business-logic-errors
            title: 业务逻辑错误
            template: |
              - **自定义异常：** {{business_exception_types}}
              - **面向用户的错误：** {{user_error_format}}
              - **错误代码：** {{error_code_system}}
          - id: data-consistency
            title: 数据一致性
            template: |
              - **事务策略：** {{transaction_approach}}
              - **补偿逻辑：** {{compensation_patterns}}
              - **幂等性：** {{idempotency_approach}}

  - id: coding-standards
    title: 编码标准
    instruction: |
      这些标准对AI代理是强制性的。与用户合作，仅定义防止不良代码所需的关键规则。解释说：

      1. 本节直接控制AI开发人员的行为
      2. 保持最小化 - 假设AI了解通用的最佳实践
      3. 专注于特定于项目的约定和陷阱
      4. 过度详细的标准会使上下文膨胀并减慢开发速度
      5. 标准将被提取到单独的文件中供开发代理使用

      对于每个标准，都要获得用户的明确确认，确认其是必要的。
    elicit: true
    sections:
      - id: core-standards
        title: 核心标准
        template: |
          - **语言和运行时：** {{languages_and_versions}}
          - **样式和Linting：** {{linter_config}}
          - **测试组织：** {{test_file_convention}}
      - id: naming-conventions
        title: 命名约定
        type: table
        columns: [元素, 约定, 示例]
        instruction: 仅在偏离语言默认值时包括
      - id: critical-rules
        title: 关键规则
        instruction: |
          仅列出AI可能违反的规则或特定于项目的要求。示例：
          - “切勿在生产代码中使用console.log - 使用logger”
          - “所有API响应都必须使用ApiResponse包装器类型”
          - “数据库查询必须使用存储库模式，切勿直接使用ORM”

          避免使用“使用SOLID原则”或“编写干净的代码”等显而易见的规则
        repeatable: true
        template: "- **{{rule_name}}:** {{rule_description}}"
      - id: language-specifics
        title: 特定于语言的指南
        condition: 需要关键的特定于语言的规则
        instruction: 仅在对于防止AI错误至关重要时添加。大多数团队不需要此部分。
        sections:
          - id: language-rules
            title: "{{language_name}} specifics"
            repeatable: true
            template: "- **{{rule_topic}}:** {{rule_detail}}"

  - id: test-strategy
    title: 测试策略和标准
    instruction: |
      与用户合作定义全面的测试策略：

      1. 使用技术栈中的测试框架
      2. 决定TDD与测试后方法
      3. 定义测试组织和命名
      4. 建立覆盖目标
      5. 确定集成测试基础设施
      6. 规划测试数据和外部依赖

      注意：基本信息在编码标准中供开发代理使用。此详细部分供QA代理和团队参考。
    elicit: true
    sections:
      - id: testing-philosophy
        title: 测试理念
        template: |
          - **方法：** {{test_approach}}
          - **覆盖目标：** {{coverage_targets}}
          - **测试金字塔：** {{test_distribution}}
      - id: test-types
        title: 测试类型和组织
        sections:
          - id: unit-tests
            title: 单元测试
            template: |
              - **框架：** {{unit_test_framework}} {{version}}
              - **文件约定：** {{unit_test_naming}}
              - **位置：** {{unit_test_location}}
              - **模拟库：** {{mocking_library}}
              - **覆盖要求：** {{unit_coverage}}

              **AI代理要求：**
              - 为所有公共方法生成测试
              - 覆盖边缘情况和错误条件
              - 遵循AAA模式（安排、行动、断言）
              - 模拟所有外部依赖
          - id: integration-tests
            title: 集成测试
            template: |
              - **范围：** {{integration_scope}}
              - **位置：** {{integration_test_location}}
              - **测试基础设施：**
                - **{{dependency_name}}:** {{test_approach}} ({{test_tool}})
            examples:
              - "**数据库：** 单元测试使用内存H2，集成测试使用Testcontainers PostgreSQL"
              - "**消息队列：** 测试使用嵌入式Kafka"
              - "**外部API：** 使用WireMock进行桩模拟"
          - id: e2e-tests
            title: 端到端测试
            template: |
              - **框架：** {{e2e_framework}} {{version}}
              - **范围：** {{e2e_scope}}
              - **环境：** {{e2e_environment}}
              - **测试数据：** {{e2e_data_strategy}}
      - id: test-data-management
        title: 测试数据管理
        template: |
          - **策略：** {{test_data_approach}}
          - **固定数据：** {{fixture_location}}
          - **工厂：** {{factory_pattern}}
          - **清理：** {{cleanup_strategy}}
      - id: continuous-testing
        title: 持续测试
        template: |
          - **CI集成：** {{ci_test_stages}}
          - **性能测试：** {{perf_test_approach}}
          - **安全测试：** {{security_test_approach}}

  - id: security
    title: 安全性
    instruction: |
      为AI和人类开发人员定义强制性安全要求：

      1. 专注于特定于实现的规则
      2. 引用技术栈中的安全工具
      3. 为常见场景定义清晰的模式
      4. 这些规则直接影响代码生成
      5. 与用户合作，确保完整性而无冗余
    elicit: true
    sections:
      - id: input-validation
        title: 输入验证
        template: |
          - **验证库：** {{validation_library}}
          - **验证位置：** {{where_to_validate}}
          - **所需规则：**
            - 所有外部输入都必须经过验证
            - 在处理前在API边界进行验证
            - 白名单方法优于黑名单方法
      - id: auth-authorization
        title: 身份验证和授权
        template: |
          - **认证方法：** {{auth_implementation}}
          - **会话管理：** {{session_approach}}
          - **所需模式：**
            - {{auth_pattern_1}}
            - {{auth_pattern_2}}
      - id: secrets-management
        title: 密钥管理
        template: |
          - **开发：** {{dev_secrets_approach}}
          - **生产：** {{prod_secrets_service}}
          - **代码要求：**
            - 切勿硬编码密钥
            - 仅通过配置服务访问
            - 日志或错误消息中不含密钥
      - id: api-security
        title: API安全
        template: |
          - **速率限制：** {{rate_limit_implementation}}
          - **CORS策略：** {{cors_configuration}}
          - **安全头：** {{required_headers}}
          - **HTTPS强制：** {{https_approach}}
      - id: data-protection
        title: 数据保护
        template: |
          - **静态加密：** {{encryption_at_rest}}
          - **传输中加密：** {{encryption_in_transit}}
          - **PII处理：** {{pii_rules}}
          - **日志记录限制：** {{what_not_to_log}}
      - id: dependency-security
        title: 依赖项安全
        template: |
          - **扫描工具：** {{dependency_scanner}}
          - **更新策略：** {{update_frequency}}
          - **批准流程：** {{new_dep_process}}
      - id: security-testing
        title: 安全测试
        template: |
          - **SAST工具：** {{static_analysis}}
          - **DAST工具：** {{dynamic_analysis}}
          - **渗透测试：** {{pentest_schedule}}

  - id: checklist-results
    title: 清单结果报告
    instruction: 在运行清单之前，提议输出完整的架构文档。一旦用户确认，执行architect-checklist并在此处填充结果。

  - id: next-steps
    title: 下一步
    instruction: |
      完成架构后：

      1. 如果项目有UI组件：
      - 使用“前端架构模式”
      - 提供本文档作为输入

      2. 对于所有项目：
      - 与产品负责人审查
      - 与开发代理一起开始故事实施
      - 与DevOps代理一起设置基础设施

      3. 如果需要，为下一个代理包括具体的提示
    sections:
      - id: architect-prompt
        title: 架构师提示
        condition: 项目有UI组件
        instruction: |
          为前端架构创建创建一个简短的提示以交接给架构师。包括：
          - 对此架构文档的引用
          - 来自PRD的关键UI要求
          - 此处做出的任何特定于前端的决定
          - 对详细前端架构的要求