9.5 KiB
9.5 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按站点时区处理达到配置结算周期的待结算记录；结算周期结束后自动入对应钱包，不再配置延迟小时或自动/手动模式。- 同一收益被重复结算、并发结算或重复定时扫描时，只能成功入账一次。
- 订单退款或取消不会取消 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 中的收益口径、结算策略、货币处理、权限、退款保持和后台入口均已确定。