cursor/plans/status_接口字段精简_8ba244ad.plan.md

name, overview, todos, isProject

name	overview	todos	isProject
status 接口字段精简	对照需求文档精简 C 端 status/claim 响应字段，并将所有金额由千分位（qf）转为大单位（与全站 getNumberFormat 一致）；innerapi 仍返回 qf 全量。	id content status package-list-for-client FreeCreditsPackageModel::listForClient() 返回精简字段，amount 经 getNumberFormat 转大单位 completed id content status slim-build-status buildStatus 去掉 activity_id；顶层金额与 packages 均转大单位 completed id content status format-first-cashout-amount firstCashout 响应 data.amount 同步转大单位（Pay 入参仍用 qf） completed id content status update-controller-phpdoc 更新 FreeCreditsController PHPDoc：金额为展示单位 float，非千分位 completed id content status client-status-test 单测断言字段白名单及 78500 qf → 78.5 等大单位转换 completed	false

Free Credits status 接口字段精简

结论

可以且应该精简。 当前 buildStatus() 直接 toArray() 透出库表列，超出需求文档中 C 端 UI 所需信息；activity_id 仅用于后台/内部关联，C 端无展示或交互用途。

你已确认：

• 只做删减，不新增 total_deposit（累计充值进度由 C 端从钱包侧获取）。
• 金额转大单位：C 端接口不再返回千分位整数，统一转为展示金额（与 AgentController::formatAmountToFloat、CommonFn::getNumberFormat 一致，默认 moneyFormat=1000、moneyDot=2，如 qf 78500 → 78.5）。

---

需求文档 vs 当前响应

需求文档（首充前免费余额定格与分档释放需求文档.md）描述的是 UI 行为，未定义 JSON 契约，但可反推 C 端必需数据：

UI 场景（文档章节）	C 端需要的数据
是否展示活动（status === -1 隐藏）	status
首页 Withdraw 是否曾达赢取门槛（§5.2、§7）	home_withdraw_unlocked
池总额 / 入口副标题「$78.50 pending」（§6.3–6.6、§9.3、§14.2）	frozen_amount
问号弹窗 / 第一档金额（§8、§10）	first_cash_amount、recharge_unlock_amount
档位列表 Withdraw / Unlock / Claim / Claimed（§9.3、§10–12）	packages[]：id、package_type、amount、status
发起 claim / 第一档提现（现有 API）	packages[].id → POST package_id

当前多出的字段：

• 顶层：activity_id（recharge_gift_config.id，仅 innerapi/编排用）
• packages[] 全表列：player_id、activity_id、uid、withdraw_order_id、claim_biz_id、unlocked_time、claimed_time、completed_time、create_time、update_time
• package_no 可保留（便于调试与稳定排序展示），也可仅靠数组顺序；建议 保留（成本低、与 DB 序号一致）

命名与单位： packages 字段由 amount_qf 改为 amount；顶层与各档 amount 均为大单位 float（非 qf），C 端可直接用于 $78.50 类文案，无需再 /1000。

---

目标响应契约（C 端）

{
  "status": 4,
  "home_withdraw_unlocked": 1,
  "frozen_amount": 78.5,
  "first_cash_amount": 20,
  "recharge_unlock_amount": 50,
  "packages": [
    {
      "id": 101,
      "package_no": 1,
      "package_type": 1,
      "amount": 20,
      "status": 1
    }
  ]
}

status === -1 时仍仅 { "status": -1 }（与现逻辑一致）。

转换规则（实现）：

// 与全站 C 端金额一致；qf 为库表 / 内部逻辑整数
private function formatClientAmount(int $amountQf): float
{
    return (float) CommonFn::getNumberFormat($amountQf);
}

• 应用于：frozen_amount、first_cash_amount、recharge_unlock_amount、packages[].amount。
• firstCashout 成功响应 data.amount 同样转大单位；调用 Pay / 钱包时仍传 qf，仅 JSON 对外转换。
• innerapi / 单测写库 仍使用 _qf 整数，不在 DB 层改单位。

---

实现方案

flowchart LR
  statusApi[status_claim_firstCashout]
  buildStatus[buildStatus]
  clientDto[toClientStatusDto]
  modelFull[listByPlayerId_toArray]
  innerapi[innerapi_list]
  statusApi --> buildStatus --> clientDto
  buildStatus --> modelFull
  innerapi --> modelFull

1. Logic 层统一转换（FreeCreditsLogic）

   • 新增 formatClientAmount(int $amountQf): float（封装 CommonFn::getNumberFormat）。
   • 供 buildStatus、listForClient（或 Model 回调）、firstCashout 响应共用。

2. Model 层 C 端 packages（FreeCreditsPackageModel）

   • 新增 listForClient(int $playerId, callable $formatAmount): array 或 Logic 内 array_map：只输出 id、package_no、package_type、amount（大单位）、status。
   • 保留 listByPlayerId() 供 innerapi、dev、集成测试。

3. 收口 DTO（buildStatus）

   • 去掉 activity_id。
   • 顶层三金额字段经 formatClientAmount；packages 用 listForClient。
   • status()、claim() 经 buildStatus 返回，结构一致。

4. firstCashout 响应

   • return ['order_id' => ..., 'amount' => $this->formatClientAmount($package->amount_qf)]。

5. 更新文档（FreeCreditsController PHPDoc）

   • 删除「千分位整数、展示时除以 1000」描述；改为「金额为大单位 float，精度见 moneyDot」。

6. 单测

   • 新增 FreeCreditsClientStatusTest：字段白名单 + 78500 qf → 78.5 转换断言。

7. 不改动

   • innerapi/controller/FreeCreditsController 仍返回全量 toArray()。
   • FreeCreditsFreezeDev 等内部工具继续用 listByPlayerId。

---

字段对照表（精简前后）

字段	精简前	精简后	说明
activity_id	有	删	C 端不需要
status	有	有	主状态机
home_withdraw_unlocked	有	有	§5.2
frozen_amount	qf 整数	float 大单位	如 78.5
first_cash_amount	qf 整数	float 大单位	如 20
recharge_unlock_amount	qf 整数	float 大单位	如 50
packages[].id	有	有	claim/cashout
packages[].package_no	有	有	序号展示
packages[].package_type	有	有	1=提现档 2=领取档
packages[].amount	amount_qf（qf）	amount（float 大单位）	重命名 + 转换
firstCashout.data.amount	qf	float 大单位	与 status 一致
packages[].status	有	有	UI 状态
packages[].player_id/uid/...	有	删	内部字段
packages[].withdraw_order_id 等	有	删	轮询靠主 status + package status

---

风险与协调

• Breaking change：C 端需改为直接使用大单位金额（不再 /1000）；删除 activity_id、amount_qf 及 packages 审计字段。
• 精度：与 ShareConfigService::moneyDot / moneyFormat 绑定，勿手写 /1000，避免与 VIP/钱包接口不一致。
• 累计充值进度：不纳入本次接口；C 端继续从钱包统计接口取（钱包侧金额亦通常为大单位）。