@zeyue0329/xiaoma-cli 1.0.47 → 1.0.49

package/xiaoma-core/templates/incremental-architecture-tmpl.yaml

@@ -0,0 +1,601 @@
+template:
+  id: incremental-architecture-template-v1
+  name: 架构增量设计文档
+  version: 1.0
+  description: 基于知识库和PRD进行架构增量设计，识别技术变动并生成增量架构文档
+  output:
+    format: markdown
+    filename: docs/architecture-increment.md
+    title: "{{project_name}} 架构增量设计文档"
+
+workflow:
+  mode: interactive
+  elicitation: advanced-elicitation
+  upstream:
+    agents:
+      - analyst  # 提供技术知识库
+      - pm       # 提供PRD文档
+    required_files:
+      - docs/prd.md
+      - docs/rag/technical/architecture.md
+    optional_files:
+      - docs/rag/technical/tech-stack.md
+      - docs/rag/technical/data-model.md
+      - docs/rag/technical/module-structure.md
+      - docs/rag/technical/coding-standards/*
+      - docs/rag/technical/middleware/*
+      - docs/rag/constraints/*
+
+sections:
+  - id: input-validation
+    title: 输入验证
+    internal: true
+    instruction: |
+      在开始架构设计之前，执行以下验证：
+
+      1. **检查PRD文档**：
+         - docs/prd.md 或 docs/epic-{name}.md 是否存在
+         - 提取功能需求(FR)、非功能需求(NFR)、数据实体、技术约束
+
+      2. **检查技术知识库**：
+         - docs/rag/technical/architecture.md (现有架构)
+         - docs/rag/technical/data-model.md (现有数据模型)
+         - docs/rag/technical/coding-standards/ (编码规范)
+         - docs/rag/technical/middleware/ (中间件规范)
+
+      3. **加载现有架构信息**：
+         - 架构模式、技术栈、模块结构
+         - 现有数据实体和关系
+         - 编码规范和中间件使用方式
+
+      如果缺少必需文件，提示：
+      "⚠️ 缺少必需的输入文件：
+      - PRD文档：请先执行 PM 智能体 *create-prd-from-rag
+      - 技术知识库：请先执行 Analyst 智能体完善技术知识"
+
+  - id: document-header
+    title: 文档信息
+    sections:
+      - id: meta-info
+        title: 元信息
+        template: |
+          | 属性 | 值 |
+          |------|-----|
+          | 文档版本 | {{version}} |
+          | 生成时间 | {{timestamp}} |
+          | 关联PRD | {{prd_path}} |
+          | 技术知识库版本 | {{rag_version}} |
+          | 架构师 | Architect Agent |
+      - id: changelog
+        title: 变更日志
+        type: table
+        columns: [日期, 版本, 变更内容, 作者]
+
+  - id: existing-architecture-summary
+    title: 现有架构概要
+    instruction: |
+      从技术知识库提取现有架构信息，作为增量设计的基线。
+
+      **来源**：
+      - docs/rag/technical/architecture.md
+      - docs/rag/technical/tech-stack.md
+      - docs/rag/technical/module-structure.md
+    sections:
+      - id: architecture-pattern
+        title: 架构模式
+        instruction: 从 architecture.md 提取架构模式描述
+        template: |
+          **架构类型**: {{architecture_type}}
+          **分层结构**: {{layer_structure}}
+          **关键特征**: {{key_characteristics}}
+      - id: tech-stack-baseline
+        title: 技术栈基线
+        type: table
+        columns: [类别, 技术, 版本, 用途]
+        instruction: 从 tech-stack.md 提取当前技术栈
+      - id: module-structure-baseline
+        title: 模块结构基线
+        instruction: 从 module-structure.md 提取现有模块结构
+        type: code
+        language: plaintext
+      - id: data-model-baseline
+        title: 数据模型基线
+        instruction: |
+          从 data-model.md 提取现有数据实体清单。
+          使用Mermaid ER图展示核心实体关系。
+
+  - id: requirement-extraction
+    title: 需求提取
+    instruction: |
+      从PRD文档提取与架构相关的需求。
+
+      **来源**：
+      - docs/prd.md 或 docs/epic-{name}.md
+    sections:
+      - id: functional-requirements
+        title: 功能性需求摘要
+        type: table
+        columns: [需求ID, 需求描述, 架构影响, 优先级]
+        instruction: |
+          提取PRD中的功能性需求(FR)，评估每个需求的架构影响：
+          - 无影响：完全在现有架构内实现
+          - 小影响：需要新增类/方法
+          - 中影响：需要新增模块/表
+          - 大影响：需要架构调整
+      - id: non-functional-requirements
+        title: 非功能性需求摘要
+        type: table
+        columns: [需求ID, 需求描述, 约束类型, 架构影响]
+        instruction: 提取PRD中的非功能性需求(NFR)，特别关注性能、安全、可用性约束
+      - id: data-requirements
+        title: 数据需求摘要
+        type: table
+        columns: [实体名称, 操作类型, 核心属性, 关联实体]
+        instruction: |
+          从PRD中提取数据实体需求，标注：
+          - 新增：PRD中定义的新实体
+          - 修改：需要变更的现有实体
+          - 复用：直接使用的现有实体
+
+  - id: change-analysis
+    title: 架构变动分析
+    instruction: |
+      对比现有架构与新需求，识别所有技术变动点。
+
+      **分析维度**：
+      1. 架构层面变动
+      2. 技术栈变动
+      3. 数据模型变动
+      4. 接口变动
+      5. 中间件变动
+
+      展示分析结果，请用户确认变动识别是否准确。
+    elicit: true
+    sections:
+      - id: change-overview
+        title: 变动总览
+        template: |
+          | 维度 | 变动等级 | 变动数量 | 主要变动 |
+          |------|----------|----------|----------|
+          | 架构层面 | {{arch_level}} | {{arch_count}} | {{arch_main}} |
+          | 技术栈 | {{tech_level}} | {{tech_count}} | {{tech_main}} |
+          | 数据模型 | {{data_level}} | {{data_count}} | {{data_main}} |
+          | 接口 | {{api_level}} | {{api_count}} | {{api_main}} |
+          | 中间件 | {{mw_level}} | {{mw_count}} | {{mw_main}} |
+
+          **总体变动等级**: {{overall_level}}
+          **风险等级**: {{risk_level}}
+      - id: architecture-changes
+        title: 架构层面变动
+        condition: 存在架构层面变动
+        sections:
+          - id: new-modules
+            title: 新增模块
+            type: table
+            columns: [模块名称, 职责, 所属层, 关联需求]
+          - id: modified-modules
+            title: 修改模块
+            type: table
+            columns: [模块名称, 变更内容, 变更原因, 关联需求]
+      - id: tech-stack-changes
+        title: 技术栈变动
+        condition: 存在技术栈变动
+        sections:
+          - id: new-technologies
+            title: 新增技术
+            type: table
+            columns: [技术名称, 版本, 用途, 引入理由, 替代方案]
+          - id: version-upgrades
+            title: 版本升级
+            type: table
+            columns: [技术名称, 当前版本, 目标版本, 升级原因, 兼容性风险]
+      - id: data-model-changes
+        title: 数据模型变动
+        sections:
+          - id: new-entities
+            title: 新增实体
+            type: table
+            columns: [实体名称, 表名, 核心字段, 关联实体, 关联需求]
+          - id: modified-entities
+            title: 修改实体
+            type: table
+            columns: [实体名称, 变更字段, 变更类型, 兼容性, 关联需求]
+          - id: new-relationships
+            title: 新增关系
+            type: table
+            columns: [源实体, 目标实体, 关系类型, 关联字段, 关联需求]
+      - id: api-changes
+        title: 接口变动
+        condition: 存在接口变动
+        sections:
+          - id: new-apis
+            title: 新增API
+            type: table
+            columns: [接口路径, 方法, 功能描述, 关联需求]
+          - id: modified-apis
+            title: 修改API
+            type: table
+            columns: [接口路径, 变更内容, 兼容性策略, 关联需求]
+      - id: middleware-changes
+        title: 中间件变动
+        condition: 存在中间件变动
+        sections:
+          - id: redis-changes
+            title: Redis变动
+            type: table
+            columns: [Key名称, 数据结构, 用途, 过期策略, 关联需求]
+          - id: mq-changes
+            title: 消息队列变动
+            type: table
+            columns: [Topic/Queue, 消息类型, 生产者, 消费者, 关联需求]
+          - id: scheduler-changes
+            title: 定时任务变动
+            type: table
+            columns: [任务名称, 执行周期, 功能描述, 关联需求]
+
+  - id: incremental-design
+    title: 增量设计详情
+    instruction: |
+      为每个变动点提供详细的增量设计方案。
+      设计必须遵循知识库中的编码规范和中间件使用规范。
+    elicit: true
+    sections:
+      - id: module-design
+        title: 模块增量设计
+        repeatable: true
+        instruction: |
+          为每个新增/修改的模块提供详细设计。
+          包结构必须遵循 docs/rag/technical/module-structure.md 中的规范。
+        sections:
+          - id: module-detail
+            title: "{{module_name}}"
+            template: |
+              **模块类型**: 新增 / 修改
+              **职责描述**: {{responsibility}}
+              **所属层**: {{layer}}
+              **关联需求**: {{related_requirements}}
+            sections:
+              - id: package-structure
+                title: 包结构设计
+                instruction: 遵循现有模块结构规范设计包结构
+                type: code
+                language: plaintext
+              - id: class-design
+                title: 核心类设计
+                instruction: |
+                  列出核心类及其职责，命名遵循编码规范：
+                  - Controller: {Module}Controller
+                  - Service: {Module}Service / {Module}ServiceImpl
+                  - DAO: {Module}Mapper / {Module}Repository
+                type: table
+                columns: [类名, 类型, 职责, 依赖]
+              - id: integration-points
+                title: 集成点
+                instruction: 描述与现有模块的集成方式
+                type: bullet-list
+
+      - id: data-model-design
+        title: 数据模型增量设计
+        repeatable: true
+        instruction: |
+          为每个新增/修改的数据实体提供详细设计。
+          设计必须遵循 docs/rag/technical/sql-standards/ 中的规范。
+        sections:
+          - id: entity-detail
+            title: "{{entity_name}}"
+            template: |
+              **操作类型**: 新增 / 修改
+              **表名**: {{table_name}}
+              **关联需求**: {{related_requirements}}
+            sections:
+              - id: field-design
+                title: 字段设计
+                type: table
+                columns: [字段名, 类型, 长度, 约束, 默认值, 说明]
+                instruction: 字段命名遵循数据库命名规范
+              - id: index-design
+                title: 索引设计
+                type: table
+                columns: [索引名, 类型, 字段, 用途]
+                instruction: 索引命名遵循 idx_{表名}_{字段} 规范
+              - id: ddl-script
+                title: DDL脚本
+                type: code
+                language: sql
+                instruction: |
+                  生成DDL脚本，遵循SQL规范：
+                  - 包含完整的字段定义
+                  - 包含索引创建
+                  - 包含注释
+              - id: migration-script
+                title: 迁移脚本
+                condition: 修改现有表
+                type: code
+                language: sql
+                instruction: 生成安全的迁移脚本，考虑向后兼容性
+
+      - id: api-design
+        title: 接口增量设计
+        repeatable: true
+        condition: 存在接口变动
+        instruction: |
+          为每个新增/修改的API提供详细设计。
+          设计必须遵循现有API规范。
+        sections:
+          - id: api-detail
+            title: "{{api_name}}"
+            template: |
+              **操作类型**: 新增 / 修改
+              **接口路径**: {{api_path}}
+              **请求方法**: {{http_method}}
+              **功能描述**: {{description}}
+              **关联需求**: {{related_requirements}}
+            sections:
+              - id: request-design
+                title: 请求设计
+                sections:
+                  - id: request-params
+                    title: 请求参数
+                    type: table
+                    columns: [参数名, 类型, 必填, 说明, 示例]
+                  - id: request-body
+                    title: 请求体
+                    type: code
+                    language: json
+              - id: response-design
+                title: 响应设计
+                sections:
+                  - id: success-response
+                    title: 成功响应
+                    type: code
+                    language: json
+                  - id: error-codes
+                    title: 错误码
+                    type: table
+                    columns: [错误码, 错误信息, 触发场景]
+              - id: controller-skeleton
+                title: Controller骨架代码
+                type: code
+                language: java
+                instruction: |
+                  生成Controller骨架代码，遵循编码规范：
+                  - 使用正确的注解
+                  - 参数校验
+                  - 统一响应格式
+
+      - id: middleware-design
+        title: 中间件增量设计
+        condition: 存在中间件变动
+        instruction: |
+          为中间件使用提供详细设计。
+          必须参考 docs/rag/technical/middleware/ 中的规范和代码示例。
+        sections:
+          - id: redis-design
+            title: Redis设计
+            condition: 存在Redis变动
+            repeatable: true
+            sections:
+              - id: redis-detail
+                title: "{{redis_key_name}}"
+                template: |
+                  **Key模式**: {{key_pattern}}
+                  **数据结构**: {{data_structure}}
+                  **用途**: {{purpose}}
+                  **过期策略**: {{expiration}}
+                  **关联需求**: {{related_requirements}}
+                sections:
+                  - id: redis-code-example
+                    title: 代码示例
+                    type: code
+                    language: java
+                    instruction: 参考 docs/rag/technical/middleware/redis.md 中的代码示例
+          - id: mq-design
+            title: 消息队列设计
+            condition: 存在MQ变动
+            repeatable: true
+            sections:
+              - id: mq-detail
+                title: "{{topic_name}}"
+                template: |
+                  **Topic/Queue**: {{topic_queue}}
+                  **消息类型**: {{message_type}}
+                  **生产者**: {{producer}}
+                  **消费者**: {{consumer}}
+                  **关联需求**: {{related_requirements}}
+                sections:
+                  - id: message-schema
+                    title: 消息格式
+                    type: code
+                    language: json
+                  - id: producer-code
+                    title: 生产者代码示例
+                    type: code
+                    language: java
+                    instruction: 参考 docs/rag/technical/middleware/mq.md 中的代码示例
+                  - id: consumer-code
+                    title: 消费者代码示例
+                    type: code
+                    language: java
+          - id: scheduler-design
+            title: 定时任务设计
+            condition: 存在定时任务变动
+            repeatable: true
+            sections:
+              - id: scheduler-detail
+                title: "{{task_name}}"
+                template: |
+                  **任务名称**: {{task_name}}
+                  **执行周期**: {{cron_expression}}
+                  **功能描述**: {{description}}
+                  **关联需求**: {{related_requirements}}
+                sections:
+                  - id: scheduler-code
+                    title: 任务代码示例
+                    type: code
+                    language: java
+                    instruction: 参考 docs/rag/technical/middleware/scheduler.md 中的代码示例
+
+  - id: impact-assessment
+    title: 影响评估
+    instruction: 评估架构变动的影响范围和风险
+    elicit: true
+    sections:
+      - id: code-impact
+        title: 代码影响
+        template: |
+          **新增代码量估算**: {{new_code_estimate}}
+          **修改代码范围**: {{modified_code_scope}}
+          **测试代码需求**: {{test_code_requirement}}
+      - id: data-impact
+        title: 数据影响
+        template: |
+          **数据迁移需求**: {{migration_requirement}}
+          **数据一致性风险**: {{consistency_risk}}
+          **备份恢复策略**: {{backup_strategy}}
+      - id: performance-impact
+        title: 性能影响
+        template: |
+          **新增负载评估**: {{load_estimate}}
+          **资源需求变化**: {{resource_change}}
+          **性能测试要求**: {{performance_test_requirement}}
+      - id: deployment-impact
+        title: 部署影响
+        template: |
+          **部署步骤变更**: {{deployment_change}}
+          **配置变更**: {{config_change}}
+          **回滚方案**: {{rollback_plan}}
+
+  - id: risk-analysis
+    title: 风险分析
+    sections:
+      - id: risk-list
+        title: 风险清单
+        type: table
+        columns: [风险ID, 风险类型, 风险描述, 可能性, 影响, 缓解措施]
+        instruction: |
+          识别所有风险，类型包括：
+          - 技术风险：新技术引入、兼容性、性能
+          - 业务风险：功能影响、数据安全、服务可用性
+          - 实施风险：复杂度、技能匹配、时间约束
+      - id: critical-risks
+        title: 关键风险详述
+        instruction: 对高风险项提供详细分析和缓解方案
+        repeatable: true
+        template: |
+          ### {{risk_name}}
+
+          **风险描述**: {{description}}
+          **可能性**: {{probability}}
+          **影响程度**: {{impact}}
+
+          **根因分析**: {{root_cause}}
+
+          **缓解措施**:
+          {{mitigation_measures}}
+
+          **应急预案**:
+          {{contingency_plan}}
+
+          **监控指标**:
+          {{monitoring_metrics}}
+
+  - id: implementation-guide
+    title: 实施指南
+    sections:
+      - id: implementation-sequence
+        title: 实施顺序
+        instruction: |
+          基于依赖关系，规划实施顺序。
+          每个阶段对应PRD中的Epic/Story。
+        type: numbered-list
+        template: |
+          1. **阶段1: {{phase1_name}}**
+             - Story: {{story_refs}}
+             - 前置条件: {{prerequisites}}
+             - 产出物: {{deliverables}}
+             - 检查点: {{checkpoints}}
+      - id: dependency-diagram
+        title: 依赖关系图
+        type: mermaid
+        mermaid_type: graph
+        instruction: 使用Mermaid图展示实施依赖关系
+      - id: checkpoints
+        title: 关键检查点
+        type: table
+        columns: [检查点, 阶段, 验证内容, 负责人]
+
+  - id: knowledge-references
+    title: 知识引用索引
+    instruction: 列出设计中引用的所有知识库文档
+    sections:
+      - id: architecture-refs
+        title: 架构知识引用
+        type: table
+        columns: [文件路径, 引用章节, 引用内容]
+      - id: coding-standard-refs
+        title: 编码规范引用
+        type: table
+        columns: [文件路径, 引用规范, 应用位置]
+      - id: middleware-refs
+        title: 中间件规范引用
+        type: table
+        columns: [文件路径, 引用示例, 应用位置]
+
+  - id: next-steps
+    title: 后续步骤
+    sections:
+      - id: developer-handoff
+        title: 开发者交接
+        instruction: |
+          生成给开发者的交接提示，包含：
+          - 需要阅读的文档清单
+          - 编码规范要点
+          - 实施注意事项
+        template: |
+          **交接给开发者**
+
+          请基于本架构增量设计文档进行开发：
+
+          **必读文档**：
+          - 架构增量设计: docs/architecture-increment.md
+          - PRD文档: {{prd_path}}
+          - 编码规范: docs/rag/technical/coding-standards/
+
+          **开发重点**：
+          - 变动模块: {{changed_modules}}
+          - 数据模型变更: {{data_changes}}
+          - 接口变更: {{api_changes}}
+
+          **注意事项**：
+          - 严格遵循编码规范
+          - 参考中间件代码示例
+          - 每个Story完成后进行集成验证
+
+          **执行命令**: *start-development docs/architecture-increment.md
+      - id: qa-handoff
+        title: QA交接
+        instruction: |
+          生成给QA的交接提示，包含：
+          - 测试范围
+          - 重点测试项
+          - 回归测试要求
+        template: |
+          **交接给QA**
+
+          请基于本架构增量设计制定测试计划：
+
+          **必读文档**：
+          - 架构增量设计: docs/architecture-increment.md (影响评估章节)
+          - PRD文档: {{prd_path}} (验收标准)
+
+          **测试范围**：
+          - 新增功能: {{new_features}}
+          - 修改功能: {{modified_features}}
+          - 回归范围: {{regression_scope}}
+
+          **重点关注**：
+          - 数据迁移验证
+          - 接口兼容性测试
+          - 性能影响验证
+
+          **执行命令**: *create-test-plan docs/architecture-increment.md