# 01-获取需求文档（{{PRODUCT}} / {{DOC_SKILL_REL}}）

## 必须执行（不要只用 AI 猜，要跑脚本）

1. 在**仓库根**（当前工作目录，可能是 `frontend/` 或 monorepo 根）执行：

```bash
cd {{DOC_SKILL_REL}}
export DOC_PRODUCT_PREFIX="{{PRODUCT_PREFIX}}"
export SDD_SYNC_SOURCE_DIR="{{SYNC_SOURCE_DIR_REL}}"
python3 confluence-doc.py {{VERSION_EXAMPLE}}
```

脚本成功后会自动将 `docs/<版本目录>/*.md` 与 `image/` 同步到本 run 的 `source/PRD.md` 与 `source/image/`（也可手动执行 `npx sdd-flow-kit sync-source-prd --run-id <runId>`）。

版本号可传：`2.3.2`、`V2.3.2`、`ADI_V2.3.2`、`ADI-V2.3.2`（脚本会归一化）。

2. 脚本会依次用关键词打开 **Confluence 专用搜索页** `dosearchsite.action?queryString=<关键词>`（非首页顶栏搜索），并依次尝试：`ADI_V*` → `ADI-V*` → `ADI_*` → `ADI-*` → `ADI_v*` → `ADI-v*` → `ADI V*` → `ADI_V*结算` → `V*` 等。

3. 匹配规则：先收集 **标题包含关键词或以关键词为前缀**、或 **URL 路径包含关键词** 的候选页，再执行 PRD 类型校验。

4. PRD 类型校验（强制黑名单）：候选页必须通过脚本内 `is_prd_page()` 与 `has_forbidden_prd_title()` 双重校验。以下标题特征会被直接拒绝：
   - `技术文档`、`技术方案`、`后端`、`详细设计`、`数据库`、`接口文档`
   - `实现文档`、`设计文档`、`开发文档`
   
   若所有候选均未通过校验，脚本必须失败退出（exit code 1），**禁止回退使用第一个非 PRD 候选**。AI 不得手动复制技术文档到 `source/PRD.md`。

5. **禁止**在 Confluence 脚本未跑完或未确认失败前，用本地 Word/原型替代 `source/PRD.md`。

6. 同步结果（自动，无需手抄）：
   - `source/PRD.md`（含 `> 原型图片目录: image/` 元数据行）
   - `source/image/`（正文图片，与 docs 版本目录一致）

## 直链兜底（可选，非默认）

仅在关键字搜索全部失败、且已知 pageId 时使用：

ADI V2.3.4 示例（`yyzcpt` 空间 pageId `109609740`）：

```bash
cd {{DOC_SKILL_REL}}
export DOC_PRODUCT_PREFIX="{{PRODUCT_PREFIX}}"
export CONFLUENCE_PAGE_ID=109609740
python3 confluence-doc.py 2.3.4
```

或：

```bash
export CONFLUENCE_PAGE_URL="https://confluence.huan.tv/spaces/yyzcpt/pages/109609740/ADI_V2.3.4结算、开票、回款数据对接欢聚"
python3 confluence-doc.py 2.3.4
```

## 路径说明

- 推荐脚本目录：`{{DOC_SKILL_REL}}`（已向上解析，可能是 `docs/adi-doc-skill` 或 `../docs/adi-doc-skill`）
- **禁止**在 ADI 需求中使用 `docs/oms-doc-skill`（会搜 OMS 文档导致「未找到」）

## 失败排查

- 输出 `❌ 未找到`：到 Confluence 确认页面标题（ADI 常为 `ADI_V2.3.4结算、开票…`，**下划线**而非 `ADI-V`）；可尝试输入更长关键词如 `ADI_V2.3.4结算`
- 输出 `✗ 命中技术文档标题，拒绝作为 PRD` 或 `跳过技术文档候选` 或 `⚠ 搜索结果均未通过 PRD 校验` 时：
  - **禁止**手动复制技术/后端/设计页到 `source/PRD.md`
  - 应在 Confluence 中找到真正的业务 PRD 页面（通常标题含「结算」「开票」「回款」「数据对接」等业务词汇）
  - 使用该页面的 pageId 或 URL 直链重跑：`CONFLUENCE_PAGE_ID=<正确pageId> python3 confluence-doc.py 2.3.4`
- 页面存在但搜不到：加 `CONFLUENCE_DEBUG=1` 查看选择器解析日志；或（可选）设置 `CONFLUENCE_PAGE_ID` / `CONFLUENCE_PAGE_URL` 直链下载
- Playwright 失败且设置 `CONFLUENCE_USE_REST=1` 时才回退 Token；登录最多重试 3 次，并用 `expect_navigation` 避免竞态
- 登录偶发失败：用 `CONFLUENCE_HEADED=1 CONFLUENCE_SLOW_MO=500` 有头观察；失败截图 `confluence-login-fail-*.png`
- `playwright` 未安装：`pip install playwright && playwright install chromium`
- Token 仅作应急回退：`CONFLUENCE_USE_REST=1`（Token 会过期，不作为默认路径）
- 仍失败：在仓库根执行 `npx sdd-flow-kit install --project {{PRODUCT}} -y` 后重试