# 社区团购预定与群互动系统 PRD V0.7

### 新增：供货商付款

平台“内部价与利润率”下增加供货商付款及年、月子菜单，每月可新建多张付款单。商品从当前开团自动带入，付款规格默认箱，可选盒、份、串等。独立维护供货商结算单价，保存后新单自动带入，与内部进货价分开；改变规格必须填写对应单价。首次到货、第二次补货、第三次、第四次手动输入，数量与金额自动汇总。草稿可继续填写，确认已付款后只读；年、月总付款仅计入已确认单据，按付款单日期归属。本次总额实时计算。历史付款单保留当时商品及价格，后续调价不修改历史记录。仅记账，不发起转账。

> 文档状态：用户体验流程审查修订稿  
> 产品阶段：MVP（首个可用版）  
> 首版终端：微信内可打开的手机 H5＋PC 管理后台  
> 首版不包含：在线支付、微信授权登录、短信验证码、积分抽奖

## 1. 产品目标

将微信群里的“手工报数”改成系统内预定，同时保留邻居在群内公开报数带来的互动和从众效果。

首版要解决四件事。

1. 平台一次发布商品和开团信息，200 位团长可直接转发各自的专属入口。
2. 邻居在手机页面中选择数量，系统逐次自动保存预定并归属到对应团长和小区/群。
3. 预定后生成可一键复制的群互动文案，邻居发回微信群。
4. 团长看到群内互动后，在团长端单个或批量审核积分；平台实时查看全部预定和积分数据。

### 1.1 核心体验定义

- **主要用户：** 微信社区群内的邻居，以首次或低频使用者为主；团长属于高频运营用户；平台管理员属于高频后台用户。
- **邻居使用场景：** 从微信群临时进入手机 H5，单手操作，容易被聊天、来电、锁屏或网络波动打断。
- **邻居唯一核心任务：** 在 60 秒内完成商品预定，并明确知道预定已保存、归属哪个团长和群、在哪里提货、何时到货、如何发群以及互动奖励处于什么状态。
- **完成标准：** 预定已经写入服务器并占用有效库存，订单记录包含客户、团长、小区/群、价格快照和商品数量；复制文案和申请互动奖励是预定完成后的独立步骤。
- **关键风险：** 多人并发导致超卖、弱网造成假成功或重复保存、群归属错误、无验证身份被冒用、积分重复领取、取消订单后积分未撤销。
- **当前交付性质：** PRD 与可点击前端原型。原型中的浏览器本地存储仅用于演示，不能作为正式业务数据源。

## 2. 用户与权限

### 2.1 平台管理员

- 创建、编辑、预览、发布、上下架开团活动和商品；支持复制上一次开团、粘贴群发文案智能识别并批量录入 10～15 个商品、手工录入和保存草稿。
- 设置商品名称、品类、主图、宣传文案、平台价、团长允许调价范围、售卖单位、每份规格、最小起订量、数量步长、可预定库存、截止时间和互动积分。
- 可预定库存允许留空，留空表示不限量；也可在开团期间改为具体库存、增加或减少库存，但不能无提示地降到已有有效预定量以下。
- 查看全平台、按活动、按商品、按团长、按小区或群的预定数据。
- 查看团长的客户数、订单数、预定量、待审积分和已发积分。
- 审核团长注册申请，启用或停用团长。
- 将团长分别归入 1 级、2 级或特级价格等级，并独立设置 A/B 配送组；价格等级决定可见供货价，配送组只用于配送批次。
- 导出 Excel/CSV 汇总表和团长分单。
- 配置第三方服务参数，查看连接测试和操作日志。

### 2.2 团长

- 提交注册申请，平台审核通过后使用。
- 管理自己负责的一个或多个小区/微信群，并为每个群设置显示名称和提货点。
- 获取每个“开团＋小区/群”的专属链接、二维码和转发文案。
- 在平台设定的调价范围内微调自己的对客售价，价格快照写入用户订单。
- 仅查看平台为自己价格等级配置的一档供货价，不得查看其他等级供货价；客户不可见任何供货价。
- 仅查看归属自己的客户、预定明细和汇总。
- 按开团、小区/群、商品、用户群昵称、手机号后四位、互动编号搜索。
- 单个审核、多选批量通过或批量驳回互动积分。
- 导出自己名下的预定汇总和客户明细。

### 2.3 邻居用户

- 通过小区/群专属链接进入，先看清团长、小区/群和提货点；首次预定时确认归属并写入订单。
- 非专属链接进入时，可通过邀请码或列表选择团长和小区/群。
- 可先匿名查看当前开团商品；第一次点击加号时填写群昵称和手机号，完成后系统自动继续刚才的预定。
- 在截止时间前修改数量或取消预定。
- 复制系统生成的互动文案，发回微信群。
- 复制成功后点击“我已发群，申请互动奖励”，系统按符合条件的商品品类生成待审核申请。
- 查看自己的预定记录、积分余额和积分明细。

## 3. 核心业务流程

```mermaid
flowchart TD
    A[平台保存开团草稿] --> B[预览并发布]
    B --> C[团长设置允许范围内售价]
    C --> D[按小区群生成专属链接]
    D --> E[邻居打开并确认群与提货信息]
    E --> F[浏览并点击加号]
    F --> G{是否已有有效身份}
    G -- 否 --> H[填写群昵称和手机号]
    H --> I[服务器校验库存并保存预定]
    G -- 是 --> I
    I --> J[页面显示已保存和互动文案]
    J --> K[邻居复制并发回群]
    K --> L[邻居申请互动奖励]
    L --> M[团长按群和用户审核]
    M --> N[积分流水入账]
    I --> O[截单后锁定预定]
    O --> P[到货后按提货点领取]
```

### 3.1 邻居手机端主任务流

| 步骤 | 这一步只做什么 | 用户输入或选择 | 唯一主操作 | 系统反馈 | 失败与恢复 | 返回或退出 |
| --- | --- | --- | --- | --- | --- | --- |
| 1. 进入开团 | 确认团长、群和时间地点 | 无 | 浏览商品 | 显示团长、群、提货点、预计到货、截单时间 | 链接失效时说明原因并提供联系团长入口 | 可直接关闭；再次打开仍进入同一开团 |
| 2. 首次预定 | 选择一个商品数量 | 点击加号 | 增加数量 | 未建身份时打开轻量身份层，保留当前商品与滚动位置 | 商品下架、售罄或已截单时在原卡片说明原因 | 关闭身份层后返回原商品，尚未产生预定 |
| 3. 填写身份 | 建立本次预定归属 | 群昵称、手机号 | 保存并继续预定 | 身份保存后自动执行刚才的一次加号操作 | 就地提示手机号格式或保存失败，不清空已填内容 | 可取消并继续浏览 |
| 4. 连续选品 | 调整各商品数量 | 加号、减号 | 调整数量 | 原卡片依次显示保存中、已预定或失败；底部汇总实时更新 | 库存不足或网络失败时恢复服务器确认的数量，并提供重试 | 切换品类、锁屏或返回页面后恢复已保存数据与位置 |
| 5. 复制文案 | 获取要发群的预定文字 | 单品或总预定 | 一键复制文案发群 | 显示“已复制，请返回微信群发送” | 剪贴板不可用时展示可长按复制的文本 | 可继续选品或稍后再复制 |
| 6. 申请奖励 | 声明已经完成群互动 | 选择申请 | 我已发群，申请互动奖励 | 按符合条件的品类生成待审核记录，显示预计积分 | 重复申请时显示已有记录；失败时可重试 | 可跳过，之后从“我的积分”再次申请 |
| 7. 查看与修改 | 核对自己的最终预定 | 修改或取消 | 保存修改 | 截单前显示预定有效，截单后显示已锁定及提货信息 | 取消失败时保留原有效订单并说明原因 | 返回商品列表时保留筛选和滚动位置 |

### 3.2 团长端主任务流

| 步骤 | 核心任务 | 主操作 | 关键反馈与恢复 |
| --- | --- | --- | --- |
| 1. 建立经营信息 | 完成团长注册并维护多个小区/群、群显示名和提货点 | 提交审核／保存群 | 显示审核状态；保存失败不丢失内容 |
| 2. 准备开团 | 查看平台商品，在允许范围内设置本团售价 | 保存售价 | 显示超范围原因；已有预定后修改只影响新预定，旧订单保留价格快照 |
| 3. 转发开团 | 为每个小区/群获得独立链接、二维码和转发文案 | 复制本群开团文案 | 明确当前链接对应哪个群，避免转错 |
| 4. 查看预定 | 按群、商品和用户查看数量及汇总 | 筛选／导出 | 数据刷新失败保留筛选；导出显示完成、部分失败或重试入口 |
| 5. 审核奖励 | 对待审互动申请单个或批量处理 | 通过／驳回 | 批量操作前显示作用范围；完成后分别报告成功和失败数量；驳回必须填写原因 |

### 3.3 平台后台主任务流

| 步骤 | 核心任务 | 主操作 | 关键反馈与恢复 |
| --- | --- | --- | --- |
| 1. 创建开团 | 复制上一次开团或批量录入本次 10～15 个商品 | 保存草稿 | 自动保存；图片上传、字段校验失败定位到具体商品 |
| 2. 配置规则 | 设置库存、规格、平台价、团长价格范围、积分、截单和到货时间 | 保存规则 | 价格范围和库存规则就地校验，不清空其他商品数据 |
| 3. 预览发布 | 检查用户看到的商品、价格、时间和群文案 | 发布开团 | 发布前显示影响范围；发布成功生成版本和操作日志 |
| 4. 运营调整 | 调整库存、时间和商品状态 | 保存调整 | 若库存低于有效预定量则阻止保存，并进入异常订单处理流程 |
| 5. 汇总与监督 | 查看全平台预定、团长分单和积分流水 | 筛选／导出 | 查询条件可保留；总数、分项和导出数据使用同一统计口径 |

## 4. 预定与互动规则建议

### 4.1 开团与商品

- 一个“开团活动”可包含多个商品，实际运营预计每次展示 10～15 个商品。
- 商品按品类分组展示，支持“全部、水果、蔬菜、水产、肉蛋、米面粮油、其他”等筛选。
- 每个商品默认显示“减号＋0＋加号”数量器，未预定数量为 0，不使用单独的“预定”按钮。
- 用户每点一次加号，该商品预定数量立即加 1 并自动保存，无需再点统一确认。
- 页面提示统一改为“点击＋即预定，系统自动保存”，不得再出现“最后一次确认”或“稍后统一提交”等冲突文案。
- 正式系统以服务器数据为唯一真实来源，浏览器本地存储只用于恢复身份令牌、筛选和滚动位置，不得作为订单与库存依据。
- 每次加减数量都是一次真实的原子更新。请求必须携带幂等标识；同一商品连续快速点击时按顺序合并或排队，服务器最终数量必须与用户最后看到的数量一致。
- 数量操作依次显示“保存中、已预定、保存失败”状态。保存中禁止对同一请求重复提交；保存失败时恢复到服务器最后确认的数量，并在商品卡内说明原因和提供“重试”。
- MVP 库存默认为同一开团商品在全部团长和小区/群之间共享。服务器在数据库事务内同时校验活动状态、截止时间和剩余库存，最后一份库存只能被一个有效请求占用。
- 用户可连续预定多个商品，底部预定汇总始终显示已预定款数、总份数、总金额和按品类去重后的总互动积分。
- 单个商品数量从 0 变为 1 后，在原卡片下方立即生成“已预定数量＋复制文案”，不弹出阻塞整页操作的成功弹窗。
- 同一用户在同一次开团内晚些再次预定时，系统累计到原预定记录，不新建与前次割裂的汇总。
- 商品列表底部自动生成一条“总预定文案”，复制内容只包含所有已预定商品、各自数量、总款数、总份数和总金额。总互动积分仅在页面汇总区展示，不进入复制内容。后续追加或减少数量时总文案实时重新生成。
- 商品支持按“份、袋、箱、斤”等单位售卖。
- “10 斤/份”用规格字段表示，用户在界面中选的数量是“份数”。
- 数量步长可设为 1、2、10 等，用于兼容“必须按 10 斤倍数报”的商品。
- 截止后用户不能新增或修改预定，管理员可手工延长截止时间。
- 平台可在开团中随时调整库存。降库存低于当前有效预定量时，系统必须阻止直接保存，并要求先选择需取消或减量的订单。
- 每个开团商品配置 1 级、2 级、特级三档团长供货价。新增商品未填写时，按平台销售价的 85%、87%、80% 自动生成，金额四舍五入到分。平台可在“商品与库存”或“内部价与利润率”逐品修改，两处共用同一份供货价格。平台可查看和编辑全部三档；团长只读取所属等级的一档；邻居端不得返回供货价。
- “内部价与利润率”自动展示当前开团全部商品，进货价手动填写、可留空，仅平台可见。既有供货价保留；原三档均为平台价占位的商品首次填写进货价时自动生成三档价格；可点击“按默认比例生成”重新计算，支持特价微调，点击“保存并同步”持久化并更新商品库存供货价。
- 利润率按用户确认的文字公式：（客户销售价－团长供货价）÷团长销售价 × 100%。本栏目以平台销售价统一作为客户销售价及团长销售价基准，三档分别计算，进货价不参与该项利润率。团长实际调整对客售价后可能不同；供货价舍入后以实际价格重算利润率，显示两位小数，不强制显示固定的 15%、13%、20%。
- 内部价格采用紧凑逐行表格，商品图片置于名称前。商品、销售价、进货价和三档供货价同行对照；底部“全部保存并同步”替代逐品保存，只提交修改行。先全量校验，再事务保存，任一行无效则整批不写入，失败保留输入；显示待保存数量。窄屏表格内部横向滚动，固定商品识别列。
- 平台“商品与库存”列表显示商品缩略图，并支持按住拖动调整展示顺序；同时提供上移、下移和键盘方向键操作。保存后的顺序同步到团长端和邻居端。
- 平台手工新增单品是默认主流程；低频批量智能识别默认折叠为小入口，点击后才展开，不占据首屏录入空间。
- 团长在平台规定的最低价和最高价内设置本团售价，不得超出范围。已有有效预定保留原价格快照，调价只影响调价成功后的新预定和新增数量，并在保存前明确提示影响范围。
- 开团活动记录预计到货时间，小区/群记录对应提货点。

### 4.2 身份与小区/群归属

- 用户可以先匿名浏览商品；第一次点击加号时才打开轻量身份层，只收集群昵称和手机号，并说明“用于团长核对预定和联系提货”。
- 身份保存成功后，系统自动执行用户刚才触发的一次加号操作，并回到原商品位置，不要求用户重新寻找和点击。
- 专属链接必须携带经过签名的开团、团长和小区/群标识。页面顶部持续显示当前团长、群、提货点、预计到货和截单时间。
- 链接缺少参数、签名无效、活动不存在或链接已停用时，不展示可操作的商品数量器；页面说明具体原因并提供“联系团长”或返回入口。
- 用户已经归属其他团长时，打开新团长链接不得静默迁移。页面显示当前归属和新入口来源，由用户明确确认；变更需要记录时间、原团长、新团长和来源链接。
- 同一团长下的用户可从不同小区/群入口进入，但每笔预定必须固定记录本次入口的小区/群，团长汇总和积分审核按该群区分。
- MVP 不提供手机验证码登录。编辑订单依赖服务器签发并保存在当前浏览器中的设备令牌；清除浏览器数据或更换设备后，由团长协助核对和修改，不能仅凭手机号直接打开他人订单。

### 4.3 订单状态

- 保存中：用户刚点击加减，服务器尚未返回结果，仅为界面临时状态。
- 预定有效：服务器已保存并成功占用库存，无需团长再次确认。
- 已锁定：到达截单时间，数量和价格锁定，用户不能自行修改。
- 已取消：用户或管理员取消。
- 已完成：后续用于表示到货领取，MVP 可保留状态但暂不要求提货核销功能。
- 用户在开团截止前可自行取消；截止后需由团长或平台处理。
- 截单前将数量减至 0 视为取消该商品。取消成功后提供短时“撤销”入口；如果取消会撤销已通过积分，操作前必须明确提示影响。
- 订单状态和互动奖励状态相互独立，团长审核的是奖励申请，不负责确认普通预定是否生效。

### 4.4 互动文案与奖励申请

单品卡片选中后的主状态统一显示如下。

```text
已预定｜糖心紫薯 × 1袋（1.5斤/袋）
```

状态主文案下方显示说明，例如“发回群并经团长确认，本次蔬菜类可得 5 互动积分 · 互动码 6217”。说明只在页面显示，不写入剪贴板。

其中“互动码”保留为用户界面文案，其产品定义是内部互动编号，用于系统记录和客服查询，不代表该编号会出现在微信群消息中。

- 单品复制按钮统一显示两行文字“互动得奖励／一键复制文案发群”。按钮使用醒目的深绿色底色和高对比白色文字，点击区不小于 44px。
- 点击后，剪贴板只包含“已预定｜商品名 × 数量单位（规格）”这一行，不复制积分提示和互动码。
- 总预定文案只复制商品清单、数量、总款数、总份数和总金额；总互动积分继续在页面显示，但不进入剪贴板。
- 互动编号仅作为系统内部申请编号，同时展示给用户和团长用于客服查询；由于编号不进入复制文案，不能再把它作为团长核对微信群消息的依据。
- 平台后台后续可编辑文案前缀和分隔样式，但积分说明与互动编号始终属于页面说明，不进入用户复制内容。
- 点击复制只代表文案进入剪贴板，不代表已经发群，也不自动发放积分。复制成功后显示“已复制，请返回微信群发送”。
- 用户发群后，通过独立按钮“我已发群，申请互动奖励”提交申请。按钮不得默认勾选，也不得把复制成功冒充为奖励申请成功。
- 团长待审记录显示开团、来源群、用户群昵称、手机号后四位、商品或总文案摘要、品类、申请时间和内部互动编号。团长主要根据群昵称、来源群、商品和时间在微信群中核对。
- 无法确认时团长可以驳回并填写原因；用户可在群内完成互动后重新申请，历史记录保留。

### 4.5 积分

- 积分状态包含符合条件未申请、待审核、已通过、已驳回、已撤销。
- MVP 互动奖励暂定为 5 分，与购买数量无关。
- 去重规则暂定为“用户＋开团活动＋商品品类”唯一。同一用户在同一次开团中，将同品类拆成 5 笔或一次预定 5 份，都只能获得一次 5 分。
- 同一次开团购买不同品类时，每个品类可分别生成一次待审互动积分。
- 单品文案可以分别复制，但同一品类只显示一份可申请奖励。复制总预定文案后，系统可一次创建多个品类申请，每个符合条件的品类各生成一条记录。
- 积分审核通过后取消订单，系统生成一条负数撤销流水，保留完整记录。
- 修改数量但仍保留该品类预定时，积分不变；退订后不再保留该品类时，已发积分自动撤销。
- 积分余额由积分流水汇总得到，不允许直接修改余额。

### 4.6 用户提供的实际开团商品样例

| 序号 | 商品 | 规格 | 团购价 | 品类 |
| --- | --- | --- | --- | --- |
| 1 | 糖心紫薯 | 1.5斤/袋 | 9.9元/袋 | 蔬菜 |
| 2 | 蒙阴黄油桃 | 2斤左右/份 | 15.5元/份 | 水果 |
| 3 | 蜜桃百香果 | 500g±30g/份 | 15.8元/份 | 水果 |
| 4 | 南非软皮柑 | 800g±50g/份 | 15元/份 | 水果 |
| 5 | 佳沃蓝莓 | 125g/盒 | 16.8元/盒 | 水果 |
| 6 | 新疆西梅 | 500g/份 | 9.9元/份 | 水果 |
| 7 | 甘极蜜哈密瓜 | 3斤±150g/个 | 9.9元/个 | 水果 |
| 8 | 无沙美贝 | 2.8～3斤左右/袋 | 15.8元/袋 | 水产 |
| 9 | 无沙花蛤 | 2.8斤左右/包 | 15元/包 | 水产 |
| 10 | 小红贝 | 1.8斤左右/包 | 9.9元/包 | 水产 |
| 11 | 福建生蚝 | 1.8～2斤/箱 | 9.9元/箱 | 水产 |

## 5. MVP 页面清单

### 5.1 邻居手机端

1. 群专属开团入口与多商品列表页，顶部持续显示团长、小区/群、提货点、预计到货和截单时间。
2. 商品列表支持 10～15 个商品、品类筛选、行内数量器、保存状态和售罄或已截单状态；商品详情在需要时使用页面或底部层展开。
3. 首次身份填写底部层，仅在第一次预定时出现，完成后回到原商品并继续刚才的操作。
4. 底部实时预定汇总和总预定详情，不设置统一提交步骤；汇总必须标明“已自动保存”。
5. 商品卡内的单品文案复制入口，以及复制后的“我已发群，申请互动奖励”入口。
6. 我的预定页，显示预定有效、已锁定、已取消、提货点和预计到货，并在截单前支持修改或取消。
7. 我的积分及流水页，显示符合条件未申请、待审核、已通过、已驳回和已撤销。

### 5.2 团长端

1. 注册与审核状态页。
2. 数据概览页。
3. 小区/微信群和提货点管理页。
4. 开团转发与团长售价设置页。
5. 预定明细与商品汇总页。
6. 互动积分待审列表和批量操作页。
7. 我的客户页。

团长端预定明细与积分审核优先适配手机浏览，但批量审核、导出和多条件对照在桌面端提供更高密度的表格布局。

### 5.3 平台管理后台

1. 登录页。
2. 全局数据看板。
3. 开团活动管理。
4. 商品编辑、库存、团长调价范围和上下架。
5. 团长审核与管理。
6. 全部预定和汇总导出。
7. 积分规则和积分流水。
8. 互动文案模板。
9. 第三方服务配置。
10. 管理员、角色权限和操作日志。

### 5.4 关键页面状态

| 页面或区域 | 默认／加载 | 成功 | 空状态 | 错误与恢复 | 禁用状态 | 中断恢复 |
| --- | --- | --- | --- | --- | --- | --- |
| 开团商品列表 | 先显示页面骨架和团长信息 | 商品与服务器预定数量一致 | 暂无商品时说明“本团尚未上新” | 加载失败说明网络原因并提供重试 | 已截单、售罄、商品下架时数量器禁用并显示文字原因 | 刷新、锁屏或切后台后恢复筛选、滚动位置和服务器订单 |
| 商品数量器 | 显示服务器已确认数量 | 显示“已预定，已自动保存” | 数量为 0 | 失败后恢复确认数量，原地显示原因与重试 | 保存中暂时禁用同商品重复请求 | 快速连续点击按顺序合并，最终与服务器一致 |
| 首次身份层 | 显示群昵称和手机号用途 | 保存后自动继续原预定 | 不适用 | 格式或网络错误就地提示，保留已填内容 | 保存中主按钮禁用 | 关闭后不产生预定；再次点击加号重新打开 |
| 文案复制与奖励 | 未复制时显示复制按钮 | 复制成功提示下一步；申请成功显示待审核 | 无符合奖励品类时不显示申请按钮 | 剪贴板失败提供长按复制；申请失败可重试 | 已申请品类显示状态而非重复按钮 | 稍后可从我的积分继续申请 |
| 我的预定 | 加载当前开团与历史记录 | 显示有效或锁定订单 | 说明如何返回开团开始预定 | 加载或取消失败时保留原订单并可重试 | 截单后修改按钮禁用并说明原因 | 跨页面返回保留查看位置 |
| 团长批量审核 | 加载待审总数和筛选条件 | 报告成功与失败数量 | 说明暂无待审核申请 | 部分失败保留失败项并允许重试 | 未选择申请时批量按钮禁用 | 刷新后保留筛选条件，不重复处理已完成记录 |
| 平台发布开团 | 自动保存草稿 | 发布成功显示版本、时间和影响团长数 | 新建时提供复制上次开团或添加商品 | 定位到具体商品字段，保留其他已填内容 | 校验未通过时禁止发布 | 刷新或会话恢复后继续草稿 |

### 5.5 跨端体验决策

| 体验点 | 邻居手机 H5 | 团长手机／桌面端 | 平台桌面后台 | 保持一致的内容 |
| --- | --- | --- | --- | --- |
| 导航与布局 | 单列商品流、底部汇总、少量一级入口 | 手机以概览和少量审核为主；桌面使用侧栏和列表详情 | 持久侧栏、表格、筛选和批量工具栏 | 开团、商品、订单、群和积分术语一致 |
| 数量与数据 | 大触控数量器，不依赖悬停 | 手机查看汇总，桌面支持筛选、批量和导出 | 多栏对照全平台数据 | 库存、价格快照和订单状态使用同一服务器口径 |
| 反馈与恢复 | 反馈靠近商品卡，处理弱网和切后台 | 批量操作报告部分成功和失败 | 草稿自动保存，发布与库存调整保留操作日志 | 所有端都区分保存中、成功和失败 |
| 高风险操作 | 取消会影响积分时先提示 | 批量驳回、截止后改单需确认并填原因 | 发布、下架、强制取消和减库存需预览影响范围 | 操作人、时间、原因和变更前后值可追溯 |

## 6. 数据模型初稿

| 数据对象 | 主要用途 |
| --- | --- |
| AdminUser | 平台管理员账号与权限 |
| Leader | 团长档案、状态、邀请码、价格等级（1级/2级/特级）和配送分组（A/B） |
| LeaderGroup | 团长负责的小区/微信群、名称和提货点 |
| CampaignGroupLink | 开团、团长、小区/群和签名令牌，用于专属入口归属与停用 |
| Customer | 邻居群昵称、手机号、默认归属团长和变更记录 |
| CustomerDeviceSession | 当前浏览器的签名设备令牌、有效期和最后使用时间 |
| Campaign | 一次开团活动、时间和状态 |
| Product | 商品公共资料 |
| CampaignProduct | 某次开团里的平台价、三档团长供货价、对客调价范围、规格、步长、排序、全局共享库存、已占用量和数据版本 |
| LeaderOffer | 团长针对某个开团商品的微调售价和价格范围快照 |
| Reservation | 预定主单、客户、团长、小区/群、状态和快照 |
| ReservationItem | 预定的商品、数量、价格快照和最后确认版本 |
| ReservationChange | 数量变更请求、幂等标识、变更前后数量、结果和失败原因 |
| InteractionClaim | 按品类生成的互动奖励申请、内部互动编号、来源群、申请时间、审核人与审核原因 |
| PointLedger | 积分增减流水和关联业务 |
| ApiConfig | 第三方服务参数的加密存储 |
| AuditLog | 后台和团长的关键操作日志 |

关键唯一性与一致性约束：

- `Reservation`：同一客户、开团、团长和小区/群只有一个有效预定主单，晚些再次进入时继续更新原单。
- `ReservationItem`：同一预定主单和开团商品只有一条有效明细，通过更新数量实现追加和退订。
- `ReservationChange`：幂等标识唯一，重复请求不得再次增加数量或扣减库存。
- `InteractionClaim`：同一客户、开团和商品品类只有一条当前有效奖励申请。
- `PointLedger`：每次入账和撤销都关联原申请；余额由不可变流水汇总，不直接写余额。
- `CampaignProduct`：已占用库存不得小于 0 或大于可售库存，库存判断和订单明细写入在同一事务中完成。

## 7. 技术架构建议

### 7.1 产品形态

首版建议做“微信内 H5 ＋ PC 管理后台”。H5 链接可直接发到 200 个团长的群里，无需小程序审核，更适合快速验证业务。后端保持独立 API，后续可增加微信小程序。

### 7.2 建议技术栈

| 层级 | 技术 | 原因 |
| --- | --- | --- |
| 移动 H5 | Vue 3＋TypeScript＋Vite＋Vant | 适合微信手机端，国内生态成熟，后续迁移 uni-app 成本可控 |
| 平台后台 | Vue 3＋TypeScript＋Vite＋Element Plus | 表格、批量操作、筛选和权限界面实现快 |
| 服务端 | NestJS＋TypeScript | 结构清晰，适合权限、审核、订单和后续扩展 |
| ORM | Prisma | 数据库模型直观，迁移和类型提示友好 |
| 数据库 | PostgreSQL | 适合订单、积分流水、统计和事务一致性 |
| 图片存储 | 本地 MinIO，线上可切换阿里云 OSS/腾讯云 COS | S3 兼容接口，本地和云端切换方便 |
| 本地环境 | Docker Compose＋pnpm workspace | 一条命令启动数据库和存储，前后端代码放在同一仓库 |
| 缓存/任务 | Redis（后续按需加） | MVP 先不引入，短信、排队和高频统计出现后再加 |

建议仓库结构。

```text
apps/
  mobile-h5/
  admin-web/
  api/
packages/
  shared-types/
  ui-tokens/
infra/
  docker-compose.yml
docs/
```

### 7.3 第三方 API 可视化配置

后台的“系统设置／第三方服务”预留以下类型。

- 图片存储：Endpoint、Bucket、Region、Access Key、Secret Key、自定义域名。
- 微信：AppID、AppSecret、授权回调域名，后续启用。
- 短信：供应商、Access Key、Secret、签名、模板 ID，后续启用。
- 安全要求：密钥加密入库、界面脱敏、修改留日志、提供“测试连接”按钮。

数据库密码、系统加密主密钥和首个超级管理员密码不适合放在可视化后台，必须放在服务器环境变量中。

### 7.4 预定写入与并发约束

- 数量变更接口接收目标数量、订单项版本和幂等标识，返回服务器最终确认数量、当前价格快照、剩余库存、订单状态和底部汇总。
- 服务端在一个数据库事务中完成活动状态校验、截单校验、库存条件更新、订单项写入和变更日志；任何一步失败都不产生部分结果。
- 同一幂等标识重复请求时返回第一次的结果，不重复增加数量或扣减库存。
- 客户端可以先展示按压反馈，但只有服务器成功返回后才能显示“已预定，已自动保存”；失败时以服务器返回数量覆盖本地临时数量。
- 至少定义并统一处理：活动不存在、链接无效、未建身份、已截单、商品下架、库存不足、价格已变化、版本冲突、请求超时和系统错误。
- 价格变化时，已经保存的数量保留原价格快照；用户继续新增数量前必须看到新价格，并明确新增部分按新价格计算。

## 8. 已选 UI 方向

### A. 邻里暖色（已选定）

- 适合人群：以家庭采购、中老年邻居为主的社区。
- 视觉：米白背景、深绿主色、橙色行动按钮、轻量圆角卡片。
- 商品列表使用“左侧紧凑产品图＋右侧名称、规格、金额和数量”的横向结构，减少大图占屏。
- 页面顶部使用可横向滚动的品类筛选，商品列表保持单列紧凑排布，避免小屏双列导致文字和规格难以辨认。
- 团长、小区/群、提货点、预计到货和截单时间在开始选品前清楚可见；页面提示“点击＋即预定，系统自动保存”。
- 每张商品卡的数量器始终可见，数量从 0 开始，点加号触发服务器保存，并在原卡片依次显示保存中、已预定或失败重试。
- 保存成功后展开“已预定数量＋复制文案”轻量状态条；复制成功后再显示“我已发群，申请互动奖励”，两个动作不混为一个状态。
- 底部固定显示“已预定多少款＋总份数＋总金额＋总互动积分＋查看全部预定”，并明确显示“已自动保存”。
- 邻居公开预定动态作为辅助信息，不抢占用户自己订单状态的优先级。
- 优点：亲和、信任感强、字大、上手快。
- 风险：促销感相对弱。

### B. 鲜购市集（备选）

- 适合人群：对秒杀、价格、剩余数量敏感的团购用户。
- 视觉：高亮橙红、鲜绿、高对比价格、开团进度和截止时间。
- 优点：成交氛围强，价格和紧迫感清楚。
- 风险：信息密度偏高，需控制视觉噪音。

### C. 群聊互动（备选）

- 适合人群：已经习惯微信群报数，迁移阻力较大的社区。
- 视觉：聊天流、邻居预定动态、蓝绿状态色、底部快捷报数。
- 优点：最接近原有群内习惯，互动感最强。
- 风险：要明确告知用户，页面内动态只展示系统预定，不是微信聊天记录。

## 9. 非功能要求

- 手机优先，最小支持 375px 宽度，主要按钮点击区不小于 44px。
- 图片压缩和懒加载，微信内首屏目标 3 秒内可操作。
- 普通说明文字在目标用户手机上不得小于 12px，并支持系统文字放大、长中文换行和横竖屏切换；核心状态不能只依赖颜色表示。
- 平台、团长、用户数据按角色严格隔离。
- 库存占用、数量变更、积分入账和积分撤销使用数据库事务；所有写入接口支持幂等标识，服务器时间作为截单判断依据。
- 用户点击后 100ms 内必须出现可感知的按压或保存中反馈；弱网、超时和断网不得显示虚假成功。
- 刷新、浏览器返回、微信切后台和锁屏恢复后，页面从服务器重新校准订单，同时尽量恢复筛选和滚动位置。
- 只收集群昵称和手机号等 MVP 必要信息，在首次填写处说明用途；手机号在团长列表中默认脱敏，导出权限和数据保留周期可由平台配置。
- 关键管理操作保留操作人、时间、对象和变更内容。
- 每日自动备份数据库，并定期验证备份可恢复。

## 10. 暂定验收标准

1. 平台可在 3 分钟内创建并上架一个开团商品。
2. 团长可获取每个小区/群的专属链接；用户打开后先看清归属信息，首次预定时确认并写入对应团长和群。
3. 用户可在 60 秒内完成首次身份填写、选数量、服务器保存预定和复制互动文案。
4. 同一用户将同一次开团的同品类拆单预定，只能获得一次 5 分互动积分。
5. 团长可对待审列表单选或多选审核，且不能看到其他团长的数据。
6. 平台的商品汇总数与各团长分单合计一致。
7. 取消已发积分的订单后，余额正确扣回且流水可追溯。
8. 一次开团展示 15 个商品时，用户可在不离开列表位置的情况下连续选择至少 5 个商品。
9. 单个商品选择成功后不出现阻塞弹窗，已选状态和复制文案入口就地显示。
10. 品类切换后底部预定单不丢失已选商品。
11. 未预定商品数量显示 0；点击加号后立即出现保存反馈，服务器确认后数量变为 1、状态显示已自动保存且单品互动文案可复制。
12. 同一用户分两个时间预定 2 款商品后，总预定文案包含两款商品的最新数量，总金额与总份数正确。
13. 总互动积分按商品品类数量去重计算，两个水果商品合计 5 分，一个水果加一个水产商品合计 10 分。
14. 单品状态显示“已预定｜商品名 × 数量单位（规格）”，复制按钮统一显示“互动得奖励／一键复制文案发群”。
15. 单品和总预定文案的剪贴板内容均不包含积分说明与互动编号；二者仍可在页面中清楚查看。
16. 当两个用户同时预定最后一份库存时，只允许一个请求成功；另一个用户看到库存不足，数量恢复为服务器确认值。
17. 当同一用户快速连续点击同一商品加号 5 次时，服务器最终数量与界面最终数量一致，不产生重复订单或多扣库存。
18. 当数量保存超时或断网时，商品卡显示失败原因和重试入口，不显示“已预定”，且用户其他已保存商品不受影响。
19. 当首次用户点击加号并完成身份填写后，系统自动继续刚才的预定，并回到原商品和原滚动位置。
20. 当专属链接无效、停用或开团不存在时，页面不允许预定，并明确说明原因和联系团长的方式。
21. 当用户复制文案时，只显示复制成功和发群提示，不自动创建积分；点击“我已发群，申请互动奖励”后才生成待审核记录。
22. 当互动编号不进入群文案时，团长仍可通过来源群、用户群昵称、商品或文案摘要和申请时间完成核对；内部编号只用于系统记录和客服查询。
23. 当用户购买同品类多个商品时，只能申请一份该品类奖励；购买多个不同品类时，每个符合条件的品类分别生成一条申请。
24. 当用户在截单前取消某品类全部预定时，该品类未审核申请自动失效；已通过积分生成可追溯的负数撤销流水。
25. 当页面文字放大至 200% 或使用 360px 宽手机时，商品名称、数量器、保存状态和主要操作不被遮挡，页面不产生整页横向滚动。

## 11. 第一轮已确认结果

1. 首版使用“昵称＋手机号＋浏览器记住”的轻量身份，后续接入微信授权或短信登录。
2. 客户默认归属一个团长。
3. 团长可管理多个小区/微信群，订单和积分审核需区分具体来源群。
4. 用户可在截止前修改数量或退订，退订后按规则撤销积分。
5. 平台可在开团中增加或减少库存。
6. 互动积分暂定 5 分，同一用户在同一开团的同品类仅奖励一次。
7. 团长可在平台设定范围内微调对客售价。
8. MVP 记录提货点和预计到货时间。
9. 用户端采用 A 邻里暖色方案，商品卡改为左图右文，下方显示本人预定状态和可复制文案。

## 12. 第二轮已确认结果

1. 互动积分按“用户＋开团活动＋商品品类”去重，下一次开团可重新获得该品类积分。
2. 平台为每个开团商品分别设置团长可用的最低售价和最高售价。
3. 平台减库存低于已预定量时，系统阻止保存，必须先选择需要减量或取消的订单。
4. 当时确认 MVP 不要求用户上传群聊截图；V0.7 将互动码调整为内部互动编号，团长改用来源群、用户群昵称、商品或文案摘要和申请时间进行人工核对。
5. 一次开团支持多个商品，数量器每次点击立即保存预定，不再设置“加入预定单后统一提交”的二次确认。
6. 实际每次开团预计 10～15 个商品，用户选择某个商品后必须可继续浏览和预定其他商品。

## 13. 第四轮已确认结果

1. 单品已选状态统一显示“已预定｜商品名 × 数量单位（规格）”。
2. 单品复制按钮当时统一显示“感恩互动／复制文案”。
3. 积分获得条件和互动编号保留在商品卡片说明区，仅供用户查看，不进入复制内容。
4. 单品复制文案只保留预定信息；总预定复制文案只保留商品清单、数量和金额汇总。

## 14. 第五轮已确认结果

1. 单品复制入口改为醒目的深绿色实心按钮，并使用高对比白色文字。
2. 按钮文案更新为两行“互动得奖励／一键复制文案发群”。
3. 按钮保持足够字号和至少 44px 的点击高度，在小屏手机上不得挤压、截断或横向溢出。

## 15. V0.7 用户体验审查修订结果

1. 明确邻居核心任务的完成标准是服务器保存成功并占用库存，复制和申请互动奖励属于后续独立步骤。
2. 补充邻居、团长和平台三端主任务流，每一步写明主操作、反馈、失败恢复和退出方式。
3. 取消普通预定的“待确认／已确认”歧义，调整为保存中、预定有效、已锁定、已取消和已完成；团长只审核互动奖励。
4. 明确点击加减即触发服务器原子保存，无统一提交；补充幂等、快速连点、最后库存竞争、弱网失败和数量回滚规则。
5. 首次身份填写延迟到第一次预定，完成后自动继续原操作；专属链接失效、跨团长归属和换设备恢复均有明确处理。
6. 修正互动编号不进入复制文案却用于群内核对的矛盾。编号仅用于系统和客服查询，团长按来源群、群昵称、商品摘要和时间核对。
7. 将“复制成功”和“我已发群，申请互动奖励”拆成两个真实状态，避免复制即得分的误解。
8. 补充默认、加载、空、成功、失败、禁用和中断恢复状态，以及手机、团长端和平台后台的跨端差异。
9. 新增并发库存、断网、链接失效、文字放大、品类去重和积分撤销等可观察验收标准。
10. 本版本更新的是 PRD；现有 `selected-a.html` 仍是前端演示原型，其中“最后一次确认”和本地存储逻辑需要在下一轮原型更新时同步。

## 16. 阶段划分建议

### 阶段 1，可用 MVP

开团和商品、库存调整、团长注册审核、多小区/群管理、提货点和到货时间、团长调价、群专属链接和自动归属、轻量客户身份、预定与退订、互动文案、品类积分去重和审核、三端数据、导出、第三方配置入口。

### 阶段 2，运营完善

微信授权或手机验证码登录、提货核销、到货通知、更完整的统计报表、异常订单处理。

### 阶段 3，增长和交易

积分抽奖、累计积分大奖、在线支付、退款、小程序、营销活动和用户分层。

## 17. V0.7 本地试用版实现状态

2026-09-05 已从静态原型升级为可本地运行的前后端一体 MVP，代码位于 `mvp/`。

- 邻居端已接入服务器与 SQLite：群专属入口、首次轻量身份、11 款商品、品类筛选、加减即保存、预定与退订、单品和总文案、独立奖励申请、我的预定和积分流水。
- 团长端已接入服务器：注册申请、多群创建与提货信息维护、群专属入口、允许范围内调价、名下预定、CSV 导出、积分单选与批量审核。
- 平台端已接入服务器：全局看板、复制和发布开团、商品文案智能识别与批量录入、手工新增、图片上传、不限量或具体库存、库存保护、团长审核、预定和积分汇总、CSV 导出、第三方配置与操作日志。
- 服务端已实现：SQLite 事务、幂等数量请求、共享库存、价格批次、按角色查询、品类积分唯一约束、退订撤销流水和关键索引。
- 自动化测试覆盖核心预定链路与管理链路；运行命令为 `node --test "tests/*.test.js"`。

本地试用版仍按本 PRD 的阶段边界不实现在线支付、微信授权登录、短信验证码、抽奖和提货核销。平台端与团长端当前使用本地演示身份，正式部署前需接入生产级登录、权限和密钥管理。