Implementation Report

---
name: implementation-report
description: 需求完成后生成实现总结报告，记录最终实现效果、关联提交、偏差记录。自动读取 .requirements/config 配置，报告与需求摘要一一对应。适用场景："生成实现报告"、"记录一下完成情况"，或需求开发完成后需归档实现结果时。需求状态变为"已完成"时自动触发，或用户手动要求。
---

# 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/ 文档 |
| 代码文件 | 实际实现 | 读取相关代码文件 |

### 输出格式

```text
📋 实现数据收集

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

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

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

---

## 阶段 2：偏差分析

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

### 偏差类型

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

### 输出格式

```text
🔍 偏差分析

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

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

---

## 阶段 3：生成报告

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

### 报告模板

```markdown
---
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` 注册文档关联并更新状态：

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

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

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

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

### 存储路径映射

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

---

## 反模式

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