@zeyue0329/xiaoma-cli 1.0.48 → 1.0.49

package/xiaoma-core/tasks/create-incremental-architecture.md

@@ -0,0 +1,525 @@
+# 基于知识库的架构增量设计任务
+
+## Purpose
+
+基于 Analyst 智能体的技术知识库产出（`docs/rag/technical/`）和 PM 智能体生成的 PRD/Epic 文档，进行架构增量设计。通过对比现有技术架构与新需求，识别技术变动点，生成架构增量设计文档。
+
+## 上游交接物
+
+```yaml
+必需输入:
+  PRD/Epic文档:
+    - docs/prd.md                       # PM生成的PRD文档
+    - 或 docs/epic-{name}.md            # PM生成的Epic文档
+
+  技术知识库:
+    - docs/rag/technical/architecture.md       # 现有技术架构
+    - docs/rag/technical/tech-stack.md         # 技术栈详情
+    - docs/rag/technical/module-structure.md   # 模块结构
+    - docs/rag/technical/data-model.md         # 数据模型
+
+可选输入:
+  分析报告:
+    - docs/rag/_analysis-report.md      # 需求分析报告（技术分析章节）
+
+  编码规范:
+    - docs/rag/technical/coding-standards/    # 编码规范目录
+    - docs/rag/technical/middleware/          # 中间件规范目录
+
+  约束条件:
+    - docs/rag/constraints/security.md        # 安全要求
+    - docs/rag/constraints/performance.md     # 性能要求
+```
+
+## Workflow Overview
+
+```
+技术知识库 + PRD → 架构差异分析 → 变动点识别 → 增量设计 → 影响评估 → 架构增量文档
+```
+
+---
+
+## Phase 1: 输入验证与上下文加载
+
+### 1.1 验证上游交接物
+
+```yaml
+执行步骤:
+  步骤1_检查PRD文档:
+    动作: 检查 docs/prd.md 或 docs/epic-{name}.md 是否存在
+    缺失处理: |
+      如果缺失PRD文档，提示用户：
+      "未找到PRD文档。请先执行 PM 智能体的 *create-prd-from-rag 命令生成PRD。"
+
+  步骤2_检查技术知识库:
+    动作: 检查 docs/rag/technical/ 目录是否存在核心文件
+    核心文件:
+      - architecture.md (现有架构)
+      - data-model.md (数据模型)
+    缺失处理: |
+      如果技术知识库不完整，提示用户：
+      "技术知识库不完整。建议先执行 Analyst 智能体完善技术知识：
+      - 缺少 architecture.md：需要补充整体技术架构信息
+      - 缺少 data-model.md：需要补充现有数据模型信息"
+
+  步骤3_加载现有架构:
+    动作: 读取并解析技术知识库
+    提取内容:
+      - 整体架构模式（单体/微服务/DDD等）
+      - 技术栈详情（框架、数据库、中间件）
+      - 模块结构（包结构、分层规范）
+      - 现有数据模型（表结构、实体关系）
+      - 编码规范（命名、注释、异常处理）
+      - 中间件使用方式（Redis、MQ、ES等）
+
+  步骤4_加载PRD需求:
+    动作: 读取并解析PRD文档
+    提取内容:
+      - 功能性需求（FR列表）
+      - 非功能性需求（NFR列表）
+      - 数据实体与关系
+      - 技术约束
+      - Epic/Story结构
+```
+
+### 1.2 上下文整合视图
+
+```yaml
+整合输出:
+  现有架构视图:
+    架构模式: {从architecture.md提取}
+    技术栈:
+      后端: {框架、版本}
+      数据库: {类型、版本}
+      缓存: {类型、用途}
+      消息队列: {类型、用途}
+    模块结构: {包结构、分层}
+    数据模型: {现有实体、关系}
+
+  新需求视图:
+    功能需求: {FR列表}
+    数据需求: {新增/修改实体}
+    性能需求: {NFR中的性能要求}
+    安全需求: {NFR中的安全要求}
+```
+
+---
+
+## Phase 2: 架构差异分析
+
+### 2.1 技术变动检测
+
+```yaml
+检测维度:
+  架构层面变动:
+    检测项:
+      - 是否需要新增模块/服务
+      - 是否需要调整分层结构
+      - 是否需要引入新的架构模式
+    判定标准:
+      无变动: 完全遵循现有模块结构
+      小变动: 在现有模块内新增包/类
+      中变动: 新增独立模块
+      大变动: 需要调整整体架构
+
+  技术栈变动:
+    检测项:
+      - 是否需要引入新框架/库
+      - 是否需要升级现有依赖版本
+      - 是否需要新增中间件
+    判定标准:
+      无变动: 使用现有技术栈
+      小变动: 新增工具类库
+      中变动: 引入新中间件
+      大变动: 核心框架变更
+
+  数据模型变动:
+    检测项:
+      - 新增数据实体
+      - 修改现有实体（字段增减）
+      - 新增实体关系
+      - 索引变更
+    判定标准:
+      无变动: 完全使用现有表结构
+      小变动: 现有表新增字段
+      中变动: 新增表/修改关联关系
+      大变动: 数据模型重构
+
+  接口变动:
+    检测项:
+      - 新增API端点
+      - 修改现有API
+      - 新增外部系统集成
+    判定标准:
+      无变动: 无接口变更
+      小变动: 新增内部API
+      中变动: 修改公开API/新增集成
+      大变动: API版本升级
+
+  中间件变动:
+    检测项:
+      - Redis使用变化（新增key类型、缓存策略）
+      - MQ使用变化（新增Topic/Queue）
+      - 定时任务变化
+      - ES索引变化
+    判定标准:
+      无变动: 遵循现有使用方式
+      小变动: 新增使用场景
+      中变动: 新增配置/调整策略
+      大变动: 中间件架构调整
+```
+
+### 2.2 变动分析报告
+
+```yaml
+分析输出格式:
+  变动总览:
+    总体变动等级: 无/小/中/大
+    主要变动领域: [列表]
+    风险等级: 低/中/高
+
+  详细变动清单:
+    - 变动ID: CHG-001
+      领域: 数据模型
+      类型: 新增
+      描述: 新增订单实体
+      影响范围: order模块
+      关联需求: FR1, FR2
+      风险等级: 低
+
+  兼容性分析:
+    向后兼容: 是/否
+    需要迁移: 是/否
+    影响范围: [受影响的模块/服务]
+```
+
+---
+
+## Phase 3: 架构增量设计
+
+### 3.1 设计原则
+
+```yaml
+设计原则:
+  最小变动原则:
+    - 优先在现有架构内扩展
+    - 避免不必要的重构
+    - 保持与现有代码风格一致
+
+  渐进演进原则:
+    - 设计可分阶段实施的方案
+    - 支持增量部署和回滚
+    - 考虑向后兼容性
+
+  知识复用原则:
+    - 复用知识库中的编码规范
+    - 遵循现有中间件使用模式
+    - 参考已有代码示例
+```
+
+### 3.2 增量设计内容
+
+```yaml
+设计内容:
+  模块增量设计:
+    新增模块:
+      - 模块名称
+      - 职责描述
+      - 包结构（遵循现有规范）
+      - 与现有模块的关系
+    修改模块:
+      - 模块名称
+      - 修改内容
+      - 修改理由
+      - 影响评估
+
+  数据模型增量设计:
+    新增实体:
+      - 实体名称
+      - 表名（遵循命名规范）
+      - 字段定义（遵循字段规范）
+      - 索引设计
+      - DDL语句
+    修改实体:
+      - 实体名称
+      - 修改字段
+      - 迁移脚本
+      - 兼容性说明
+
+  接口增量设计:
+    新增API:
+      - 接口路径（遵循URL规范）
+      - 请求方法
+      - 请求参数（遵循参数规范）
+      - 响应格式（遵循响应规范）
+      - 错误码定义
+    修改API:
+      - 接口路径
+      - 变更内容
+      - 版本策略
+      - 兼容性说明
+
+  中间件增量设计:
+    Redis:
+      - 新增Key定义（遵循Key命名规范）
+      - 数据结构选择
+      - 过期策略
+      - 代码示例（参考知识库）
+    MQ:
+      - 新增Topic/Queue
+      - 消息格式
+      - 消费者配置
+      - 代码示例（参考知识库）
+    定时任务:
+      - 任务名称
+      - 执行周期
+      - 实现方式
+      - 代码示例（参考知识库）
+```
+
+### 3.3 知识库规范引用
+
+```yaml
+规范引用:
+  编码规范引用:
+    来源: docs/rag/technical/coding-standards/
+    引用内容:
+      - 命名规范 → 类/方法/变量命名
+      - 分层规范 → Controller/Service/DAO实现
+      - 异常处理 → 错误处理方式
+      - 日志规范 → 日志打印方式
+
+  中间件规范引用:
+    来源: docs/rag/technical/middleware/
+    引用内容:
+      - Redis规范 → 缓存实现参考
+      - MQ规范 → 消息处理参考
+      - 定时任务规范 → 任务实现参考
+
+  SQL规范引用:
+    来源: docs/rag/technical/sql-standards/
+    引用内容:
+      - 表设计规范 → DDL编写
+      - 查询规范 → SQL编写
+      - 性能规范 → 索引设计
+```
+
+---
+
+## Phase 4: 影响评估与风险分析
+
+### 4.1 影响评估
+
+```yaml
+评估维度:
+  代码影响:
+    - 新增代码量估算
+    - 修改代码范围
+    - 测试代码需求
+
+  数据影响:
+    - 数据迁移需求
+    - 数据一致性风险
+    - 备份恢复策略
+
+  性能影响:
+    - 新增负载评估
+    - 资源需求变化
+    - 性能测试要求
+
+  部署影响:
+    - 部署步骤变更
+    - 配置变更
+    - 回滚方案
+```
+
+### 4.2 风险分析
+
+```yaml
+风险分析:
+  技术风险:
+    - 新技术引入风险
+    - 兼容性风险
+    - 性能风险
+
+  业务风险:
+    - 功能影响范围
+    - 数据安全风险
+    - 服务可用性风险
+
+  实施风险:
+    - 实施复杂度
+    - 团队技能匹配
+    - 时间约束
+
+  缓解措施:
+    - 每个风险的缓解方案
+    - 监控和告警策略
+    - 应急预案
+```
+
+---
+
+## Phase 5: 输出架构增量文档
+
+### 5.1 文档结构
+
+```yaml
+文档结构:
+  元信息:
+    - 文档版本
+    - 生成时间
+    - 关联PRD
+    - 关联知识库版本
+
+  变动总览:
+    - 变动等级
+    - 主要变动领域
+    - 风险等级
+
+  详细设计:
+    - 模块增量设计
+    - 数据模型增量设计
+    - 接口增量设计
+    - 中间件增量设计
+
+  实施指南:
+    - 实施顺序
+    - 依赖关系
+    - 检查点
+
+  知识引用:
+    - 引用的规范文档
+    - 代码示例来源
+
+  下游交接:
+    - 开发者交接
+    - QA交接
+```
+
+### 5.2 输出文件
+
+```yaml
+主输出:
+  架构增量文档:
+    路径: docs/architecture-increment.md
+    格式: Markdown
+
+辅助输出:
+  变动清单:
+    路径: docs/architecture-changes.yaml
+    格式: YAML
+    内容: 结构化的变动清单，便于追踪
+
+  DDL脚本:
+    路径: docs/ddl/
+    格式: SQL
+    内容: 数据库变更脚本
+
+  知识引用索引:
+    路径: docs/architecture-knowledge-refs.md
+    内容: 设计中引用的知识库文档清单
+```
+
+---
+
+## Phase 6: 下游交接
+
+### 6.1 交接给开发者
+
+```yaml
+开发者交接:
+  必读文件:
+    - docs/architecture-increment.md    # 架构增量设计
+    - docs/prd.md                       # PRD文档
+    - docs/rag/technical/coding-standards/  # 编码规范
+
+  关注点:
+    - 新增模块的包结构
+    - 数据模型变更
+    - 中间件使用方式（含代码示例）
+    - 接口设计规范
+
+  建议命令: "*start-development docs/architecture-increment.md"
+```
+
+### 6.2 交接给QA
+
+```yaml
+QA交接:
+  必读文件:
+    - docs/architecture-increment.md    # 架构增量设计（测试策略章节）
+    - docs/prd.md                       # PRD文档（验收标准）
+
+  关注点:
+    - 功能测试范围
+    - 集成测试要求
+    - 回归测试范围
+    - 性能测试要求
+
+  建议命令: "*create-test-plan docs/architecture-increment.md"
+```
+
+---
+
+## 使用说明
+
+### 激活命令
+
+```
+*create-incremental-architecture [prd_path] [rag_path]
+```
+
+### 执行参数
+
+```yaml
+参数:
+  prd_path: PRD文档路径 (默认: docs/prd.md)
+  rag_path: RAG知识目录路径 (默认: docs/rag/)
+  output_path: 输出路径 (默认: docs/architecture-increment.md)
+  interactive: 交互模式 (默认: true)
+```
+
+### 交互模式流程
+
+1. **验证阶段**: 检查上游交接物完整性
+2. **分析阶段**: 展示架构差异分析结果，确认变动点
+3. **设计阶段**: 逐模块进行增量设计，关键节点请求确认
+4. **评估阶段**: 展示影响评估和风险分析
+5. **输出阶段**: 生成架构增量文档，提示下游交接
+
+### YOLO模式
+
+通过 `*yolo` 命令切换YOLO模式，一次性完成所有步骤，跳过中间确认环节。
+
+---
+
+## 任务完成标志
+
+```yaml
+完成条件:
+  必要输出:
+    - docs/architecture-increment.md
+
+  完成提示: |
+    ✅ 架构增量设计完成！
+
+    📄 输出文件: docs/architecture-increment.md
+    📊 变动等级: {change_level}
+    ⚠️ 风险等级: {risk_level}
+
+    📋 变动摘要:
+    - 模块变动: {module_changes}
+    - 数据模型变动: {data_model_changes}
+    - 接口变动: {api_changes}
+    - 中间件变动: {middleware_changes}
+
+    🔄 下一步建议:
+    - 开发实施: *start-development docs/architecture-increment.md
+    - 测试计划: *create-test-plan docs/architecture-increment.md
+
+    💡 请在开发前确认架构设计，特别关注:
+    - 风险清单中的高风险项
+    - 数据迁移方案
+    - 回滚策略
+```