478 lines
18 KiB
YAML
478 lines
18 KiB
YAML
# <!-- 由 BMAD™ Core 驱动 -->
|
||
template:
|
||
id: brownfield-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: |
|
||
重要 - 需要范围和评估：
|
||
|
||
此架构文档适用于需要全面架构规划的现有项目的重大增强。在继续之前：
|
||
|
||
1. **验证复杂性**：确认此增强需要架构规划。对于简单的添加，建议：“对于不需要架构规划的更简单的更改，请考虑改用产品负责人的 brownfield-create-epic 或 brownfield-create-story 任务。”
|
||
|
||
2. **必需输入**：
|
||
- 完成的 brownfield-prd.md
|
||
- 现有的项目技术文档（来自 docs 文件夹或用户提供）
|
||
- 对现有项目结构的访问权限（IDE 或上传的文件）
|
||
|
||
3. **深度分析任务**：在提出任何架构建议之前，您必须对现有代码库、架构模式和技术约束进行彻底分析。每个建议都必须基于实际的项目分析，而不是假设。
|
||
|
||
4. **持续验证**：在此过程中，明确地与用户验证您的理解。对于每个架构决策，请确认：“根据我对您现有系统的分析，我建议[决策]，因为[来自实际项目的证据]。这是否符合您系统的实际情况？”
|
||
|
||
如果缺少任何必需的输入，请在继续之前请求它们。
|
||
elicit: true
|
||
sections:
|
||
- id: intro-content
|
||
content: |
|
||
本文档概述了使用{{enhancement_description}}增强{{project_name}}的架构方法。其主要目标是作为AI驱动开发新功能的指导性架构蓝图，同时确保与现有系统的无缝集成。
|
||
|
||
**与现有架构的关系：**
|
||
本文档通过定义新组件如何与当前系统集成来补充现有项目架构。当新旧模式之间出现冲突时，本文档提供了在实施增强功能的同时保持一致性的指导。
|
||
- id: existing-project-analysis
|
||
title: 现有项目分析
|
||
instruction: |
|
||
分析现有项目结构和架构：
|
||
|
||
1. 审查 docs 文件夹中的现有文档
|
||
2. 检查当前的技术栈和版本
|
||
3. 识别现有的架构模式和约定
|
||
4. 注意当前的部署和基础设施设置
|
||
5. 记录任何约束或限制
|
||
|
||
关键：分析后，明确验证您的发现：“根据我对您项目的分析，我确定了您现有系统的以下几点：[关键发现]。在我提出架构建议之前，请确认这些观察结果是准确的。”
|
||
elicit: true
|
||
sections:
|
||
- id: current-state
|
||
title: 当前项目状态
|
||
template: |
|
||
- **主要目的：** {{existing_project_purpose}}
|
||
- **当前技术栈：** {{existing_tech_summary}}
|
||
- **架构风格：** {{existing_architecture_style}}
|
||
- **部署方法：** {{existing_deployment_approach}}
|
||
- id: available-docs
|
||
title: 可用文档
|
||
type: bullet-list
|
||
template: "- {{existing_docs_summary}}"
|
||
- id: constraints
|
||
title: 已识别的约束
|
||
type: bullet-list
|
||
template: "- {{constraint}}"
|
||
- id: changelog
|
||
title: 变更日志
|
||
type: table
|
||
columns: [变更, 日期, 版本, 描述, 作者]
|
||
instruction: 跟踪文档版本和变更
|
||
|
||
- id: enhancement-scope
|
||
title: 增强范围和集成策略
|
||
instruction: |
|
||
定义增强功能将如何与现有系统集成：
|
||
|
||
1. 审查棕地PRD增强范围
|
||
2. 识别与现有代码的集成点
|
||
3. 定义新旧功能之间的界限
|
||
4. 建立兼容性要求
|
||
|
||
验证检查点：在提出集成策略之前，请确认：“根据我的分析，我提出的集成方法考虑了[特定的现有系统特征]。这些集成点和边界尊重您当前的架构模式。此评估是否准确？”
|
||
elicit: true
|
||
sections:
|
||
- id: enhancement-overview
|
||
title: 增强概述
|
||
template: |
|
||
**增强类型：** {{enhancement_type}}
|
||
**范围：** {{enhancement_scope}}
|
||
**集成影响：** {{integration_impact_level}}
|
||
- id: integration-approach
|
||
title: 集成方法
|
||
template: |
|
||
**代码集成策略：** {{code_integration_approach}}
|
||
**数据库集成：** {{database_integration_approach}}
|
||
**API集成：** {{api_integration_approach}}
|
||
**UI集成：** {{ui_integration_approach}}
|
||
- id: compatibility-requirements
|
||
title: 兼容性要求
|
||
template: |
|
||
- **现有API兼容性：** {{api_compatibility}}
|
||
- **数据库模式兼容性：** {{db_compatibility}}
|
||
- **UI/UX一致性：** {{ui_compatibility}}
|
||
- **性能影响：** {{performance_constraints}}
|
||
|
||
- id: tech-stack-alignment
|
||
title: 技术栈对齐
|
||
instruction: |
|
||
确保新组件与现有技术选择保持一致：
|
||
|
||
1. 使用现有技术栈作为基础
|
||
2. 仅在绝对必要时才引入新技术
|
||
3. 用明确的理由证明任何新的添加
|
||
4. 确保与现有依赖项的版本兼容性
|
||
elicit: true
|
||
sections:
|
||
- id: existing-stack
|
||
title: 现有技术栈
|
||
type: table
|
||
columns: [类别, 当前技术, 版本, 在增强中的用途, 说明]
|
||
instruction: 记录必须维护或与之集成的当前技术栈
|
||
- id: new-tech-additions
|
||
title: 新技术添加
|
||
condition: 增强需要新技术
|
||
type: table
|
||
columns: [技术, 版本, 目的, 理由, 集成方法]
|
||
instruction: 仅在增强需要新技术时包括
|
||
|
||
- id: data-models
|
||
title: 数据模型和模式更改
|
||
instruction: |
|
||
定义新的数据模型以及它们如何与现有模式集成：
|
||
|
||
1. 识别增强所需的新实体
|
||
2. 定义与现有数据模型的关系
|
||
3. 规划数据库模式更改（添加、修改）
|
||
4. 确保向后兼容性
|
||
elicit: true
|
||
sections:
|
||
- id: new-models
|
||
title: 新数据模型
|
||
repeatable: true
|
||
sections:
|
||
- id: model
|
||
title: "{{model_name}}"
|
||
template: |
|
||
**目的：** {{model_purpose}}
|
||
**集成：** {{integration_with_existing}}
|
||
|
||
**关键属性：**
|
||
- {{attribute_1}}: {{type_1}} - {{description_1}}
|
||
- {{attribute_2}}: {{type_2}} - {{description_2}}
|
||
|
||
**关系：**
|
||
- **与现有：** {{existing_relationships}}
|
||
- **与新的：** {{new_relationships}}
|
||
- id: schema-integration
|
||
title: 模式集成策略
|
||
template: |
|
||
**所需数据库更改：**
|
||
- **新表：** {{new_tables_list}}
|
||
- **修改的表：** {{modified_tables_list}}
|
||
- **新索引：** {{new_indexes_list}}
|
||
- **迁移策略：** {{migration_approach}}
|
||
|
||
**向后兼容性：**
|
||
- {{compatibility_measure_1}}
|
||
- {{compatibility_measure_2}}
|
||
|
||
- id: component-architecture
|
||
title: 组件架构
|
||
instruction: |
|
||
定义新组件及其与现有架构的集成：
|
||
|
||
1. 识别增强所需的新组件
|
||
2. 定义与现有组件的接口
|
||
3. 建立清晰的边界和职责
|
||
4. 规划集成点和数据流
|
||
|
||
强制验证：在提出组件架构之前，请确认：“我提出的新组件遵循我在您代码库中识别出的现有架构模式：[特定模式]。集成接口尊重您当前的组件结构和通信模式。这是否符合您项目的实际情况？”
|
||
elicit: true
|
||
sections:
|
||
- id: new-components
|
||
title: 新组件
|
||
repeatable: true
|
||
sections:
|
||
- id: component
|
||
title: "{{component_name}}"
|
||
template: |
|
||
**职责：** {{component_description}}
|
||
**集成点：** {{integration_points}}
|
||
|
||
**关键接口：**
|
||
- {{interface_1}}
|
||
- {{interface_2}}
|
||
|
||
**依赖：**
|
||
- **现有组件：** {{existing_dependencies}}
|
||
- **新组件：** {{new_dependencies}}
|
||
|
||
**技术栈：** {{component_tech_details}}
|
||
- id: interaction-diagram
|
||
title: 组件交互图
|
||
type: mermaid
|
||
mermaid_type: graph
|
||
instruction: 创建Mermaid图，显示新组件如何与现有组件交互
|
||
|
||
- id: api-design
|
||
title: API设计和集成
|
||
condition: 增强需要API更改
|
||
instruction: |
|
||
定义新的API端点并与现有API集成：
|
||
|
||
1. 规划增强所需的新的API端点
|
||
2. 确保与现有API模式的一致性
|
||
3. 定义身份验证和授权集成
|
||
4. 如果需要，规划版本控制策略
|
||
elicit: true
|
||
sections:
|
||
- id: api-strategy
|
||
title: API集成策略
|
||
template: |
|
||
**API集成策略：** {{api_integration_strategy}}
|
||
**身份验证：** {{auth_integration}}
|
||
**版本控制：** {{versioning_approach}}
|
||
- id: new-endpoints
|
||
title: 新的API端点
|
||
repeatable: true
|
||
sections:
|
||
- id: endpoint
|
||
title: "{{endpoint_name}}"
|
||
template: |
|
||
- **方法：** {{http_method}}
|
||
- **端点：** {{endpoint_path}}
|
||
- **目的：** {{endpoint_purpose}}
|
||
- **集成：** {{integration_with_existing}}
|
||
sections:
|
||
- id: request
|
||
title: 请求
|
||
type: code
|
||
language: json
|
||
template: "{{request_schema}}"
|
||
- id: response
|
||
title: 响应
|
||
type: code
|
||
language: json
|
||
template: "{{response_schema}}"
|
||
|
||
- id: external-api-integration
|
||
title: 外部API集成
|
||
condition: 增强需要新的外部API
|
||
instruction: 记录增强所需的新外部API集成
|
||
repeatable: true
|
||
sections:
|
||
- id: external-api
|
||
title: "{{api_name}} API"
|
||
template: |
|
||
- **目的：** {{api_purpose}}
|
||
- **文档：** {{api_docs_url}}
|
||
- **基本URL：** {{api_base_url}}
|
||
- **身份验证：** {{auth_method}}
|
||
- **集成方法：** {{integration_approach}}
|
||
|
||
**使用的关键端点：**
|
||
- `{{method}} {{endpoint_path}}` - {{endpoint_purpose}}
|
||
|
||
**错误处理：** {{error_handling_strategy}}
|
||
|
||
- id: source-tree-integration
|
||
title: 源代码树集成
|
||
instruction: |
|
||
定义新代码将如何与现有项目结构集成：
|
||
|
||
1. 遵循现有项目组织模式
|
||
2. 确定新文件/文件夹的放置位置
|
||
3. 确保与现有命名约定的一致性
|
||
4. 规划对现有结构的最小干扰
|
||
elicit: true
|
||
sections:
|
||
- id: existing-structure
|
||
title: 现有项目结构
|
||
type: code
|
||
language: plaintext
|
||
instruction: 记录当前结构的相关部分
|
||
template: "{{existing_structure_relevant_parts}}"
|
||
- id: new-file-organization
|
||
title: 新文件组织
|
||
type: code
|
||
language: plaintext
|
||
instruction: 仅显示对现有结构的新增内容
|
||
template: |
|
||
{{project-root}}/
|
||
├── {{existing_structure_context}}
|
||
│ ├── {{new_folder_1}}/ # {{purpose_1}}
|
||
│ │ ├── {{new_file_1}}
|
||
│ │ └── {{new_file_2}}
|
||
│ ├── {{existing_folder}}/ # 带有新增内容的现有文件夹
|
||
│ │ ├── {{existing_file}} # 现有文件
|
||
│ │ └── {{new_file_3}} # 新增内容
|
||
│ └── {{new_folder_2}}/ # {{purpose_2}}
|
||
- id: integration-guidelines
|
||
title: 集成指南
|
||
template: |
|
||
- **文件命名：** {{file_naming_consistency}}
|
||
- **文件夹组织：** {{folder_organization_approach}}
|
||
- **导入/导出模式：** {{import_export_consistency}}
|
||
|
||
- id: infrastructure-deployment
|
||
title: 基础设施和部署集成
|
||
instruction: |
|
||
定义增强功能将如何与现有基础设施一起部署：
|
||
|
||
1. 使用现有的部署管道和基础设施
|
||
2. 确定任何需要的基础设施更改
|
||
3. 规划部署策略以最小化风险
|
||
4. 定义回滚程序
|
||
elicit: true
|
||
sections:
|
||
- id: existing-infrastructure
|
||
title: 现有基础设施
|
||
template: |
|
||
**当前部署：** {{existing_deployment_summary}}
|
||
**基础设施工具：** {{existing_infrastructure_tools}}
|
||
**环境：** {{existing_environments}}
|
||
- id: enhancement-deployment
|
||
title: 增强部署策略
|
||
template: |
|
||
**部署方法：** {{deployment_approach}}
|
||
**基础设施更改：** {{infrastructure_changes}}
|
||
**管道集成：** {{pipeline_integration}}
|
||
- id: rollback-strategy
|
||
title: 回滚策略
|
||
template: |
|
||
**回滚方法：** {{rollback_method}}
|
||
**风险缓解：** {{risk_mitigation}}
|
||
**监控：** {{monitoring_approach}}
|
||
|
||
- id: coding-standards
|
||
title: 编码标准和约定
|
||
instruction: |
|
||
确保新代码遵循现有项目约定：
|
||
|
||
1. 从项目分析中记录现有编码标准
|
||
2. 确定任何特定于增强功能的要求
|
||
3. 确保与现有代码库模式的一致性
|
||
4. 定义新代码组织的标准
|
||
elicit: true
|
||
sections:
|
||
- id: existing-standards
|
||
title: 现有标准合规性
|
||
template: |
|
||
**代码风格：** {{existing_code_style}}
|
||
**Linting规则：** {{existing_linting}}
|
||
**测试模式：** {{existing_test_patterns}}
|
||
**文档风格：** {{existing_doc_style}}
|
||
- id: enhancement-standards
|
||
title: 特定于增强功能的标准
|
||
condition: 增强需要新模式
|
||
repeatable: true
|
||
template: "- **{{standard_name}}:** {{standard_description}}"
|
||
- id: integration-rules
|
||
title: 关键集成规则
|
||
template: |
|
||
- **现有API兼容性：** {{api_compatibility_rule}}
|
||
- **数据库集成：** {{db_integration_rule}}
|
||
- **错误处理：** {{error_handling_integration}}
|
||
- **日志记录一致性：** {{logging_consistency}}
|
||
|
||
- id: testing-strategy
|
||
title: 测试策略
|
||
instruction: |
|
||
定义增强功能的测试方法：
|
||
|
||
1. 与现有测试套件集成
|
||
2. 确保现有功能保持不变
|
||
3. 规划测试新功能
|
||
4. 定义集成测试方法
|
||
elicit: true
|
||
sections:
|
||
- id: existing-test-integration
|
||
title: 与现有测试集成
|
||
template: |
|
||
**现有测试框架：** {{existing_test_framework}}
|
||
**测试组织：** {{existing_test_organization}}
|
||
**覆盖率要求：** {{existing_coverage_requirements}}
|
||
- id: new-testing
|
||
title: 新的测试要求
|
||
sections:
|
||
- id: unit-tests
|
||
title: 新组件的单元测试
|
||
template: |
|
||
- **框架：** {{test_framework}}
|
||
- **位置：** {{test_location}}
|
||
- **覆盖目标：** {{coverage_target}}
|
||
- **与现有集成：** {{test_integration}}
|
||
- id: integration-tests
|
||
title: 集成测试
|
||
template: |
|
||
- **范围：** {{integration_test_scope}}
|
||
- **现有系统验证：** {{existing_system_verification}}
|
||
- **新功能测试：** {{new_feature_testing}}
|
||
- id: regression-tests
|
||
title: 回归测试
|
||
template: |
|
||
- **现有功能验证：** {{regression_test_approach}}
|
||
- **自动化回归套件：** {{automated_regression}}
|
||
- **手动测试要求：** {{manual_testing_requirements}}
|
||
|
||
- id: security-integration
|
||
title: 安全集成
|
||
instruction: |
|
||
确保与现有系统的安全一致性：
|
||
|
||
1. 遵循现有的安全模式和工具
|
||
2. 确保新功能不引入漏洞
|
||
3. 保持现有的安全态势
|
||
4. 为新组件定义安全测试
|
||
elicit: true
|
||
sections:
|
||
- id: existing-security
|
||
title: 现有安全措施
|
||
template: |
|
||
**身份验证：** {{existing_auth}}
|
||
**授权：** {{existing_authz}}
|
||
**数据保护：** {{existing_data_protection}}
|
||
**安全工具：** {{existing_security_tools}}
|
||
- id: enhancement-security
|
||
title: 增强安全要求
|
||
template: |
|
||
**新安全措施：** {{new_security_measures}}
|
||
**集成点：** {{security_integration_points}}
|
||
**合规要求：** {{compliance_requirements}}
|
||
- id: security-testing
|
||
title: 安全测试
|
||
template: |
|
||
**现有安全测试：** {{existing_security_tests}}
|
||
**新安全测试要求：** {{new_security_tests}}
|
||
**渗透测试：** {{pentest_requirements}}
|
||
|
||
- id: checklist-results
|
||
title: 清单结果报告
|
||
instruction: 执行architect-checklist并在此处填充结果，重点关注特定于棕地的验证
|
||
|
||
- id: next-steps
|
||
title: 下一步
|
||
instruction: |
|
||
完成棕地架构后：
|
||
|
||
1. 审查与现有系统的集成点
|
||
2. 与开发代理一起开始故事实施
|
||
3. 设置部署管道集成
|
||
4. 规划回滚和监控程序
|
||
sections:
|
||
- id: story-manager-handoff
|
||
title: 故事管理员交接
|
||
instruction: |
|
||
为此棕地增强创建一个简短的提示，以便与故事管理员一起工作。包括：
|
||
- 对此架构文档的引用
|
||
- 与用户验证的关键集成要求
|
||
- 基于实际项目分析的现有系统约束
|
||
- 第一个要实施的故事，并带有清晰的集成检查点
|
||
- 强调在整个实施过程中保持现有系统的完整性
|
||
- id: developer-handoff
|
||
title: 开发人员交接
|
||
instruction: |
|
||
为开始实施的开发人员创建一个简短的提示。包括：
|
||
- 对此架构和从实际项目中分析的现有编码标准的引用
|
||
- 与用户验证的与现有代码库的集成要求
|
||
- 基于真实项目约束的关键技术决策
|
||
- 具有特定验证步骤的现有系统兼容性要求
|
||
- 清晰的实施顺序，以最小化对现有功能的风险
|