9.9 KiB
9.9 KiB
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
src/Core/DBMigratorPart2.php或最终负责收益表 schema 的文件包含作者、订单、文章、购买者、货币、原始支付金额、比例快照、会员等级、作者收益金额、状态和时间字段，并同步提升 schema 版本。src/Payment/Revenue.php或拆分后的作者收益服务实现create_from_paid_order(order)，且同一订单重复调用只保留一条作者收益记录。- 现金订单仅创建现金收益记录，积分订单仅创建积分收益记录；作者购买自己的付费文章不会创建收益记录。
- 普通用户、一级会员、二级会员分别按 60%、70%、80% 计算，并把生成时比例保存到收益记录。
- 支付成功但权益未完成时不创建收益；权益完成后的支付流程能够创建待结算记录。
- 创作分成关闭时，收益生成入口被跳过；相关收益服务测试覆盖上述场景。
Phase 2 — 收益自动/手动结算与退款冲正
用户故事：7、10、11、12、13、14
What to build
实现待结算收益的到期判断、自动结算、后台手动逐笔/批量结算，以及退款或取消后的取消、冲正和待追缴流程。现金收益写入现金余额，积分收益写入积分余额；所有状态转换和余额操作具备幂等性。
Done when
src/Payment/Revenue.php或拆分后的结算服务实现settle(record_ids, actor)，现金和积分分别调用对应原子余额服务并写入对应流水。settlement scheduler仅在自动模式下处理达到配置延迟时间的待结算记录，默认延迟 24 小时；手动模式下定时任务不入账。- 同一收益被重复结算、并发结算或重复定时扫描时，只能成功入账一次。
Refund reversal handler实现cancel_or_reverse(order_id, reason)：未入钱包记录变为已取消/退款，已入钱包记录按货币执行冲正。- 冲正时余额不足不会产生负余额，收益记录转为待追缴，并保存应冲正金额、错误信息和审计信息。
- 重复退款通知和重复冲正请求保持幂等；服务测试覆盖自动结算、手动结算、退款前结算、退款后结算和余额不足场景。
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 中的收益口径、结算策略、货币处理、权限、退款冲正和后台入口均已确定。