邹方成
45815bfb7d
refactor(utils): 修复密码哈希比较逻辑错误 feat(user): 新增按状态筛选优惠券接口 docs: 添加虚拟发货与任务中心相关文档 fix(wechat): 修正Code2Session上下文传递问题 test: 补充订单折扣与积分转换测试用例 build: 更新配置文件与构建脚本 style: 清理多余的空行与注释
93 lines
3.7 KiB
Markdown
93 lines
3.7 KiB
Markdown
## 范围与原则
|
||
|
||
* 仅完善用户端（管理端与其 API 保持不变）。
|
||
|
||
* 目标：用户可在 App 端对其奖品资产执行：邀请他人填写地址、兑换积分；若用户已有默认地址，可在 App 端提交发货申请（生成待发货记录），后续由管理端流程发货。
|
||
|
||
## 用户端功能
|
||
|
||
* 我的资产列表与详情
|
||
|
||
* 展示每条资产的当前状态：`持有`、`共享待地址`、`待发货`、`已发货`、`已兑换`。
|
||
|
||
* 操作区：
|
||
|
||
* `邀请他人填写地址`：生成分享链接/二维码，显示有效期与复制按钮；允许撤销与重新生成。
|
||
|
||
* `兑换为积分`：弹窗确认兑换规则与积分值，成功后资产变为“已兑换”。
|
||
|
||
* `申请发货`（可选）：当用户已有默认地址时展示；提交后资产进入“待发货”。
|
||
|
||
* 分享落地页（公域 H5/Web）
|
||
|
||
* 通过一次性 `share_token` 打开表单，填写地址后提交；成功页提示“已提交，等待发货”。
|
||
|
||
* 链接过期/撤销/已消费时展示对应状态页。
|
||
|
||
## 后端（仅用户端与公域接口）
|
||
|
||
* 创建共享地址请求（App 端）
|
||
|
||
* `POST /api/app/inventory/{inventory_id}/address-share/create`
|
||
|
||
* 返回：`share_url`、`expires_at`、`qrcode`（可选）与当前资产状态。
|
||
|
||
* `POST /api/app/inventory/{inventory_id}/address-share/revoke`
|
||
|
||
* 撤销未使用的请求，状态改为 `revoked`。
|
||
|
||
* 申请发货（App 端，可选）
|
||
|
||
* `POST /api/app/inventory/{inventory_id}/request-shipping`
|
||
|
||
* 条件：用户存在默认地址；未兑换/未发货。
|
||
|
||
* 行为：创建 `ShippingRecords` 为“待发货”，后续由管理端更新物流信息。
|
||
|
||
* 兑换积分（App 端）
|
||
|
||
* `POST /api/app/inventory/{inventory_id}/redeem-to-points`
|
||
|
||
* 规则：依据奖品配置（如 `exchange_points_amount`）；写 `user_points_ledger` 动作 `REDEEM_REWARD`，更新 `user_points`；资产标记为“已兑换”。
|
||
|
||
## 数据与安全
|
||
|
||
* 共享请求模型：`shipping_shared_address_requests`（一次性 `share_token`、有效期、状态、审计字段、地址快照或 `user_address_id`）。
|
||
|
||
* 状态机：`OWNED`→`AWAITING_ADDRESS_SHARED`→`SHIPPING_PENDING`→`SHIPPED`；或 `OWNED`→`REDEEMED`。
|
||
|
||
* 幂等与并发：事务校验资产状态；链接一次性消耗；重复操作返回已处理错误码。
|
||
|
||
* 审计：记录创建人、撤销、提交人（可匿名）、IP/UA；所有动作可追踪。
|
||
|
||
## 前端实现（App）
|
||
|
||
* App 页面
|
||
|
||
* `资产详情页`：按钮与状态展示、结果提示、列表刷新；分享弹窗含链接、二维码、有效期、撤销。
|
||
|
||
* `积分兑换弹窗`：展示规则与额度，确认后调用兑换 API。
|
||
|
||
* `申请发货`：若存在默认地址，直接申请；否则引导“邀请他人填写地址”或“去设置默认地址”。
|
||
|
||
## 测试与验收
|
||
|
||
* 单元测试：共享请求生命周期（创建/撤销/过期/提交）、资产状态流转、兑换与申请发货幂等并发。
|
||
|
||
* 集成测试：App 端创建链接→公域表单提交→资产进入待发货；重复提交与过期处理；兑换后禁止申请发货。
|
||
|
||
* 验收：用户端操作闭环生效；状态与流水正确；无重复副作用；管理端无需改动即可继续履约。
|
||
|
||
## 文档与 Swagger
|
||
|
||
* 更新 App 与公域接口说明、错误码、状态枚举与审计字段；保留管理端文档不变。
|
||
|
||
* 执行时按 6A 规范生成 ALIGNMENT/CONSENSUS/DESIGN/TASK/ACCEPTANCE/FINAL 文档并持续维护。
|
||
|
||
## 上线与回滚
|
||
|
||
* 先灰度用户端；监控链接使用量、失败率与发货效率。
|
||
|
||
* 如需回滚，关闭公域入口并撤销未消费请求；资产状态回退并保留审计。
|
||
|