sync: 迭代文档更新模式 + implementation-artifacts 支持 + 强制验证门禁 + phase-03 平台检查

## 变更内容 - d8d-prototype/workflow.md: [U] 增量更新细分为 [D]/[P]/[A] 子选项 + evidence 格式 + 验证门禁 - d8d-prototype/step-05: 扫描范围增加 implementation-artifacts/ + 文档分组策略 - d8d-prototype/step-05b: 新增迭代文档更新步骤（d8d-dev 产物自动发现） - d8d-prototype/step-06: server.js 模板添加 .yaml/.yml MIME 类型 - d8d-prototype/step-07: 合并强制验证门禁（禁止 curl 替代截图） - d8d-dev/phase-03: 多应用/单应用检查 + Next.js/uni-app 平台专项检测 ## 测试 - [ ] 在新项目中运行 SETUP 阶段验证 - [ ] 执行 /d8d-prototype 后选择 [U] → [D] 验证文档中心更新
2026-04-08 07:19:51 +00:00
parent 5bd98cb8d1
commit 92bf47ffcc
6 changed files with 197 additions and 34 deletions
--- a/.claude/skills/d8d-dev/phase-03-implement.md
+++ b/.claude/skills/d8d-dev/phase-03-implement.md
@@ -7,10 +7,12 @@
 1. **前置检查**
   - 数据库连接：`psql -U postgres -h localhost -c "SELECT 1"` （容器内置 PG 17）
   - Redis 连接：`redis-cli ping` （容器内置 Redis 7）
-   - 数据库迁移状态：`cd api && npx prisma migrate status`
-   - Dev server 状态：`pm2 list` 检查 api/admin/mini-h5 是否 `online`
-   - 未运行则启动：`pm2 start ecosystem.config.js` 并等待 ready（`curl -sf http://localhost:3001/api/health`）
+   - 数据库迁移状态：`cd api && npx prisma migrate status`（多应用）或 `npx prisma migrate status`（单 Next.js 应用）
+   - Dev server 状态：`pm2 list` 检查服务是否 `online`
+   - 未运行则启动并等待 ready
   - 失败时自动修复：创建数据库、运行迁移、重启 pm2 服务
+   - **Next.js 平台检查**：按 `./reference/platform-nextjs.md` 逐项检测（NextAuth trustHost、Prisma 7 adapter 等）
+   - **uni-app 平台检查**：按 `./reference/platform-uni-app.md` 逐项检测（图标、导航栏等）

 2. **加载原型参考**
   - 从 Story 规格文件中读取关联的原型文件路径
--- a/.claude/skills/d8d-prototype/steps/step-05-generate-docs.md
+++ b/.claude/skills/d8d-prototype/steps/step-05-generate-docs.md
@@ -10,12 +10,26 @@

 ### 5.1 扫描项目文档

-扫描以下目录中的 `.md` 文件，作为文档系统的内容来源：
+扫描以下目录中的 `.md` 和 `.yaml` 文件，作为文档系统的内容来源：

- `_bmad-output/` 下的所有文档
+- `_bmad-output/planning-artifacts/` — 规划文档（PRD、架构、UX 设计、产品简报等）
+- `_bmad-output/implementation-artifacts/` — 实现产物（Story 规格、旅程验证、Pipeline 状态等，**可能不存在**）
+- `_bmad-output/` 根目录下的文件
 - 项目根目录的 README.md、DESIGN.md 等
 - docs/ 目录下的文档

+#### 文档分组策略
+
+按类型将文档卡片分组展示：
+
+| 分组 | 来源目录 | 文件模式 | 图标色 |
+|------|---------|---------|--------|
+| **Planning** | `planning-artifacts/` | 全部 .md | 蓝色/绿色/紫色/琥珀色 |
+| **Implementation - Story 规格** | `implementation-artifacts/` | `X-Y-title.md` | 蓝色 |
+| **Implementation - 旅程验证** | `implementation-artifacts/` | `epic-N-journeys.md` | 绿色 |
+| **Implementation - Pipeline** | `implementation-artifacts/` | `pipeline-*.md`, `pipeline-*.yaml`, `sprint-status.yaml` | 橙色 |
+| **Other** | 项目根目录 | README.md 等 | 灰色 |
+
 ### 5.2 生成 docs-index.html

 文档首页功能：
--- a/.claude/skills/d8d-prototype/steps/step-05b-update-docs.md
+++ b/.claude/skills/d8d-prototype/steps/step-05b-update-docs.md
@@ -0,0 +1,142 @@
+# Step 5b: 迭代文档更新
+
+**Progress: 迭代模式** — 仅在 [U] → [D] 更新文档中心 时执行
+
+## STEP GOAL
+
+重新扫描 `_bmad-output/` 所有子目录，更新 `docs-index.html` 和 `view-doc.html`，使文档中心反映最新的项目文档（包括 d8d-dev 技能生成的 implementation-artifacts）。
+
+与 step-05 的区别：
+- step-05 是**首次生成**（从零创建）
+- step-05b 是**迭代更新**（扫描新内容，重建文档页面，不影响其他原型页面）
+
+## 执行序列
+
+### 5b.1 全量扫描 _bmad-output/
+
+扫描 `_bmad-output/` 下所有子目录的 `.md` 和 `.yaml` 文件：
+
+```
+_bmad-output/
+├── planning-artifacts/     ← 规划阶段产物（首次即存在）
+│   ├── product-brief.md
+│   ├── prd.md
+│   ├── ux-design-specification.md
+│   ├── architecture.md
+│   └── epics.md
+├── implementation-artifacts/ ← 实现阶段产物（d8d-dev 后才存在）
+│   ├── X-Y-title.md          ← Story 规格
+│   ├── epic-N-journeys.md    ← 旅程验证
+│   ├── pipeline-context.md   ← Pipeline 上下文
+│   ├── pipeline-state.yaml   ← Pipeline 状态
+│   └── sprint-status.yaml    ← Sprint 状态
+└── (未来可能的新子目录)
+```
+
+**扫描逻辑**（使用 Bash 命令）：
+```bash
+find ../_bmad-output -type f \( -name "*.md" -o -name "*.yaml" -o -name "*.yml" \) | sort
+```
+
+### 5b.2 按类型分组
+
+将扫描到的文件按以下规则分组：
+
+| 分组 | 匹配规则 | 卡片图标色 | 说明 |
+|------|---------|-----------|------|
+| Planning | `planning-artifacts/*.md` | 各文档独立配色 | PRD、架构、UX 等 |
+| Story 规格 | `implementation-artifacts/\d+-\d+-*.md` | 蓝色 | X-Y-title.md 格式 |
+| 旅程验证 | `implementation-artifacts/epic-*-journeys.md` | 绿色 | Epic 级别的 E2E 验证 |
+| Pipeline 状态 | `implementation-artifacts/pipeline-*.md`, `pipeline-*.yaml`, `sprint-status.yaml` | 橙色 | 开发流程状态文件 |
+| Other | 不匹配上述规则的文件 | 灰色 | 兜底分组 |
+
+### 5b.3 重建 docs-index.html
+
+**保留原有的整体设计风格**（Tailwind CSS、卡片布局），但增加分组标题和更多卡片。
+
+#### 布局结构
+
+```
+┌─────────────────────────────────────────────┐
+│  Documentation Center              [← Back] │
+├─────────────────────────────────────────────┤
+│                                              │
+│  📋 Planning                                 │
+│  ┌──────────────┐ ┌──────────────┐          │
+│  │ Product Brief│ │ PRD          │ ...      │
+│  └──────────────┘ └──────────────┘          │
+│                                              │
+│  🔧 Implementation — Story Specs            │
+│  ┌──────────────┐ ┌──────────────┐          │
+│  │ 1-1 Project  │ │ 1-2 Database │ ...      │
+│  └──────────────┘ └──────────────┘          │
+│                                              │
+│  ✅ Implementation — Journey Tests           │
+│  ┌──────────────┐ ┌──────────────┐          │
+│  │ Epic 2       │ │ Epic 3       │ ...      │
+│  └──────────────┘ └──────────────┘          │
+│                                              │
+│  📊 Implementation — Pipeline                │
+│  ┌──────────────┐ ┌──────────────┐          │
+│  │ Pipeline Ctx │ │ Pipeline St  │ ...      │
+│  └──────────────┘ └──────────────┘          │
+│                                              │
+└─────────────────────────────────────────────┘
+```
+
+#### 卡片链接格式
+
+对于 implementation-artifacts 中的文件，使用子目录前缀：
+```html
+<a href="view-doc.html?doc=implementation-artifacts/1-1-project-init.md">
+```
+
+### 5b.4 更新 view-doc.html fetch 路径
+
+更新 fetch 路径数组，确保覆盖所有 `_bmad-output/` 子目录：
+
+```javascript
+const paths = [
+    `../_bmad-output/planning-artifacts/${docName}`,
+    `../_bmad-output/implementation-artifacts/${docName}`,
+    `../_bmad-output/${docName}`,
+    `../${docName}`
+];
+```
+
+注意：当 `docName` 包含子目录前缀时（如 `implementation-artifacts/1-1-project-init.md`），需要正确处理路径：
+
+```javascript
+// 如果 docName 包含子目录，直接拼接到 _bmad-output/ 下
+const paths = [
+    `../_bmad-output/${docName}`,           // 带子目录前缀的完整路径
+    `../_bmad-output/planning-artifacts/${docName}`,
+    `../_bmad-output/implementation-artifacts/${docName}`,
+    `../${docName}`
+];
+```
+
+### 5b.5 更新 server.js（如需）
+
+检查 server.js 是否已支持 `.yaml`/`.yml` MIME 类型，如缺失则补充：
+
+```javascript
+'.yaml': 'text/yaml; charset=utf-8',
+'.yml': 'text/yaml; charset=utf-8',
+```
+
+### 5b.6 更新状态文件
+
+- 更新 `last_updated`
+- 将 `step-05b-update-docs` 加入 `completed_steps`（如该字段存在）
+
+## 完成标志
+
+- [ ] `_bmad-output/` 所有子目录已扫描
+- [ ] 文件按类型分组正确
+- [ ] docs-index.html 已重建，包含所有文档的分组卡片
+- [ ] view-doc.html fetch 路径覆盖所有子目录
+- [ ] server.js 支持 .yaml/.yml MIME 类型
+- [ ] 状态文件已更新
+
+**完成后，向用户展示更新结果和预览地址。**
--- a/.claude/skills/d8d-prototype/steps/step-06-generate-server.md
+++ b/.claude/skills/d8d-prototype/steps/step-06-generate-server.md
@@ -34,6 +34,8 @@ const MIME_TYPES = {
    '.woff': 'font/woff',
    '.woff2': 'font/woff2',
    '.ttf': 'font/ttf',
+    '.yaml': 'text/yaml; charset=utf-8',
+    '.yml': 'text/yaml; charset=utf-8',
 };

 const server = http.createServer((req, res) => {
--- a/.claude/skills/d8d-prototype/steps/step-07-validate.md
+++ b/.claude/skills/d8d-prototype/steps/step-07-validate.md
@@ -2,6 +2,10 @@

 **Progress: Step 7 of 7** — Next: 完成

+## STEP GOAL
+
+使用 Playwright MCP 和图片 MCP 对所有已生成的页面进行自动化验证，输出验证报告。
+
 ## ⚠️ 强制验证（不可跳过）

 本步骤**禁止**用以下方式替代：
@@ -16,10 +20,6 @@
 3. 发现问题 → 修复 → 重新截图验证
 4. 全部通过 → 写入验证报告 → 标记完成

-## STEP GOAL
-
-使用 Playwright MCP 和图片 MCP 对所有已生成的页面进行自动化验证，输出验证报告。
-
 ## 执行序列

 ### 7.1 验证流程
--- a/.claude/skills/d8d-prototype/workflow.md
+++ b/.claude/skills/d8d-prototype/workflow.md
@@ -20,30 +20,6 @@
 - 💾 **始终**在每步/每页面完成后更新状态文件
 - 🎯 **始终**严格遵循步骤文件中的指令

-## 🔒 步骤完成门禁（强制）
-
-每个步骤标记完成前，**必须**满足以下条件，无证据 = 未完成：
-
-### 通用门禁（所有步骤）
-1. ✅ 已完整 Read 当前步骤文件
-2. ✅ 步骤文件中每条指令都已执行
-3. ✅ 状态文件 `completed_steps` 包含 `evidence` 字段
-
-### 验证步骤门禁（Step 7 专属）
-1. ✅ 使用 `mcp__playwright__browser_take_screenshot` 对平铺入口截图
-2. ✅ 使用 `mcp__zai-mcp-server__analyze_image` 分析截图，验证：
-   - 桌面端页面：布局列数正确，内容按桌面端比例缩放
-   - 移动端页面：手机框架包裹，375×812 尺寸
-   - 文字可读、UI 元素清晰
-3. ✅ 生成验证报告文件 `prototype/VALIDATION-REPORT.md`
-4. ✅ 分析结果中无 ❌ 级别问题（有则必须修复后重新验证）
-
-### ❌ 禁止的替代行为
- ❌ 用 curl/wget HTTP 状态码代替截图验证
- ❌ 只检查文件是否存在
- ❌ 跳过图片分析直接标记完成
- ❌ 自行声称"验证通过"而不提供截图证据
-
 ## 状态文件：.prototype-state.md

 状态文件位于输出目录 `prototype/.prototype-state.md`，用于跟踪前后台每个页面的生成进度。
@@ -95,6 +71,30 @@ page_counts:
 3. **每个步骤完成时**：将步骤名和 evidence 加入 `completed_steps`（必须有 evidence，描述具体做了什么）
 4. **全部完成时**：设置 `status: completed`

+## 🔒 步骤完成门禁（强制）
+
+每个步骤标记完成前，**必须**满足以下条件，无证据 = 未完成：
+
+### 通用门禁（所有步骤）
+1. ✅ 已完整 Read 当前步骤文件
+2. ✅ 步骤文件中每条指令都已执行
+3. ✅ 状态文件 `completed_steps` 包含 `evidence` 字段
+
+### 验证步骤门禁（Step 7 专属）
+1. ✅ 使用 `mcp__playwright__browser_take_screenshot` 对平铺入口截图
+2. ✅ 使用 `mcp__zai-mcp-server__analyze_image` 分析截图，验证：
+   - 桌面端页面：布局列数正确，内容按桌面端比例缩放
+   - 移动端页面：手机框架包裹，375×812 尺寸
+   - 文字可读、UI 元素清晰
+3. ✅ 生成验证报告文件 `prototype/VALIDATION-REPORT.md`
+4. ✅ 分析结果中无 ❌ 级别问题（有则必须修复后重新验证）
+
+### ❌ 禁止的替代行为
+- ❌ 用 curl/wget HTTP 状态码代替截图验证
+- ❌ 只检查文件是否存在
+- ❌ 跳过图片分析直接标记完成
+- ❌ 自行声称"验证通过"而不提供截图证据
+
 ## 状态机：启动与恢复

 ### 初始化流程
@@ -115,7 +115,10 @@ page_counts:
   +-- [有状态文件，status=completed] → 已完成
       → 询问用户：
         [R] 重新生成（删除状态文件，从头开始）
-         [U] 增量更新（选择前台/后台/特定页面）
+         [U] 增量更新 — 选择更新范围：
+           [D] 更新文档中心 — 重新扫描 _bmad-output/，更新 docs-index.html + view-doc.html
+           [P] 更新特定页面 — 选择前台/后台/特定页面重新生成
+           [A] 全部更新 — 文档 + 页面一起更新
         [V] 查看当前原型（启动服务器）
 ```