138 lines
9.9 KiB
Markdown
138 lines
9.9 KiB
Markdown
# Plan: 用户创作收益中心
|
||
|
||
## Architectural Decisions
|
||
|
||
以下决策贯穿全部阶段：
|
||
|
||
- **作者收益与推广返佣分离**：创作中心只读取付费文章作者收益，不读取 `Rebate` 推广返佣数据。
|
||
- **收益记录以订单为源**：支付成功且权益发放完成后，每笔符合条件的付费订单最多生成一条作者收益记录。
|
||
- **收益生成时快照**：保存原始支付金额、货币、作者分成比例和适用会员等级，后续配置或等级变化不影响历史记录。
|
||
- **现金与积分彻底分离**：分别记录、统计、结算、写入流水和执行冲正；不换算、不合并。
|
||
- **统一认证边界**：前台作者 ID 始终取当前登录用户，后台接口复用支付中心权限模型；所有 REST 路由必须提供 `permission_callback`。
|
||
- **原子余额操作**：现金和积分余额只能通过现有余额服务变更，不直接修改用户 meta。
|
||
- **最终结构替换**：新增或调整表结构时直接更新最终 schema 版本，不增加旧字段双读、迁移层或兼容路径。
|
||
- **后台职责保持分层**：配置进入 Vue SPA 的“支付&付费 > 创作中心”，收益运营继续使用 Native 支付中心现有“创作分成”页面。
|
||
- **创作开关是完整功能门控**：关闭后隐藏前台入口、停止新收益生成、停止自动和手动结算；历史记录仅保留后台查询。
|
||
|
||
---
|
||
|
||
## Phase 1 — 付费订单产生可追踪作者收益
|
||
|
||
**用户故事**：1、2、3、4、8、9、15
|
||
|
||
### What to build
|
||
|
||
建立作者收益的最终数据结构和统一服务入口，接入支付成功且权益发放完成后的订单流程。实现普通用户、一级会员、二级会员三档比例，现金订单与积分订单分别生成收益记录，并保证支付回调重复执行时不会重复生成。
|
||
|
||
同时完成创作分成基础配置的后端读取与校验，使收益服务能够使用独立于其他会员分成配置的比例和功能开关。
|
||
|
||
### Done when
|
||
|
||
- [x] `src/Core/DBMigratorPart2.php` 或最终负责收益表 schema 的文件包含作者、订单、文章、购买者、货币、原始支付金额、比例快照、会员等级、作者收益金额、状态和时间字段，并同步提升 schema 版本。
|
||
- [x] `src/Payment/Revenue.php` 或拆分后的作者收益服务实现 `create_from_paid_order(order)`，且同一订单重复调用只保留一条作者收益记录。
|
||
- [x] 现金订单仅创建现金收益记录，积分订单仅创建积分收益记录；作者购买自己的付费文章不会创建收益记录。
|
||
- [x] 普通用户、一级会员、二级会员分别按 60%、70%、80% 计算，并把生成时比例保存到收益记录。
|
||
- [x] 支付成功但权益未完成时不创建收益；权益完成后的支付流程能够创建待结算记录。
|
||
- [x] 创作分成关闭时，收益生成入口被跳过；相关收益服务测试覆盖上述场景。
|
||
|
||
---
|
||
|
||
## Phase 2 — 收益自动/手动结算与退款冲正
|
||
|
||
**用户故事**：7、10、11、12、13、14
|
||
|
||
### What to build
|
||
|
||
实现待结算收益的到期判断、自动结算、后台手动逐笔/批量结算，以及退款或取消后的取消、冲正和待追缴流程。现金收益写入现金余额，积分收益写入积分余额；所有状态转换和余额操作具备幂等性。
|
||
|
||
### Done when
|
||
|
||
- [x] `src/Payment/Revenue.php` 或拆分后的结算服务实现 `settle(record_ids, actor)`，现金和积分分别调用对应原子余额服务并写入对应流水。
|
||
- [x] `settlement scheduler` 仅在自动模式下处理达到配置延迟时间的待结算记录，默认延迟 24 小时；手动模式下定时任务不入账。
|
||
- [x] 同一收益被重复结算、并发结算或重复定时扫描时，只能成功入账一次。
|
||
- [x] `Refund reversal handler` 实现 `cancel_or_reverse(order_id, reason)`：未入钱包记录变为已取消/退款，已入钱包记录按货币执行冲正。
|
||
- [x] 冲正时余额不足不会产生负余额，收益记录转为待追缴，并保存应冲正金额、错误信息和审计信息。
|
||
- [ ] 重复退款通知和重复冲正请求保持幂等；服务测试覆盖自动结算、手动结算、退款前结算、退款后结算和余额不足场景。
|
||
|
||
---
|
||
|
||
## Phase 3 — 用户中心作者收益页面可用
|
||
|
||
**用户故事**：1、2、3、4、5、6、7、15、16
|
||
|
||
### What to build
|
||
|
||
将用户中心“创作中心”从文章管理页面改造成作者收益页面。实现现金/积分双货币收益卡片、待结算与已入钱包展示、创作分成说明 Tab、收入明细 Tab，以及基于现有用户中心 REST/Ajax 机制的无刷新筛选和分页。
|
||
|
||
保留独立的“收益中心”推广返佣入口，确保两个页面的数据和开关互不影响。
|
||
|
||
### Done when
|
||
|
||
- [ ] `src/User/Center.php`、`inc/helpers/user-center-renderers/sidebar-commerce.php` 和相关侧栏逻辑在创作分成关闭时隐藏创作中心入口，但仍显示独立的收益中心入口。
|
||
- [ ] 用户中心创作中心渲染器不再输出文章发布、草稿、审核、编辑、删除或文章管理内容。
|
||
- [ ] `Creator income view model and renderers` 实现现金/积分今日收入、累计收益、待结算和已入钱包数据，并排除取消、退款和待追缴金额。
|
||
- [ ] `GET /wp-json/aksrt/v1/user-center/...` 作者收益接口只使用当前认证用户，未登录或访问他人数据时被拒绝；路由均具备 `permission_callback`。
|
||
- [ ] 创作分成 Tab 输出经过 `wp_kses` 处理的后台 HTML；收入明细默认每页 20 条、按产生时间倒序，并包含文章、订单、支付金额、作者分成金额、货币和收益状态。
|
||
- [ ] `assets/js/routes/user-center.js` 完成两个 Tab、筛选、分页和 History API 无刷新加载；请求失败时保留卡片和布局并显示可重试提示。
|
||
- [ ] 前台交互测试验证现金/积分分栏、空状态、筛选组合、退款/待追缴展示、移动端无横向溢出，以及创作中心与收益中心数据隔离。
|
||
|
||
---
|
||
|
||
## Phase 4 — 后台配置和支付中心运营闭环
|
||
|
||
**用户故事**：8、9、10、11、12
|
||
|
||
### What to build
|
||
|
||
在“支付&付费 > 创作中心”集中提供创作开关、三档独立分成比例、处理模式、延迟时间、现金提示阈值和说明 HTML 配置。复用现有支付中心“创作分成”Native 运营页面，补齐作者收益查询、筛选、逐笔/批量结算、退款冲正和待追缴查看。
|
||
|
||
### Done when
|
||
|
||
- [ ] `src/Admin/Schema/SchemaPayment.php`、`assets/admin/src/schema/sections/payment/index.js` 和支付菜单文件共同注册“创作中心”配置项。
|
||
- [ ] 配置 REST 能加载和保存开关、60/70/80 比例、自动/手动模式、延迟小时数、50 元提示阈值和 HTML 说明；非法比例、负数延迟和不允许的模式值被拒绝。
|
||
- [ ] `src/Settings/PaymentRuntime.php` 或对应 `AKSRT_Settings` 运行时读取器只读取新的创作中心配置，不增加旧配置双读或静默 fallback。
|
||
- [ ] `src/Admin/PaymentController.php` 和现有 Native 支付运营页面支持按作者、文章、货币、收益状态、订单状态和时间查询收益记录。
|
||
- [ ] 管理员可逐笔或批量结算，已处理记录不会重复入账；普通用户无法访问运营接口。
|
||
- [ ] 后台可查看已取消/退款、冲正和待追缴记录，并显示失败原因与审计信息。
|
||
- [ ] `php tools/audit-admin-contracts.php` 通过，后台配置与运营测试覆盖保存、权限、查询和操作结果。
|
||
|
||
---
|
||
|
||
## Phase 5 — 全链路验证与交付收口
|
||
|
||
**用户故事**：全部用户故事，重点覆盖异常、权限和部署契约
|
||
|
||
### What to build
|
||
|
||
对收益生成、结算、退款冲正、用户中心、后台配置和运营页面进行跨模块联调，完成静态检查、前端构建、契约审计和可用的 WordPress/外部 Docker harness 验证。修复跨阶段集成问题，并明确记录环境不可用时未执行的运行时验证。
|
||
|
||
### Done when
|
||
|
||
- [ ] 收益服务测试覆盖比例快照、货币分离、订单幂等、到期结算、退款冲正、待追缴和并发重复操作。
|
||
- [ ] 前台交互测试覆盖开关门控、本人数据隔离、双货币卡片、Tab 无刷新、分页筛选、错误重试、移动端布局和推广返佣隔离。
|
||
- [ ] 后台配置与运营测试覆盖 Schema/REST 契约、权限、自动/手动模式、批量结算、退款记录和待追缴查询。
|
||
- [ ] `php tools/audit-admin-contracts.php` 返回成功状态。
|
||
- [ ] `assets/admin` 执行 `npm run build` 成功，生成的 `assets/admin/build/` 文件保持可加载。
|
||
- [ ] 按环境条件完成 PHP 静态检查和 WordPress/外部 Docker harness 运行验证；缺少运行环境时，在交付记录中明确列出未执行项及原因。
|
||
|
||
---
|
||
|
||
## Out of Scope
|
||
|
||
- 本次不实现“我的收入”卡片提现按钮，也不新增提现申请、审核或支付流程。
|
||
- 本次不改造或合并推广返佣收益中心。
|
||
- 本次不恢复或迁移用户中心内的文章发布、草稿、审核、编辑、删除和文章管理入口。
|
||
- 本次不实现按文章汇总的“我的商品”列表；收入明细固定按单笔作者收益记录展示。
|
||
- 本次不提供作者收益导出、图表、趋势分析、排行榜或销售漏斗。
|
||
- 本次不提供站内作者与购买者之间的订单争议处理流程。
|
||
- 本次不允许现金与积分互相兑换、折算或合并统计。
|
||
- 本次不设置作者收益进入钱包的 50 元结算门槛；该金额只用于现金提现提示。
|
||
- 本次不允许余额因冲正而变为负数，也不实现自动追缴扣款之外的催收流程。
|
||
- 本次不为旧收益结构增加兼容读取、双路实现或历史数据迁移。
|
||
- 本次不新增独立后台收益工作台，后台运营继续复用现有支付中心“创作分成”页面。
|
||
- 本次不引入新的前端框架、支付网关或货币体系。
|
||
|
||
## Open Questions
|
||
|
||
暂无。PRD 中的收益口径、结算策略、货币处理、权限、退款冲正和后台入口均已确定。
|