137 lines
9.5 KiB
Markdown
137 lines
9.5 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` 按站点时区处理达到配置结算周期的待结算记录；结算周期结束后自动入对应钱包，不再配置延迟小时或自动/手动模式。
|
||
- [x] 同一收益被重复结算、并发结算或重复定时扫描时，只能成功入账一次。
|
||
- [x] 订单退款或取消不会取消 pending 收益、冲正 settled 收益或产生待追缴记录；收益只按正常周期进入对应钱包。
|
||
- [ ] 服务测试覆盖现金/积分比例快照、周期边界、自动结算、手动重试、退款后收益保持和并发幂等场景。
|
||
|
||
---
|
||
|
||
## Phase 3 — 用户中心作者收益页面可用
|
||
|
||
**用户故事**：1、2、3、4、5、6、7、15、16
|
||
|
||
### What to build
|
||
|
||
将用户中心“创作中心”改造成作者收益页面。实现现金/积分双货币收益卡片、待结算与已结算展示、结算备注和三列收入明细，并保留基于现有用户中心 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`。
|
||
- [ ] 结算备注输出经过 `wp_kses` 处理的后台 HTML；收入明细默认每页 20 条、按产生时间倒序，移除货币 Tab 和状态筛选。
|
||
- [ ] `assets/js/routes/user-center.js` 只转发创作中心分页参数并保持 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 默认比例、结算周期和 HTML 备注；非法比例和周期值被拒绝。
|
||
- [ ] `src/Settings/PaymentRuntime.php` 或对应 `AKSRT_Settings` 运行时读取器只读取新的创作中心配置，不增加旧配置双读或静默 fallback。
|
||
- [ ] `src/Admin/PaymentController.php` 和现有 Native 支付运营页面支持按作者、文章、货币、收益状态、订单状态和时间查询收益记录。
|
||
- [ ] 管理员可逐笔或批量结算，已处理记录不会重复入账；普通用户无法访问运营接口。
|
||
- [ ] 后台只运营 pending/settled 收益记录；退款不提供作者收益冲正或追缴入口。
|
||
- [ ] `php tools/audit-admin-contracts.php` 通过，后台配置与运营测试覆盖保存、权限、查询和操作结果。
|
||
|
||
---
|
||
|
||
## Phase 5 — 全链路验证与交付收口
|
||
|
||
**用户故事**：全部用户故事，重点覆盖异常、权限和部署契约
|
||
|
||
### What to build
|
||
|
||
对收益生成、周期结算、退款保持、用户中心、后台配置和运营页面进行跨模块联调，完成静态检查、前端构建、契约审计和可用的 WordPress/外部 Docker harness 验证。修复跨阶段集成问题，并明确记录环境不可用时未执行的运行时验证。
|
||
|
||
### Done when
|
||
|
||
- [ ] 收益服务测试覆盖现金/积分比例快照、货币分离、订单幂等、周期到期结算、退款后收益保持和并发重复操作。
|
||
- [ ] 前台交互测试覆盖开关门控、本人数据隔离、双货币卡片、分页、错误重试、移动端布局和推广返佣隔离。
|
||
- [ ] 后台配置与运营测试覆盖 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 中的收益口径、结算策略、货币处理、权限、退款保持和后台入口均已确定。
|