feat(points): 对齐后端积分/订阅 API 最终契约（types + API 层改造） #1956

Merged

auto-approve-bot merged 36 commits from fix/points-api-contract-v2 into develop 2026-09-16 10:53:58 +08:00

Conversation 4 Commits 36 Files Changed 18

+1649 -1127

xiaoxia commented 2026-09-16 10:21:39 +08:00

Owner

Copy Link

Copy Source

📋 改造概述

对齐灵应 09:16 确认的 staging 实测最终契约，完成积分/订阅系统的类型层 + API 层改造。保持 POINTS_API_MOCK=true，等后端 P0（支付通道接入）完成后切 false 联调。

✅ 完成项

类型层（api/points/types.ts + api/subscription/types.ts）

• 字段改名：scene_name→name、points_per_use→base_points、包 id→code、units→quantity
• 单位统一：价格全部 price_cents（分），前端 ÷100 展示
• 流水枚举：PointsTxType = "add" | "deduct"（refund 通过 source=refund:<origin> 前缀标识）
• 余额精简：移除 free_clips_used/limit/remaining，免费额度改由 DailyUsage 提供
• 包结构：移除 4 档 discounted_price_for_*，前端按 price_cents * (user_discount ?? 1) / 100 算折后
• 流水分页：{items,total,page,page_size}；source_name 移除，前端按 source 映射中文名；ref_id 是 "" 非 null；移除 signed_amount，前端按 type 算正负
• 新增类型：DailyUsage（GET /usage/daily）、MembershipResponse（GET /points/subscription/membership，含 max_resolution）、SubscriptionPlan（GET /subscription/plans，4 档 free/monthly/quarterly/yearly）、BillingRecord（GET /subscription/billing-records）、CreateRechargeOrderResponse.pay_params/points_amount/expire_at
• 订阅重构：旧 MemberType(free/monthly/quarterly/yearly) + billing_cycle(monthly/yearly) 双维度 → 新 PlanId(free/monthly/quarterly/yearly) + BillingCycle，旧 PlanType 保留别名兼容；端点 POST /subscription/subscribe → POST /subscription/change-plan {target_plan_id,billing_cycle}；取消续费拆为 /subscription/cancel + /subscription/toggle-auto-renew {enabled}
• 错误响应：统一 {error:{code,message,valid_scenes?}}
• 规则补回 description 字段（后端已补）

API 层（api/points/index.ts + api/subscription/subscription.ts）

• 所有请求改走 apiClient（baseURL=/api/v1 + token 拦截器），不再用裸 request
• 新增接口：getDailyUsage()、getMembership()、getSubscriptionPlans()
• 更新接口：getPointsPackages/getPointsRules/getPointsTransactions/checkPoints/createPointsOrder 字段对齐
• 拆分接口：订阅相关 API 收敛到 api/subscription/（changePlan/cancelSubscription/toggleAutoRenew/getSubscriptionPlans/getBillingRecords）
• MOCK 数据：MOCK_BALANCE/RULES/PACKAGES/TRANSACTIONS/DAILY_USAGE/MEMBERSHIP/PLANS/BILLING 全部更新匹配新类型，pay_params: {}、points_amount 字段已补

消费端最小适配

• pointsStore：init 并行拉取 balance + rules + subscription + dailyUsage + membership；新增 dailyUsage/membership 状态；optimisticAdd/Deduct 同步更新 membership.points_balance
• PointsBadge：会员标签优先取 membership.member_type，降级取 subscription.plan_id；tooltip 展示 max_resolution
• PointsCost：props 改 source + quantity + durationMinutes，units 保留兼容；非会员免费额度从 dailyUsage.free_clips_remaining 取；支持 compact 模式
• points/Center：免费额度卡片改为 dailyUsage 驱动；会员标签+倍率提示从 store 取；reset_at 展示重置时间
• points/Packages：pkg.code/pkg.price_cents，getDiscountPriceCents 算折后；createPointsOrder 提示支付通道待接入
• points/Transactions：type 改 add/deduct，SOURCE_LABEL 前端映射 source→中文名（含 refund: 前缀）；分页走 Tabs 本地过滤（服务端分页预留）
• subscription/Plans：走 getSubscriptionPlans() 动态渲染 4 档，changePlan({target_plan_id,billing_cycle})；移除旧 SUBSCRIPTION_PLANS 硬编码
• subscription/Billing：Descriptions 展示当前订阅、Switch 自动续费、Cancel 二次确认；账单表列对齐新 BillingRecord（amount_cents/plan_id/order_type/status）
• subscription/UpgradeSubscription：付费档位改为 monthly/quarterly/yearly；constants.ts 价格对齐 19.9/39.9/159；useSubscription hook 同步 PlanId/BillingCycle 类型
• generate/hooks/pointsCost：hasEnoughPoints 签名更新（接收 dailyUsage/plans/currentPlanId/freeMultiplier），非会员 ceil(base × 1.15)、会员 floor(base × points_discount)；PointsBadge 路径保留 points_balance 冗余
• generate/GeneratePage：从 store 解构 dailyUsage/rules 传入 hasEnoughPoints；useMemo deps 补齐

🔴 等后端 P0（不阻塞本次合入）

1. 支付通道：POST /points/recharge pay_params 当前返回 {}，支付跳转待通道接入后对接
2. POINTS_API_MOCK 切 false 联调：等后端所有端点稳定后切真实接口
3. 向导步骤编号 off-by-one：已在 Issue #1954 跟踪，另起 PR 修复

🧪 验证

• Prettier 格式化通过
• ESLint: TS 类型对齐（旧字段全部移除，无残留）
• MOCK 模式 UI 可正常渲染积分中心/充值/流水/订阅页

## 📋 改造概述 对齐灵应 09:16 确认的 staging 实测最终契约，完成积分/订阅系统的类型层 + API 层改造。保持 `POINTS_API_MOCK=true`，等后端 P0（支付通道接入）完成后切 false 联调。 ## ✅ 完成项 ### 类型层（api/points/types.ts + api/subscription/types.ts） - **字段改名**：`scene_name→name`、`points_per_use→base_points`、包 `id→code`、`units→quantity` - **单位统一**：价格全部 `price_cents`（分），前端 `÷100` 展示 - **流水枚举**：`PointsTxType = "add" | "deduct"`（refund 通过 `source=refund:<origin>` 前缀标识） - **余额精简**：移除 `free_clips_used/limit/remaining`，免费额度改由 `DailyUsage` 提供 - **包结构**：移除 4 档 `discounted_price_for_*`，前端按 `price_cents * (user_discount ?? 1) / 100` 算折后 - **流水分页**：`{items,total,page,page_size}`；`source_name` 移除，前端按 `source` 映射中文名；`ref_id` 是 `""` 非 null；移除 `signed_amount`，前端按 type 算正负 - **新增类型**：`DailyUsage`（GET /usage/daily）、`MembershipResponse`（GET /points/subscription/membership，含 `max_resolution`）、`SubscriptionPlan`（GET /subscription/plans，4 档 free/monthly/quarterly/yearly）、`BillingRecord`（GET /subscription/billing-records）、`CreateRechargeOrderResponse.pay_params/points_amount/expire_at` - **订阅重构**：旧 `MemberType(free/monthly/quarterly/yearly)` + `billing_cycle(monthly/yearly)` 双维度 → 新 `PlanId(free/monthly/quarterly/yearly)` + `BillingCycle`，旧 `PlanType` 保留别名兼容；端点 `POST /subscription/subscribe` → `POST /subscription/change-plan {target_plan_id,billing_cycle}`；取消续费拆为 `/subscription/cancel` + `/subscription/toggle-auto-renew {enabled}` - **错误响应**：统一 `{error:{code,message,valid_scenes?}}` - **规则补回 description 字段**（后端已补） ### API 层（api/points/index.ts + api/subscription/subscription.ts） - 所有请求改走 `apiClient`（baseURL=/api/v1 + token 拦截器），不再用裸 request - **新增接口**：`getDailyUsage()`、`getMembership()`、`getSubscriptionPlans()` - **更新接口**：`getPointsPackages/getPointsRules/getPointsTransactions/checkPoints/createPointsOrder` 字段对齐 - **拆分接口**：订阅相关 API 收敛到 `api/subscription/`（`changePlan/cancelSubscription/toggleAutoRenew/getSubscriptionPlans/getBillingRecords`） - **MOCK 数据**：MOCK_BALANCE/RULES/PACKAGES/TRANSACTIONS/DAILY_USAGE/MEMBERSHIP/PLANS/BILLING 全部更新匹配新类型，`pay_params: {}`、`points_amount` 字段已补 ### 消费端最小适配 - **pointsStore**：init 并行拉取 balance + rules + subscription + dailyUsage + membership；新增 `dailyUsage/membership` 状态；`optimisticAdd/Deduct` 同步更新 membership.points_balance - **PointsBadge**：会员标签优先取 `membership.member_type`，降级取 `subscription.plan_id`；tooltip 展示 max_resolution - **PointsCost**：props 改 `source + quantity + durationMinutes`，`units` 保留兼容；非会员免费额度从 `dailyUsage.free_clips_remaining` 取；支持 compact 模式 - **points/Center**：免费额度卡片改为 `dailyUsage` 驱动；会员标签+倍率提示从 store 取；`reset_at` 展示重置时间 - **points/Packages**：`pkg.code/pkg.price_cents`，`getDiscountPriceCents` 算折后；createPointsOrder 提示支付通道待接入 - **points/Transactions**：type 改 add/deduct，`SOURCE_LABEL` 前端映射 source→中文名（含 `refund:` 前缀）；分页走 Tabs 本地过滤（服务端分页预留） - **subscription/Plans**：走 `getSubscriptionPlans()` 动态渲染 4 档，`changePlan({target_plan_id,billing_cycle})`；移除旧 SUBSCRIPTION_PLANS 硬编码 - **subscription/Billing**：Descriptions 展示当前订阅、Switch 自动续费、Cancel 二次确认；账单表列对齐新 BillingRecord（amount_cents/plan_id/order_type/status） - **subscription/UpgradeSubscription**：付费档位改为 monthly/quarterly/yearly；constants.ts 价格对齐 19.9/39.9/159；useSubscription hook 同步 PlanId/BillingCycle 类型 - **generate/hooks/pointsCost**：`hasEnoughPoints` 签名更新（接收 dailyUsage/plans/currentPlanId/freeMultiplier），非会员 `ceil(base × 1.15)`、会员 `floor(base × points_discount)`；PointsBadge 路径保留 points_balance 冗余 - **generate/GeneratePage**：从 store 解构 dailyUsage/rules 传入 hasEnoughPoints；useMemo deps 补齐 ## 🔴 等后端 P0（不阻塞本次合入） 1. **支付通道**：POST /points/recharge pay_params 当前返回 {}，支付跳转待通道接入后对接 2. **POINTS_API_MOCK 切 false 联调**：等后端所有端点稳定后切真实接口 3. **向导步骤编号 off-by-one**：已在 Issue #1954 跟踪，另起 PR 修复 ## 🧪 验证 - Prettier 格式化通过 - ESLint: TS 类型对齐（旧字段全部移除，无残留） - MOCK 模式 UI 可正常渲染积分中心/充值/流水/订阅页

xiaoxia added 18 commits 2026-09-16 10:21:39 +08:00

chore(points): align types/api with final backend contract - apps/web/src/api/points/types.ts 1d960a9111

chore(points): align types/api with final backend contract - apps/web/src/api/subscription/types.ts d022895542

chore(points): align types/api with final backend contract - apps/web/src/pages/points/Transactions.tsx 7e9a6ff358

chore(points): align types/api with final backend contract - apps/web/src/pages/subscription/hooks/useSubscription.ts 875b54df7f

chore(points): align types/api with final backend contract - apps/web/src/components/common/PointsBadge/index.tsx a4e54011ca

chore(points): align types/api with final backend contract - apps/web/src/pages/subscription/Billing.tsx 5745d51b5a

chore(points): align types/api with final backend contract - apps/web/src/pages/points/Center.tsx e4f70f8449

chore(points): align types/api with final backend contract - apps/web/src/pages/points/Packages.tsx d022454b2b

chore(points): align types/api with final backend contract - apps/web/src/pages/generate/hooks/pointsCost.ts 917152a8ac

chore(points): align types/api with final backend contract - apps/web/src/api/subscription/index.ts e8174c1680

chore(points): align types/api with final backend contract - apps/web/src/pages/subscription/UpgradeSubscription.tsx 5cefc5d630

chore(points): align types/api with final backend contract - apps/web/src/store/pointsStore.ts 0abd23466a

chore(points): align types/api with final backend contract - apps/web/src/api/subscription/subscription.ts 838418614b

chore(points): align types/api with final backend contract - apps/web/src/pages/subscription/Plans.tsx efa33f210f

chore(points): align types/api with final backend contract - apps/web/src/pages/subscription/constants.ts e404de4fed

chore(points): align types/api with final backend contract - apps/web/src/pages/generate/GeneratePage.tsx 71e36d1f30

chore(points): align types/api with final backend contract - apps/web/src/api/points/index.ts b37ca41207

chore(points): align types/api with final backend contract - apps/web/src/components/common/PointsCost/index.tsx 8dbc8b48f3

xiaoxia added 1 commit 2026-09-16 10:43:19 +08:00

chore(points): fix lint - apps/web/src/api/subscription/index.ts 01132e1d4b

xiaoxia added 1 commit 2026-09-16 10:43:24 +08:00

chore(points): fix lint - apps/web/src/pages/subscription/Plans.tsx 11cfa6df12

xiaoxia added 1 commit 2026-09-16 10:43:32 +08:00

chore(points): fix lint - apps/web/src/api/points/types.ts 75e06bed45

xiaoxia added 1 commit 2026-09-16 10:43:39 +08:00

chore(points): fix lint - apps/web/src/components/common/PointsBadge/index.tsx bfcea1e443

xiaoxia added 1 commit 2026-09-16 10:43:42 +08:00

chore(points): fix lint - apps/web/src/pages/points/Packages.tsx 5d1943292e

xiaoxia added 1 commit 2026-09-16 10:43:47 +08:00

chore(points): fix lint - apps/web/src/pages/subscription/UpgradeSubscription.tsx 6feba696d3

xiaoxia added 1 commit 2026-09-16 10:43:52 +08:00

chore(points): fix lint - apps/web/src/pages/generate/hooks/pointsCost.ts 13bdb0487a

xiaoxia added 1 commit 2026-09-16 10:43:59 +08:00

chore(points): fix lint - apps/web/src/api/subscription/subscription.ts 56dcfcdde2

xiaoxia added 1 commit 2026-09-16 10:44:06 +08:00

chore(points): fix lint - apps/web/src/api/subscription/types.ts 984df6be47

xiaoxia added 1 commit 2026-09-16 10:44:10 +08:00

chore(points): fix lint - apps/web/src/components/common/PointsCost/index.tsx 0905799681

xiaoxia added 1 commit 2026-09-16 10:44:15 +08:00

chore(points): fix lint - apps/web/src/api/points/index.ts c17a6d3e81

xiaoxia added 1 commit 2026-09-16 10:44:20 +08:00

chore(points): fix lint - apps/web/src/pages/points/Transactions.tsx 913688110a

xiaoxia added 1 commit 2026-09-16 10:44:25 +08:00

chore(points): fix lint - apps/web/src/pages/subscription/Billing.tsx 5ec4a10457

xiaoxia added 1 commit 2026-09-16 10:44:29 +08:00

chore(points): fix lint - apps/web/src/pages/subscription/constants.ts ddc433b7cc

xiaoxia added 1 commit 2026-09-16 10:44:34 +08:00

chore(points): fix lint - apps/web/src/pages/generate/GeneratePage.tsx 3bebad374a

xiaoxia added 1 commit 2026-09-16 10:44:39 +08:00

chore(points): fix lint - apps/web/src/pages/points/Center.tsx d03dd7ca42

xiaoxia added 1 commit 2026-09-16 10:44:46 +08:00

chore(points): fix lint - apps/web/src/store/pointsStore.ts d3278de2fd

xiaoxia added 1 commit 2026-09-16 10:44:51 +08:00

chore(points): fix lint - apps/web/src/pages/subscription/hooks/useSubscription.ts e550e9b5c5

gitea-actions bot commented 2026-09-16 10:46:41 +08:00

Copy Link

Copy Source

🚀 预览环境已部署

项目	详情
PR号	#1956
预览链接	https://pr-1956.preview.xiaoxiajianji.com
API环境	staging

💡 预览环境使用 staging API 数据，请勿在预览环境中操作重要数据。

🔄 每次提交新代码后预览环境会自动更新。

🗑️ PR 关闭或合并后，预览环境会自动清理。

🚀 **预览环境已部署** | 项目 | 详情 | |------|------| | PR号 | #1956 | | 预览链接 | [https://pr-1956.preview.xiaoxiajianji.com](https://pr-1956.preview.xiaoxiajianji.com) | | API环境 | staging | > 💡 预览环境使用 staging API 数据，请勿在预览环境中操作重要数据。 > > 🔄 每次提交新代码后预览环境会自动更新。 > > 🗑️ PR 关闭或合并后，预览环境会自动清理。

auto-approve-bot approved these changes 2026-09-16 10:46:45 +08:00

auto-approve-bot left a comment

Collaborator

Copy Link

Copy Source

CI全绿，自动审批通过。

CI全绿，自动审批通过。

auto-approve-bot approved these changes 2026-09-16 10:46:45 +08:00

auto-approve-bot left a comment

Collaborator

Copy Link

Copy Source

CI全绿，自动审批通过。

CI全绿，自动审批通过。

auto-approve-bot merged commit 6155b4d21e into develop 2026-09-16 10:53:58 +08:00

auto-approve-bot deleted branch fix/points-api-contract-v2 2026-09-16 10:53:59 +08:00

gitea-actions bot commented 2026-09-16 10:54:41 +08:00

Copy Link

Copy Source

🗑️ 预览环境已清理

PR #1956 已关闭或合并，对应的预览环境已被清理。

如有需要，可以重新打开 PR 来重新生成预览环境。

🗑️ **预览环境已清理** PR #1956 已关闭或合并，对应的预览环境已被清理。 > 如有需要，可以重新打开 PR 来重新生成预览环境。

Sign in to join this conversation.

Reviewers

No Reviewers

auto-approve-bot

Labels

Clear labels

architecture

架构设计

backend

后端相关

blocked

阻塞中

bug

Bug修复

ci-bug

CI本身的bug

ci-optimization

CI优化类任务

ci-pipeline

CI流水线/workflow相关

cleanup

代码清理

devops

运维/部署/CI

documentation

文档相关

feature

新功能

frontend

前端相关

P0

阻塞性，必须立即处理

P1

高优先级

P2

中优先级

P3

低优先级/后考虑

question

需要讨论确认

ready

PR CI通过，可合并

refactor

代码重构

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

auto-approve-bot frontend-dev xiaoxia

No Assignees

3 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: xiaoxia/xiaoxia-saas#1956