moi-storybook

name	moi-storybook
description	创建、补全、审查或更新一个用于 MOI 客户业务 Storybook、产品用户旅程、端到端走查、生成式 AI、事件驱动、定时任务、人工审批或工作流验收的 GitHub 单 Issue。当用户要求整理 Storybook Issue、客户场景、User Journey、业务走查或验收故事时使用。所有 Scene、实际结果、证据、验收项和问题跟踪必须放在同一个 Issue 中。不要用于前端组件开发工具 Storybook。

MOI 业务 Storybook

围绕一个客户场景或一条完整业务主线，产出一个容易理解、可继续细化，并在需要时可执行验收的 GitHub 单 Issue。

基本规则

• 一个 Storybook 只使用一个 Issue，不创建 Scene 或 User Story 子 Issue；只有确需独立研发 owner 和排期时才链接外部 Bug、Feature 或 PR。
• 单 Issue Storybook 模版 是标题、章节、表格和验收附录的唯一格式来源。
• 默认先讲需求来源、客户或内部发起方、用户目标、业务流程、期望结果和当前问题，再写产品或验收细节。
• 不得虚构客户背景、样例、环境、输入、ID、实际结果、证据、Issue、owner 或结论。
• 用户明确提供给当前 Storybook 的样例文件必须逐个原样保存到 IDC MinIO 的独立 Storybook 目录，并全部列入 Issue；小文件可以同时直接附到 Issue，大文件必须使用 S3。详细目录、凭据、上传和核对规则见 样例数据存储规范。
• Storybook 的 S3 目录按 #<Issue号>-<Issue名称>-样例数据 命名；测试新构造的样例文件也使用该前缀。用户提供的原始文件不得为满足命名规范而改名。
• 未经用户明确同意，不得裁剪、抽样、脱敏、改名、拆分、合并、解压、重新压缩或用自制代表集替代。
• 只有用户明确要求时，才创建或编辑 GitHub Issue；发现已有 Issue 时不得擅自改写。
• 实际创建 Storybook Issue 时，必须加入 Project New MatrixOne Intelligence，添加 Label storybook，并默认 Assign 给 gavin-wang-note。
• 客户需求还必须添加 Label customer/<客户名称>；非客户需求不得添加 customer/*。

角色分工

• 提报模式（默认）：面向非专业提报人，只收集需求来源、具体客户或内部发起方、业务目标、使用场景、业务流程、期望结果和样例状态。
• 测试模式：仅在用户明确要求测试、走查、验收或自动化时启用；由测试补充测试夹具、环境、精确步骤、断言、实际结果和证据。
• 提报人不需要填写 Fixture ID、文件哈希、Step ID、Result ID、断言、自动化入口或运行参数。

执行流程

1. 确定模式与边界

• 默认使用提报模式；只有明确进入测试工作时才使用测试模式。
• 一个 Storybook 对应一个客户场景或一条逻辑完整的业务旅程。
• 请求包含互不相关的业务主线时，先说明建议边界，不要静默混在一个 Issue 中。

2. 询问样例

如果当前对话没有可访问样例，且用户尚未回答是否有样例，先问：

这个场景有能说明业务的样例文件吗？如果有，请上传获准使用的原始或脱敏文件，或提供可访问链接；如果没有，请直接说明，我会记录是否需要由测试后续构造样例。

• 提报模式下，用户有样例时只需上传并说明样例代表的业务；明确提供给当前 Storybook 的多个文件默认都要上传，不得只选择其中一部分。用户没有样例时，询问是否授权测试后续构造合成样例并记录选择，不要求提报人设计测试数据。
• 测试模式下，实际读取已有样例并记录文件名、格式、版本或哈希、规模、代表性内容、权限和脱敏要求。没有样例但已获授权构造时，用一至三个简短问题确认：
  1. 业务种类、目标和需要提取的字段或内容。
  2. 文件格式、数据类型，以及单文件或批量文件。
  3. 页数、行数或记录数、语言、边界情况，以及是否需要标准答案。
• 测试负责提出最小可用方案并生成合成样例；全部内容使用虚构信息，明确标记为“合成测试数据”，按照 样例数据存储规范 命名，并记录生成规格、字段说明、标准答案、版本或哈希和适用范围。
• 暂无样例且未授权构造时，提报仍可继续，但必须记录为“待测试补充”。
• 已经上传或回答过时，不重复询问。敏感资料只使用获准版本；是否脱敏、裁剪或转换必须由用户决定，不能因判断文件敏感而自行加工。

样例附件完整性

• 上传前列出用户提供的全部原始文件，核对文件名、数量和大小；用户提供压缩包时，该压缩包本身就是原始文件，不得自行解压或重新打包。
• 完整读取并执行 样例数据存储规范：一个 Storybook 创建一个以 Issue 编号和名称命名的独立目录，全部原始文件都保存到该目录，不能与其他 Storybook 共用。
• 在 5.1 业务样例 中写明 S3 Bucket、Storybook 目录和每个原始文件的对象位置；不能只写本地路径，也不能只上传一个自制汇总包。
• 小文件在 S3 保存后，可以再将同一原文件直接附到 Issue；超过 GitHub 当前附件限制或直接上传失败的文件不得压缩规避，必须以 S3 位置交付。
• S3、权限或网络问题导致原文件无法保存时，记录具体文件和阻塞原因并立即向用户说明；不得把样例状态写成“已全部提供”。
• 未经用户明确授权，不得通过压缩、拆分、裁剪、抽样、脱敏、转换格式或提交到代码仓库、Release、LFS 等方式绕过上传限制。
• 交付前逐项比对“用户提供的文件清单”“S3 对象清单”和“Issue 中记录的文件清单”；缺少任何原始文件时，只能报告为未完整上传。

3. 确认需求来源并检索背景

• 每个 Storybook 必须注明需求来源类型：客户需求、内部产品需求、市场共性需求 或 探索验证。用户未说明时先询问，不能自行归类。
• 客户需求必须记录具体客户全称、需求提出人或角色、来源证据、提出或确认时间及确认状态；缺失项写“待确认”，不能用公开背景代替客户确认。
• 内部产品需求、市场共性需求或探索验证应记录内部发起方或 owner、提出依据和相关证据。
• 再搜索目标仓库中的客户项目、讨论、相关文档和 Storybook，并按需搜索官网或其他权威公开来源；只保留与当前用户、数据、流程或下游用途直接相关的背景。
• 在正文中链接来源，并区分已确认事实、仓库记录和推断。

4. 检查重复 Issue

• 创建前同时搜索 Open 和 Closed Issue，组合使用客户名称、项目名、业务目标、输入类型、下游用途及 Storybook 常见标识。
• 打开最相关候选阅读正文，不能只看标题。
• 同一客户、同一用户目标且流程基本相同时，停止创建，返回已有 Issue、重复依据和“未创建”的结论。
• 部分重合时说明差异。只有新需求确属独立业务主线时才新建；补充已有 Issue 需要用户明确授权。
• 新建 Storybook 时，先完成查重并确认需要创建；创建 Issue 获得编号后，再按 #<Issue号>-<Issue名称>-样例数据 建立 S3 目录和上传样例，最后回填 Issue，避免目录缺少可追溯的 Issue 编号。

5. 选择内容深度并收集证据

• 提报模式只使用模板中的“业务 Storybook”，不要求填写验收附录。
• 测试模式在已有业务 Storybook 后追加“可执行验收附录”，不重写提报人已经确认的业务内容。
• 优先使用样例、源文档、权威判定基准、产品实际状态和日志；保留准确的环境、工作区、对象、文件、模型、执行 ID、产物路径和错误文本。
• 没有实际证据时，只写预期和待确认内容，不把目标行为写成已经实现或验证。

6. 编写或更新 Issue

• 完整读取模板，删除不适用章节，不保留空表格、模板说明或大量无意义 TODO。
• 新建 Issue 时，先用完整业务正文创建 Issue 并获得编号；样例位置可暂记为“创建后上传并回填”，但不得把它当作最终交付。
• 按 Issue 编号和最终标题创建 S3 独立目录，将用户提供的全部原始样例逐个保存；测试构造的文件使用规范名称。
• 上传完成后立即更新 5.1 业务样例，列出目录、每个对象位置和可访问方式；小文件可额外附到 Issue。存在阻塞时保留原文件名和未上传原因，不得替换为自制样例。
• Issue、评论、日志和正文中不得出现 MinIO 密码、访问密钥、Session、Cookie 或其他凭据。
• 使用客户业务语言；开头应让非技术读者快速理解谁要做什么、为什么、如何完成、得到什么以及当前卡点。
• 预期结果、实际观察和证据分开记录；明确“已证明”和“尚未证明”。
• 走查发现的问题默认留在同一个 Storybook Issue 中；只有确需独立修复或排期时才链接外部 Issue。
• 创建后立即确认 Project 为 New MatrixOne Intelligence、Label 包含 storybook、Assignee 为 gavin-wang-note；用户明确指定其他 Assignee 时以用户要求为准。
• 客户需求还要确认 Label 包含与具体客户全称一致的 customer/<客户名称>；非客户需求确认没有 customer/*。
• 如果 Project、Label 或 Assignee 因权限、字段、标签或账号不存在而未成功设置，明确报告未完成项，不得把 Issue 视为完整交付。

测试补充与验收门槛

• 以下内容由测试负责，不要求 Storybook 提报人提供。
• 提报完成但尚未经过测试补充时，内容状态最多为 READY FOR REVIEW，执行结果保持 NOT RUN。
• 每个必须验收的 Scene 只有同时具备以下内容，才可标记 READY FOR TEST：
  1. 可访问的真实样例，或用户确认规格和标准答案的可复现测试夹具。
  2. 另一名执行者可以照做的精确操作、输入、配置和顺序。
  3. 可观察、可判定的预期结果、验证方法和证据来源。
• 合成样例只能证明相应功能路径；除非客户明确认可其代表性，否则不能替代真实客户数据的最终验收。
• 只有实际执行、按判定标准核对并保留证据后，才能写 PASS。创建成功、HTTP 200、绿色状态或任务完成本身不能证明业务结果正确。
• 生成式 AI 或定性结果必须使用关键事实、禁止项、可接受答案集合、引用覆盖或评分量表，不能只写“回答正确”。

输出

提报模式未命中重复 Issue 时，输出推荐标题和元数据、易读的业务 Storybook、需求来源与背景证据、样例状态、查重结果，以及少量待确认项；不输出专业测试表格。

测试模式更新同一个 Issue，追加测试夹具、精确操作、预期结果、实际结果和证据，不要求提报人补写这些内容。

命中重复 Issue 时，不生成新的完整正文；输出已有 Issue 链接、重复或部分重合依据、本次未创建的结论，以及需要用户授权后才能执行的补充建议。

交付前确认：角色分工正确、需求来源和业务流程清楚、Open/Closed 已查重；每个 Storybook 使用符合 #<Issue号>-<Issue名称>-样例数据 规则的独立 S3 目录，用户提供的全部原始样例均已逐个原样保存，测试构造文件命名合规，并已在 Issue 中写明位置，或已明确报告阻塞；实际创建的 Issue 已加入 New MatrixOne Intelligence、已添加 Label storybook、默认已 Assign 给 gavin-wang-note，客户需求已添加 Label customer/<客户名称>、非客户需求没有 customer/*；只有测试模式才要求验收夹具、精确步骤和证据。