邹方成
45815bfb7d
refactor(utils): 修复密码哈希比较逻辑错误 feat(user): 新增按状态筛选优惠券接口 docs: 添加虚拟发货与任务中心相关文档 fix(wechat): 修正Code2Session上下文传递问题 test: 补充订单折扣与积分转换测试用例 build: 更新配置文件与构建脚本 style: 清理多余的空行与注释
3.7 KiB
范围与原则
-
仅完善用户端（管理端与其 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 文档并持续维护。
上线与回滚
-
先灰度用户端；监控链接使用量、失败率与发货效率。
-
如需回滚，关闭公域入口并撤销未消费请求；资产状态回退并保留审计。