## 范围与原则

* 仅完善用户端（管理端与其 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 文档并持续维护。

## 上线与回滚

* 先灰度用户端；监控链接使用量、失败率与发货效率。

* 如需回滚，关闭公域入口并撤销未消费请求；资产状态回退并保留审计。