Table of Contents

需求总览

本页用途
事实来源边界
当前需求索引
交付节奏
未决问题
已确认的界面决定
登记规则
原型与设计资产

原型门禁
线上原型与按需 HTML 快照
原型确认记录

状态规则
更新时机
最小验收清单

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

需求总览

本页用途

本页是 cmsp 长期需求的索引，回答「现在有哪些需求、各自处在什么状态、详细规则和工单在哪里」。它不复制工单全文，也不保存聊天记录。

产品代码尚未开始，本页目前主要用于固定已确认的需求边界和未决问题，避免在实现阶段把假设当成事实。

事实来源边界

内容	事实来源	本地镜像
长期需求、业务规则、系统边界	本页与对应 Wiki 主题页	`docs/`
单次任务的需求、方案、测试、验收	Gitea 工单	无
淘宝流程的目标行为规范	业务规则与术语	`docs/`
已验证的参考实现	仓库外两份 Python 项目，见项目档案	无

当前需求索引

编号	需求领域	目标	状态	主题文档	工单
R1	商品同步	从货憨憨拉取指定 Shopee 店铺的商品列表并落入本地 SQLite	已确认，未实现	架构与代码地图路径一	待创建
R2	专属 Chrome 与淘宝登录	启动固定 Profile 的专属 Chrome，由使用者手动登录，程序做两层登录检查	已确认，未实现	业务规则与术语	待创建
R3	淘宝以图搜	用商品主图调用 MTOP 以图搜接口，解析同款商品列表	已确认，未实现	业务规则与术语	待创建
R4	详情视频提取与下载	打开同款商品详情页，提取介绍视频地址，下载 MP4 并校验完整性	已确认，未实现	业务规则与术语	待创建
R5	视频上传货憨憨	把本地视频上传到货憨憨素材空间并关联到对应商品，使 Shopee 可见	接口契约未确认，排在最后	业务规则与术语规则 19	待创建
R6	桌面界面	左侧可折叠导航（商品列表 / 参数设置）+ 两行工具栏 + 商品表格 + 运行日志子窗口	原型已确认，未实现	架构与代码地图	待创建
R7	任务引擎与断点	批量任务的队列、并发、进度事件、断点续传与全局停止门	已确认，未实现	业务规则与术语	待创建
R8	本地状态存储	SQLite 保存商品、任务、视频、上传状态与货憨憨认证状态	表结构未确认	架构与代码地图	待创建

状态取值见下方「状态规则」。工单创建后把编号填入表格，不要另建第二份清单。

交付节奏

按 MVP 分三段交付。这个顺序是负责人于 2026-09-02 确认的，不要随意调整。

阶段	包含需求	交付后能做什么	阻塞条件
MVP1	R1 商品同步（含 R6 界面、R8 存储的基础部分）	看到指定店铺的商品列表，数据落本地	无
MVP2	R2 淘宝登录 + R3 以图搜 + R4 视频下载	本地拿到视频文件，人工上传即可使用	无
MVP3	R5 回传货憨憨（含 R7 任务引擎完善）	全自动，Shopee 商品页可见视频	Q1、Q2 未解决前不能开始

把 R5 放在最后有三个理由，都是硬约束而不是偏好：

只有它缺接口契约。 Q1 与 Q2 至今没有任何参考实现，负责人提供的商品页抓包中 uploadFiles、batchUpdateShopProductVideo、getMaterialSize 出现 0 次。
只有它写真实数据。 R1~R4 全部是只读操作；R5 是第一个写入货憨憨并最终影响线上 Shopee 商品的环节，风险等级不同，必须等前面稳定。
图片空间只剩约 26 GB（已用 98.7%）。 视频体积远大于图片，现在批量上传大概率触发「容量不足」。这段时间用于清理旧素材或扩容。

MVP2 完成后工具已具备实用价值：最耗时的「找同款、提取视频、下载」已自动化，剩余的人工上传只是在货憨憨后台点几下。即使 R5 长期阻塞，工具也不是半成品。

顺带解决 Q1 与 Q2：MVP2 交付后，使用者必然会在货憨憨后台手动上传视频，那次操作就是抓取上传接口的最佳时机，且是真实业务场景下的完整请求，比专门构造一次更可靠。

未决问题

这些问题在实现相关需求前必须先解决。它们是假设，不是事实，不得据此编码。

编号	问题	影响需求	当前状态
Q1	货憨憨素材上传的文件字段名，以及视频与图片是否走同一接口	R5	待抓包确认
Q2	`batchUpdateShopProductVideo` 的完整请求体字段与返回结构	R5	只在货憨憨接口文档的接口清单中出现，无字段说明，待抓包确认

| Q4 | 下载与上传的默认并发数，以及淘宝风控的实际容忍阈值 | R4、R7 | 待实测 | | Q5 | SQLite 表结构与迁移方式 | R8 | 待设计 | | Q6 | 上传后 Shopee 侧的生效延迟与验证方式 | R5 | 待实测 |

Q3 已于 2026-09-03 关闭：负责人实测图搜结果准确，决定批量全自动、不做人工确认，但采用的同款商品 ID 必须落库。

Q1 与 Q2 是整条链路上唯一没有已验证参考实现的环节：仓库外的 Python 项目只实现了图片上传，视频上传接口没有代码；负责人提供的商品页 HAR 中这三个接口也出现 0 次。

解决时机：MVP2 交付后，使用者手动上传视频时抓包。在此之前 MVP3 不启动。

已确认的界面决定

以下决定来自 2026-09-02 确认的原型，实现必须遵守；要改先更新原型并重新确认。

决定	内容	理由
导航形式	左侧可折叠导航栏，展开 176px、收起 64px；只有「商品列表」和「参数设置」两项	侧栏比顶部 tab 更易扩展；不放筛选器，避免与工具栏的商品状态筛选混淆
登录状态位置	只在侧栏底部显示货憨憨与淘宝两个状态灯，全局唯一	避免同一事实在多处显示导致不一致
工具栏	两行。上行筛选：店铺、蝦皮ID、创建时间范围、状态、重置、搜索；下行操作：下载数据、下载视频、上传数据、运行日志	六项筛选加四个按钮一行放不下（需约 1650px，可用仅 1208px）
搜索条件映射	店铺 → `platformShopId`；蝦皮ID → `itemIds`；创建时间 → `createTimeStart`/`createTimeEnd`；状态 → `itemStatus`	均为 `product/shop/getPage` 原生参数，不额外造接口
店铺来源	店铺下拉必须调用 `erp/shop/all` 获取当前账号店铺，不手工维护	账号可用店铺会变化
运行日志	独立子窗口，主界面保留精简任务条（当前商品、进度、用时、停止按钮）	任务运行时需同时看列表与进度
路径选择	Chrome 可执行文件用文件选择框（`*.exe`），用户数据目录与视频保存目录用目录选择框	手打 Windows 路径易错；两者是不同的对话框 API
同款选择	批量时全自动：按图搜返回顺序依次尝试同款，第一个有视频的即采用，不做人工确认。但必须把实际采用的淘宝同款商品 ID 记入 `videos.source_item`，以便事后抽查与回溯	负责人 2026-09-03 确认图搜结果准确度可接受；几百个商品逐个人工确认不现实，记录来源即可满足回溯需要
表格列	主图、蝦皮ID、标题、店铺、价格、视频、下载状态、上传状态、创建时间、操作	下载与上传状态分列，因为 `getPage` 不返回视频字段（见 Q7）

登记规则

一个需求领域一行，不按工单粒度拆分。
需求进入实现阶段时创建工单，并把工单编号填回表格。
需求的详细规则写进对应主题 Wiki 页，本页只保留一句话目标和入口链接。
未决问题确认后，从「未决问题」表移除，并把结论写进对应主题页。
不复制完整工单、不粘贴聊天记录、不写入账号密码或真实店铺数据。

原型与设计资产

原型门禁

本项目为轻量模式，按真实需要选择设计证据，不为流程制作原型：

文案、局部样式或布局、复用现有组件的调整：可直接实施，不需要原型，一句话或标注截图即可。
商品列表页与参数设置页的首次实现属于新页面：已通过 Quant-UX 线上原型审核并于 2026-09-02 确认，见下方「原型确认记录」。实现必须与该原型一致；页面结构、主要流程、状态或异常处理变化时先更新原型并重新确认。
出现明显交互不确定性（例如 Q3 的人工确认交互），或返工成本明显时，才制作可审阅原型。
后端、接口、任务引擎不制作 UI 原型；改为在工单记录必要的技术设计、数据结构与状态机。

线上原型与按需 HTML 快照

确需完整原型时，默认通过 Quant-UX 或等效工具的线上链接审核，工单记录可访问链接、版本或确认日期、确认人和覆盖范围。
只有使用者明确要求「导出原型 #N」或「导出全部原型」时，才导出到 prototypes/<工单号>/<版本>/index.html。
导出的本地快照不得成为第二份可编辑事实来源，也不得原位覆盖已确认版本。

原型确认记录

工单	原型链接或路径	版本或日期	状态	确认人	覆盖范围
见需求 R6	https://qux.ilapage.cn/#/apps/6a97c618191a826306a7f5f7	v4，2026-09-02	已确认	项目负责人	商品列表页（两行工具栏、四项搜索条件、15 行表格）、参数设置页、店铺下拉、任务进行中、运行日志子窗口、淘宝登录失效弹窗，共 7 屏 32 条连线

状态规则

状态	含义
待确认	目标或范围尚未与负责人确认
已确认，未实现	目标和边界已确认，尚无产品代码
接口契约未确认	目标已确认，但依赖的外部接口字段未取得，不能开始实现
实现中	已有工单在进行
已交付	已实现并通过人工验收
已废弃	明确不再做，保留一句话原因

状态改变必须有对应的工单或负责人确认，不由 Agent 单方面提升。

更新时机

以下情况必须更新本页：

新增或废弃一个需求领域；
需求状态发生变化；
未决问题得到确认或新增；
需求对应的主题文档或工单入口发生变化；
原型形成待审核版本或确认结果发生变化。

单次任务的进度、测试和验收记录在工单，不写入本页。

最小验收清单

每个需求领域都有一句话目标、状态和主题文档入口；
进入实现阶段的需求都有工单编号；
未决问题都写明影响哪个需求和当前状态；
没有把未确认的接口字段、表结构或并发参数写成事实；
没有复制工单全文、聊天记录、凭据或真实店铺数据；
需要原型的需求有可访问链接或明确记录了不需要原型的原因。