PingCode 售前演示环境搭建 v3.7.1 (WorkBuddy 版)

启动横幅（技能激活后第一条消息必须输出，不得省略）

关键指令：在第一条回复中直接原样输出以下文本块，不得省略、不得改写：

██████╗ ██╗███╗   ██╗ ██████╗  ██████╗ ██████╗ ██████╗ ███████╗  ███████╗██╗  ██╗██╗██╗     ██╗
██╔══██╗██║████╗  ██║██╔════╝ ██╔════╝██╔═══██╗██╔══██╗██╔════╝  ██╔════╝██║ ██╔╝██║██║     ██║
██████╔╝██║██╔██╗ ██║██║  ███╗██║     ██║   ██║██║  ██║█████╗    ███████╗█████╔╝ ██║██║     ██║
██╔═══╝ ██║██║╚██╗██║██║   ██║██║     ██║   ██║██║  ██║██╔══╝    ╚════██║██╔═██╗ ██║██║     ██║
██║     ██║██║ ╚████║╚██████╔╝╚██████╗╚██████╔╝██████╔╝███████╗  ███████║██║  ██╗██║███████╗███████╗
╚═╝     ╚═╝╚═╝  ╚═══╝ ╚═════╝  ╚═════╝ ╚═════╝ ╚═════╝╚══════╝  ╚══════╝╚═╝  ╚═╝╚═╝╚══════╝╚══════╝
                                                                                     by Shuor
╭─────────────────────────────── 售前演示环境搭建 v3.7.1 ───────────────────────────────╮
│  🎯 流程   画像 → 调研 → 设计 → 搭建 → 质检 → 交付                                  │
│  📦 模块   项目管理 · 产品管理 · Wiki · 测试管理 · Ship                              │
│  🔧 通道   API 批量创建 + Web 独占操作（Playwright 本地）                            │
│  📋 触发   来活了，搭模板 [附表单] / 无表单→自动打开填写                             │
╰──────────────────────────────────────────────────────────────────────────────────────╯

横幅输出后，立即解析表单数据或打开表单，进入 Phase 1。

核心原则

1. 内容贴合客户业务 — 绝不使用"示例项目""测试数据"等通用名称
2. 先确认后执行 — Phase 3 方案必须经用户确认，再进入 Phase 4
3. 推荐 hybrid 项目 — 客户不确定类型时一律推混合项目（可关功能，不可反向）
4. 同级必并发，禁止纯串行 — 实测 PingCode 限流宽松（POST 并发 15 / GET 40 无 429，单 POST ~440ms）。同级无依赖对象必须用 batchCreateParallel（concurrency=10，无需 sleep）并发；串行 + sleep 建一层是错误做法。字段名详见 references/api.md
5. 每个事项必须完整 — 描述、子步骤、时间、层级，四者缺一不可
6. Phase 5 强制自动质检 — Phase 4 完成后必须自动触发质检，未达标项自动修复，不通过不得交付

进度显示（每个阶段开始时必须执行，始终置顶）

每进入一个新阶段，第一件事就是输出进度条。进度条贯穿全流程，使用填充块 + 百分比，始终置顶在阶段输出上方。

主进度条（Phase 1~6）

╔══════════════════════════════════════════════════════════════╗
║  🚀 搭建进度  [████████████████░░░░░░░░░░░░░░░░]  50% (3/6)  ║
║  ✅ 画像  ✅ 调研  ⏳ 设计  ⬜ 搭建  ⬜ 质检  ⬜ 交付          ║
╚══════════════════════════════════════════════════════════════╝

填充规则：█ = 已完成阶段，░ = 未完成阶段。每完成 1/6 填充约 5 个方块。
- Phase 1: ███░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 17% (1/6)
- Phase 2: ████████░░░░░░░░░░░░░░░░░░░░░░░░ 33% (2/6)
- Phase 3: ████████████████░░░░░░░░░░░░░░░░ 50% (3/6)
- Phase 4: ███████████████████████░░░░░░░░░ 67% (4/6)
- Phase 5: ███████████████████████████████░ 83% (5/6)
- Phase 6: ████████████████████████████████ 100% (6/6)

图标规则：✅ 已完成 | ⏳ 进行中 | ⬜ 待开始

Phase 4 子进度条

Phase 4 内部，每完成一个模块后输出子进度条替代主进度条：

║  📦 搭建子进度  [████████░░░░░░░░]  ✅项目 ✅工作项 ⏳Wiki ⬜Ship ⬜TestHub  ║

填充规则同上，每完成 1/5 约 5 格。子进度条仅 Phase 4 内部使用，Phase 4 结束后恢复主进度条。

输出示例（Phase 3 开头）

╔══════════════════════════════════════════════════════════════╗
║  🚀 搭建进度  [████████████████░░░░░░░░░░░░░░░░]  50% (3/6)  ║
║  ✅ 画像  ✅ 调研  ⏳ 设计  ⬜ 搭建  ⬜ 质检  ⬜ 交付          ║
╚══════════════════════════════════════════════════════════════╝

📌 Phase 3/6 — 方案设计
...

快速入口：表单模式

触发词 /来活了搭模板 或输入 来活了，搭模板 附带结构化信息时，直接解析并进入 Phase 2：

来活了，搭模板

公司: {名称}
行业: {行业}
产品线:        ← 每行 "  - 产品名"
  - {产品1}
  - {产品2}
团队规模: {10-50/50-200/200-500/500+}
研发模式: {Scrum/Kanban/瀑布/混合}
搭建模块: {项目管理、产品管理、知识库、测试管理...}
特殊要求: {如"重点搭建30条用例、需瀑布+Scrum混合"}
启用: {工时登记、历史数据模拟、自定义字段、自动标签、交付物}
禁用: {工时登记、历史数据模拟...}
自定义工作项类型: {标配:工程变更申请+技术评审, 硬件包:风险项+合规检查项 / 否}
演示深度: {广度优先/深度优先}
环境地址: {https://xxx.pingcode.com}
client_id={id}
client_secret={secret}

=== 会议录音文字 ===
{粘贴初次方案交流的会议录音转写，可选}
=== 结束 ===

无结构化信息时，立即在终端打开表单（Windows: start "" "templates/form.html" / Mac: open templates/form.html），同时告知用户填完后粘贴回来。

快速入口：修订模式（贴合回路）

触发词 来活了，改环境：对已搭好的环境，用新文档/会谈反应做增量贴合（POC=探针，搭完不是终点）。详见 references/fit_loop.md。

来活了，改环境
环境标识: {identifier}
context: {客户}_context.json
输入: --from-doc={客户需求.xlsx} 或 --from-followup={会谈纪要.md}

流程：适配器产补丁 → 合并入 context store(低不盖高) → 差分渲染 → dry-run 预览(增/改/删 + 待裁定) → 确认落地 + 回写 store/manifest。

Phase 1: Discover（客户画像）

> 进度横幅：
> > ╔══════════════════════════════════════════════════════════════╗ > ║ 🚀 搭建进度 [███░░░░░░░░░░░░░░░░░░░░░░░░░░░░] 17% (1/6) ║ > ║ ⏳ 画像 ⬜ 调研 ⬜ 设计 ⬜ 搭建 ⬜ 质检 ⬜ 交付 ║ > ╚══════════════════════════════════════════════════════════════╝ >
> 📌 Phase 1/6 — 客户画像

无表单数据时，向用户逐项询问收集：

必填: 公司名、行业、产品线(2-5个)、团队规模
选填: 研发模式偏好、搭建模块、PingCode 环境 + API 凭证

→ 生成 {公司名}_profile.md 保存到工作目录。

Phase 2: Research（业务调研）

> 进度横幅：
> > ╔══════════════════════════════════════════════════════════════╗ > ║ 🚀 搭建进度 [████████░░░░░░░░░░░░░░░░░░░░░░░░] 33% (2/6) ║ > ║ ✅ 画像 ⏳ 调研 ⬜ 设计 ⬜ 搭建 ⬜ 质检 ⬜ 交付 ║ > ╚══════════════════════════════════════════════════════════════╝ >
> 📌 Phase 2/6 — 业务调研

有录音: 优先提取客户痛点、技术栈、产品架构、功能需求。WebSearch 仅补充。
无录音: 并行 WebSearch ≥3 方向 — "{公司名} 产品 行业" / "{行业} 研发管理 最佳实践" / "{公司名} 招聘 技术栈"

输出 1: 核心技术栈、产品架构、行业标准/合规、主要客户。追加到画像文件。

输出 2（必须）: 生成 {公司名}_vocab.json 业务词典，Phase 3/4 所有命名从此词典取词：

{
  "产品线": ["产品名1", "产品名2"],
  "团队角色": ["职位/角色名"],
  "行业术语": ["领域关键词", "技术术语", "标准规范名"],
  "痛点标签": ["客户痛点描述"],
  "客户名称": "{公司名}",
  "项目前缀": "{公司名缩写}"
}

命名强制规则：Phase 3/4 中所有工作项 title、Wiki 空间名、测试库名，必须包含词典中至少一个词。禁止出现"示例/通用/测试"等与词典无关的自造业务词。

行业模板选取（塑造蓝图的行业大脑）

调研后、进入 Phase 3 前，按客户「行业」选/生成行业结构模板（详见 references/verticals/_README.md）：

1. 匹配：读 references/verticals/ 下各文件名 + 首行 synopsis 注释，就近匹配客户行业。
2. 三分支：
   - 命中 curated：加载该 <行业>.md，其「项目类型 / 阶段门 / 工作项骨架 / 测试维度 / 术语」直接驱动 Phase 3 蓝图，types 块进 Phase 3.7。⚠️ 工作项骨架因行业而异——汽车电子/医疗等用需求驱动多级（阶段→需求→子需求(架构/设计)→任务），不要套敏捷 史诗/特性/故事；builder 按模板骨架建。
   - 未命中（长尾）：现场 WebSearch 该行业研发流程/标准/术语，生成同形态结构包（散文 + types YAML）用于本次搭建；交付时（Phase 6）询问是否沉淀。
   - 都不沾边 / 调研薄：降级走通用 WBS（现状），并在蓝图标注"本行业未沉淀模板，结构按通用搭，建议补"。
3. 专属类型优先补 PingCode 短板：缺口处（如 ASPICE SUP.10 变更请求）正是最该建的自定义类型——既补功能、又是演示讲合规的抓手。
4. 行业结构随整份蓝图在 Phase 3.6 一并确认，不新增确认关。

信息充分度判断（必须执行，再进入 Phase 3）

调研完成后，对照以下问题自评：

判断规则：
- "不知道" ≥ 2 项 → 停止，主动向用户要补充材料，说明缺哪些信息、建议提供什么（内部文档、上次演示反馈、产品介绍 PPT）
- "不确定" ≥ 3 项 → 在 Phase 3 蓝图中标注哪些内容是推测的，让用户确认前知情
- 其余情况 → 正常进入 Phase 3

> 带着薄弱素材硬搭，输出只是"看起来有结构的通用模板"。主动暂停比搭完再返工代价小得多。

Phase 3: Design（方案设计）

> 进度横幅：同前，Phase 3 = 50% (3/6)
> 📌 Phase 3/6 — 方案设计

3.1 项目规划

每个项目 5-6 分组，每组 4-7 工作项。

混合/瀑布项目需规划「阶段」，默认参考 PMP 五大过程组，但根据客户实际灵活调整：

> 具体用哪种，在 Phase 3 设计时根据客户规模和产品复杂度判断，或由 特殊要求 字段指定。

混合/瀑布项目的工作项必须创建交付目标：
- API: POST /v1/project/deliverables，字段: name + project_id + work_item_id
- 每个 Story 和 Task 必须关联一个交付物（独立对象，非 description 文本）
- 格式: 具体的、可验证的产出物（如"《系统需求规格书》v1.0——通过评审签字"）

3.2 工作项结构铁律（实战验证，必须遵守）

（一）必须带描述和子步骤 — 不允许空壳：
- 标题: 不加编号前缀，直接描述内容（如"国网华东——TIEE3000通信协议适配"，不用"TK-001 xxx"）
- 工作项: description ≥3 行（场景+技术要求+影响/建议）
- 测试用例: precondition + steps[{description, expected_value}] ≥3 步
- 产品需求: description ≥3 行（业务价值+技术方案+验收标准）
- 工单: description ≥3 行（客户信息+问题描述+期望解决方式）

（二）必须有父子层级 — 双轨制，不允许平铺：
- 产品管理线: 阶段 → 需求(含parent_id) → Task(含parent_id)
- 研发开发线: 阶段(plan) → 史诗(顶层,plan关联) → Feature(含parent_id) → Story(含parent_id) → Task/Bug(含parent_id)
- 里程碑挂阶段下(含parent_id)
- Bug 必须挂 Story 下，不允许跳级
- 创建顺序: 阶段 → 里程碑(含parent) / 需求(含parent) / 史诗(plan=阶段) → Feature→Story→Task/Bug

（三）必须有时间 + 预估工时 — 根据标题和描述智能推断：
- 时间: Math.floor(new Date(年, 月-1, 日).getTime()/1000)（只到天）
- 工时: estimated_workload（单位：小时），remaining_workload 初始与预估相同
- 必须理解标题语义，根据工作量和复杂度推断合理的时间和工时，而非机械分配：

• 推断逻辑: 从标题关键词判断复杂度（"开发/实现/移植" > "优化/改进" > "文档/配置"），从描述中提取具体量化目标校准工时
• 示例: "行波采集板卡FPGA固件开发" → 80h, 3周 / "EMC浪涌防护电路设计" → 40h, 2周 / "系统需求规格书编写" → 16h, 1周

（四）必须跨模块关联 — 创建完成后建立链接：
- 工单 → 产品需求 / 产品需求 → 工作项 / 测试用例 → 工作项

（五）内容贴合业务 — 含客户真实产品、场景、行业标准

3.3 Wiki 设计

3-5 个空间，按产品线或部门维度。每空间 3-5 页 Markdown。

3.4 测试库设计

2-3 个库，每库 2-3 套件，每套件 3-5 用例。含前置条件+步骤+预期+优先级。
生成 1 个测试计划 + 执行记录（pass/fail/blocked 混合）。

3.5 高级功能配置

历史数据模拟

• 按比例分配工作项时间线: 完成(~35%) / 进行中(~15%) / 待开始(~50%)
• 自动生成 2 个历史 Sprint，已完成工作项关联对应 Sprint
• Bug 按收敛曲线分布: 早期集中发现 → 后期逐步修复
• 引擎: node scripts/pingcode_historical.js

工时登记（随机模拟）

• 范围: 只登可执行层级 story/task/bug（阶段/里程碑/需求/史诗/特性不登）；start_at 晚于今天的跳过
• 量: 单项总量 ≈ estimated_workload × 随机(0.3~1.0)；拆 1~3 条（受 总量/6 约束），单条 ≤8h、≥1h
• 日期: 在 [start, min(end, 今天)] 均匀铺开 → 对齐北京当日0点 → 不晚于今天
• 登记人: report_by_id = 该工作项负责人(assignee)，兜底随机用户池（谁干的活谁登工时，企业鉴权必填）
• 类型: 按标题关键词映射 设计/测试/研发 → workload_type id
• 引擎: node scripts/pingcode_workload.js（--identifiers=A,B 限定项目，--dry 预览）

自定义字段

• Web 通道创建，每项目 4 个字段 (单选/多选/单行/多行)
• 根据行业自动匹配模板: 汽车电子/半导体/电力/物联网/通用
• 字段名和选项贴合客户业务场景

标签

• 从行业+产品线推断业务术语词典
• 每项目 8-12 个标签，按工作项类型分配
• 生成器: node scripts/pingcode_tags.js

3.6 确认

输出 {公司名}_blueprint.md，必须向用户确认后进入 Phase 3.7。

3.7 自定义工作项类型（Web，Phase 4 前强制执行）

> Phase 4 前必须完成：每轮搭建必须检查应建类型是否已存在，未建必须先建。不通过不进入 Phase 4。

目的：在管理后台为客户创建行业专属工作项类型并配置自定义字段，使 Phase 4 中可用这些类型的 type_id 创建工作项。

类型分层策略

各类型字段速查

> ⚠️ 下表选项值仅为示例。实际选项 _id 与文字因环境而异，运行时一律以 GET /v1/project/work_item_properties 的 live options 为准，禁止硬编码（实测 daocloud-test「变更类型」是 日常/临时，非设计/工艺/材料/软件）。

完整操作路径（三步，强制执行）

路径①：创建类型 — /admin/product/pjm/configuration/work-item

1. 点击「新建」按钮
2. 表单填写：
   - 名称*：输入类型名（如"工程变更申请"），≤32字符
   - 图标*：随机选一个图标（共30个，任选即可）
   - 分组*：点击下拉 → 键盘输入分组名 → Enter
     分组规则：需求类→"需求"，任务类→"任务"，事务类→"事务"
3. 点击「确定」

路径②：加入混合项目流程 — /admin/product/pjm/configuration/templates

1. 点击「混合项目流程」行进入详情
2. 点击「添加」按钮 → 弹出"添加类型"弹窗
3. 下拉选择类型名 → 确定
4. 重复第2-3步，将所有新类型加入流程

路径③：配置类型字段 — 混合项目流程详情页

1. 检查类型是否已在流程中（搜索框搜类型名），不在则先执行路径②
2. 点击目标类型的「配置」→ 展开子项（工作流/属性与视图/提醒/通知/权限）
3. 点击「属性与视图」行的「配置」→ 弹出属性与视图弹窗（CDK 第1层）
4. 点击弹窗中「添加」→ 弹出"添加属性"弹窗（CDK 第2层）
5. 点击「创建新属性」→ 弹出"新建属性"弹窗（CDK 第3层）
6. 填写：
   - 名称*：输入字段名，≤32字符
   - 类型*：点击选择（单行/多行/单选/多选/日期等13种）
     ⚠️ 单选 vs 级联单选：文字都含"单选"，必须用 exact match！
        正确：page.getByText('单选', { exact: true })
        错误：page.locator('text=单选') → 同时命中两个
   - 单选类型：选完后点「下一步」（非「确定」），进入数据项页
   - 数据项*（仅单选/多选）：点击「添加数据项」→ 弹出输入框 → 填值 → Enter
     逐个添加，每输完一个按 Enter 确认
7. 点击「确定」保存字段 → 回到第2层"添加属性"弹窗
8. 重复第4-7步，为当前类型添加所有字段
9. 全部字段加完后，逐层关闭弹窗（取消/×）

Playwright CDK 弹窗操作铁律（必读）

> 核心原则：禁止使用 ref！ PingCode Angular CDK 每次弹窗/切换都会重新生成 ref 编号，快照拿到的 [ref=e681] 点下去时大概率已失效。

其他铁律：
- 少拍全量快照：能用 page.evaluate() + 条件判断确认状态就不拍 50KB YAML。只在需要定位新元素时 snapshot
- 下拉菜单：CDK overlay 不在原 DOM 位置。先 click 触发 → 等 overlay 出现 → 在 overlay 中 text-click 选项
- 类型存在性验证：创建前先搜索确认类型是否已存在，不盲信"已创建"的说法
- 属性数量验证：创建完成后检查属性数是否增加（新建类型从 ~7 起步），确认字段生效

13种属性类型速查

单选类型：两步流程（易错点）

Step 1: 填名 + 选"单选" + 可选配置 → 点「下一步」（不是「确定」！）
Step 2: 数据项页 → 点击「添加数据项」→ 弹出输入框 → 填值 → Enter
        → 重复添加直到全部选项输入完毕 → 点「确定」

自动化执行（纯本地 Playwright + Edge 复用登录态）

四段流水（= node scripts/ui/fields.js）:
1. build_type.js — 路径①建工作项类型(名称+图标+分组,计数差验证);
2. add_type_to_flow.js — 路径②把类型加进「混合项目流程」(新类型必须先入流程才能配字段);
3. build_attr.js — 在「工作项属性」全局库建字段属性(单选/多选[+自定义颜色]/成员[+多成员],数据项录入=输入后点弹窗空白失焦提交,不按 Enter);
4. attach_attr.js — 把字段挂到类型(该类型「属性与视图」→添加属性→thy-select 搜+选+确定)。

提速版: node scripts/ui/batch_type_fields.js --type=<类型> 单会话+不重导航,~1 分钟/类型。

ngx-tethys 铁律: ① 只认真实鼠标/键盘(.fill()/evaluate-click 对下拉/搜索/数据项无效); ② 数据项点空白失焦提交、别按 Enter(否则"数据项已存在"); ③ 行级「配置」用 evaluate el.click()(新类型在列表底部、坐标在屏外); ④ 屏外按钮(右上"添加" x≈1749)用 evaluate 打 data-auto 标记 + locator.click(自动滚入); ⑤ 验证看"N 属性"计数差,别信详情面板文本; ⑥ 查重走 API GET /v1/project/work_item_types(认证必带 grant_type=client_credentials)。

注意：
- 禁止用 ref：一律用 text/role/placeholder 选择器，参见上方铁律表
- 单选 exact match：getByText('单选', { exact: true })，踩过坑
- 单选有「下一步」：不是直接出数据项，要先点下一步
- 弹窗三层叠加：属性与视图 → 添加属性 → 新建属性，每层单独操作
- 创建完成后记录返回的 type_id，Phase 4 中可用这些类型创建工作项
- 类型创建完后必须在混合项目流程中添加，否则项目中使用不到
- 属性数验证：新建类型默认 ~7 属性，加完自定义字段后应有明显增长（如 7→11 加 4 字段）

3.7b 项目级字段配置（给「已有项目」按清单挂/建字段，非搭 demo）

> 何时用：客户给一份字段清单（Excel/PRD），要配到某个已存在项目的已有工作项类型上——不是从零搭模板。入口脚本 node scripts/ui/project_fields.js。与 §3.7 的区别是导航走项目设置、不走组织后台模板。

路径：项目设置 → 工作项配置（需页面右上「开启本地配置」为 ON，本地化后不同步全局）→ 目标类型行「配置」→ 子项「属性与视图」「配置」→ 全屏模态右上蓝色「+添加」→「添加属性」弹窗：
- 选择属性 = 挂已有全局属性（已挂的会从下拉消失＝天然幂等）
- 创建新属性 = 新建，一步同时"建+挂"，自动进全局库；其「新建属性」表单 DOM 与组织后台完全一致（input[name="propertyName"] + 13 类型卡 getByText(kind,{exact:true})），建字段/数据项逻辑复用 §3.7。

⚠️ 致命坑（务必记住）：创建成功后，模态右侧「属性配置」面板也有一个 input[name="propertyName"]，与新建弹窗重名。所以"input 消失＝成功"的判据永远为假→误报失败→多余 Escape 把整个模态关掉→后续字段级联"弹窗未开"。正解：靠「新建属性弹窗」三特征判开/关——叶子文本含"新建属性" + 含类型卡"单行文本" + 含"取消"按钮；成功路径绝不 Escape（模态要留着继续建下一个）。

工作流（对账优先，方案 A）：
1. 先 dump 全局库对账：客户 admin 常已建过大批同源字段（曾遇 51 个）。用探针（选择属性下拉滚动收全，解析 名字 （类型） 去后缀）比对清单 → 已有的复用挂载、缺的才新建（方案A=复用已有+只建缺，别造重复）。
2. 写 spec.json：{ "<类型>": [ {name,action:"attach"} | {name,action:"create",kind,items} ] }（凭证/客户数据不入库，放 scratchpad）。
3. 跑：node scripts/ui/project_fields.js --env=<租户> --project=<identifier> --spec=<spec.json> [--type= --offset= --limit=] [--dry]。--dry 先预览；执行幂等（attach 找不到＝已挂→skip；create 遇"已存在"→转挂→skip）。
4. 验证：回列表读该类型「N 属性」计数差；或开属性面板逐个确认字段在。类型真名以截图/DOM 为准（body innerText 可能把"采购申请单明细"拆成"采购申请明细"，matches=0）。

3.8 Pre-flight（强制：每次 Phase 4 前必须执行）

目的：环境间 ID 差异巨大（case_types、ticket_priorities、ticket_types、states），禁止硬编码。每次搭建前拉一遍动态 ID。

必须执行的探测:

GET /v1/project/work_item_types  → 取 phase type_id (名称="阶段")
GET /v1/testhub/case_types        → 取 case type_id 列表
GET /v1/ship/ticket_types         → 取 ticket type_id 列表
GET /v1/ship/ticket_priorities    → 取 ticket priority_id 列表
GET /v1/directory/users           → 取用户池 (assignee/participant)
GET /v1/project/work_item_properties → resolvePropertyCatalog：自定义字段 name↔key↔options（供 Phase 4 生成与 4.4 写值）

必须验证的字段（创建前用单条测试验证）:

测试用例: 用探测到的 type_id 发一条 → 确认 200 → DELETE
工单:     用探测到的 type_id + priority_id 发一条 → 确认 200
需求:     用 product_id 发一条 → 确认 200

禁止行为:
- 禁止用 references/api.md 里的 system ID 常量直接建 case/ticket/idea
- 禁止假设 work_item priority_id 可以用于 ticket priority_id
- 禁止假设上一个项目的 ID 在本项目可用
- 每轮新搭建必须重新探测，不可复用上一轮的探测结果

> Why: 连续 3 个项目都在测试用例/工单/需求创建阶段因 ID 不匹配反复失败，浪费大量时间。Pre-flight 一步到位解决。

3.8b 关系自检矩阵（强制：Phase 4 批量建前必做）

> Why: 「什么能挂什么」「什么用 parent_id、什么用 phase_id」因环境而异，假设必翻车。建项目后、批量建工作项前，用 1 个阶段 + 各类型单条试探，记录真实规则再批量。睿恩 需求✗task，daocloud-test 需求✓task——同一句话两个环境相反。

必测矩阵（创建测试项→读结果→删除）：

铁律：
- 探测目标要选准（按 title 子串找易误中阶段——阶段名常含"详细设计"等词）；探测项创建后立即删除。
- 把矩阵结果存成本轮规则，build 按规则走，不照搬上一环境。

3.9 Pre-flight 探测脚本模板（直接复制使用）

用法：node pre-flight.js --client_id={表单 client_id} --client_secret={表单 client_secret}

> 脚本模板详见 references/api.md 中的 Pre-flight 章节。每次新搭建必须重新运行。

Phase 4: Build（批量创建）

> 进度横幅：
> > ╔══════════════════════════════════════════════════════════════╗ > ║ 🚀 搭建进度 [███████████████████████░░░░░░░░░] 67% (4/6) ║ > ║ ✅ 画像 ✅ 调研 ✅ 设计 ⏳ 搭建 ⬜ 质检 ⬜ 交付 ║ > ╚══════════════════════════════════════════════════════════════╝ >
> 📌 Phase 4/6 — 批量创建
> 子进度初始：⏳ 项目 → ⬜ 工作项 → ⬜ Wiki → ⬜ Ship → ⬜ TestHub

4.0 Build Manifest（幂等性保障）

Phase 4 开始前必须创建 {公司名}_build_manifest.json，记录所有计划对象及创建状态：

{
  "client": "{公司名}",
  "items": [
    { "type": "project",   "name": "{项目名}", "id": null, "status": "PENDING" },
    { "type": "work_item", "name": "{工作项名}", "id": null, "status": "PENDING" },
    { "type": "wiki_page", "name": "{页面名}", "id": null, "status": "PENDING" }
  ]
}

状态规则：
- 每创建成功一个对象 → 立即将 status 更新为 DONE，记录返回的 id
- 创建失败 → 标记为 FAILED，记录错误信息
- 重新执行时：跳过所有 DONE 的对象，只重试 FAILED 和 PENDING

> 这让每次搭建变成可恢复的事务。中途失败不再需要从头来，也不会产生重复数据。

按顺序执行: Pre-flight探测 → 认证 → 项目 → 获取用户列表 → 创建阶段(PMP) → 里程碑(挂阶段) → 需求(产品线,挂阶段) → 史诗(phase_id关联阶段) → Feature→Story→Task/Bug(含随机负责人+关注人+描述+phase_id) → Sprint(含历史) → 工时登记(模拟,登记人=assignee) → 自定义字段(Web) → 标签 → Wiki → Ship产品空间 → 工单(需 product_id+type_id+priority_id) → 需求(需 product_id) → 测试库 → 套件 → 用例(用探测到的 type_id) → 计划 → 执行记录

构建顺序铁律: 项目/工作项 → Wiki → Ship(产品+工单+需求) → TestHub。后三步依赖前一步的 ID，禁止跨模块并行。

同级必并发（铁律，非可选）：⚠️ 实测 PingCode 限流宽松（POST 并发 15 无 429，单 POST ~440ms），搭建慢的唯一原因就是串行。同级无依赖对象必须用 batchCreateParallel（concurrency=10，无需 sleep），纯串行 + sleep(200) 建一层是错误做法（138 工作项串行 ~1分多 → 层内并发 ~15-20s）。

按层同步 + 层内全并发 —— 必须一层层建（子项要父 id），但同层兄弟全并发；results 与输入一一对齐（失败位 null），便于接父子：

// 第 N 层：并发建本层全部，results[i] 对齐 defs[i]
const { results: epics } = await api.batchCreateParallel(epicDefs,
  def => api.createWorkItem(token, def, baseUrl), { concurrency: 10 });
// 下一层依赖上层 id：等本层并发完成，再并发建下一层
const featDefs = epics.flatMap((ep, i) => ep ? epicDefs[i].features.map(f => ({ ...f, parentId: ep.id })) : []);
const { results: feats } = await api.batchCreateParallel(featDefs,
  def => api.createWorkItem(token, def, baseUrl), { concurrency: 10 });

顺序：阶段(并发) → 里程碑/史诗/需求(并发) → 特性(并发) → 故事(并发) → 任务/缺陷(并发)；phase_id 修正、交付物、工时登记同样并发。跨模块仍串行（构建顺序铁律），但模块内同级一律并发。

4.1 各对象必填字段速查矩阵

所有对象创建前必须对照此表检查字段，禁止凭记忆：

> 关键区分：
> - test_library_id（用例库）≠ library_id（无此字段）
> - phase_id（阶段关联，所有工作项通用）≠ plan_id（文档用词，API 无效）
> - identifier：项目用短大写如 GVRVERIFY；测试库用大写开头如 GX100TEST
> - Ship 工单用 ticket_priorities 的 ID（5cb946...），不用 work_item 的 priority ID（67f32d...）

必须遵守的规则：
1. 认证是 GET /v1/auth/token?...（不是 POST）
2. 工作项按双轨层级创建:
- 产品线: 阶段 → 需求(含parent_id=阶段) → 任务
- 研发线: 阶段 → 史诗(顶层,plan关联) → 特性(含parent_id) → 用户故事(含parent_id) → 任务/缺陷(含parent_id)
3. 每个 Hybrid/瀑布项目必须先创建 PMP 阶段（type_id=阶段，从 GET /v1/project/work_item_types 获取）。参考 PMP 五大过程组或客户业务灵活调整。每阶段下挂里程碑。史诗通过「所属计划」关联阶段（非 parent_id）。需求可挂阶段下作为子工作项。
4. 所有工作项必须随机分配负责人：Phase 4 开始时 GET /v1/directory/users 获取用户列表 → 每个工作项创建时随机选 assignee_id → 随机添加 1-3 个 participant_ids。
5. 每个 Story 下至少挂 1 个 Task 或 Bug，严禁 Story 无子工作项。Bug 必须挂 Story 下，不能跨级挂 Feature。
6. 时间用 new Date(年, 月-1, 日) 计算 Unix 秒，根据标题语义智能推断合理周期（非机械分配）
7. 每个工作项必须带 description ≥3 行 + estimated_workload（小时）+ remaining_workload（初始同预估）
8. 工作项 type_id 字符串: "task"/"story"/"bug"/"epic"/"feature"；阶段 type_id 通过 API 动态获取
9. 测试用例用 test_library_id（不是 library_id）
10. 测试计划 assignee_id + start_at 必填
11. Wiki 页面 content 和 format_type: "markdown" 必须同时存在
12. 环境间 ID 不通用: case_types、ticket_types、states 必须 GET 动态获取，禁止硬编码
13. Sprint/Plan 的 assignee_id 必填
14. 混合/瀑布项目工作项必须关联交付目标: POST /v1/project/deliverables { name, project_id, work_item_id }
15. Ship 工单: 必须同时传 product_id + type_id + priority_id（priority_id 用 ticket_priorities 探测到的值，不是 work_item priority_id）
16. Ship 需求: 必须传 product_id，不需要 priority_id
17. 测试用例: type_id 必须用 pre-flight 探测到的 case_type ID（daocloud-test 只有 3 种：信息类/功能需求/评审类）

防踩坑速查（实战血泪教训，每次 Phase 4 前必读）

详见 references/api.md

4.2 内容填充强制步骤

Wiki 页面和测试用例不能空壳。工作项创建完毕后，必须单独执行内容填充：

Wiki 填充：
- 每个空间 ≥ 2 页 Markdown 内容
- 页面 content + format_type: "markdown" 必须同时存在
- 内容贴合客户业务场景（技术文档模板、SOP、设计规范等）

测试用例填充：
- 每条用例 ≥ 3 步，每步含 description + expected_value
- 格式：[{description: "操作xxx", expected_value: "预期xxx"}, ...]
- 用例创建后关联到测试计划，生成执行记录（pass/fail/blocked 混合）

4.3 phase_id 继承问题 & 批量 PATCH 修复

已知问题：创建子工作项时即使传入正确的 phase_id，PingCode 后端也会用父工作项的 phase_id 覆盖。所有子工作项创建后必须 PATCH 修正。

修复方式：批量 PATCH：

// 收集所有需要修正的子工作项 → 批量一次 PATCH
const patchList = childItems.map(item => ({
  id: item.id,
  fields: { phase_id: correctPhaseId }
}));
await api.batchUpdateWorkItems(token, patchList, baseUrl);

• batchUpdateWorkItems 封装了 PATCH /v1/project/work_items，支持传数组批量更新（注意：某些环境 batch PATCH 报 100008 property_name，须降级逐条或用 batchCreateParallel 并发逐条）
• 一个项目下所有子工作项的 phase_id 修复，并发一把搞定

强化规则：
- phase_id 必须全量显式 PATCH：子项创建时父若尚无 phase（顶层后补），子项就完全悬空（不在任何阶段）。所以 build 末尾对每个需求/任务/自定义按其目标阶段全量 PATCH phase_id，不只顶层。验证口径：「无阶段的工作项数」必须为 0。
- 里程碑用 parent_id=阶段，不要 phase_id（phase_id 对里程碑无效→悬空）；且不要把里程碑混进 phase_id 批次（会拖累整批失败）。
- 跨阶段父子允许：子可在比父更晚的阶段（客户需求 G1 → 系统需求 G2 → 软件需求 G4 一条链横跨多阶段，正是 V 模型）。PATCH 子项 phase_id 到不同于父的阶段会生效。
- 全阶段必铺满：垂直行业(如 ASPICE)的每个阶段门都要有内容，G1 概念立项、G7 系统验证/量产不能空。左侧需求分解(客户→系统→架构→软件→设计→实现)，右侧验证(软件验证 SWE.4/5/6、系统验证 SYS.4/5、量产)。建后按阶段计数自检，每阶段 >0。

4.4 自定义字段语义填值（紧跟 4.3 phase_id 修复）

• 生成约定：自定义类型工作项的 blueprint 带 properties（字段名键、人读值：单选写选项文字、文本写串、日期写日期、成员写显示名）。模型不碰 key/_id。
• 写入：用 node scripts/pingcode_custom_fields.js——4.3 回读每条工作项时顺带 discoverTypeFields（.properties keys ∩ resolvePropertyCatalog）→ buildPropertiesPatch（名→key、选项文字→_id、按类型格式化、跳过不适用字段）→ applyPropertyValues 并发 PATCH（可并进 4.3 同批 body）。
• 容错：非法选项回落合法默认+warn，绝不发非法 _id；类型无自定义字段→no-op。

4.5 自动加管理员（Phase 4 末尾，manifest 驱动）

• 用 node scripts/pingcode_admin.js 的 sweepAdmins(token, build_manifest, baseUrl, {formAdmin, sampleProjects, users})：捞本轮新建的 project/wiki/ship/testhub（manifest 容器项）→ 解析 admin（表单优先，否则扫已有成员里的「管理员」）→ 并发 addMember(role_id=管理员)，幂等。
• admin 找不到且表单没填 → 整步跳过并在 Phase 5/6 告警，不瞎猜。
• manifest 需记录容器类型：project / wiki_space / ship_product / test_library（供 containerModuleOf 识别）。

Phase 5: QA Review（自动质检与修复）

> 进度横幅：
> > ╔══════════════════════════════════════════════════════════════╗ > ║ 🚀 搭建进度 [███████████████████████████████░] 83% (5/6) ║ > ║ ✅ 画像 ✅ 调研 ✅ 设计 ✅ 搭建 ⏳ 质检 ⬜ 交付 ║ > ╚══════════════════════════════════════════════════════════════╝ >
> 📌 Phase 5/6 — 自动质检
> 强制执行：Phase 4 结束后立即自动触发，无需用户指令。质检未通过前不得进入 Phase 6。

5.0 自检脚本（优先执行）

Phase 4 结束后，第一步必须运行自检脚本，让机器先做全量客观检查，再由 AI 处理内容质量问题：

node scripts/pingcode_check.js \
  --env=xxx.pingcode.com \
  --client_id=xxx \
  --client_secret=xxx

# 发现结构问题时，加 --fix 自动修复：
node scripts/pingcode_check.js --env=... --client_id=... --client_secret=... --fix

# 保存 JSON 报告供 Phase 6 附用：
node scripts/pingcode_check.js --env=... --client_id=... --client_secret=... --report={公司名}_qc.json

脚本覆盖检查范围：

结果判定：
- 脚本退出码 0 → 全部通过，继续 5.1 质检
- 脚本退出码 1 → 有 fail 项，必须先修复（运行 --fix 或手动处理）再继续
- 脚本退出码 2 → 脚本本身报错，检查网络/凭证后重试

5.1 质检标准矩阵

脚本运行完（或修复完）后，继续通过 API 查询验证以下内容（脚本无法自动修复的部分）：

A. 数量达标

B. 结构合规

C. 内容质量

D. 业务贴合度抽检

从所有工作项中随机抽取 5 条，对每条自问：

> "如果客户在演示中看到这条内容，他会认为这是他们公司的真实工作数据吗？"

判断标准：
- ✅ 通过：名称含客户产品线/行业术语，描述有具体业务场景
- ❌ 不通过：名称泛化（如"功能开发""需求分析"），或描述像通用模板

不通过时：将该工作项的 title 和 description 按业务词典重写，然后重新抽检直到 5/5 通过。

5.2 质检与修复循环

最多执行 3 轮：
  1. GET 查询各模块实际状态（工作项列表、Wiki 页面、测试用例、工单/需求）
  2. 对照 5.1 矩阵，记录所有不合格项
  3. 按 B（结构）→ A（数量）→ C（内容）→ D（抽检）顺序执行自动修复
  4. 重新 GET 验证修复结果

  ↓ 全部通过 → 生成 QC 报告，进入 Phase 6
  ↓ 3 轮后仍有未修复项 → 在报告中列出残留问题，询问用户是否继续

5.3 QC 报告格式（追加到交付文档头部）

## QC 质检报告

| 质检项 | 实际值 | 标准 | 状态 |
|-------|-------|------|------|
| PMP 阶段数 | {n} | ≥4 | ✅/❌ |
| Story 均有子工作项 | {n}/{total} | 100% | ✅/❌ |
| Bug 挂载合规 | {n}/{total} | 100% | ✅/❌ |
| 工作项有描述比例 | {n}% | ≥90% | ✅/❌ |
| Wiki 页面有内容 | {n}/{total} | 100% | ✅/❌ |
| 测试用例有步骤 | {n}/{total} | 100% | ✅/❌ |
| 工单/需求数量 | {n} | ≥3 | ✅/❌ |
| 业务贴合度抽检 | {n}/5 通过 | 5/5 | ✅/❌ |

**自动修复记录**：
- [修复] {问题描述} → {解决方式}

**质检结论**：通过 {n} 项 / 共 {n} 项，经 {n} 轮自动修复后达标

Phase 6: Present（交付摘要）

> 进度横幅：100% 触发彩蛋 🎉
> > ╔══════════════════════════════════════════════════════════════╗ > ║ 🚀 搭建进度 [████████████████████████████████] 100% (6/6) ║ > ║ ✅ 画像 ✅ 调研 ✅ 设计 ✅ 搭建 ✅ 质检 ⏳ 交付 ║ > ╚══════════════════════════════════════════════════════════════╝ >
> 📌 Phase 6/6 — 交付摘要
>
> 🎊 100% 彩蛋（进度条满时必须输出，动态填入实际数据）：
> > ✨ ───────────────────── ✨ > ⏱️ 省下 ~{N} 小时 → 够你摸三条鱼 > 🐟 🐟 🐟 > 🎣 > 🤖 {X} 工作项 · {Y} Wiki 页 · {Z} 测试用例 > ☕ Skill 全自动代劳，你只负责喝咖啡 > ✨ ───────────────────── ✨ >
>
> {N} 计算规则：N = ⌈(工作项数×2 + Wiki页数×5 + 测试用例数×2) / 60⌉，加调研设计 4h 基数，向上取整。
> 示例：102工作项 + 13Wiki + 20用例 → ≈ 6h 基础 + 4h 调研设计 = ~10h

生成 {公司名}_delivery.md：项目全景 + 层级树 + Wiki 目录 + 测试覆盖 + 演示路径

行业模板沉淀（仅当本次为长尾现场生成）：若本次行业未命中 curated 模板而是现场生成的，交付后询问用户：
> "『{行业}』这次是现场生成的，要不要沉淀成正式模板？"

用户认可 → 写 references/verticals/{行业}.md（用户过目/微调）→ node scripts/vertical_template.js 校验通过 → 提交。下次同行业即升级为 curated 命中。

参考资源

双通道操作策略

> Web 通道 = 纯本地 Playwright（channel:'msedge' + 持久化 profile ~/.pingcode-presales-edge-profile 复用登录态,首次手工登一次,不上云）。入口 node scripts/ui/fields.js; 全部 ngx-tethys 铁律见 references/web_ops.md。

案例

WorkBuddy 版说明

本文件由 Claude Code 版 pingcode-presales v3.7.1 适配而来。

平台差异：
- 触发方式：WorkBuddy 中通过 /来活了搭模板 斜杠命令或自然语言触发词 "来活了，搭模板" 激活
- 脚本执行：所有 Node.js 脚本路径保持不变，在终端中执行
- 浏览器自动化：通过 WorkBuddy MCP Playwright 工具执行（等同于 Claude Code 版）
- 用户交互：确认步骤通过 WorkBuddy 原生对话交互完成
- 文件操作：使用 WorkBuddy 内置的读写文件能力