# App账号状态、公共权益与广告接入（0.3.0）

## 账号生命周期

所有路径相对 /v1/apps/{appId}。普通接口使用HUOHUA_APP_TOKEN；/management/和/ads/callbacks/使用独立HUOHUA_APP_MANAGEMENT_TOKEN（配置managementTokenEnv），互不通用且不能下发App前端。管理操作必须由App管理员权限校验后代理，不能把普通用户请求直接转为管理请求。

- POST /auth/revoke-all-sessions：{sessionToken,operationId}，验证本人后撤销所有会话（含当前），返回completed/reauthenticate。
- POST /auth/deactivate：{sessionToken,password,operationId}，当前密码二次确认后注销，删除密码哈希及登录名明文，保存登录名摘要墓碑，不允许同登录名重新注册领取新礼包。
- GET /management/users/{userId}：状态active/disabled/deleted与sessionEpoch。
- POST /management/users/{userId}/{disable|enable|delete|revoke}：{operationId,reason}。禁用可恢复，注销不可恢复。每次变更会话代次并撤销旧会话，恢复后需重新登录。delete也支持外部身份账号的受控注销。

operationId在本App内唯一且固定，建议1～120位字母数字冒号下划线横线；同操作重试不重复执行，不同正文使用相同ID返回409。自助操作首次需有效会话；失效后的同操作重试可在原会话记录仍保留时返回已完成，记录已清理则通过管理状态查询恢复，不重新注册。

注销保留用户ID、身份摘要、状态、必要审计、推广/权益/事件幂等事实，不能用来自动复活用户。它不删除App业务数据库的测评报告；App后端应先持久化关闭任务并阻断访问，再调用公共注销及清理本地资料，失败持续重试。禁用和注销拒绝新登录、领奖、消费和业务事件；已经发生的待发事件仍可靠送达，不重复制造事实。既有消费预留可继续确认或取消；未确认礼包的自动发奖需用户有效，禁用时等待恢复，注销时交受控异常处理，不强行给已注销账号发奖。

## 权益字段与奖励配置

公共服务维护同一份权威余额，App业务库不得再维护同一字段的可写余额。配置字段为整数，带单位与最大余额，不允许负数、溢出或前端指定任意奖励数量。字段定义首次使用绑定后不可直接改单位/上限，调整必须先做数据迁移。场景奖励变更后旧操作ID不能套新规则重复发奖。

~~~json
{
  "managementTokenEnv": "HUOHUA_APP_MANAGEMENT_TOKEN",
  "entitlementFields": {"assessment_unlock_credits": {"unit": "次", "maxBalance": 1000000}},
  "rewardScenes": {
    "ad_unlock": {"field": "assessment_unlock_credits", "amount": 1},
    "new_user_gift": {"field": "assessment_unlock_credits", "amount": 1}
  },
  "giftRewardScene": "new_user_gift",
  "adPlacements": {
    "opening": {"provider": "csj", "type": "splash"},
    "unlock": {"provider": "csj", "type": "rewarded", "rewardScene": "ad_unlock", "keyEnv": "HUOHUA_APP_CSJ_UNLOCK_KEY"}
  }
}
~~~

密钥来自服务端环境，不填明文入文档。不同App和广告位分配独立渠道密钥。模板默认只启用开屏记录；有真实渠道密钥和受控回调入口后再添加激励配置。礼包confirm在同一公共事务直接按giftRewardScene发入该字段，重复confirm不重复发。没有giftRewardScene时沿用外部权益兼容方式，不同时在本地又加一次额度。

- GET /users/{userId}/entitlements：balances数组，含field/balance/held/available，available=balance-held。未发生流水的字段视为零。
- GET /users/{userId}/entitlements/operations?after=上一页末项ID：每页100项，按operationId排序。GET /entitlements/operations/{operationId}查询单条。
- POST /management/entitlements/grant：{appUserId,scene,operationId}，受控后端按已配置奖励场景发放，返回完整manual:前缀操作ID。不提供任意字段数量的公开加款接口。
- POST /entitlements/reservations：{appUserId,field,amount,operationId}，占用可用余额，返回完整consume:前缀操作ID。重试使用原输入ID。
- POST /entitlements/operations/{完整操作ID}/confirm，正文{}：扣减balance并释放held；cancel正文{}释放held不扣款。相反的终态冲突409。

App事务写稳定业务ID及恢复任务，先预留公共额度，再本地生成报告/解锁，成功后confirm，失败cancel。超时先查询原操作，不能换ID重扣。公共预留不自动到期释放，以免报告已生成却因确认丢失得到免费权益；App必须有持久恢复/对账工作。

## 广告（以0.4.0流程为准）

广告现在按SDK完成通知先发奖，后台异步验真，异常记录由火花表单人工核查。完整协议见[广告先发奖异步验真与火花核查](广告先发奖异步验真与火花核查.md)。回调只更新验真事实，不会再发第二次奖励或自动追回。

## 升级与有晟适配

数据库自动升级为版本3。停写备份后升级，旧用户为active、sessionEpoch为0；新增状态、审计、墓碑、字段定义、余额、权益操作、广告上下文及交易表。双向迁移包含这些表，不直接以旧版二进制打开新库。配置新增字段定义时，先离线迁移再启动唯一权威实例。

有晟停止本地bcrypt和硬编码ID，代理公共认证；本地保留头像、封禁业务入口、测评和报告。对新手礼包、广告赠送的测评额度均读取公共assessment_unlock_credits，停用本地重复加款和原SSV发奖路径。提交报告时使用公共预留/确认/取消，不凭本地缓存余额发放权益。App后台封禁同步公共disable，注销协调公共deactivate；账号管理凭据只用于已授权管理操作。

现有本地历史额度不能凭启动时自动覆盖公共余额；先盘点并以唯一迁移操作逐笔对账导入。真实任务字段和奖励审核仍由火花manifest决定，广告及权益事实不自动代表赏金任务已完成。App无需上传心理答案或报告正文。