# 需求

> 本文只定义产品需要什么以及如何验收。技术实现和字段存储方式见 [`04-architecture.md`](04-architecture.md)。

## 一、业务现状

| 项 | 当前事实 |
| --- | --- |
| 用户 | 个人卖家或小团队运营人员，同时维护多个跨境店铺 |
| 常见痛点 | 店铺入口、Chrome 会话、商品资料、图片、话术和待办分散 |
| 当前项目 | 空项目，尚无生产代码和历史数据 |
| 首发平台 | Windows 10/11 x64 桌面 |
| 首发平台业务 | 字段支持多平台，功能和示例优先覆盖 Shopee |
| 数据来源 | 用户手工录入、本地文件、CSV/XLSX；平台官方 API 后置 |
| 网络边界 | 核心数据管理离线可用；打开 Chrome 或显式代理检测时才联网 |

## 二、用户角色

- **店铺运营**：维护店铺、商品、图片、客服记录和个人待办。
- **团队负责人**：在同一台电脑查看负责人、状态、模板和处理记录。
- **未登录用户**：首发没有 ShopHelm 云账号，启动本机应用即可使用。

首发没有应用内角色权限。平台后台权限仍由 Chrome 中的平台账号决定。

## 三、发布顺序

1. 业务阶段一：多店铺运营台。
2. 业务阶段四：商品运营助手。
3. 业务阶段五：客服助手。

工程上先完成地基和高风险原型，再依上述业务顺序交付。

## 四、首发功能需求

### 4.1 今日工作台

| ID | 需求 | 优先级 |
| --- | --- | --- |
| DASH-001 | 展示最近打开的店铺，并可直接再次打开 | P0 |
| DASH-002 | 展示今天到期和已逾期的店铺待办、客服跟进 | P0 |
| DASH-003 | 展示待上架、需优化的商品和最近图片导出 | P0 |
| DASH-004 | 提供新增店铺、商品、客服跟进和图片预览入口 | P0 |

### 4.2 多店铺运营台

| ID | 需求 | 优先级 |
| --- | --- | --- |
| STORE-001 | 新增、查看、编辑、归档店铺 | P0 |
| STORE-002 | 维护平台、国家/站点、店铺名、账号标识、负责人、标签、状态和备注 | P0 |
| STORE-003 | 按关键词、平台、国家、负责人、标签和状态筛选 | P0 |
| STORE-004 | 每个店铺绑定唯一 Chrome profile 目录和起始地址 | P0 |
| STORE-005 | 一键用绑定 profile 打开外部 Chrome，并更新最后打开时间 | P0 |
| STORE-006 | 显示未运行、启动中、运行中、已退出和启动失败状态 | P0 |
| STORE-007 | profile 已被占用时阻止重复启动，并给出可操作提示 | P0 |
| STORE-008 | 维护订单、商品、营销、客服、数据等快捷链接，并用当前店铺 profile 打开 | P0 |
| STORE-009 | 可选配置 HTTP/HTTPS/SOCKS 普通无认证代理 | P0 |
| STORE-010 | 维护店铺待办及到期时间 | P0 |
| STORE-011 | 备份并恢复本地业务数据和配置引用 | P0 |
| STORE-012 | 批量打开、分组视图和快捷键 | P2 |

归档店铺不得自动删除 Chrome profile。首发不支持需要用户名/密码认证的代理自动注入。

### 4.3 商品运营助手

| ID | 需求 | 优先级 |
| --- | --- | --- |
| PROD-001 | 新增、查看、编辑、归档商品草稿 | P0 |
| PROD-002 | 维护店铺、商品名、SKU、成本、售价、币种、库存、链接、状态和备注 | P0 |
| PROD-003 | 管理标题模板和描述模板 | P0 |
| PROD-004 | 维护上架检查项，并显示未完成项 | P0 |
| PROD-005 | 根据明确输入计算收入、成本和基础利润参考，不把结果称为财务利润 | P0 |
| PROD-006 | CSV 和 XLSX 导入/导出商品草稿，导入前显示校验结果 | P0 |
| PROD-007 | 关联主图、详情图、Logo、角标和水印等本地图片素材 | P0 |
| IMG-001 | 选择一张底图和一张叠加图进行预览 | P0 |
| IMG-002 | 调整叠加图位置、缩放和透明度，并可恢复默认值 | P0 |
| IMG-003 | 选择输出尺寸与 PNG/JPG 格式后导出合成图 | P0 |
| IMG-004 | 导出记录关联回商品，且默认不覆盖任何输入文件 | P0 |
| PROD-008 | 多语言草稿、关键词库和标题候选 | P1 |
| IMG-005 | 保存图片模板、批量套用和批量导出 | P2 |

首发图片工具只支持“单底图 + 单叠加图”。旋转、混合模式、滤镜、抠图、文字排版和任意多图层不在范围内。

### 4.4 客服助手

| ID | 需求 | 优先级 |
| --- | --- | --- |
| CS-001 | 新增、查看、编辑、归档客服话术 | P0 |
| CS-002 | 按售前、物流、退款、退货、催发货、评价、缺货、尺码、售后等分类 | P0 |
| CS-003 | 维护语言、标题、正文和使用次数 | P0 |
| CS-004 | 一键复制话术正文，并给出成功或失败反馈 | P0 |
| CS-005 | 记录买家问题、店铺、订单标识、问题类型、状态、下次跟进时间和备注 | P0 |
| CS-006 | 按店铺、状态和到期时间筛选跟进记录 | P0 |
| CS-007 | 支持变量预览、多语言回复草稿和超时提醒 | P1 |
| CS-008 | 对接官方聊天 API 或辅助打开聊天页 | P2 |

首发不读取真实聊天消息，也不自动发送回复。

### 4.5 设置和数据安全

| ID | 需求 | 优先级 |
| --- | --- | --- |
| SET-001 | 配置 Chrome 可执行文件、profile 根目录和默认图片导出目录 | P0 |
| SET-002 | 配置默认货币、显示语言和日志目录 | P0 |
| SEC-001 | SQLite、日志、导出文件和测试数据中不出现平台明文密码 | P0 |
| SEC-002 | 所有外部文件路径在使用前校验存在性、类型和可读写权限 | P0 |
| SEC-003 | 删除、恢复、覆盖和批量动作必须有明确影响说明和确认 | P0 |
| AUDIT-001 | 记录店铺打开、备份恢复、导入和图片导出结果，不记录秘密 | P1 |

## 五、核心用户流程

### 5.1 打开正确店铺

1. 用户在店铺列表搜索或筛选目标店铺。
2. 用户点击打开或某个快捷入口。
3. 系统检查 Chrome 路径、profile 和代理配置。
4. 若 profile 已占用，系统阻止重复启动并说明原因。
5. 若可启动，外部 Chrome 使用该店铺 profile 打开目标地址。
6. 系统显示运行状态并记录最后打开时间。

### 5.2 整理商品并导出主图

1. 用户创建或导入商品草稿。
2. 用户补充价格、SKU、模板和检查项。
3. 用户关联底图与 Logo/角标/水印。
4. 用户在预览中调整位置、缩放和透明度。
5. 用户选择输出尺寸和格式。
6. 系统导出新文件并将记录关联到商品，原图保持不变。

### 5.3 复用话术并跟进

1. 用户按分类和语言找到话术。
2. 用户一键复制并在平台页面手工发送。
3. 用户记录买家问题和下次跟进时间。
4. 到期记录出现在今日工作台。
5. 用户更新处理状态直至解决。

## 六、首发验收标准

### 6.1 店铺

- 可创建至少 20 条店铺记录，重启应用后仍存在。
- 两个店铺使用不同 profile 目录启动 Chrome，登录会话和缓存目录不相同。
- 同一 profile 运行中再次打开时，不启动第二个实例，并显示占用提示。
- 快捷入口使用绑定 profile 打开配置的 URL。
- 配置无认证代理后，Chrome 启动参数包含对应代理；无代理时不附加代理参数。
- 归档店铺后默认列表不显示，但 profile 目录仍存在且可恢复记录。

### 6.2 商品和图片

- 可手工创建商品，也可从有效 CSV/XLSX 导入；无效行会列出行号和原因，不部分静默导入。
- 价格计算结果能追溯到全部输入，不使用隐含汇率或费率。
- 图片预览和导出使用同一组几何参数；基准测试图中叠加层位置误差不超过 1 个输出像素。
- PNG 保留预期透明度；JPG 使用明确背景色。
- 导出到独立文件，输入图片校验和与内容不变。
- 退出并重进应用后，图片素材和导出记录仍关联到原商品。

### 6.3 客服

- 可按分类和语言维护话术，重启后不丢失。
- 点击复制后，系统剪贴板内容与话术正文一致。
- 可创建关联店铺的跟进记录，并在到期日出现在工作台。
- 任何流程都不会自动向平台发送消息。

### 6.4 数据和恢复

- 在包含店铺、商品、图片引用、话术和跟进的数据库上完成备份。
- 在测试目录中恢复备份后，记录数量、关联和设置与备份时一致。
- 备份或恢复失败时保留原数据库，不留下被应用当成有效数据的半成品。
- 对 SQLite 文件和日志进行文本检查，不含测试输入的明文密码标记。

## 七、非功能要求

| 维度 | 要求 |
| --- | --- |
| 平台 | 首发支持 Windows 10/11 x64 |
| 可用性 | 无云账号、无平台 API 时，除外部 Chrome 操作外核心 CRUD 可离线使用 |
| 数据一致性 | 外键启用；多表写入使用事务；所有时间按 UTC 存储、按本地时区显示 |
| 性能 | 500 条店铺或 5000 条商品数据下，筛选和翻页不冻结 UI；阻塞操作不得在 Gio frame 中执行 |
| 可恢复性 | 应用异常退出后数据库可再次打开；运行状态可从真实进程重新核对 |
| 可访问性 | 关键动作有文字或标准图标与 tooltip；状态不只依赖颜色表达 |
| 可诊断性 | 用户可看到可行动的错误；日志包含错误码和上下文，但不含秘密 |
| 语言 | 首发界面为简体中文；业务内容允许多语言 |

## 八、范围决策

| 问题 | 当前决策 |
| --- | --- |
| 产品名 | 店小航 ShopHelm |
| 应用形态 | Windows 本地桌面应用 |
| UI | Go + Gio |
| 数据 | 本地 SQLite 和本地文件引用 |
| 应用账号 | 首发不需要 |
| 平台密码 | 首发不保存 |
| 代理 | 首发只支持无认证代理 |
| 平台能力 | 字段支持多平台，优先按 Shopee 场景设计 |
| RPA | 不进入首发主链路 |
| 图片 | 首发单底图、单叠加图、单张导出 |

## 九、后续范围

- 官方 Shopee Open Platform API。
- 订单、库存、利润和广告 ROI。
- 图片模板与批量导出。
- AI 标题、描述、图片和客服建议。
- 团队账号、权限、同步与审计。
- 在平台允许范围内、人工确认的辅助 RPA。

## 十、待确认但不阻塞地基

- 公开发布前采用哪个仍受支持的 Go 版本。
- 默认支持哪些 Shopee 站点和后台快捷链接种子。
- 价格计算器首发需要哪些用户显式输入的费率。
- 首发安装包采用 ZIP 便携版还是安装器。

这些问题必须在对应实现任务前定稿，不允许 agent 在业务代码中静默猜测。