diff --git a/product-planning/SKILL.md b/product-planning/SKILL.md index d68f0ee..bcaf101 100644 --- a/product-planning/SKILL.md +++ b/product-planning/SKILL.md @@ -1,6 +1,6 @@ --- name: product-planning -description: 产品规划总入口（唯一入口），三段式调度：① 产品需求 ② 产品功能 ③ 界面交互。三段以 references/stage-* 承载，本文件是总调度与约束。可整段跑也可只调一段。当用户要做产品规划、从零做新产品、只做某一阶段、或不知道从哪开始时调用。 +description: 产品规划总入口（唯一入口），四段式调度：① 产品需求 ② 产品功能 ③ 界面交互 ④ 原型说明文档。四段以 references/stage-* 承载，本文件是总调度与约束。可整段跑也可只调一段。当用户要做产品规划、从零做新产品、只做某一阶段、或不知道从哪开始时调用。 --- # 产品规划总入口 @@ -13,27 +13,29 @@ description: 产品规划总入口（唯一入口），三段式调度：① 产 本文件管调度与约束。各段怎么做，写在 `references/stage-*` 各自的文件里。 -## 三段结构（可整段跑，也可只调一段） +## 四段结构（可整段跑，也可只调一段） | 段 | 回答的问题 | 子步 | 调用 | 产出物 | |---|---|---|---|---| | **① 产品需求** | 要做的东西凭什么成立：什么问题、为谁、为什么值得做 | 1a 需求文档（grill 压测）/ 1b 竞品分析 / 1c 用户画像 / 1d 产品策略 / 1e 使用场景 | `stage-discovery` | `docs/pm/<项目>/research/*`。其中 1b 交两种体例：`research/1b-竞品分析.md`（汇总对比）＋ `research/1b-独立分析/<竞品名>.md`（独立分析） | | **② 产品功能** | 要做哪些功能、什么不做、长成什么骨架 | 2a 产品功能 / 2b 界面布局 | `stage-requirements` | `docs/pm/<项目>/prd/2a-产品功能.md` 与 `prd/2b-界面布局.md`（两份） | | **③ 界面交互** | 长什么样、怎么操作 | 3a 视觉规范 / 3b 原型 / 3c GPT参考版 / 3d 审查打磨 | `stage-delivery` | `docs/pm/<项目>/DESIGN.md`、`designs/<项目>/*.html`、`designs/<项目>/3c-GPT参考版.md` | +| **④ 原型说明文档** | 现有原型怎么用、每条需求落到哪、坏了怎样、怎么核对 | 4a 场景盘点 / 4b 说明区 / 4c 演示引导（可选） | `stage-proto-doc` | 原型内嵌说明区 ＋ 独立产品文档 `designs/<项目>/产品文档.html`（两份共用同一套 R/S/F 编号） | -三段只通过落盘文件耦合。段间交接口如下，这是唯一的契约，越界即失效： +四段只通过落盘文件耦合。段间交接口如下，这是唯一的契约，越界即失效： | 交接 | 由谁给 | 给什么 | 给到哪为止 | |---|---|---|---| | ① → ② | ① | 问题定义、需求澄清决策表（含 grill 压测的 B 节：做成什么样 / 哪些情况不成立 / 状态怎么流转）、取证结论（1b 汇总对比体 ＋ 1b 独立分析体、1c 用户画像）、产品定位、《使用场景》＝用户故事（②段功能的直接推导依据） | 功能清单归②段产出，1a 写到需求与形态为止 | | ② → ③ | ② | 功能清单（每条带优先级 ＋ 状态流转）、界面布局（有哪几页 / 每页几个板块 / 板块怎么排 / 跨页关系）、每页主操作、信息承载分档（主屏常驻 / 可点入） | 视觉归③段。骨架必须给全，骨架不给全，③段就一版一个样 | +| ③ → ④ | ③ | 已跑通的单文件原型 HTML（页面、模块、控件、状态、交互、跳转、反馈＝界面事实的唯一依据） | 说明区与独立产品文档归④段；⛔ ④段不重新规划产品、不重新设计界面 | > 口径：②段钉骨架，③段做皮肉。两侧逐行对照与用户原话只在②段 `references/stage-requirements/SKILL.md` 的 §②—③ 交接口 定义一次 —— 本入口不复述。要点两条：②段要给全「归②段」列；③段不许增删移动板块，缺板块回②段改。 > ②→③ 最容易搞坏。旧病灶：②段说「必须能读到」，③段读成「必须常驻主屏」，五类信息就全铺一屏成了信息墙。分档表把「读到」明确成「一次点击内可达」，防的就是这句歧义。骨架是灰块（有哪些块、什么顺序），③段给的是视觉与交互实现（排版、点哪有什么反馈、空态、响应式）。两件事各管一维，③段不会退化成照抄。 -> 三段各占一个词，互不共用（2026-10-02 定）：产品 / 功能 / 界面。改段名前先对照这张表；两个段名里出现同一个词，边界一定在漂。旧名「调研与方案 / 需求与结构」都含「需求」，③段旧名里的「交付」是三段共有的属性，都属名实不符，已改。 -> 🔴 **④段「原型说明文档」已于 2026-10-14 删除**（用户令：「第4部分完全没法用，都删除」）。原做法是往原型 HTML 里注入说明区注解层（场景 / 流程图 / 三段说明 / 演示引导），实测不好用 ⇒ 整段连方法论一并撤掉。新写法待定（正另行征询）。原件已按改包纪律留备份，备份位置与删段理由见当日 memory 记录。 +> 四段各占一个词，互不共用（2026-10-02 定）：产品 / 功能 / 界面 / 说明。改段名前先对照这张表；两个段名里出现同一个词，边界一定在漂。旧名「调研与方案 / 需求与结构」都含「需求」，③段旧名里的「交付」是三段共有的属性，都属名实不符，已改。 +> 🔴 **④段的沿革（2026-10-14 → 10-15）**：10-14 按用户令删掉**旧版**④段 —— 旧做法是往原型 HTML 注入说明区注解层（状态 → 场景 → 从左到右流程图 → 功能作用/输入边界/异常情况 三段 → 逐步骤演示引导），实测没法用，整段连方法论一并撤掉。10-15 用备份里的**新版**④段装上：改成「解释与记录现有原型」，交**两份产物**（原型内嵌说明区 ＋ 独立产品文档 `designs/<项目>/产品文档.html`），内容按「需求列表 → 用户场景 → 操作流程 → 功能」四块 ＋ 附录铺，配 R/S/F 编号体系与语体规范。判据正文在 `references/stage-proto-doc/`，⛔ 旧版那套（状态轴、三段必填、逐步骤演示）不再使用。 > ①叫「产品需求」不叫「需求调研」：该段产出 `research/1a-需求文档.md`、`1b-竞品分析.md`、`1c-用户画像.md`，也产出 `1d-产品策略.md`、`1e-使用场景.md`，「调研」二字盖不住后半截。 > ⭐ 1b 是①段唯一交两种体例的子步：独立分析体 `research/1b-独立分析/<竞品名>.md`（竞品池每一个一份），汇总对比体 `research/1b-竞品分析.md`（恒一份）。职责边界与定案原话见 `references/stage-discovery/references/competitor-analysis.md` §0.4。 @@ -51,7 +53,7 @@ description: 产品规划总入口（唯一入口），三段式调度：① 产 ## 项目与路径约定（单一真源） -> 三段全部遵守本节。各段 `SKILL.md` 与 `references/` 里出现 `docs/pm/...` 时，`<项目>` 一律指本节定义的 slug。 +> 四段全部遵守本节。各段 `SKILL.md` 与 `references/` 里出现 `docs/pm/...` 时，`<项目>` 一律指本节定义的 slug。 ### `<项目>` 是什么 @@ -75,6 +77,7 @@ description: 产品规划总入口（唯一入口），三段式调度：① 产 | ① 产品需求 | `docs/pm/<项目>/research/` | | ② | `docs/pm/<项目>/prd/` | | ③ | `docs/pm/<项目>/DESIGN.md`、`designs/<项目>/*.html`、`designs/<项目>/3c-GPT参考版.md` | +| ④ | 原型内嵌说明区（写进 `designs/<项目>/*.html` 自身）＋ 独立产品文档 `designs/<项目>/产品文档.html` | ### 文档的两态：当前版与过期版 @@ -142,16 +145,18 @@ DESIGN.md 说明：`@google/design.md` 提供 `lint` / `diff` / `export` / `spec | 你说什么 | 模式 | 从哪开始 | |---|---|---| -| 「规划 XX」「从零做 XX」 | 全流程（自动处理） | `stage-discovery` → `stage-requirements` → `stage-delivery`，一路跑完，段间不停下来问（含①段末） | -| 「先确认方案」「跑完方案停下等我」「规划 XX，先给方案」 | 方案确认 | 同一套三段，唯一差别是①段末停下等你确认方案，确认后才进②③ | -| 「只做产品需求」「只做产品功能」「只做界面交互」 | 单段 | 只调对应那一个 stage skill，不展开其他段 | +| 「规划 XX」「从零做 XX」 | 全流程（自动处理） | `stage-discovery` → `stage-requirements` → `stage-delivery` → `stage-proto-doc`，一路跑完，段间不停下来问（含①段末） | +| 「先确认方案」「跑完方案停下等我」「规划 XX，先给方案」 | 方案确认 | 同一套四段，唯一差别是①段末停下等你确认方案，确认后才进②③④ | +| 「只做产品需求」「只做产品功能」「只做界面交互」「只做原型说明文档」 | 单段 | 只调对应那一个 stage skill，不展开其他段 | | 已有②段，要出原型 | 单段 | 直接调 `stage-delivery`，从它的 3a 起 | +| 已有原型，要补说明 | 单段 | 直接调 `stage-proto-doc`，从它的 4a 起 | | 只问某个单点 | 单段 | 不跑任何段，在对应 stage skill 内点名子步，或直接说要看哪份方法论 | -「只调一段」成立的原因：三段之间只通过落盘文件耦合，没有隐式状态。 +「只调一段」成立的原因：四段之间只通过落盘文件耦合，没有隐式状态。 - ②只读 `docs/pm/<项目>/research/*`；缺失时标注 `【假设】`继续，不催促回补① - ③只读 `docs/pm/<项目>/prd/*`；缺失时同样标 `【假设】`继续 +- ④只读 `designs/<项目>/*.html`（界面事实的唯一依据），另按需读 `docs/pm/<项目>/prd/*` 与 `research/1a-需求文档.md` 定业务意图；缺失时标 `【假设】`继续，并在段末偏离单里写明 ## 执行规则 @@ -160,7 +165,7 @@ DESIGN.md 说明：`@google/design.md` 提供 `lint` / `diff` / `export` / `spec | 模式 | 段之间 | 段之内 | |---|---|---| | 全流程（自动处理） | 一路跑完，段间不停下来问（含①段末）。每段结束按「标准收尾格式」输出一段报告，输出完即刻进下一段 | 子步之间不反问，做完直接进下一个子步 | -| 方案确认 | 与全流程完全相同，只有一处不同：①段末停下等你确认方案；确认后②③一路跑完、段间不停 | 同上 | +| 方案确认 | 与全流程完全相同，只有一处不同：①段末停下等你确认方案；确认后②③④一路跑完、段间不停 | 同上 | | 单段 | 不涉及 | 不越界，不催促回补前段 | 这两条是全流程模式下的两个独立分支，不要混：全流程（自动处理）没有①段末的强制停；「停下等确认方案」只在「方案确认」模式下发生。二选一由用户定（界面里点【生成原型和文档】时选「自动处理」或「先确认方案」，或在会话里直接说明）；用户没明说时按自动处理走，不要在自动处理模式下自作主张停下来问。 @@ -235,16 +240,18 @@ DESIGN.md 说明：`@google/design.md` 提供 `lint` / `diff` / `export` / `spec - 只跑一次 `grill-me`：①没定义需求就去取证，或②拿①段的需求定义代替功能压测直接写②段 - 把自动补全当默认动作：用户没说话就替用户拍板，还没标 `【假设】`、没进待复核清单 - 手写 Mermaid 代替 diagram-design，手写 token 表代替 DESIGN.md -- 绕过三段自己手搓，或重写它们的内容（该调 `stage-*` 就调） +- 绕过四段自己手搓，或重写它们的内容（该调 `stage-*` 就调） - 把供给件的内部路径按本 skill 目录去拼，或改它们的正文 —— 供给件指③段自带的 `oil-ui-pro`，以及 §供给 各档落在 `assets/` 下的件（它们是随③段携带的供给件，改动只写 `stage-delivery` 自己的 `SKILL.md` / `references/`；默认档与可选档平行，不缝成一条流水线，也不把 `oil-ui-pro` 的评分循环当成本段 Gate 的替代） - 猜 `<项目>`：定不出来还硬写，把产物落到别的项目目录下 - 把 `DESIGN.md` 写到仓库根：多项目会互相覆盖 - 段间停下来问「要不要继续」：全流程（自动处理）模式下直接进下一段，只在段末输出报告 -- 把两种模式混用：在自动处理模式下自作主张停下问方案，或在「方案确认」模式下确认前就开跑②③ +- 把两种模式混用：在自动处理模式下自作主张停下问方案，或在「方案确认」模式下确认前就开跑②③④ - 在「方案确认」模式下把①段的方案当成已确认就往下跑：该模式下①段末必须停下等用户确认（含「不做什么」） -- 下游擅自裁剪上游已拍板项：②③发现要砍①段或决策表里已拍板的东西时，不许自行裁掉或改口径，必须列成「与已定决策的差异」交用户显式确认 -- 把模式当成段：模式是「要不要在①段末停」的开关，不是第四个段，别为它单独造段或造产物 +- 下游擅自裁剪上游已拍板项：②③④发现要砍①段或决策表里已拍板的东西时，不许自行裁掉或改口径，必须列成「与已定决策的差异」交用户显式确认 +- 把模式当成段：模式是「要不要在①段末停」的开关，不是第五个段，别为它单独造段或造产物 - 跑了却不说：没声明当前段 / 子步与依据文件，或偏离了被调 skill 的主流程却不声明、不记偏离单（应为：开工先声明、每个子步再声明、偏离当场声明） +- 让③段顺手把说明区或产品文档写了（那是第④段 `stage-proto-doc` 的活） +- ④段里重新规划产品、重新设计界面，或写原型上没有的页面 / 功能 / 业务规则（④段只解释与记录**现有**原型） - 问外部模型时堆砌背景：把过程留痕、废弃做法、内部约束清单整段贴进去（应按「征询外部模型（GPT）的提问口径」只给关键背景 ＋ 明确问题） ## 改名 / 改供给后的自检 @@ -253,7 +260,7 @@ DESIGN.md 说明：`@google/design.md` 提供 `lint` / `diff` / `export` / `spec python scripts/check_naming.py --ws <工作区> ``` -它查三段段名与子步名在「总入口 ↔ 各段 `SKILL.md` ↔ 各段 `references/`」之间有没有漂，包括 H1 与子步表是否一致、总入口子步列有没有漏项、runbook 必读表有没有引用已移除的资产、两份副本是否一致。纯静态比对，不需要渲染，不需要外部依赖。 +它查四段段名与子步名在「总入口 ↔ 各段 `SKILL.md` ↔ 各段 `references/`」之间有没有漂，包括 H1 与子步表是否一致、总入口子步列有没有漏项、runbook 必读表有没有引用已移除的资产、两份副本是否一致。纯静态比对，不需要渲染，不需要外部依赖。 为什么必须有它：实测当天漏过两次，当时没有任何门禁会报错。 @@ -261,7 +268,7 @@ python scripts/check_naming.py --ws <工作区> 第二次（2026-10-06）：②段收窄为「只细化功能」（7 份产出变 1 份）后，各段 `SKILL.md` 都改了，但总入口的三处仍写着旧结构——四段表的②段子步列仍是「2a 功能定义与压测 / 2b 功能流转 / 2c 功能图示」，四段表的①段子步列「1c 产品定位与商业设计」未随段内改名（段内已改称「产品定位与场景」），正文仍写「①与②各跑一次 `grill-me`」并指向两份同名文档，实际全场只有①段一份。闸门当场报 6 个 FAIL，根因是「改了承载段、忘了总入口」。 -由此立一条硬纪律，与「换供给不能只改承载段」同型：凡改子步结构 / 段内产出清单 / 段间交接口，必须连带改总入口 `product-planning/SKILL.md` 的「三段结构」表与「交接口」表，不改就是半改状态。 +由此立一条硬纪律，与「换供给不能只改承载段」同型：凡改子步结构 / 段内产出清单 / 段间交接口，必须连带改总入口 `product-planning/SKILL.md` 的「四段结构」表与「交接口」表，不改就是半改状态。 改了段名 / 子步名 / 判据供给源之后必须跑一次，并把结果记进当日 memory。改完不校验，下次读契约的人拿到的是错的配方。 diff --git a/product-planning/references/_留痕/stage-proto-doc-SKILL-20261014-替换前.md b/product-planning/references/_留痕/stage-proto-doc-SKILL-20261014-替换前.md new file mode 100644 index 0000000..8c70891 --- /dev/null +++ b/product-planning/references/_留痕/stage-proto-doc-SKILL-20261014-替换前.md @@ -0,0 +1,86 @@ +--- +name: stage-proto-doc +description: 产品规划第④段，原型说明文档。在已交付的原型 HTML 上补说明区：第一层轴默认按用户路径分段（也可按③段原型的实际状态，状态名一律以原型为准），每段下按「使用场景 → 从左到右流程图 → 步骤说明（功能作用 / 输入边界 / 异常情况）」铺开，并给每条流程配逐步骤的演示引导。当用户要给原型加功能说明区、写原型说明文档、做操作指引演示，或说"只做原型说明文档"时调用。 +--- + +# ④ 原型说明文档 + +回答"第一层轴怎么分段、每段有哪些场景、每个场景怎么走、每一步到底做什么、边界在哪、坏了会怎样"。 + +产出长在原型 HTML 自身（`designs/<项目>/*.html`），不额外落 md，免得两处维护、说法对不上。 + +顺序 4a → 4b → 4c。说明区先齐，再挂演示引导。 + +> 表格「读」列是该方法论文档，相对路径的基准是本 skill 目录。执行子步前先读它。 + +## 输入 + +| 来自 | 读什么 | 用来定什么 | +|---|---|---| +| ③ | `designs/<项目>/*.html` | 要挂说明区的原型本体；状态数与状态名以它为准 | +| ② | `docs/pm/<项目>/prd/2a-产品功能.md` · `docs/pm/<项目>/prd/2b-界面布局.md` | 术语口径、状态流转、异常路径、页面骨架 | +| ① | `docs/pm/<项目>/research/1d-产品策略.md` | "不做什么"的边界，说明区不得写出范围外的能力 | + +上游缺失时标 `【假设】`继续，不强制回补。 + +## 4a 场景盘点 + +| 子步 | 读 | 产出 | +|---|---|---| +| 场景盘点（必做，最先） | `references/doc-area-spec.md` | 第一层轴 × 使用场景清单 | + +**第一层轴怎么定**：默认按**用户路径**编排 —— 用户从进来到交付要走过的几段（例：定先决条件 → 交待素材 → 出稿 → 只修局部 → 交付）。 +**界面状态数与状态名一律以③段原型的实际为准**，⛔ 不许硬套「正常态 / 加载中 / 空态 / 加载失败」四态；原型里有几个状态就盘几个， +状态降级成场景上的一枚徽标即可（同一场景只属于一段）。无论用哪种轴，都不许只写正常路径。 +场景粒度是"人要完成的一件事"，不是"一个按钮"。典型一条：拿到一批数据 → 判一条 → 遇到没跑完的怎么办 → 批量的影响范围 → 筛不到东西时。 + +## 4b 说明区 + +读 `references/doc-area-spec.md`，按它给的层级与交互铺： + +1. 说明区挂在原型对应位置的下方，随当前所在的那一段（或状态）一起变 +2. 每个场景一条：可点开，点开后是该场景的从左到右流程图（序号节点 + 箭头） +3. 点流程里的某一步，在流程图下方出该步说明，固定三段：功能作用 / 输入边界 / 异常情况 +4. 同级单开：一次只展开一个场景、一次只选中一个步骤；再点已选中的步骤即收起 + +三段缺一不可，且必须是对着原型实测过的事实，不是套话： + +| 段 | 写什么 | 判定标准（可核对） | +|---|---|---| +| 功能作用 | 这个组件做什么、给谁看、落笔后产生什么 | 换一个组件，这句话就不成立 | +| 输入边界 | 取值域 / 上限 / 前置条件 / 可选与必填 | 能说出"什么不被接受"或"最多几条" | +| 异常情况 | 失败 / 空 / 禁用 / 重复提交 / 文案红线 | 至少覆盖一种"坏了怎么办"，且给出恢复路径 | + +## 4c 演示引导 + +读 `references/guided-tour.md`，给每条流程挂"演示"按钮： + +1. 每个步骤补三样数据：`target`（要高亮的选择器）、`setup`（这一步的前置条件）、`hint`（操作指引，与功能说明 `desc` 分开写） +2. 演示按 `上一步 / 下一步 / 完成` 逐步骤推进，气泡给"第 N / M 步" +3. 纯概念步骤不给 target，不参与演示，按钮置灰并写明原因 + +## 硬约束 + +- 说明区是非产品功能，它是原型的自解释注解层。交付时要明说，别让人误以为产品里真有一个说明页。 +- 只有原型上有的事实才许写。每一段说明都要能在原型里点到对应元素；写不出 `target` 的步骤，要么承认是概念步骤，要么回去改原型。 +- 不得把自动结论表述为人工认可（红线，本项目实测抓过）：机器判定只能说"进入队列 / 待人工逐条查看"，不许写成"通过 / 已认可"。 +- 文案口径跟②段走。同一个概念在说明区与②段里必须同名，冲突时改说明区。 +- 4c 交付前必须浏览器实测，逐步骤真点一遍，走完全流程再退出。未跑实测不得报完成。 +- 段内子步之间不反问，做完直接进下一个子步；**停线规则**见 `product-planning` 的「执行规则」，⛔ 本段不复述。 +- `<项目>` 按 `product-planning` 的「项目与路径约定」定；定不出来就停下问用户，不许猜。 + +## 完成标准 + +- 原型的每个状态都有场景，四态齐备（缺哪个要写明为什么） +- 每个场景有从左到右流程图，每个步骤都有 `功能作用 / 输入边界 / 异常情况` 三段且非空 +- 演示引导能从第一步走到完成，退出后界面回到演示前（含筛选、抽屉） +- 有实测回报（走过的步骤数、失败项、控制台报错原文） + +## 反面清单 + +- 只写正常路径，跳过加载 / 空 / 错误三个状态的说明 +- 三段说明写成语义重复的三句话，或整段是"该功能可以提升效率"这类空话 +- 把演示引导做成遮罩弹窗，挡住它要教人点的那个东西 +- 演示中途改动了用户的筛选 / 抽屉，退出后不还原 +- 概念步骤硬凑一个 target，或演示到一半被判"元素不可见"直接结束 +- 只写说明区就报完成，没跑过逐步骤实测（自查看不出死按钮） diff --git a/product-planning/references/stage-delivery/SKILL.md b/product-planning/references/stage-delivery/SKILL.md index a943228..68d7102 100644 --- a/product-planning/references/stage-delivery/SKILL.md +++ b/product-planning/references/stage-delivery/SKILL.md @@ -8,9 +8,9 @@ description: 产品规划第③段，界面交互。设计工程供给默认来 回答两个问题：长什么样、怎么操作。产出 `docs/pm/<项目>/DESIGN.md` 与 `designs/<项目>/*.html`。 > 段名为什么是「界面交互」（2026-10-02 定）： -> 删「交付」：①②③都产出落盘文件，「交付」是三段共有的属性，不是③的专属，留着会让人以为③管完就结束了。 +> 删「交付」：①②③都产出落盘文件，「交付」是三段共有的属性，不是③的专属；④段也在交付（说明区与独立产品文档），留着会让人以为③管完就结束了。 > 补「交互」：本段原先只讲「长什么样」，可 3b 原型硬要求每个按钮、每个跳转都真能走（`:236`），3c 的参考版对照也要逐项看空态 / 加载 / 错误 / 反馈（`:148`、`:150`）。交互判据一直在做，却没有名字，补上才与本段实际职责相符。 -> ⚠️ 2026-10-14 变更：原先还有一条「与④段的界：③造物、④描述物」，因④段整段删除，该条一并撤掉。③段仍是最后一段，3d 完就交付原型本身。 +> 与④段的界：③造物（界面与交互本身），④解释与记录（说明区与独立产品文档，只记现有原型、不重新设计）。 > `<项目>` 按 `product-planning` 的「项目与路径约定」定；定不出来就停下问用户，不许猜。`DESIGN.md` 放项目目录，不放仓库根，避免多项目互相覆盖。 @@ -328,7 +328,7 @@ Gate-1 方向门（硬闸，不可跳）——按本表逐项自检（字段定 - 3b 交付前必须用 `browser-harness` 跑实测；脚本查不出死按钮，未跑实测不得进 3c，不得报完成。 - 3c GPT 参考版必做：原型初稿 + 实测过后立刻做，不许用「我觉得没问题」代替。参考版原文（三句话说明 ＋ 完整 HTML）必须落盘，不得伪造或转述失真；未取得参考版时要在 `3c-GPT参考版.md` 与收尾里明示，未取得不等于已通过。贴进去的需求与风格文本先脱敏。 - Gate-2 / Gate-3 不许口头通过：阻断项要么修完，要么留痕；「未取得审查」不等于已通过。 -- 3d 完就交付原型本身；本段是最后一段，原型之外不再有说明区那一层（原④段已于 2026-10-14 删除）。 +- 原型的说明区与独立产品文档不是本段的事：由第④段 `stage-proto-doc` 负责。3d 完就交付原型本身。 - `DESIGN.md` 落 `docs/pm/<项目>/`，不放仓库根。 - 段内子步之间不反问，做完直接进下一个子步。停线规则（哪几种情况停、怎么判）见 `product-planning` 的「执行规则」—— ⛔ 本段不复述，免得两处漂。 - `<项目>` 按 `product-planning` 的「项目与路径约定」定；定不出来就停下问用户，不许猜。 @@ -370,6 +370,7 @@ Gate-1 方向门（硬闸，不可跳）——按本表逐项自检（字段定 - 把「未取得外部审查」当已通过 - 工具型页面做**逐区块**的入场编排；用 `linear`/`ease` 做过渡曲线；用 `@keyframes` 做交互过渡 - 越界回头改②段的功能取舍（那是第②段）——⚠️ 但「骨架缺板块」是例外：必须回②段改，⛔ 不许就地在原型里加 +- 顺手把说明区 / 独立产品文档写了（那是第④段 `stage-proto-doc`） ## 待补（2026-10-02 登记 · 2026-10-06 更新） @@ -378,6 +379,6 @@ Gate-1 方向门（硬闸，不可跳）——按本表逐项自检（字段定 ⛔ 修复后的纪律：判据来源必须单一可查。某条判据若在 runbook 与 craft 各有一份且口径不同，以本项目追加条为准，并在 §3.4 显式标注「本项目追加」。 - ~~工具型页面的版式库~~：已于 2026-10-02 补齐。新建 `references/layouts-tooling.md`，四类形态各给一份可判定骨架：行式列表 / 表格式清单 / 详情面板 / 主从侧区。每类带形态判定句（判不出形态就去改 D0 `结构骨架`）＋ 可机械核对的判定要点（如「一屏可见行数 ≥6」「数字列右对齐」「表头必须写判据来源」「未跑必须能作为取值存在」）。已接进三处：3b 正文（形态判定先行）｜runbook §1 必读表 D2 行（工具型另读）｜runbook「⛔ 四样 craft 接不住」表（第四行）。 ⭐ 红线：⛔ 不许拿营销页骨架顶替工具型，那是「没做形态判定」的默认行为，等于退回 18 轮前的病根。 -- ~~①②段的同型改造~~：已于 2026-10-02 完成。四段已改名为「①产品需求 / ②产品功能 / ③界面交互 / ④原型说明文档」，并各自重划了子步职责（见 `product-planning` 的四段表与交接口表）。⚠️ 其中④段已于 2026-10-14 整段删除（用户令），现为三段。 +- ~~①②段的同型改造~~：已于 2026-10-02 完成。四段已改名为「①产品需求 / ②产品功能 / ③界面交互 / ④原型说明文档」，并各自重划了子步职责（见 `product-planning` 的四段表与交接口表）。⚠️ 其中④段 10-14 删过旧版、10-15 用备份里的新版装上，段名未变。 - ⛔ 骨架归属已于 2026-10-06 反转：本节原口径是「页面结构归本段，唯一落点是 D0」；用户定案改为「②段钉骨架，③段做皮肉」（原话：页面关系和布局必须在第二步确认清楚，不然第三步没有方向 一会一个样子）。⇒ `必要内容` / `结构骨架` 两个字段口径已调整，从「本段独立裁决」改为「在②段给定骨架之内决定视觉与交互实现」。详见本文件开头「⭐⭐ 页面骨架不归本段了」块。 ⚠️ 待核：`references/execution-runbook.md` 的 D0 段仍写着旧口径（「独立推导几个页面」），需同步改。另，`gate-<段号>-<段名>.md` 本项目从未建立，属存量缺口。 \ No newline at end of file diff --git a/product-planning/references/stage-discovery/SKILL.md b/product-planning/references/stage-discovery/SKILL.md index f374128..5fd4903 100644 --- a/product-planning/references/stage-discovery/SKILL.md +++ b/product-planning/references/stage-discovery/SKILL.md @@ -7,7 +7,7 @@ description: 产品规划第①段，产品需求。五个子步依次产出五 回答"做什么、为谁、为什么值得做"。产出只有五份，全部落 `docs/pm/<项目>/research/`。 -> 段名定为「产品需求」（2026-10-02 定）：本段 1b 做调研，1d/1e 定产品策略与场景，"调研"盖不住后半截，还会让②段的"需求"二字失去归属。三段各占一个词：产品 / 功能 / 界面。 +> 段名定为「产品需求」（2026-10-02 定）：本段 1b 做调研，1d/1e 定产品策略与场景，"调研"盖不住后半截，还会让②段的"需求"二字失去归属。四段各占一个词：产品 / 功能 / 界面 / 说明。 ## ⭐⭐ 产出白名单（2026-10-06 用户定案 · 硬规矩） @@ -224,6 +224,6 @@ description: 产品规划第①段，产品需求。五个子步依次产出五 - 凭空给 Importance / Satisfaction 打分：没有任何数据源支撑的数字，不许出现在交付物里 - 五份没过「说人话」内容准则就落盘 —— 口径与门槛见 `product-planning` 的「执行规则」内容准则条 - 把推演出来的用户画像当用研结论进 1c——三个 JTBD 若都追不到一句用户原话，那是自证不是用研 -- 越界去写②段或出原型（那是第②③段） +- 越界去写②段、出原型或写原型说明文档（那是第②③④段） 📎 本段删过的产出与方法论（原产出长什么样、为什么删、原反面清单里被撤掉的那一条）见 `_留痕/①段-已删除产出与方法论.md`，正文不展开；防复活由 `scripts/check_naming.py` 的 `DEAD_OUTPUTS` 机器判。 diff --git a/product-planning/references/stage-proto-doc/SKILL.md b/product-planning/references/stage-proto-doc/SKILL.md new file mode 100644 index 0000000..14e2fec --- /dev/null +++ b/product-planning/references/stage-proto-doc/SKILL.md @@ -0,0 +1,172 @@ +--- +name: stage-proto-doc +description: 产品规划第④段，原型说明文档。在③段已跑通的原型 HTML 上补说明区，并产出一份能独立阅读的产品文档：第一层轴默认按用户路径分段（也可按原型的实际状态，状态名一律以原型为准），每段按「需求列表（表格）→ 用户场景 → 操作流程 → 功能」四块铺开。当用户要给原型加功能说明区、写产品文档、做操作指引演示，或说「只做原型说明文档」时调用。 +--- + +# ④ 原型说明文档 + +## 定位 + +- 本段解释和记录**现有**原型：不重新规划产品，不重新设计界面。 +- 交付两份产物：原型内嵌说明区、可独立发送的产品文档。两份共用同一套编号、场景、流程与功能定义。 +- 原型是界面行为的核对依据；①段的决策表与②段的功能清单是业务意图的补充依据。 +- **第一层轴**默认按用户路径分段（例：定依据 → 交待素材 → 出稿 → 只修局部 → 交付）；也可以按③段原型的实际状态分段，**状态名一律以原型为准**，原型里有几个状态就写几个。 +- 说明区是注解层，不是产品功能。交付时明说，免得让人以为产品里真有一个说明页。 + +## 输入 + +| 来自 | 读什么 | 用来定什么 | +|---|---|---| +| ③ | `designs/<项目>/*.html` | 界面事实的唯一依据：页面、模块、控件、状态、交互、跳转、反馈 | +| ② | `docs/pm/<项目>/prd/2a-产品功能.md` · `prd/2b-界面布局.md` | 术语口径、优先级、功能条目编号 | +| ① | `docs/pm/<项目>/research/1a-需求文档.md` | 需求来源与「不做什么」的边界 | + +- 原型是界面事实，需求资料只定业务意图；两者冲突时显式记录，不静默选一个。 +- **上游缺失时**：先把缺的那一段补出来（②段缺失就先要一份最小术语表）；用户不要补，就在文档里逐处标 `【假设】`，并在段末的偏离单里写明「本段未判术语一致」。 +- `<项目>` 按 `product-planning` 的「项目与路径约定」定；定不出来停下问用户，不猜。 + +顺序 4a → 4b → 4c。说明区先齐，再挂演示引导。 + +## 4a 场景盘点（必做，最先） + +读 `references/doc-area-spec.md`。产出：第一层轴 × 使用场景清单，并给每条场景占好关联的需求编号。 + +## 4b 说明区（两份产物） + +读 `references/doc-area-spec.md` 铺框架，读 `references/doc-language-spec.md` 定语言：两份产物写完后，逐句过它第五节的自检清单。 + +**产物 A · 原型内嵌说明区** + +- 写进原型 HTML 自身，不依赖外链。 +- 放在原型对应位置的下方，随当前所在的那一段一起变。 +- 含需求索引、用户场景、操作流程、功能说明四块。 +- 不覆盖业务区域，不改既有交互逻辑；原型结构不适合直接嵌入时，给可插入的 HTML 片段与插入位置。 + +**产物 B · 独立产品文档** + +- 单独一个 HTML 文件，落 `designs/<项目>/产品文档.html`，双击能开，能单独发给不看原型的人。 +- 四块顺序固定，另加附录「原型页面地址」。 + +## 4c 演示引导（可选） + +读 `references/guided-tour.md`，给每条流程挂「演示」按钮。**用户不要演示时整体跳过**，跳过就在段末写明「本段未做演示引导」，完成标准里对应的那几条一并免检。 + +## 产品文档框架（四块 ＋ 一附录） + +### 一、需求列表（表格） + +一行 = 一条需求 = 一个用户场景。列：序号／需求／环节／优先级／本期做不做／对应功能。 + +- 每行只描述一条可独立识别的需求。 +- 序号用 `R001`、`R002`…… 全篇唯一且连续；**需求条数 = 不同编号的数量**。 +- 环节指向第一层轴里的某一段，名称与那一段一致。 +- 优先级用统一等级，不留空。 +- 「本期做不做」只填「是／否／待确认」。 +- 「对应功能」引用功能章节里真实存在的编号与名称。 + +### 二、用户场景 + +每条需求一段，四行写完：场景名（关联需求 R00x）／前提／目标／原型位置。 + +- 场景名描述「人要完成的一件事」，不写模块名。 +- 前提写明任务开始时成立的条件。 +- 目标能通过一个明确结果判断是否完成。 +- 原型位置写到「页面 → 模块 → 控件或状态」，能在原型上点到。 + +### 三、操作流程 + +每个场景一条从左到右的步骤链，2–6 步，一步一行：序号／这一步做什么（动词开头，并写出可观察的界面结果）。 + +- 起点满足场景前提，终点对应场景目标。 +- 步骤里的按钮、菜单、字段、状态名称与原型逐字一致。 +- 流程里不出现原型没有、也没确认过的操作。 + +### 四、功能 + +每项功能五项，缺一项不算写完：功能名（功能编号 F00x）／做什么／入口在哪／输入边界／异常与恢复。 + +- 功能名与原型界面上的叫法一致。 +- 「做什么」写处理行为与可观察结果，不写功能口号。 +- 「入口在哪」给到可定位的页面与控件。 +- 「输入边界」覆盖输入类型、必填、格式、长度、范围；无输入的功能写「无用户输入」。 +- 「异常与恢复」写异常触发条件、界面反馈、恢复操作；原型没体现就写「原型未体现」，不写成已实现。 + +### 附录 · 原型页面地址 + +逐个列出原型文件路径，以及各页面干什么。 + +## 编号与关联 + +- 需求 `R001`…、场景 `S001`…、功能 `F001`…，各自全篇唯一。 +- 同一场景、同一功能在不同章节重复出现时复用同一编号。 +- 每条需求至少关联一项功能，没落实的标「未映射」。 +- 功能可以服务多条需求；多对多时逐项列出关联编号。 +- 页面、模块、控件的数量不等于需求数量。 + +## 语体口径 + +- **完整规范读 `references/doc-language-spec.md`**：术语来源优先级、逐条禁用清单、五组对错对照、以及一份逐句自检清单。写每一句都照它过，自检任一项不通过就改。 +- 元信息（条数、口径、读法）写进表格的列、条目的字段或表头里；标题后面与标题下面都不另起说明行（踩过的坑：在标题下用小字解释「这一节是什么、为什么这么排」，2026-10-14 用户第三次点名，前两次分别是原型的状态小字与章节注解）。 +- 客观、书面的说明文，一句话只表达一个主要意思。 +- 用确切的页面名、模块名、控件名、状态名与业务术语；同一个概念全篇同名。 +- 描述行为用可验证的动词：显示、输入、选择、提交、生成、跳转。 +- 区分「已实现／未实现／待确认」三种状态，各写各的。 +- **禁用清单**：营销话术、主观评价、模糊程度词（大概、尽量、适当）、无依据的效果承诺、「相关页面／适当提示／处理异常」这类无法定位的说法、第一人称、比喻、空转评价（「值得注意的是」「具有重要意义」）。 +- 缺失信息明确标记，不用推测性描述填空白。规则文件本身也用这套语体写。 + +## 硬约束 + +- 只用原型上真实存在的事实；每条说明都能在原型上指到对应元素。 +- 不擅自新增页面、功能、需求、业务规则或交互。 +- 把静态展示与真实数据处理能力分开写；把模拟数据、模拟提交、演示反馈与真实后端能力分开写。 +- 把计划实现与已实现分开写。 +- 不遗漏编号，不重复分配编号。 +- 两份产物的名称、编号、范围、入口、行为描述必须一致。 +- 说明区不依赖外链，不破坏原型原有功能。 +- 原型与需求资料的差异显式记录。 +- 自动结论不写成人工认可：机器判定只能说「进入队列／待人工逐条查看」，不写成「通过／已认可」。 +- 段内不反问，做完直接进下一个子步；停线规则见 `product-planning` 的「执行规则」。 +- 原型是生成物时，改动走它自己的生成链，不手改产物。 + +## 完成标准 + +- 独立产品文档含规定的四块＋附录，顺序固定，双击能开。 +- 原型内嵌说明区能在原型里直接找到并读到。 +- 每条需求有唯一编号、优先级、本期范围、功能映射状态。 +- 每条需求至少一条场景，每个场景一条流程，每条流程 2–6 步且能在原型中逐项核对。 +- 每项功能含名称、职责、入口、输入边界、异常与恢复五项。 +- 引用的编号都存在，编号唯一性成立。 +- 两份产物没有互相矛盾的描述。 +- 未确认事项都有标记，并在段末列出待确认清单。 +- 原型原有页面与交互通过回归检查。 + +## 自查清单 + +- [ ] 输入原型能运行、关键交互能走完 +- [ ] 实际实现／模拟行为／待确认三者的界线划清了 +- [ ] 需求列表一行一条、编号唯一且可数 +- [ ] 需求／环节／优先级／本期范围／对应功能五列都填了 +- [ ] 每条需求至少展开一个场景 +- [ ] 场景有前提、目标、原型位置、需求关联 +- [ ] 每个场景一条流程，每条 2–6 步 +- [ ] 每项功能五项齐全 +- [ ] 界面名称与原型逐字一致 +- [ ] 失效编号、孤立功能、未映射需求已清理 +- [ ] 两份产物同一套定义、可相互核对 +- [ ] 说明区没破坏原型运行 +- [ ] 上游缺失处已标 `【假设】` 并写进偏离单 +- [ ] 未做演示引导时已写明并免检对应条目 + +## 反面清单 + +- 只写页面介绍，不写需求、场景、流程和功能 +- 用功能模块代替需求，需求条数没法统计 +- 用「用户使用系统」这类泛化描述代替具体场景 +- 用「点击按钮后完成操作」代替可核对的步骤与结果 +- 用「支持多种格式」代替明确的输入边界或待确认标记 +- 用「发生错误时提示用户」代替异常条件、反馈和恢复路径 +- 把原型里的静态假数据写成真实业务数据 +- 把未实现、未验证、未定义的行为写成既有能力 +- 两份产物里功能名称、编号或流程对不上 +- 改原型业务逻辑去迎合文档描述 +- 以篇幅、术语数量或排版代替可验证的完整性 diff --git a/product-planning/references/stage-proto-doc/references/doc-area-spec.md b/product-planning/references/stage-proto-doc/references/doc-area-spec.md new file mode 100644 index 0000000..e274df7 --- /dev/null +++ b/product-planning/references/stage-proto-doc/references/doc-area-spec.md @@ -0,0 +1,75 @@ +# 原型说明区规范 + +> 本文件是 `stage-proto-doc` 的方法论文档，由模型按需加载，没有斜杠命令。 + +## 定位 + +说明区是原型自带的注解层，不是产品功能。它不回答"长什么样"，回答的是： + +> 站在这个界面上，我这一步在干什么、我能输入什么、什么情况下它不给好脸色。 + +所以它必须贴在原型对应位置的下方，随当前所在的那一段（或状态）标出。抽出来写一份独立文档，读者就得自己脑补对应关系。 + +## 层级 + +``` +第一层轴（默认＝用户路径段；也可按③段原型的实际状态。 + 状态名以原型为准，⛔ 别硬套「正常态 / 加载中 / 空态 / 加载失败」） +└── 使用场景（人要完成的一件事，可点开） + ├── 场景引言（一句话：什么前提下、要达成什么） + ├── 从左到右的流程图（序号节点 + 箭头，横向可滚动） + └── 步骤说明（点某一步 → 在流程图下方出三段） + ├── 功能作用 + ├── 输入边界 + └── 异常情况 +``` + +四层各管一段：状态说"界面此刻处于什么处境"，场景说"人在这个处境下想干成什么"，流程说"这件事分几步走"，步骤说明说"这一步的职责与边界"。少任何一层，读者都会拿别层的信息去补，然后补错。 + +## 场景怎么写 + +- 粒度是"人要完成的一件事"，不是一个按钮。"提交驳回"不算场景，"驳回一条片段并完成失败模式归类"才算。 +- 一个状态下的场景数控制在 2–4 个。1 个说明不了分支，5 个以上就该拆状态。 +- 顺序按发生频率排，不按界面从上到下排。 +- 引言一句话写清前提。例："预审排队、执行中或失败时人工仍可决策，但必须清楚自己在无依据的情况下决策。" + +## 从左到右流程图 + +| 规则 | 说明 | +|---|---| +| 形态 | 横向 `ol`，每项 = 序号圆点 + 步骤名，项间一个 `→` 箭头 | +| 溢出 | 横向滚动，不换行——换行会读成两条并行流程 | +| 交互 | 点步骤 → 流程图下方出说明；再点收起；同级只选中一个 | +| 键盘 | 步骤是 `button`；`aria-current` 标当前项；说明区 `role="region"` 带 `aria-controls` | +| 箭头 | `aria-hidden`，它只是视觉连接符，不进朗读 | + +步数控制在 2–6 步：超过 6 步说明这个场景该拆，1 步说明它还不算流程。 + +## 步骤说明：三段 + +三段是固定骨架，不改名、不合并、不省段。 + +| 段 | 回答的问题 | 合格判据 | 不合格示例 | +|---|---|---|---| +| 功能作用 | 这一步做什么、给谁看、落笔后产生什么 | 换一个组件这句话就不成立 | "展示相关信息，提升审核效率" | +| 输入边界 | 取值域 / 上限 / 前置条件 / 必填与选填 | 说得出"什么不被接受"或"最多几条" | "支持筛选" | +| 异常情况 | 失败 / 空 / 禁用 / 重复提交 / 恢复路径 / 文案红线 | 至少一种"坏了怎么办"，且给出出路 | "暂不支持" | + +写输入边界，常见切入点：数量上限、字数或时长范围、哪些状态才可用、必填项有哪些、一次作用于一条还是全部。 +写异常情况，常见切入点：加载中能不能点、失败了怎么重试、重复提交怎么挡、空的时候显示什么、禁用要不要给原因、文案不能写成什么。 + +### 文案红线 + +- 不得把自动结论表述为人工认可。机器判定只能说"进入队列 / 待人工逐条查看"，不写成"通过 / 已认可 / 已确认"。 +- 不用无法区分成因的笼统文案。"暂无数据"要拆成"批次为空"与"筛选无结果"两条出路。 +- 不承诺原型里点不出来的能力。说明区每条都要能在原型上指到对应元素。 +- 异常态必须给恢复路径。只写"失败了"不算说明，要写清楚下一步按哪里。 + +## 自查（逐条打勾） + +- [ ] 第一层轴覆盖完整（用户路径的每一段、或原型实际有的每个状态都有场景），缺的写明原因 +- [ ] 第一层轴的每一段 1–4 个场景，每个场景 2–6 步 +- [ ] 每步三段齐全，且各自能通过上面的合格判据 +- [ ] 全文没有"通过 / 已认可"这类把机器结论说成人审的词 +- [ ] 每个禁用态都给了原因，每个异常态都给了恢复路径 +- [ ] 说明区文案与②段术语逐词一致 diff --git a/product-planning/references/stage-proto-doc/references/doc-language-spec.md b/product-planning/references/stage-proto-doc/references/doc-language-spec.md new file mode 100644 index 0000000..11c8503 --- /dev/null +++ b/product-planning/references/stage-proto-doc/references/doc-language-spec.md @@ -0,0 +1,322 @@ +# 产品文档语言规范 + +> 来源：ChatGPT 网页版（2026-10-14，会话 `6acf7fc1-8d10-83e8-b328-8e885f5efb8c`）。 +> 用法：写④段的两份产物时逐句过一遍；第五节自检清单任一项不通过就改。 +> 它管**语言**；文档骨架（需求列表／用户场景／操作流程／功能）见上一级 `SKILL.md`。 + +--- + +## 一、语体与句式 +### 1.1 语体要求 + +使用客观、正式、书面的说明文语体。 + +面向产品、开发、设计人员，确保读者不查看原型也能理解文档内容。 + +描述系统行为时使用可验证的事实，不使用主观评价或个人感受。 + +区分已实现行为、计划行为、未实现行为和待确认事项。 + +不使用聊天式表达、营销式表达、口号式表达或未经证实的效果承诺。 + +### 1.2 句式要求 + +一句话只表达一个主要意思。 + +一个句子只描述一个主要动作、判断、规则或结果。 + +存在多个独立动作时，拆分为多个句子，并按执行顺序排列。 + +存在条件关系时，明确写出条件和对应结果。 + +存在因果关系时，明确写出原因和结果，不使用含糊的连接词。 + +描述操作时，优先使用「操作主体＋动作＋对象＋结果」句式。 + +描述规则时，优先使用「适用条件＋处理规则＋预期结果」句式。 + +描述异常时，明确异常条件、系统反馈和恢复方式。 + +删除不影响事实含义的铺垫、重复解释和语气修饰。 + +不得为了追求简短而省略执行主体、操作对象、条件或结果。 + +### 1.3 句子验收标准 + +一个句子包含两个及以上可独立执行的动作时，拆句。 + +一个句子包含两个及以上独立判断条件时，按规则复杂度拆分或使用列表。 + +句子出现代词时，必须能够从当前句或明确的上下文唯一确定指代对象。 + +句子出现条件时，必须能够判断条件成立与不成立时的处理方式。 + +句子描述完成状态时，必须给出可观察或可判断的完成标志。 + +## 二、名词与术语 +### 2.1 术语来源优先级 + +按以下顺序确定文档中的术语： + +原型界面上实际显示的页面名、模块名、按钮名、字段名和状态名。 + +已确认的产品需求、功能定义及业务术语表。 + +行业内含义明确且与当前业务一致的通用术语。 + +无法从以上来源确认的术语，标记为「待确认」，不得自行创造。 + +### 2.2 界面名称使用规则 + +界面已有名称时，文档必须使用原名称，不得随意改写、缩写或替换同义词。 + +首次提及界面元素时，使用完整名称。 + +同一对象在全文中必须使用同一名称。 + +页面名、模块名、控件名、字段名和状态名不得混用。 + +界面名称与业务概念不一致时，分别说明界面名称和业务概念，不得强行合并。 + +原型中没有名称的元素，不得擅自赋予正式名称；必要时使用位置描述并标记「待命名」。 + +引用按钮、菜单、字段或状态时，使用其实际显示文本，并通过引号或上下文明确其为界面名称。 + +### 2.3 新术语与未知术语处理 + +新术语必须有明确的业务定义、使用范围和来源。 + +同一概念存在多个叫法时，确定一个标准名称，其余叫法仅在必要时作为别名说明。 + +不得通过拼接常见词语创造未经定义的产品术语。 + +不得将技术实现名称直接当作用户可见的功能名称，除非产品资料明确采用该名称。 + +不得把个人理解、推测或临时命名写成已确认的业务定义。 + +无法确认术语含义时，记录待确认事项，不得通过上下文猜测后直接定稿。 + +### 2.4 指代与缩写 + +不使用指向不明确的「它」「这个」「相关内容」「上述功能」。 + +可以唯一定位对象时，直接使用对象名称。 + +缩写首次出现时，应给出中文全称及必要的英文全称。 + +缩写在全文中必须保持一致，不得交替使用全称、简称和自造简称造成歧义。 + +## 三、禁用清单 + +以下词语和句式在正式产品文档中一律禁用。确需表达对应含义时，必须替换为明确、可验证的描述。 + +### 3.1 聊天式表达 + +「我们可以……」 + +「你可以……」 + +「用户只要……就行」 + +「点一下……」 + +「然后就……」 + +「这个地方……」 + +「这里的话……」 + +「其实就是……」 + +「简单来说……」 + +「大概是……」 + +「差不多……」 + +「之类的……」 + +「等等」「诸如此类」 + +### 3.2 空泛动词与模糊表达 + +「搞定」「弄好」「处理一下」 + +「做一下」「操作一下」「配置一下」 + +「支持相关操作」 + +「进行相应处理」 + +「展示相关信息」 + +「提供便捷能力」 + +「实现快速处理」 + +「优化体验」 + +「提升效率」 + +「满足用户需求」 + +「智能处理」「自动优化」——未明确处理规则时禁用。 + +「实时更新」「快速响应」——未定义时效或判定标准时禁用。 + +「灵活配置」「多种方式」「丰富内容」——未列出具体范围时禁用。 + +### 3.3 无明确依据的程度词 + +「非常」「特别」「极其」 + +「十分方便」「十分简单」 + +「更加友好」「更加完善」 + +「高效」「便捷」「流畅」 + +「强大」「先进」「全面」 + +「无缝」「极致」「完美」 + +「大幅提升」「显著改善」 + +「一键完成」「秒级完成」——未验证对应行为或性能时禁用。 + +### 3.4 含糊的指代与范围词 + +「相关页面」「对应位置」——未给出具体名称或路径时禁用。 + +「相应内容」「相关信息」——未说明具体对象时禁用。 + +「适当提示」「必要时处理」——未定义触发条件时禁用。 + +「部分数据」「一些情况」「某些用户」——未限定范围时禁用。 + +「正常情况下」「特殊情况下」——未定义条件时禁用。 + +「根据实际情况」「视情况而定」——未说明判断规则时禁用。 + +「等」「等等」——用于省略必要枚举项时禁用。 + +### 3.5 空泛承诺与无依据结论 + +「确保用户满意」 + +「保证数据准确」 + +「避免所有错误」 + +「全面覆盖用户场景」 + +「系统会自动处理所有问题」 + +「用户能够轻松完成全部操作」 + +「该功能已经成熟稳定」 + +「该设计符合所有用户习惯」 + +以上表述只有在具备明确的验证依据、适用范围和判定标准时，才可以改写为具体的事实或约束。 + +### 3.6 不合格句式 + +「用户进入页面后，可以看到很多信息。」 + +「系统会根据情况进行相应处理。」 + +「用户点击按钮，然后系统就会完成操作。」 + +「如果有问题，系统会给出提示。」 + +「该功能主要用于提升用户体验。」 + +「支持多种输入方式，满足不同用户需求。」 + +「出现异常时，用户可以自行处理。」 + +「页面包含账号、内容、数据等相关模块。」 + +这些句式缺少具体对象、条件、行为、结果或处理规则，不得直接用于正式文档。 + +## 四、对错对照 +### 第 1 组：操作说明 + +不规范： 用户点一下提交按钮，然后就可以完成创建。 + +规范： 用户点击「提交」按钮后，系统校验表单必填项。校验通过时，系统创建记录并显示提交结果。 + +### 第 2 组：页面说明 + +不规范： 这里可以看到账号的各种信息，方便用户进行管理。 + +规范： 「账号列表」显示账号名称、所属平台、运营状态和最近更新时间。用户可通过列表操作入口查看账号详情。 + +### 第 3 组：输入规则 + +不规范： 用户填写相关信息就行，格式不对的话系统会提示。 + +规范： 用户必须填写「账号名称」字段。字段长度限制及允许字符范围为待确认。输入校验失败时的提示文案和恢复方式为待确认。 + +### 第 4 组：异常处理 + +不规范： 如果操作失败，系统会进行相应处理，用户重新试一下即可。 + +规范： 操作失败时，系统应显示失败原因和可执行的恢复操作。失败提示、重试条件及数据保留规则尚未确认。 + +### 第 5 组：功能价值 + +不规范： 该功能可以帮助运营人员高效地管理内容，提升工作效率。 + +规范： 「内容列表」集中显示内容标题、发布平台、审核状态和计划发布时间。运营人员可在列表中筛选内容，并进入详情页查看单条内容。 + +## 五、自检清单 + +每句话必须逐项检查。任一项不通过，必须修改后再提交。 + +语体检查： 是否存在聊天用语、口号、营销话术或主观评价？存在即不通过。 + +单义检查： 一个句子是否包含多个可独立执行的动作或多个独立结论？存在且未清晰拆分时不通过。 + +对象检查： 是否能明确指出句子描述的用户、系统、页面、控件、数据或业务对象？不能明确指出时不通过。 + +术语检查： 页面名、模块名、控件名和状态名是否与原型一致？不一致且未经说明时不通过。 + +来源检查： 是否出现没有来源、没有定义或未经确认的术语？存在且未标记时不通过。 + +动作检查： 是否明确写出发生了什么操作或系统行为？仅写「处理」「支持」「实现」而没有具体行为时不通过。 + +条件检查： 是否存在「如果」「当」「在……情况下」等条件表达，却没有说明对应结果？存在即不通过。 + +结果检查： 是否声称操作完成，却没有可观察的结果或完成标志？存在即不通过。 + +边界检查： 是否使用「多种」「部分」「适当」「相关」等词，却没有给出具体范围？存在即不通过。 + +事实检查： 是否将模拟行为、计划能力或未验证规则写成已实现事实？存在即不通过。 + +异常检查： 是否只写「提示用户」或「进行处理」，没有明确异常条件和恢复路径？存在即不通过。 + +独立阅读检查： 不查看原型的产品、开发和设计人员，是否能根据描述定位对象并理解行为？不能时不通过。 + +一致性检查： 同一对象在全文中是否存在多个未经定义的名称？存在即不通过。 + +精简检查： 删除某个词句后，事实、条件、动作或结果是否完全不受影响？若不受影响，应删除该词句。 + +## 六、最终验收规则 + +文档中的每句话都必须通过第五节自检。 + +所有界面名称必须有原型或已确认资料作为依据。 + +所有业务规则必须有明确来源；无来源的规则标记为「待确认」。 + +所有操作说明必须明确操作对象和可观察结果。 + +所有异常说明必须明确触发条件、反馈和恢复方式；尚未定义的内容标记为「待确认」。 + +禁用清单中的表达不得直接出现在正式说明正文中，必要的引用、规则举例和本规范自身的说明除外。 + +任何无法判断真假的描述均不得作为已确认事实写入文档。 + +文档以准确、可定位、可验证、可独立阅读为合格标准，不以篇幅或修辞作为质量标准。 diff --git a/product-planning/references/stage-proto-doc/references/guided-tour.md b/product-planning/references/stage-proto-doc/references/guided-tour.md new file mode 100644 index 0000000..22ccc3b --- /dev/null +++ b/product-planning/references/stage-proto-doc/references/guided-tour.md @@ -0,0 +1,93 @@ +# 演示引导（操作指引） + +> 本文件是 `stage-proto-doc` 的方法论文档，由模型按需加载，没有斜杠命令。 + +## 它是什么 + +说明区把流程写清楚了，读者仍要自己在界面上找——"这条筛选在左栏还是顶栏？" + +演示引导在真界面上按步骤带一遍：点流程的「演示」，高亮框住这一步该动的元素，气泡给操作指引，`上一步 / 下一步` 推进，`完成` 收尾。 + +它同样是原型的注解层，不是产品功能。交付时要明说，不能让人以为产品里真有一个新手引导。 + +## 数据契约 + +每个步骤在原有字段外必须补三样，缺一样就演示不了： + +| 字段 | 作用 | 注意 | +|---|---|---| +| `target` | 要高亮的选择器 | 必须是当前状态下真实存在且可见的元素；纯概念步骤不给 `target` | +| `setup` | 这一步的前置条件 | 例：切到某条片段、填入某关键词、打开某抽屉。浮层类 setup 必须在设 `target` 之前执行，否则量不到 | +| `hint` | 操作指引：手该往哪放 | 与 `desc` 分开写。`desc` 回答"这是什么"，`hint` 回答"你要点哪"；两处写一样等于没写 | + +演示可用的步骤数 = 有 `target` 的步骤数。全场景没有可演示步骤时，按钮置灰并写明原因，不是点了没反应。 + +## 单步的执行顺序（照抄这个顺序） + +1. 收掉上一次留下的浮层（抽屉 / 弹窗 / 放大层），把临时筛选复位 +2. 应用本步 `setup`（切片段 → 重渲染 → 填筛选 → 开抽屉） +3. 把说明区同步选中到这一步，并展开它所在场景 +4. 记下 `target`，滚动到它可见处 +5. 画高亮环与气泡，起重绘定时器 +6. 播报"第 N 步 + 操作指引" + +顺序错了就会出现"抽屉还没露出来就去量它"这类问题。 + +## 实测踩过的坑 + +### 1. 一次性测量一定过期 → 必须幂等重绘 + +量一次目标元素的位置就画环，过一会儿环会错位。实测数据：同一个元素在首帧后仍在变，宽度 `303.33 → 318.67`、顶部 `0.15 → -11.85`（页面滚动量恒定，是滚动条出现/消失带来的回流）。 + +做法：定时器（约 120ms）反复调用重绘函数，函数幂等——每次重新量、重新画；用几何 key（`left/top/width/height` 取整拼串）去重，没变就直接返回，避免无意义的重排。 + +别用 `scroll` / `resize` 监听代替定时器：滚动过程中环会滞后，元素自身回流也不触发这两个事件。 + +### 2. 浮层的可见性过渡会误杀演示 + +抽屉这类浮层的 `visibility` 会参与 `transition`，`data-open="true"` 之后约 200ms 内 `getComputedStyle().visibility` 仍是 `hidden`，判定函数返回"不可见"。这时直接结束演示，用户会看到"演示刚开始就自己关了"。 + +做法：给约 2 秒的容错窗口——不可见时先重试，超时才判定失败并给出原因。定时器天然负责重试。 + +### 3. 高亮环不要加 transition + +环的几何每 120ms 重画一次，再加过渡会互相打架：出现拖影，几何断言永远对不上。要让环动起来，靠重绘频率，不靠 CSS 过渡。 + +### 4. 挖空遮罩用大 spread 的 box-shadow + +一个 `position: fixed` 的环 + `box-shadow: 0 0 0 9999px rgba(0,0,0,.45)` 就是"四周压暗、中间挖空"，实测可用（用像素采样验证过：#F7F6F3 的底色被压到约 `(144,143,141)`）。 + +不要为此改成 `clip-path: polygon(...)`——单个 `polygon()` 是一条自相交多边形，不是多个子路径，想挖洞得用 `path()`。能用一行阴影解决就别引这条坑。 + +### 5. 退出要成对处理：收浮层 + 还原现场 + +演示会临时改筛选关键词、开抽屉。退出时只隐藏浮层，这些临时态会留给用户。做法：启动时快照当前筛选与关键词，退出时反向还原，再统一重渲染。 + +顺序有讲究：先关浮层，后清 `tourOn` 标记。关闭浮层会触发焦点归还逻辑，标记还在时它会被守卫拦住，不会把焦点从用户手上抢走。 + +### 6. 键盘与边界 + +| 场景 | 行为 | +|---|---| +| `ESC` | 退出演示（演示进行中优先于"关闭顶层浮层"） | +| 演示进行中按全局快捷键（`j/k/a/r` 等） | 一律屏蔽，否则按 `j` 会切走当前片段，演示当场跑偏 | +| 演示中切换界面状态 | 自动结束演示并播报原因（说明区内容已随状态换掉，会讲错） | +| 焦点 | 演示中不抢焦点；浮层用 `aria-modal="false"`，因为它是注解层不是模态框 | +| 进度文案 | 气泡常驻"第 N / M 步 + 场景名"，末步按钮文案改「完成」 | + +### 7. 视觉断言要用像素采样，不要看缩略图 + +看截图判断颜色 / 遮罩 / 选中态会误判——缩略图渲染会改变颜色与对比，看出来的"遮罩没生效""高亮与说明不一致"经常是假象。 + +做法：颜色 / 遮罩 / 选中态这类断言，用 `PIL` 取区域均值或点采样来判，别靠肉眼。 + +## 交付前实测清单 + +- [ ] 每个有 `target` 的步骤都能从「演示」走到「完成」，无中途自动结束 +- [ ] 每一步的高亮环都框住目标元素（框住 = 环矩形与目标矩形在各边差相等） +- [ ] 抽屉类步骤：环确实画在抽屉上，且退出后抽屉被收起 +- [ ] 退出后筛选 / 关键词回到演示前的值 +- [ ] 演示中按全局快捷键不改变界面 +- [ ] 切换界面状态时演示自动结束并播报 +- [ ] 纯概念步骤不参与演示，按钮置灰且有原因 +- [ ] 全程无控制台报错（异常事件数 = 0） diff --git a/product-planning/references/stage-requirements/SKILL.md b/product-planning/references/stage-requirements/SKILL.md index 5030ffa..6eedadc 100644 --- a/product-planning/references/stage-requirements/SKILL.md +++ b/product-planning/references/stage-requirements/SKILL.md @@ -8,7 +8,7 @@ description: 产品规划第②段，产品功能。只做一件事：把①段 回答「要做哪些产品功能、哪些明确不做、页面骨架怎么排」。产出两份： `docs/pm/<项目>/prd/2a-产品功能.md`（功能清单）＋ `docs/pm/<项目>/prd/2b-界面布局.md`（页面骨架）。 -> 段名与①「产品需求」构成 `产品需求 → 产品功能 → 界面交互` 的对称链，三段各占一个词（产品 / 功能 / 界面），无一词共用（2026-10-02 用户定）。旧名「需求与结构」「界面与交付」已废。 +> 段名与①「产品需求」构成 `产品需求 → 产品功能 → 界面交互 → 原型说明` 的对称链，四段各占一个词（产品 / 功能 / 界面 / 说明），无一词共用（2026-10-02 用户定）。旧名「需求与结构」「界面与交付」已废。 > > 与①段的分界：①回答「要解决什么问题、用户怎么用它」，②回答「要做哪些功能、长成什么骨架」。判据看文档主体 —— 主体是功能条目的有无与优先级、页面与板块骨架，归②；主体是问题、用户、取证与取舍理由，归①。 > @@ -154,7 +154,7 @@ description: 产品规划第②段，产品功能。只做一件事：把①段 - ⛔ 把某条信息标为「主屏常驻」却答不上「缺了主操作就做不成事」：按判据应归「可点入」 - 状态流转只画正常路径，不管失败与并发；或状态挂不到任何功能条目上（凭空中间态） - ⛔ 在本段写视觉（清单见 §②—③ 交接口）—— 那是③段 -- 越界去出原型（那是第③段） +- 越界去出原型或写说明文档（那是第③④段） - 把 `【假设】` 原样带进②段当既定事实；或假设已被实现却从不回填状态 - 只写「暂缓」而不给复核人 / 复核时机 / 结论落点 —— 等于让这条永远挂着 - ⛔ 两份没过「说人话」内容准则就落盘 —— 口径与门槛见 `product-planning` 的「执行规则」内容准则条 diff --git a/product-planning/scripts/check_naming.py b/product-planning/scripts/check_naming.py index b365879..2ec5f85 100644 --- a/product-planning/scripts/check_naming.py +++ b/product-planning/scripts/check_naming.py @@ -1,8 +1,8 @@ #!/usr/bin/env python3 # -*- coding: utf-8 -*- -"""三段流水线**命名一致性**自检（纯静态文本比对，不需要渲染、不需要外部依赖）。 +"""四段流水线**命名一致性**自检（纯静态文本比对，不需要渲染、不需要外部依赖）。 -只查一件事：**三段的段名 / 子步名，在总入口、各段 SKILL.md、各段 references 之间有没有漂。** +只查一件事：**四段的段名 / 子步名，在总入口、各段 SKILL.md、各段 references 之间有没有漂。** ⛔ 本脚本**不查视觉、几何、配色** —— 那些判据归③段 §供给·工艺数值判据，本脚本一概不碰。 为什么需要它（不是"为了严谨"，是实测过的两次真实事故）： @@ -48,11 +48,17 @@ STAGES = [ "h1": "# ③ 界面交互", "subs": ["3a 视觉规范", "3b 原型", "3c GPT参考版", "3d 审查打磨"], }, + { + "slug": "stage-proto-doc", + "cn": "原型说明文档", + "h1": "# ④ 原型说明文档", + # 4b/4c 允许只在一处出现完整（总入口与段内都写全），但**两处都必须能读到** + "subs": ["4a 场景盘点", "4b 说明区", "4c 演示引导"], + }, ] -# 2026-10-14 用户令：④段「原型说明文档」整段删除（原做法＝往原型 HTML 注入说明区注解层， -# 实测不好用）⇒ `references/stage-proto-doc/` 连方法论一并撤掉，本表同步去掉该项。 -# 该段的段名与子步名转入下面的 DEPRECATED（提示级），用来查正文里的残留引用。 +# ④段沿革（2026-10-14 → 10-15）：10-14 按用户令删掉旧版（做法＝往原型 HTML 注入说明区注解层，实测不好用）； +# 10-15 用备份里的新版装上（两份产物 ＋ R/S/F 编号 ＋ 四块框架），本表随之恢复该项。 # 已废止的旧名。出现在「废止理由块」里是正当的（那是留痕）， # 所以这里只做**提示级**检查（不计入 FAIL），人工确认上下文即可。 @@ -68,8 +74,8 @@ DEPRECATED = [ "00-问题定义.md", "01-需求澄清.md", "10-参考实装拆解.md", "11-竞品分析.md", "12-用户画像.md", "strategy/30-产品策略.md", "strategy/31-使用场景.md", - # 2026-10-14 ④段整段删除：段名与三个子步名一并废止 - "④ 原型说明文档", "4a 场景盘点", "4b 说明区", "4c 演示引导", + # 2026-10-14 旧版④段的做法废止（状态轴 / 三段必填 / 逐步骤演示），段名与子步名**仍在使用**， + # 故不列入本表；新版的判据在段内 `references/doc-language-spec.md` 等三份。 ] # ⛔ 2026-10-06 用户定案：①段**产出白名单**——本段只许这五份，第 6 份须用户明确要求。 @@ -200,10 +206,10 @@ def check_root(root, label): add("PASS", f"[{label}] 技能根存在", root) # 1) 每段：frontmatter 闭合 + H1 与权威表一致 + 每个子步都有 H2 - # ⚠️ 2026-10-05 整合后：三段收进 references//，不再是技能根下的平级目录。 + # ⚠️ 2026-10-05 整合后：四段收进 references//，不再是技能根下的平级目录。 # 本函数按「技能包 = 一个目录，SKILL.md 在最外层」的形态定位： # /SKILL.md ← 总入口（曾为 /product-planning/SKILL.md） - # /references//SKILL.md ← 三段（曾为 //SKILL.md） + # /references//SKILL.md ← 四段（曾为 //SKILL.md） # ⛔ 不许改回平级探测：那会让整合形态静默退回「一目录套多技能」而门禁照样全绿。 for st in STAGES: p = os.path.join(root, "references", st["slug"], "SKILL.md") @@ -241,26 +247,26 @@ def check_root(root, label): for st in STAGES: num = STAGES.index(st) + 1 - circled = "①②③"[num - 1] + circled = "①②③④"[num - 1] # 段名必须以「圈号 + 空格 + 段名」成对出现，避免只匹配到散落正文 ok = f"**{circled} {st['cn']}**" in text add("PASS" if ok else "FAIL", - f"[{label}] {rel} 三段结构表含 `{circled} {st['cn']}`", "") + f"[{label}] {rel} 四段结构表含 `{circled} {st['cn']}`", "") # 子步：总入口表里每个子步都要能被逐个读到 for st in STAGES: for sub in st["subs"]: - if sub.split()[0] in ("3d",): - # 3d 在总入口可能与相邻子步合并书写，只要求"子步号 + 关键词"能被搜到 + if sub.split()[0] in ("3d", "4b", "4c"): + # 3d/4b/4c 在总入口可能与相邻子步合并书写，只要求"子步号 + 关键词"能被搜到 kw = sub.split(" ", 1)[1] if " " in sub else sub ok = (sub in text) or (kw in text) else: ok = sub in text add("PASS" if ok else "FAIL", - f"[{label}] {rel} 三段结构表子步列含 `{sub}`", "") + f"[{label}] {rel} 四段结构表子步列含 `{sub}`", "") - # 交接口表：两条边必须都在 - for edge in ("① → ②", "② → ③"): + # 交接口表：三条边必须都在 + for edge in ("① → ②", "② → ③", "③ → ④"): add("PASS" if edge in text else "FAIL", f"[{label}] {rel} 交接口表含 `{edge}`", "")