feat: 根目录文档、脚本、gitignore

2026-10-08 16:15:33 +08:00
commit e98660ce4e
284 changed files with 26838 additions and 0 deletions
@@ -0,0 +1,71 @@
+# DAR 模板（缺陷分析报告）
+
+> 使用说明：按 8D/根因分析思路组织，所有结论需引用证据。
+
+## 0. 文档信息
+- 缺陷编号/版本/作者/日期/状态
+
+## 1. 缺陷概述
+- 问题描述（简要）
+- 影响范围（用户/业务/系统）
+- 严重级别与优先级
+
+## 2. 复现信息
+- 复现步骤
+- 期望结果 vs 实际结果
+- 环境信息（版本/设备/网络/账号）
+- 相关日志/截图/接口请求
+
+## 3. 时间线
+- 首次发现时间
+- 影响窗口
+- 处置时间线
+
+## 4. 临时遏制措施（Containment）
+- 当前止损方案
+- 影响控制范围
+
+## 5. 根因分析
+- 直接原因
+- 根本原因（5 Whys/鱼骨图）
+- 触发条件与边界
+
+## 6. 纠正措施（Corrective Action）
+- 修复方案
+- 影响评估
+- 回归验证要点
+
+## 7. 效果验证
+- 验证方式与结果
+- 监控/指标变化
+
+## 8. 预防措施与改进
+- 预防机制（监控、测试、流程）
+- 长期改进计划
+
+## 9. 经验总结
+- 经验教训
+- 可复用的规则/检查项
+
+## 10. 证据与引用
+- 引用 `materials_index.md`
+- 引用 `CODEMAP/DOMAINMAP/RUNTIME` 证据
+
+## 11. 证据映射表（强制）
+| 章节 | 关键结论 | 证据 |
+|---|---|---|
+| 复现信息 | | |
+| 根因分析 | | |
+| 纠正措施 | | |
+| 效果验证 | | |
+
+## 12. 系统资产引用（强制）
+| 资产类型 | 路径 | 用途 |
+|---|---|---|
+| CodeMap | | |
+| DomainMap | | |
+| Runtime | | |
+
+## 图表要求（强制）
+- 至少 1 个 mermaid 图（流程图/时序图/状态图任选其一）
+- 至少 1 张表（缺陷时间线/影响范围/根因列表等）
@@ -0,0 +1,80 @@
+# FRD 模板（参考）
+
+> 使用说明：聚焦“可实现的功能规格”。需求条目建议编号并采用明确语句（例如：WHEN/IF 条件下系统 SHALL 做什么）。
+
+## 0. 文档信息
+- 版本/作者/日期/状态
+- 适用范围
+
+## 1. 引言
+- 目的
+- 范围
+- 术语与缩写
+- 参考资料（引用 `materials_index.md`）
+
+## 2. 总体描述
+- 产品视角（系统边界、上下游）
+- 功能概览
+- 用户特征
+- 约束条件
+- 假设与依赖
+
+## 3. 功能需求（核心）
+> 建议使用编号与模板化语句。
+
+### 3.x 功能需求列表（示例格式）
+- ID: FR-001
+  - 场景/触发条件：WHEN/IF ...
+  - 需求：系统 SHALL ...
+  - 业务规则/边界条件
+  - 优先级
+  - 依据/来源（引用）
+  - 验收标准
+
+## 4. 外部接口需求
+- 用户界面（页面/交互/输入输出）
+- 硬件接口
+- 软件接口/第三方接口
+- 通信接口/协议
+
+## 5. 数据需求
+- 数据实体/字段定义
+- 数据校验与规则
+- 存储与迁移要求
+
+## 6. 非功能需求
+- 性能（响应时间、吞吐、并发）
+- 安全（权限、审计、隐私）
+- 可靠性/可用性
+- 可维护性/可扩展性
+
+## 7. 追踪与验收
+- 需求追踪矩阵（需求 ↔ 设计 ↔ 测试）
+- 验收用例清单
+
+## 8. 风险与开放问题
+- 风险清单与应对
+- 待澄清问题（指向 questions 文件）
+
+## 9. 参考资料与索引
+- 引用 `materials_index.md`
+- 引用 `CODEMAP/DOMAINMAP/RUNTIME` 证据
+
+## 10. 证据映射表（强制）
+| 章节 | 关键结论 | 证据 |
+|---|---|---|
+| 功能需求 | | |
+| 接口需求 | | |
+| 数据需求 | | |
+| 非功能需求 | | |
+
+## 11. 系统资产引用（强制）
+| 资产类型 | 路径 | 用途 |
+|---|---|---|
+| CodeMap | | |
+| DomainMap | | |
+| Runtime | | |
+
+## 图表要求（强制）
+- 至少 1 个 mermaid 图（流程图/时序图/状态图任选其一）
+- 至少 1 张表（需求条目清单/接口列表/字段定义等）
@@ -0,0 +1,109 @@
+# PRD 模板（参考）
+
+> 使用说明：按需裁剪，保留证据标注。所有关键结论需引用 `materials_index.md` 中的来源 ID。
+
+## 0. 文档信息
+- 版本/作者/日期/状态
+- 适用范围
+
+## 1. 业务背景
+- 现状与痛点（含数据或事实证据）
+- 业务目标与问题陈述
+- 相关历史决策（可链接 `decision_log.md`）
+
+## 2. 目标与成功指标
+- 业务目标（可量化）
+- 成功指标（KPI/北极星指标）
+- 约束条件与边界
+
+## 3. 用户与场景
+- 目标用户/角色
+- 关键使用场景/用户故事
+- 价值链路/利益相关方
+
+## 4. 需求范围
+- 范围内（In Scope）
+- 范围外（Out of Scope）
+- 假设与依赖
+
+## 5. 整体方案介绍
+- 方案概述
+- 核心机制/策略（示例：双轨机制）
+- 结算/计费/策略规则
+- 字段新增/调整
+- 方案对比与取舍
+
+## 6. 需求内容（按端/渠道/角色/场景/模块拆解）
+
+### 6.1 端/渠道覆盖矩阵（强制）
+| 端/渠道 | 是否覆盖 | 核心差异点 | 证据 |
+|---|---|---|---|
+| 管理端 | | | |
+| 商户平台 | | | |
+| 合伙人平台 | | | |
+| 小程序/H5 | | | |
+| 其他端 | | | |
+
+### 6.2 角色/场景/模块拆解
+- 角色视角（如：管理员/商户/司机/运营）
+- 场景视角（如：下单/履约/结算/售后）
+- 模块视角（如：订单/计费/权限/配置）
+
+> 每个端内建议包含：
+- 业务流程
+- 关键页面/交互
+- 规则与校验
+- 接口/数据
+
+## 7. 数据与埋点
+- 数据口径与字段定义
+- 统计/埋点需求
+- 指标计算方式
+- 导出/对账口径（页面字段、导出字段、对账字段的一致性与差异）
+
+## 8. 差异点清单（强制）
+> 记录“现状 vs 目标”的差异，避免只写方案不写差异。
+
+| 维度 | 现状 | 目标 | 影响范围 | 证据 |
+|---|---|---|---|---|
+| 策略差异 | | | | |
+| 口径差异 | | | | |
+| UI/交互差异 | | | | |
+
+## 9. 风险确认与应对
+- 风险清单（合规/业务/技术/体验）
+- 风险等级与应对措施
+- 回滚/灰度策略
+
+## 10. 里程碑与发布计划
+- 阶段目标
+- 里程碑与交付物
+- 上线策略与验收标准
+
+## 11. 其他需求 / 备注
+- 会议过程与重要结论（可简述）
+- 需后续决策事项
+
+## 12. 证据映射表（强制）
+| 章节 | 关键结论 | 证据 |
+|---|---|---|
+| 业务背景 | | |
+| 方案介绍 | | |
+| 需求内容 | | |
+| 数据与口径 | | |
+| 风险 | | |
+
+## 13. 系统资产引用（强制）
+| 资产类型 | 路径 | 用途 |
+|---|---|---|
+| CodeMap | | |
+| DomainMap | | |
+| Runtime | | |
+
+## 14. 参考资料与索引
+- 引用 `materials_index.md` 的来源 ID
+- 必要时补充 `CODEMAP/DOMAINMAP/RUNTIME` 引用
+
+## 图表要求（强制）
+- 至少 1 个 mermaid 图（流程图/时序图/状态图任选其一）
+- 至少 1 张表（范围清单/风险列表/需求拆解等）
@@ -0,0 +1,66 @@
+# 原型覆盖度对照表
+
+> 使用说明：在 Proto Round 3 阶段生成此文件到 {workdir}/prototypes/prototype_coverage.md
+
+## 文档章节 vs 原型文件
+
+| PRD/FRD 章节 | 关键场景 | 原型文件 | 覆盖度 | 备注 |
+|---|---|---|---|---|
+| _示例: 6.1 商户端计费展示_ | _双轨里程对比_ | `screenshots/v1-merchant-billing.png` | ✅ 完整 | _- 已包含所有关键元素_ |
+| _示例: 6.2 司机端结算_ | _最短路线支付_ | `webapp/index.html#driver-settlement` | ✅ 完整 | _可点击交互_ |
+| _示例: 6.3 差异告警_ | _超限 fallback_ | `screenshots/v1-alert-dialog.png` | ⚠️ 部分 | _仅静态截图，未实现交互_ |
+| _示例: 6.4 配置开关_ | _商户启用双轨_ | - | ❌ 缺失 | _待补充_ |
+
+**覆盖度图例**：
+- ✅ 完整：原型完整展示该场景的关键信息和交互
+- ⚠️ 部分：原型仅覆盖部分元素或缺少交互
+- ❌ 缺失：该场景尚无对应原型
+
+## 原型文件清单
+
+| 文件路径 | 类型 | 用途 | 状态 |
+|---|---|---|---|
+| `prototypes/design.pen` | Pencil | 整体视觉稿 | ✅ 完成 |
+| `prototypes/screenshots/v1-merchant-billing.png` | 截图 | 商户端计费页 | ✅ 完成 |
+| `prototypes/screenshots/v1-alert-dialog.png` | 截图 | 差异告警弹窗 | ✅ 完成 |
+| `prototypes/webapp/index.html` | HTML | 交互原型（司机端） | ✅ 完成 |
+| `prototypes/webapp/merchant.html` | HTML | 交互原型（商户端） | 🔄 进行中 |
+
+**状态图例**：
+- ✅ 完成：已完成并归档
+- 🔄 进行中：正在制作
+- ⏸️ 暂停：等待反馈或资源
+- ❌ 废弃：不再需要
+
+## 待补充原型
+
+按优先级排序：
+
+- [ ] **P0**: 6.4 配置开关（商户后台页面） - 影响商户端功能演示
+- [ ] **P1**: 7.2 埋点示意（数据看板截图） - 需要展示数据监控界面
+- [ ] **P2**: 附录流程图可视化（Mermaid 图转 UI） - 可选增强
+
+## 反馈记录
+
+### Proto Feedback Round 1 (2026-02-09)
+- **用户反馈**: 商户端计费页的双轨里程对比不够明显
+- **调整方案**: 增加对比高亮样式，使用差异色块标注
+- **状态**: ✅ 已修复 → `screenshots/v2-merchant-billing.png`
+
+### Proto Feedback Round 2 (待补充)
+- **用户反馈**:
+- **调整方案**:
+- **状态**:
+
+## 原型验收标准
+
+- [x] 所有 P0/P1 章节均有对应原型（覆盖度 ≥ 80%）
+- [x] 关键交互路径可演示（至少 1 个可点击的 Web Artifact）
+- [ ] 视觉风格符合品牌/行业规范
+- [ ] 技术栈与实际开发可对齐
+- [x] 截图已归档到文档中（PRD/FRD 证据映射表中已引用）
+
+---
+
+**最后更新**: 2026-02-09
+**原型状态**: proto_in_progress → proto_complete（待验收通过后更新）
@@ -0,0 +1,262 @@
+# 会话状态报告模板
+
+> 用于会话恢复时自动生成状态报告。Claude 读取相关文件后填充此模板。
+
+## 基础信息
+
+```markdown
+📊 会话状态报告
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📁 工作目录：{workdir}
+📄 文档类型：{doc_type}  # PRD / FRD / DAR
+📌 项目简称：{project_alias}
+📋 文档标题：{document_title}
+🔢 当前 Round：{current_round}
+📊 会话状态：{session_status}  # in_progress / pending_review / finalized
+
+📝 已完成内容：
+   - 章节：{completed_chapters}/{total_chapters}
+   - 证据映射：{evidence_count} 条
+   - Mermaid 图：{mermaid_count} 个
+   - 表格：{table_count} 个
+
+❓ 遗留问题：
+   - P0（阻塞）：{p0_count} 个
+   - P1（关键）：{p1_count} 个
+   - P2（细节）：{p2_count} 个
+
+🎨 原型状态：{proto_status}  # proto_pending / proto_in_progress / proto_complete / disabled
+   - 启用状态：{proto_enabled}  # true / false
+   - Proto Round：{proto_round}  # 0 / 1 / 2 / 3
+   - 技术路径：{tech_stack}  # ["Pencil"] / ["Web Artifact"] / ["Pencil", "Web Artifact"]
+   - 产出文件：
+     {proto_output_list}
+   - 未解决问题：{proto_unresolved_count} 个
+
+⏰ 会话时间：
+   - 创建时间：{created_at}
+   - 上次更新：{last_updated_at}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## 数据来源映射
+
+### 从 session.yaml 提取
+```yaml
+workdir: {path}
+doc_type: {prd/frd/dar}
+project_alias: {alias}
+current_round: {round}
+session_status: {status}
+unresolved_questions:
+  - id: P0-1-1  # 统计 P0/P1/P2
+prototype:
+  enabled: {true/false}
+  status: {proto_status}
+  proto_round: {0-3}
+  tech_stack: [...]
+  outputs: [...]
+  unresolved_proto_questions: [...]
+created_at: {timestamp}
+last_updated_at: {timestamp}
+```
+
+### 从 summary.md 提取
+- 快速回顾已完成的主要内容
+- 提取关键进展摘要
+
+### 从 outputs/{doc_type}.md 提取
+```bash
+# 统计章节数
+grep "^## " outputs/prd.md | wc -l
+
+# 统计 Mermaid 图
+grep "```mermaid" outputs/prd.md | wc -l
+
+# 统计表格
+grep "^|" outputs/prd.md | wc -l
+
+# 统计证据标注
+grep "\[.*:.*\]" outputs/prd.md | wc -l
+```
+
+### 从 questions/round_*.yaml 提取
+```bash
+# 统计遗留问题
+grep "priority: P0" questions/round_*.yaml | wc -l
+grep "priority: P1" questions/round_*.yaml | wc -l
+grep "priority: P2" questions/round_*.yaml | wc -l
+
+# 过滤已回答的问题（answer 不为空）
+```
+
+### 从 prototypes/ 目录提取
+```bash
+# 检查原型文件存在性
+ls prototypes/*.pen 2>/dev/null
+ls prototypes/webapp/index.html 2>/dev/null
+ls prototypes/screenshots/*.png 2>/dev/null
+```
+
+## 状态诊断规则
+
+### 健康度评估
+
+**🟢 健康（可继续）**
+- P0 问题 = 0
+- 证据覆盖率 >= 80%
+- 所有章节至少 1 条证据或 `[ASSUMPTION]`
+
+**🟡 警告（需注意）**
+- P0 问题 1-2 个
+- 证据覆盖率 50%-80%
+- 部分章节缺少图表
+
+**🔴 阻塞（需修复）**
+- P0 问题 >= 3 个
+- 证据覆盖率 < 50%
+- 缺少必备文件（session.yaml/desc.md）
+
+### 建议工作模式
+
+**推荐 [A] 继续模式**：
+- 当前 Round 未完成
+- 存在遗留问题待解答
+- 章节完成度 < 100%
+
+**推荐 [B] 修改模式**：
+- 用户明确提出新需求
+- 需要重写已完成章节
+- 证据源发生重大变化
+
+**推荐 [C] 局部模式**：
+- 只需微调单个章节
+- 修正文字错误/格式问题
+- 补充遗漏的证据标注
+
+**推荐 [D] 原型模式**：
+- prototype.enabled = true
+- 用户要求更新原型
+- 新增界面/交互需求
+
+**推荐 [E] 定稿模式**：
+- current_round >= 3
+- P0/P1 问题 = 0
+- 证据覆盖率 = 100%
+- 用户明确说"可以定稿"
+
+## 报告输出示例
+
+### 示例 1：进行中的 PRD
+
+```markdown
+📊 会话状态报告
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📁 工作目录：./dual-billing-20260209-1500
+📄 文档类型：PRD
+📌 项目简称：dual-billing
+📋 文档标题：双计费模式产品需求文档
+🔢 当前 Round：2
+📊 会话状态：in_progress
+
+📝 已完成内容：
+   - 章节：3/7（已完成：业务背景、用户故事、功能清单）
+   - 证据映射：12 条
+   - Mermaid 图：1 个（用户流程图）
+   - 表格：2 个（功能优先级、角色权限）
+
+❓ 遗留问题：
+   - P0（阻塞）：0 个
+   - P1（关键）：5 个（计费规则细节、异常处理）
+   - P2（细节）：3 个（UI 交互、提示文案）
+
+🎨 原型状态：proto_pending
+   - 启用状态：true
+   - Proto Round：0（尚未开始）
+   - 技术路径：[]
+   - 产出文件：无
+   - 未解决问题：0 个
+
+⏰ 会话时间：
+   - 创建时间：2026-02-09 10:30
+   - 上次更新：2026-02-09 14:20
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+💡 建议工作模式：
+- [A] 继续模式 ✨ **推荐**（解决 5 个 P1 问题并补充第 4-7 章）
+- [B] 修改模式（如有新需求变更）
+- [D] 原型模式（先完成原型再继续文档）
+```
+
+### 示例 2：接近定稿的 FRD
+
+```markdown
+📊 会话状态报告
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📁 工作目录：./order-refactor-20260208-0900
+📄 文档类型：FRD
+📌 项目简称：order-refactor
+📋 文档标题：订单模块重构功能规格书
+🔢 当前 Round：5
+📊 会话状态：pending_review
+
+📝 已完成内容：
+   - 章节：10/10（全部完成）
+   - 证据映射：38 条
+   - Mermaid 图：5 个（时序图、状态机、ER 图）
+   - 表格：8 个（接口定义、数据字典、状态流转）
+
+❓ 遗留问题：
+   - P0（阻塞）：0 个
+   - P1（关键）：0 个
+   - P2（细节）：1 个（日志格式规范）
+
+🎨 原型状态：proto_complete
+   - 启用状态：true
+   - Proto Round：3（已完成）
+   - 技术路径：["Pencil", "Web Artifact"]
+   - 产出文件：
+     - prototypes/order_flow.pen
+     - prototypes/webapp/index.html
+     - prototypes/screenshots/order_detail.png
+     - prototypes/prototype_coverage.md
+   - 未解决问题：0 个
+
+⏰ 会话时间：
+   - 创建时间：2026-02-08 09:00
+   - 上次更新：2026-02-09 16:45
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+💡 建议工作模式：
+- [E] 定稿模式 ✨ **推荐**（解决 1 个 P2 问题后可定稿）
+- [C] 局部模式（快速补充日志规范）
+```
+
+### 示例 3：损坏的会话
+
+```markdown
+⚠️ 会话验证失败
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📁 工作目录：./broken-session-20260201-1000
+❌ 缺失文件：
+   - session.yaml（必备）
+   - summary.md（必备）
+
+✅ 存在文件：
+   - desc.md
+   - outputs/prd.md（可能不完整）
+   - materials/（部分资料）
+
+💡 恢复选项：
+- [A] 基于现有文件重建 session.yaml（需手动填充元数据）
+- [B] 放弃恢复，创建新会话（建议）
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## 使用说明
+
+1. **触发时机**：用户提供已存在工作目录路径时立即读取文件并生成报告
+2. **必读文件**：session.yaml、summary.md、questions/*.yaml、outputs/*.md
+3. **可选文件**：prototypes/*（如果启用原型）
+4. **输出格式**：使用上述模板，填充实际数据
+5. **模式建议**：根据状态诊断规则自动推荐工作模式