Implementation Report（实现报告）

需求开发完成后，自动归档实现结果，形成完整的需求→设计→实现→验收链路。

定位

design-craft → 开发实现 → implementation-report
    技术设计      编码提交       归档实现结果

• 输入：需求 ID、git 提交记录、实际实现情况
• 输出：实现报告文档 + meta.json 状态更新
• 边界：只记录"实现了什么"，不管"怎么实现"（设计文档负责）

核心原则

1. 事实导向：只记录实际发生的事情，不写计划或期望
2. 偏差必录：实现与设计不一致的地方必须记录，不隐瞒
3. 可追溯：每个提交、每个偏差都有对应的设计文档章节引用
4. 自动化优先：尽可能从 git 历史和需求元数据自动提取信息

工作流总览

阶段 1：收集实现数据    → 从 git 历史和需求元数据提取信息
阶段 2：偏差分析        → 对比设计与实现，记录偏差
阶段 3：生成报告        → 输出结构化实现报告
阶段 4：需求管理集成    → 更新 meta.json 状态和文档关联

---

阶段 1：收集实现数据

从多个来源自动提取实现信息。

数据来源

来源	提取内容	提取方式
meta.json	需求元数据（feature、tags、depends_on）	req list --id {REQ-NNN}
git 历史	关联提交的变更内容	git log --oneline {commit_hash}
设计文档	设计方案（用于偏差对比）	读取需求目录下的 design/ 文档
代码文件	实际实现	读取相关代码文件

输出格式

📋 实现数据收集

需求信息：
  ID: REQ-NNN
  功能: {功能名称}
  状态: 实施中
  关联提交: {commit1}, {commit2}

设计文档：
  - design/DESIGN.md（主设计）
  - design/S01_子需求_DESIGN.md

请确认数据是否完整，有无遗漏的提交或文档。

---

阶段 2：偏差分析

对比设计文档与实际实现，记录偏差。

偏差类型

偏差类型	说明	严重度
方案偏差	实现方案与设计不一致	高
范围偏差	实现范围超出或小于设计范围	中
接口偏差	接口签名与设计不一致	高
数据偏差	数据模型与设计不一致	高
遗漏	设计中有但未实现	中
额外实现	设计中无但实际实现了	低

输出格式

🔍 偏差分析

| 编号 | 偏差类型 | 设计描述 | 实际实现 | 严重度 | 原因 |
|------|----------|----------|----------|--------|------|
| D-01 | 方案偏差 | ... | ... | 高 | ... |
| D-02 | 额外实现 | — | ... | 低 | ... |

若无偏差，输出：✅ 实现与设计一致，无偏差。

---

阶段 3：生成报告

将收集的数据和偏差分析合并为结构化报告。

报告模板

---
id: {REQ-NNN}
feature: {功能名称}
status: 已完成
created: {YYYY-MM-DD HH:mm:ss}
updated: {YYYY-MM-DD HH:mm:ss}
version: {N}
tags: [{标签}]
depends_on: [{依赖}]
author: AI
document_type: report
---

# 实现报告：{功能名称}

## 实现摘要

{一句话概述最终实现效果}

## 关联提交

| 提交 Hash | 提交信息 | 关联子需求 |
|-----------|----------|-----------|
| {hash} | {message} | {S-XX} |

## 偏差记录

| 编号 | 偏差类型 | 设计描述 | 实际实现 | 原因 |
|------|----------|----------|----------|------|
| ... | ... | ... | ... | ... |

（若无偏差，写"实现与设计一致，无偏差"）

## 验收结果

- [ ] 功能验证通过
- [ ] 性能指标达标
- [ ] 异常路径覆盖

---

阶段 4：需求管理集成

自动触发条件

项目中存在 .requirements/config 且 storage_path 指向有效目录。

集成步骤

1. 写入实现报告到需求目录后，调用 req update 注册文档关联并更新状态：

req update {REQ-NNN} \
  --docs add report.md,report --status 已完成 --changelog "实现报告归档"

2. 追加关联提交（如果 meta.json 中尚未记录）：

req update {REQ-NNN} \
  --commit {git_hash}

3. 错误处理：
   • 需求 ID 不存在 → 提示用户先创建需求，跳过集成
   • 文件锁超时 → 自动重试 1 次，仍失败则告知用户
   • 状态校验失败 → 提示具体错误，不自动修复

存储路径映射

产出物	存储路径	docs 类型
实现报告	report.md	report

---

反模式

• ❌ 报告只写"已完成"无具体内容 → 必须记录实际实现效果
• ❌ 隐瞒偏差 → 偏差必须如实记录
• ❌ 忘记更新 meta.json 状态 → 必须同步更新为"已完成"
• ❌ 忘记追加 commit → 关联提交必须写入 meta.json