# 前端需求筛选强制集成

## 功能说明

当你在项目中说 **"开发 XX 版本"** 时，系统会**强制要求先调用 `fe-requirement-filter` skill 进行需求拆分**，从混合 PRD 中筛选出纯前端需求。

## 触发流程

```mermaid
graph TD
    A[用户: 开发 ADI V2.3.4] --> B[guard/invoke 识别版本意图]
    B --> C[自动注入 .fe-filter-required.json]
    C --> D[生成 NEXT.md 强制步骤 0]
    D --> E[AI 调用 fe-requirement-filter skill]
    E --> F[生成 PRD-frontend.md]
    F --> G[gate fe-filter-done 通过]
    G --> H[继续生成 05 验收清单]
```

## 工作机制

### 1. 自动标记（runGuard.ts）

当执行 `npx sdd-flow-kit guard "开发 ADI V2.3.4" -y` 时：

```typescript
// 自动写入标记文件
openspec/PRD/<runId>/.fe-filter-required.json
{
  "required": true,
  "product": "ADI",
  "reason": "版本开发强制要求先筛选前端需求",
  "createdAt": "2024-01-01T00:00:00.000Z",
  "status": "pending"
}
```

### 2. NEXT.md 强制步骤

在 `NEXT-with-prd-enrich.template.md` 中，阶段 A 第 0 步：

```markdown
### 0. 前端需求筛选（强制步骤）

**🔴 强制执行**：在生成验收清单（05）之前，必须先筛选出纯前端需求。

**触发标记**：检测到 `.fe-filter-required.json` 文件，状态为 `pending`

**执行方式**：
- 在 AI 工具中调用 `fe-requirement-filter` skill
- 或手动触发："提取前端需求"、"过滤前端需求"

**输出**：
- `source/PRD-frontend.md`（纯前端需求文档）
- `.fe-filter-report.json`（筛选报告）
```

### 3. 门禁检查

执行 `npx sdd-flow-kit gate --run-id <runId> --expect fe-filter-done`：

**检查项**：
1. ✅ `.fe-filter-required.json` 存在且格式正确
2. ✅ `status` 字段为 `completed`
3. ✅ `source/PRD-frontend.md` 存在且非空（>100 字符）
4. ✅ `.fe-filter-report.json` 存在（筛选报告）

**失败示例**：
```bash
❌ fe-filter-status: 前端需求筛选状态：pending。请在 AI 工具中调用 fe-requirement-filter skill
❌ frontend-prd-exists: 缺少 source/PRD-frontend.md 文件
```

## 使用步骤

### 步骤 1：触发版本开发

```bash
npx sdd-flow-kit guard "开发 ADI V2.3.4版本" -y --agent cursor
```

或在 Cursor 中直接说：
```
开发 ADI V2.3.4版本
```

### 步骤 2：查看 NEXT.md

系统会自动打开：
```
openspec/PRD/<runId>/NEXT.md
```

你会看到第 0 步强制要求。

### 步骤 3：调用 fe-requirement-filter skill

在 Cursor/Claude 中说：
```
提取前端需求
```

或：
```
过滤前端需求，生成前端需求文档
```

### 步骤 4：skill 自动执行

`fe-requirement-filter` skill 会：
1. 读取 `source/PRD.md`
2. 按判定标准筛选前端条目
3. 生成 `source/PRD-frontend.md`
4. 生成 `.fe-filter-report.json`
5. 自动更新 `.fe-filter-required.json` 状态为 `completed`

### 步骤 5：门禁验证

```bash
npx sdd-flow-kit gate --run-id <runId> --expect fe-filter-done
```

通过后才能继续生成 05 验收清单。

## 生成的文件

### .fe-filter-required.json（标记文件）

```json
{
  "required": true,
  "product": "ADI",
  "reason": "版本开发强制要求先筛选前端需求",
  "createdAt": "2024-01-01T00:00:00.000Z",
  "status": "completed",
  "completedAt": "2024-01-01T01:00:00.000Z"
}
```

### source/PRD-frontend.md（纯前端需求）

```markdown
# ADI V2.3.4 前端需求文档

## 1. 订单列表

### 1.1 列表展示
- 支持分页查询
- 表格列：订单号、客户名称、金额、状态、操作时间
- 状态枚举：待审核(0)、已通过(1)、已拒绝(2)

### 1.2 筛选功能
- 日期范围选择
- 状态下拉筛选
- 客户名称搜索（模糊匹配）

...
```

### .fe-filter-report.json（筛选报告）

```json
{
  "filteredAt": "2024-01-01T01:00:00.000Z",
  "kept": 45,
  "removed": 23,
  "pending": 3,
  "details": {
    "keptCategories": ["UI交互", "页面展示", "表单校验", "列表筛选"],
    "removedCategories": ["SQL优化", "数据聚合", "定时任务", "接口字段"],
    "pendingItems": [
      "条目12: 导出功能（前后端协作，待确认归属）",
      "条目34: 数据排序（可前端可后端，待确认实现方）"
    ]
  }
}
```

## 集成到现有项目

### 方式 1：已有项目升级

如果你的项目已安装 `sdd-flow-kit`，执行：

```bash
npm install sdd-flow-kit@latest
# 或
pnpm add -D sdd-flow-kit@latest

# 重新运行 postinstall 更新 skill
node ./node_modules/sdd-flow-kit/dist/postinstall.js
```

### 方式 2：新项目安装

```bash
cd <your-project>
pnpm add -D sdd-flow-kit
npx sdd-flow-kit install --project ADI -y
```

## 配置选项

### 禁用强制筛选（不推荐）

如果确实不需要筛选，在 `.session-state.json` 中设置：

```json
{
  "feFilterRequired": false
}
```

或在 `guard` 时手动跳过：

```bash
# 手动更新状态为 skipped
echo '{"required":true,"status":"skipped","reason":"PRD已是纯前端"}' > openspec/PRD/<runId>/.fe-filter-required.json
```

### 自定义 skill 路径

如果你的 `fe-requirement-filter` skill 在其他位置，在 `.cursor/skills/` 或 `.claude/skills/` 中创建符号链接：

```bash
ln -s /path/to/fe-requirement-filter .cursor/skills/fe-requirement-filter
```

## 故障排查

### 问题 1：gate fe-filter-done 失败

**症状**：
```
❌ fe-filter-status: 前端需求筛选状态：pending
```

**解决**：
1. 确认是否已调用 `fe-requirement-filter` skill
2. 检查 `source/PRD-frontend.md` 是否生成
3. 手动更新状态：
   ```bash
   # 更新标记文件
   cat > openspec/PRD/<runId>/.fe-filter-required.json <<EOF
   {
     "required": true,
     "status": "completed",
     "completedAt": "$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
   }
   EOF
   ```

### 问题 2：skill 未触发

**症状**：说"提取前端需求"但 skill 没反应

**解决**：
1. 检查 skill 是否已安装：
   ```bash
   ls .cursor/skills/fe-requirement-filter/SKILL.md
   # 或
   ls .claude/skills/fe-requirement-filter/SKILL.md
   ```
2. 确认 skill 路径正确：
   ```bash
   # 查看 skill metadata
   head -n 10 .cursor/skills/fe-requirement-filter/SKILL.md
   ```
3. 重新安装 skill（如果在外部路径）

### 问题 3：PRD-frontend.md 为空

**症状**：文件生成了但内容很少

**原因**：
- PRD 文档所有条目都被判定为后端
- 判定标准过严

**解决**：
1. 检查 `.fe-filter-report.json` 中的 `removedCategories`
2. 根据实际情况调整 skill 判定逻辑
3. 或手动补充 `PRD-frontend.md`

## 最佳实践

### 1. PRD 文档准备

在触发版本开发前，确保：
- ✅ PRD 文档已从 Confluence 下载到 `docs/<产品>-v<版本>/`
- ✅ 每条需求尽量明确标注 `【前端】` 或 `【后端】`
- ✅ 前后端混合的需求拆分为独立条目

### 2. 筛选后审查

`fe-requirement-filter` 生成文档后：
- ✅ 检查 `.fe-filter-report.json` 中的 `pendingItems`
- ✅ 对待确认条目进行人工裁定
- ✅ 必要时补充或删减 `PRD-frontend.md` 内容

### 3. 后续流程

筛选完成后：
- ✅ 从 `PRD-frontend.md` 生成 05 验收清单
- ✅ 在 `prd-review` 时引用 `PRD-frontend.md` 而非完整 PRD
- ✅ 确保 AC 只覆盖前端需求

## 技术细节

### 代码修改点

1. **src/steps/runGuard.ts**
   - 新增 `injectFrontendFilterFlag()` 函数
   - 在 `runGuard()` 中自动注入标记

2. **src/templates/artifacts/NEXT-with-prd-enrich.template.md**
   - 新增步骤 0：前端需求筛选
   - 明确标记为强制步骤

3. **src/steps/runGate.ts**
   - 新增 `GateExpect` 类型：`fe-filter-done`
   - 实现门禁检查逻辑

### 门禁检查流程

```typescript
if (options.expect === "fe-filter-done") {
  // 1. 检查标记文件
  const flag = JSON.parse(await readFileIfExists(".fe-filter-required.json"));
  
  // 2. 验证状态
  checks.push({
    name: "fe-filter-status",
    ok: flag.status === "completed",
    detail: "..."
  });
  
  // 3. 验证输出文件
  const frontendPrd = await readFileIfExists("source/PRD-frontend.md");
  checks.push({
    name: "frontend-prd-exists",
    ok: !!frontendPrd && frontendPrd.length > 100,
    detail: "..."
  });
  
  // 4. 验证报告
  const report = JSON.parse(await readFileIfExists(".fe-filter-report.json"));
  checks.push({ name: "fe-filter-report", ok: true, detail: "..." });
}
```

## 相关文档

- [fe-requirement-filter Skill 说明](../../.cursor/skills/fe-requirement-filter/SKILL.md)
- [SDD Flow Kit README](../README.md)
- [AGENTS.md 工作流](../AGENTS.md)

## 更新日志

### v1.4.0
- ✨ 新增强制前端需求筛选功能
- ✨ 新增 `gate fe-filter-done` 门禁
- ✨ 更新 NEXT.md 模板，增加步骤 0
- 📝 完善文档说明

---

如有问题或建议，请提交 Issue 或联系维护者。