@prd-improve/cli 1.0.0 → 1.1.0

package/dist/skill/prd-improve-forge/checklists/batch-import.md

@@ -0,0 +1,195 @@
+# 批量导入类功能 · 边界追问清单
+
+> 本清单由 PRD Skill 在检测到"批量导入"类功能时自动加载。
+> 所有问题的答案最终都要落到 `prd.yaml` 对应模块里,Skill 不要凭空生成答案。
+
+---
+
+## 触发加载条件
+
+当功能描述中出现以下特征之一,Skill 应加载本清单:
+
+- 关键词:"批量"、"批处理"、"一次性导入"、"成批"、"bulk"
+- 涉及 CSV / Excel / JSON / 文本文件 / 外部数据源的解析入库
+- 涉及"追加"、"合并"、"去重"、"覆盖"等数据动作
+- 一次处理规模 N ≥ 2 的任务
+- 涉及"文件上传 + 解析 + 入库"的组合动作
+
+典型功能:
+- 批量导入历史 PRD 文件
+- 客户数据批量导入 (CSV)
+- 从旧系统批量迁移订单
+- 批量创建用户 / 配置文件批量上传
+- 批量同步外部系统数据
+
+---
+
+## 使用原则 (Skill 执行协议)
+
+1. **分轮次追问,每轮至多 3-5 个问题**。不要一次性抛 50 个。
+2. **按优先级顺序**:P0 先、P1 次、P2 最后。P0 未答完不进入 P1。
+3. **有选项的题给选项**:凡是"常见答案"列出的,用 "A / B / C / D / 其他" 的方式让用户选。
+4. **用户说"够了,直接生成"**:
+   - 未回答的 **P0** 问题 → 进 `prd.yaml` 的 `open_questions`,`severity: blocking`
+   - 未回答的 **P1 / P2** 问题 → 进 `open_questions`,`severity: non_blocking`
+5. **不要替用户决策业务规则**。给选项可以,但最终选择必须来自用户。
+
+---
+
+## Q 清单 (按 prd.yaml 模块归类)
+
+### 1. 输入源与数据范围
+
+→ 答案落到 `entities` / `main_flow` / `data_and_api.data_constraints`
+
+- **[P0]** 数据从哪里来?**选:** 本地文件上传 / URL 下载 / API 拉取 / 粘贴文本 / 拖拽目录 / 系统内选择
+- **[P0]** 支持哪些文件格式?CSV / Excel (xlsx/xls) / JSON / YAML / Markdown / TXT / 其他
+- **[P0]** 单次导入的"单位"是什么?单文件还是文件夹?单行还是多行?
+- **[P1]** 用户是分批次上传还是一次性全量上传?
+- **[P1]** 数据结构是否固定?有没有必填字段、可选字段、字段顺序要求?
+- **[P2]** 是否提供模板下载(标准格式示例)?
+
+### 2. 重复与冲突处理
+
+→ 答案落到 `business_rules` / `edge_cases`
+
+- **[P0]** 重复数据的判定依据是什么?主键 / 业务字段组合 / hash / 用户自选
+- **[P0]** 遇到重复数据如何处理?**选:** 覆盖 / 跳过 / 报错 / 让用户选 / 规则判定(如时间戳最新覆盖)
+- **[P0]** 单次批次**内**的自身重复如何处理?(同一个文件里两条相同的行)
+- **[P1]** 跨批次重复如何处理?(今天导入过的,明天再导一次)
+- **[P1]** 重复操作是否产生审计日志?日志保留多久?
+
+### 3. 部分成功与失败处理
+
+→ 答案落到 `edge_cases` / `scenarios` / `business_rules`
+
+- **[P0]** 是否允许部分成功?**选:** 允许(成功入库,失败跳过) / 不允许(一条失败全量回滚) / 让用户选
+- **[P0]** 失败行如何回报给用户?**选:** 下载失败清单 CSV / 页面内表格列出 / 弹窗列出前 N 条 / 仅显示错误总数
+- **[P0]** 失败行的数据是否保留?保留在哪里?保留多久?
+- **[P1]** 用户能否对失败行重试?(单条重试 / 批量重试 / 修改后重新导入)
+- **[P1]** 什么错误算"可恢复"、什么算"不可恢复"?
+- **[P2]** 失败率达到什么阈值自动中止整个任务?
+
+### 4. 任务状态与并发
+
+→ 答案落到 `entities.lifecycle_states` / `state_permissions` / `business_rules`
+
+- **[P0]** 导入任务有哪些状态?(建议基础集: pending / running / paused / succeeded / partial_succeeded / failed / canceled)
+- **[P0]** 同一个用户能否同时发起多个导入?**选:** 允许并行 / 排队等待 / 后来者报错
+- **[P1]** 同一批数据被先后两次提交导入,是否幂等?
+- **[P1]** 系统级并发上限?(全局同时最多 N 个任务)
+- **[P2]** 任务队列顺序策略?FIFO / 用户优先级 / 项目优先级
+
+### 5. 中断、暂停、恢复
+
+→ 答案落到 `edge_cases` / `main_flow` / `state_permissions`
+
+- **[P0]** 用户能否主动取消运行中的任务?**选:** 能 / 只能暂停 / 不能
+- **[P0]** 取消 / 暂停后,已入库的数据如何处理?**选:** 全部回滚 / 保留 / 让用户选
+- **[P0]** 浏览器关闭 / 网络中断 / 系统重启后任务还继续吗?
+- **[P1]** 用户下次回到页面能否看到进行中任务的进度?
+- **[P1]** 重启后能从断点继续,还是必须重新开始?
+- **[P2]** 暂停中的任务能否被修改参数后恢复?
+
+### 6. 追加与合并
+
+→ 答案落到 `in_scope` / `out_of_scope` / `business_rules` / `state_permissions`
+
+- **[P0]** "追加"具体是什么语义?**选:** 追加新文件到同一任务 / 追加数据到已有集合 / 本期不支持追加
+- **[P0]** 追加允许发生在哪些任务状态下?(pending / running / paused / succeeded / 都允许?)
+- **[P1]** 追加数据与原数据的重复规则是否与首次导入一致?
+- **[P1]** 追加产生新任务记录,还是沿用原任务 ID?
+- **[P2]** 单任务的追加次数上限?
+
+### 7. 数据约束
+
+→ 答案落到 `data_and_api.data_constraints`
+
+- **[P0]** 单文件大小上限?(MB)
+- **[P0]** 单次批次数据条数上限?
+- **[P1]** 总容量上限?(用户级配额 / 项目级配额 / workspace 级配额)
+- **[P1]** 单条数据的字段长度 / 数值范围上限?
+- **[P2]** 支持的字符编码?(只 UTF-8 还是多编码)
+- **[P2]** 特殊字符处理?(换行、引号、unicode 控制字符)
+
+### 8. 性能与容量
+
+→ 答案落到 `data_and_api.performance_constraints`
+
+- **[P0]** N 条数据期望在多久内完成?(定义"快"的可测标准)
+- **[P1]** 任务进行时对系统其他功能有什么影响?(用户还能用其他功能吗?)
+- **[P1]** 峰值并发场景下的降级策略?(排队 / 拒绝 / 降速)
+- **[P2]** 是否支持高优先级任务插队?
+
+### 9. 权限、审计、安全
+
+→ 答案落到 `data_and_api.security_constraints` / `state_permissions`
+
+- **[P0]** 谁有权限发起导入?(所有登录用户 / 特定角色 / 项目成员 / workspace 管理员)
+- **[P0]** 谁能看到导入任务的详情?(本人 / 同项目成员 / 管理员)
+- **[P1]** 导入的数据是否含敏感字段?(手机 / 身份证 / 邮箱 / 金额)如何脱敏展示?
+- **[P1]** 失败文件是否保留用于审计?保留多久?谁能下载?
+- **[P2]** 大批量前是否需要二次确认?(超过 N 条弹确认框)
+- **[P2]** 导入操作是否计入审计日志?日志保留多久?
+
+### 10. 进度与反馈 UI
+
+→ 答案落到 `ui_interaction`
+
+- **[P0]** 任务进度如何展示?**选:** 进度条 / 百分比数字 / 当前处理行号 / 只显示"进行中" / 组合
+- **[P0]** 失败结果如何展示?(与 Q3 的失败回报方式对齐)
+- **[P1]** 用户需要等在页面上,还是可以离开?
+- **[P1]** 任务完成 / 失败是否通知用户?**选:** 站内消息 / 邮件 / 不通知 / 用户可配
+- **[P1]** 空状态 / 加载状态 / 错误状态分别展示什么?(对齐 `ui_interaction` 三态必填)
+- **[P2]** 进度更新频率?(实时推送 / 每秒轮询 / 每 N 条刷新)
+
+### 11. 验收与可观测
+
+→ 答案落到 `acceptance_criteria` / `data_and_api.security_constraints`
+
+- **[P0]** 怎么判断一次任务"成功"?需要达到多少成功率阈值?
+- **[P1]** 开发需要哪些日志 / 指标来排查问题?
+- **[P1]** 测试需要哪些固定数据样例来做回归?
+- **[P2]** 运维需要哪些报警项?(失败率过高 / 任务积压 / 单任务耗时过长)
+
+---
+
+## 常见答案池 (Skill 用来快速给用户多选)
+
+| 问题主题 | 常见选项 |
+|---|---|
+| 重复处理 | 覆盖 / 跳过 / 报错 / 让用户选 / 规则判定(如时间戳最新覆盖) |
+| 部分成功 | 允许(成功入库) / 不允许(全量回滚) / 让用户选 |
+| 失败回报 | 下载 CSV / 表格展示 / 弹窗前 N 条 / 只报数量 |
+| 取消处理 | 全部回滚 / 保留已入库 / 让用户选 |
+| 并发策略 | 允许并行 / 排队 / 后来者报错 |
+| 追加语义 | 追加文件 / 追加数据 / 不支持 |
+| 进度展示 | 进度条 / 百分比 / 当前行号 / 组合 |
+| 通知方式 | 站内消息 / 邮件 / 不通知 / 用户可配 |
+| 权限粒度 | 所有登录用户 / 特定角色 / 项目成员 / 管理员 |
+| 文件格式 | CSV / Excel / JSON / YAML / Markdown / TXT |
+
+---
+
+## Top 5 最易被漏掉的问题 (Skill 必问)
+
+即使用户说"简单场景就行",这 5 个也**必须**至少追问一轮。如果用户答不上来,全部转入 `open_questions` 且 `severity: blocking`:
+
+1. **同一批次内的自身重复怎么处理** —— 不是跨批次,是同一次导入的文件里自己有重复。90% PM 会漏。
+2. **任务进行中,能否发起第二个任务** —— 影响并发架构和 UX。
+3. **导入一半浏览器关闭,再回来看到什么** —— 决定任务持久化、断点恢复、通知策略。
+4. **"追加"的精确语义** —— PM 说"可以追加"时通常没想清楚是追文件还是追数据、允许在哪些状态下追。差异巨大。
+5. **失败行的数据保留策略** —— 同时牵涉审计、数据安全、用户二次处理三方,常常被忽略。
+
+---
+
+## 本清单的演化约定
+
+发现新场景或遗漏时:
+
+1. 先写入本文件对应分类,并标 P0 / P1 / P2
+2. 若有新选项,同步更新"常见答案池"
+3. 如果某 P1 问题频繁被用户答不上来,升级为 P0
+4. 如果某类功能(如"跨系统同步")与批量导入差异过大,拆出独立 checklist(如 `checklists/cross-system-sync.md`)
+
+当前版本:v0.1 · 本清单与 `templates/prd.yaml` (schema_version v0.2) 对齐