# 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: | 为开始实施的开发人员创建一个简短的提示。包括： - 对此架构和从实际项目中分析的现有编码标准的引用 - 与用户验证的与现有代码库的集成要求 - 基于真实项目约束的关键技术决策 - 具有特定验证步骤的现有系统兼容性要求 - 清晰的实施顺序，以最小化对现有功能的风险