@rdmind/rdmind 0.0.9-alpha.0 → 0.0.9-alpha.2

package/.knowledge/.ext/.bmad-core/templates/architecture-tmpl.yaml

@@ -0,0 +1,651 @@
+# <!-- Powered by 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: |
+          在开始架构设计之前，先确认一下项目是否基于某个starter模板或现有代码库：
+
+          1. 查看PRD和需求文档，看看有没有提到：
+          - 项目模板（比如 Create React App、Next.js、Vue CLI、Angular CLI 等）
+          - 作为基础的现有项目或代码库
+          - 脚手架工具或样板项目
+          - 要克隆或改造的之前项目
+
+          2. 如果提到了starter模板或现有项目：
+          - 让用户通过以下方式提供访问：
+            - 提供starter模板文档链接
+            - 上传/附加项目文件（小项目的话）
+            - 分享项目仓库链接（GitHub、GitLab等）
+          - 分析starter/现有项目，了解：
+            - 预配置的技术栈和版本
+            - 项目结构和组织方式
+            - 内置脚本和工具
+            - 现有的架构模式和约定
+            - starter模板带来的限制或约束
+          - 用这个分析来指导架构决策
+
+          3. 如果没提到starter模板，但这是新项目：
+          - 根据技术栈偏好推荐合适的starter模板
+          - 说明好处（快速搭建、最佳实践、社区支持）
+          - 让用户决定是否使用
+
+          4. 如果用户确认不使用starter模板：
+          - 从零开始设计架构
+          - 说明需要手动配置所有工具和环境
+
+          在继续架构设计之前，把决定记录在这里。如果没有，就写"不适用"
+        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. 主要架构风格（比如单体、微服务、Serverless、事件驱动）
+          2. PRD中的仓库结构决策（Monorepo/Polyrepo）
+          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的技术假设和项目目标保持一致
+
+          常见的模式考虑：
+          - 架构风格模式（Serverless、事件驱动、微服务、CQRS、六边形架构）
+          - 代码组织模式（依赖注入、Repository、模块、工厂）
+          - 数据模式（事件溯源、Saga、每个服务一个数据库）
+          - 通信模式（REST、GraphQL、消息队列、发布订阅）
+        template: '- **{{pattern_name}}:** {{pattern_description}} - _理由:_ {{rationale}}'
+        examples:
+          - '**Serverless架构:** 使用AWS Lambda进行计算 - _理由:_ 符合PRD对成本优化和自动扩缩容的要求'
+          - '**Repository模式:** 抽象数据访问逻辑 - _理由:_ 支持测试和未来数据库迁移的灵活性'
+          - '**事件驱动通信:** 使用SNS/SQS进行服务解耦 - _理由:_ 支持异步处理和系统弹性'
+
+  - id: tech-stack
+    title: 技术栈
+    instruction: |
+      这是技术选型的最终决定章节。与用户一起做出具体选择：
+
+      1. 查看PRD技术假设和.bmad-core/data/technical-preferences.yaml中的偏好设置
+      2. 对于每个类别，提供2-3个可行选项，说明优缺点
+      3. 基于项目需求做出明确推荐
+      4. 获得用户对每个选择的明确批准
+      5. 记录具体版本（避免"latest"，固定具体版本）
+      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 | 后端框架 | 企业级，依赖注入好，符合团队模式 |'
+
+  - id: data-models
+    title: 数据模型
+    instruction: |
+      定义核心数据模型/实体：
+
+      1. 查看PRD需求，识别关键业务实体
+      2. 对于每个模型，说明其用途和关系
+      3. 包含关键属性和数据类型
+      4. 展示模型间的关系
+      5. 与用户讨论设计决策
+
+      在转到数据库schema之前，先创建清晰的概念模型。
+    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中的仓库结构（monorepo/polyrepo）
+      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: Project requires external API integrations
+    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: Project includes REST API
+    type: code
+    language: yaml
+    instruction: |
+      如果项目包含REST API：
+
+      1. 创建OpenAPI 3.0规范
+      2. 包含epic/story中的所有端点
+      3. 基于数据模型定义请求/响应schema
+      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: 数据库Schema
+    instruction: |
+      将概念数据模型转换为具体的数据库schema：
+
+      1. 使用技术栈中选择的数据库类型
+      2. 使用适当的符号创建schema定义
+      3. 包含索引、约束和关系
+      4. 考虑性能和可扩展性
+      5. 对于NoSQL，展示文档结构
+
+      以适合数据库类型的格式呈现schema（SQL DDL、JSON schema等）
+    elicit: true
+
+  - id: source-tree
+    title: 源码树
+    type: code
+    language: plaintext
+    instruction: |
+      创建反映以下内容的项目文件夹结构：
+
+      1. 选择的仓库结构（monorepo/polyrepo）
+      2. 服务架构（单体/微服务/serverless）
+      3. 选择的技术栈和语言
+      4. 上面的组件组织
+      5. 选择框架的最佳实践
+      6. 清晰的关注点分离
+
+      根据项目需求调整结构。对于monorepo，展示服务分离。对于serverless，展示函数组织。包含语言特定的约定。
+    elicit: true
+    examples:
+      - |
+        project-root/
+        ├── packages/
+        │   ├── api/                    # 后端API服务
+        │   ├── web/                    # 前端应用
+        │   ├── shared/                 # 共享工具/类型
+        │   └── infrastructure/         # IaC定义
+        ├── scripts/                    # Monorepo管理脚本
+        └── package.json                # 根package.json with workspaces
+
+  - 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包装类型"
+          - "数据库查询必须使用repository模式，永远不要直接使用ORM"
+
+          避免明显的规则如"使用SOLID原则"或"写干净代码"
+        repeatable: true
+        template: '- **{{rule_name}}:** {{rule_description}}'
+      - id: language-specifics
+        title: 语言特定指南
+        condition: Critical language-specific rules needed
+        instruction: 仅在防止AI错误的关键情况下添加。大多数团队不需要这个章节。
+        sections:
+          - id: language-rules
+            title: '{{language_name}} 特定规则'
+            repeatable: true
+            template: '- **{{rule_topic}}:** {{rule_detail}}'
+
+  - id: test-strategy
+    title: 测试策略和标准
+    instruction: |
+      与用户一起定义全面的测试策略：
+
+      1. 使用技术栈中的测试框架
+      2. 决定TDD vs 测试后方法
+      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}}
+              - **Mock库:** {{mocking_library}}
+              - **覆盖率要求:** {{unit_coverage}}
+
+              **AI代理要求:**
+              - 为所有公共方法生成测试
+              - 覆盖边界情况和错误条件
+              - 遵循AAA模式（Arrange, Act, Assert）
+              - Mock所有外部依赖
+          - id: integration-tests
+            title: 集成测试
+            template: |
+              - **范围:** {{integration_scope}}
+              - **位置:** {{integration_test_location}}
+              - **测试基础设施:**
+                - **{{dependency_name}}:** {{test_approach}} ({{test_tool}})
+            examples:
+              - '**数据库:** 单元测试用内存H2，集成测试用Testcontainers PostgreSQL'
+              - '**消息队列:** 测试用嵌入式Kafka'
+              - '**外部API:** 用WireMock进行stubbing'
+          - id: e2e-tests
+            title: 端到端测试
+            template: |
+              - **框架:** {{e2e_framework}} {{version}}
+              - **范围:** {{e2e_scope}}
+              - **环境:** {{e2e_environment}}
+              - **测试数据:** {{e2e_data_strategy}}
+      - id: test-data-management
+        title: 测试数据管理
+        template: |
+          - **策略:** {{test_data_approach}}
+          - **Fixtures:** {{fixture_location}}
+          - **Factories:** {{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: Checklist结果报告
+    instruction: 在运行checklist之前，提供完整架构文档的输出。用户确认后，执行architect-checklist并在此填充结果。
+
+  - id: next-steps
+    title: 下一步
+    instruction: |
+      完成架构后：
+
+      1. 如果项目有UI组件：
+      - 使用"前端架构模式"
+      - 提供此文档作为输入
+
+      2. 对于所有项目：
+      - 与产品负责人review
+      - 使用开发代理开始story实现
+      - 使用DevOps代理设置基础设施
+
+      3. 如需要，包含下一个代理的具体提示
+    sections:
+      - id: architect-prompt
+        title: 架构师提示
+        condition: Project has UI components
+        instruction: |
+          创建简短的提示交给架构师进行前端架构创建。包含：
+          - 对此架构文档的引用
+          - PRD中的关键UI需求
+          - 在此做出的任何前端特定决策
+          - 请求详细的前端架构