后续开发 TODO

更新时间：2026-07-01

当前后端基线

后端已经完成可本地验证的商用 SaaS 骨架：

Supabase/PostgreSQL 多租户 schema、RLS、索引、触发器。
Node.js API 分层：core/features。
学生端核心 API：题库、练习、答题、模考交卷报告、练习历史、学习统计、排行榜（租户默认关闭）、错题复习计划、错题、收藏、背单词、知识手册、分数线、视频播放签名、资料、订单详情/状态轮询、优惠券领取/抵扣、激活码预检查/兑换、权益、个人中心、男女预设头像、考试倒计时、签到积分、题目反馈、勋章、站内通知。
租户后台 API：品牌、域名、设置、支付账户、登录 provider、私密密钥、活动、考试日期、题目反馈处理、用户站内通知查看、激活码、优惠券、勋章管理/发放、成员权限、审计、内容管理、班级/教师/学生、学生批量导入、批量分班、学生备注、跟进任务。
租户主题系统：平台默认经典蓝、专注绿、高对比三套模板，租户可保存草稿、发布主题，公开租户解析只返回已发布主题，Taro 租户设置页已接第一版主题操作台。
平台后台 API/worker：租户、租户详情、账务资料维护、平台员工列表/创建/编辑/启停、平台审计日志查询/导出、平台审计告警规则/列表/确认/解决、审计告警外部通知渠道/事件、platform-audit-alerts worker、platform-audit-notifications worker、SaaS 套餐、订阅、订阅账单候选预览/dry-run/批量生成、自动计费 worker、服务费收款、逾期标记、内部催缴台账、催缴外部通知渠道/事件、platform-dunning-notifications worker、用量、套餐额度判定和用量超额账单。
销售/代理/CRM 增长链路：邀请码、扫码事件、首绑保护、团队、统计、CRM 配置/队列、none/direct/round_robin/referrer 跟进分配策略、CRM worker、分佣规则、成员比例、订单/激活码归因、结算生成、审核、打款状态、结算导出和凭证复核；Taro 租户营销中心已接 CRM、分佣和优惠券规则/核销报表第一版操作台。
销售/代理转化报表第一版已完成：GET /api/referral/conversion-report 由后端统一聚合触达/扫码、新增客资、已分配、有效成交、成交来源、成交金额、预计佣金、CRM 失败、跟进积压、成员排行、日趋势和近期未成交客资；租户管理员可看全局或指定成员，销售/代理只能看本人，Taro 租户营销中心已接第一版看板。
内容导航：content_entries/content_nodes 支持任意深度入口和分类。
练习组卷：question_collections/practice_blueprints 支持顺序、随机、全真模拟快照。
模考报告与学习统计：practice_session_reports/practice_session_report_sections 支持交卷、评分、题型/小节统计、错题解析汇总和历史查询；/api/learning/stats、trend、practice-sessions/history、wrong-questions/review-plan 可支撑个人中心和学习报告基础页。
练习访问控制：practice_daily_usage/practice_access_events 支持免费每日额度、SVIP 范围校验、SVIP-only 内容拦截和答题 session 快照保护。
内容导入：题目、单词、知识手册、分数线、视频 JSON/CSV/Excel 预览、校验、导入、幂等、审计。
内容导出：题库 JSON、paper_json、打印 payload 导出基础已完成，支持集合/入口/分类范围、导出 job、审计、跨租户拒绝、答案/解析开关和复合题子题脱敏。
租户组织范围：班级、班级成员、教师/班主任/助教/学生分组，教师按负责班级查看学生，字段权限可脱敏学生手机号。
学生运营管理：学生批量 upsert、禁用/恢复、批量分班、备注、跟进任务、跟进效果统计、学习督导自动化、督导规则模板、定时生成 worker、批量 CRM 推送已完成接口和集成测试；学生写入口已拒绝头像 URL、第三方头像字段和 primaryRole，学生头像统一走男女预设；Taro 租户学生运营页已接学生创建/更新、状态切换、批量导入、批量分班、备注、跟进任务、跟进看板、学习督导预览/生成、保存每日督导规则和 CRM 推送第一版；后续补督导触达联动、效果归因和更细导入模板体验。
旧题库运营缺口已补一批：考试日期/倒计时、题目反馈/纠错处理、反馈运营聚合报表、每日签到积分和积分流水、学习排行榜已完成接口和集成测试但租户默认关闭。
勋章管理已完成租户后台维护、手动发放、重复发放幂等、学生个人中心展示、权限点和集成测试；签到连续天数、积分阈值、反馈解决、积分活动任务、练习次数、单词掌握和模考成绩自动发放已完成并纳入 API 集成测试；自动/手动发放会写入用户站内通知。学生激励以后台配置勋章自动发放为主，不默认启用排行榜竞争。后续补更细活动效果看板和更细前端运营配置体验。
积分活动和兑换第一阶段已完成：租户后台可配置积分任务/兑换商品并查看领取/兑换记录，学生端可查询任务、领取奖励、查看兑换商品、兑换并生成 redeem_cost 积分流水；优惠券兑换会生成 coupon_redemptions，手工/自定义商品进入待履约订单；兑换完成或待履约会写入用户站内通知；Taro 学生个人中心已接积分任务、兑换商品和积分明细第一版，租户营销中心已接积分任务/兑换操作台、反馈运营摘要和积分风控只读摘要第一版。后续补更细活动效果看板。
用户站内通知第一版已完成：反馈处理、反馈奖励、勋章发放、积分兑换会创建 user_notifications；学生端可查询/标记状态，租户后台具备 notifications:read 权限的成员可查看租户内通知；Taro 学生个人中心已接消息摘要，独立消息中心已接状态/类型筛选、批量已读、归档/忽略和站内安全跳转第一版，租户营销中心已接用户通知查看和筛选第一版。后续补外部微信订阅消息/短信、批量统计和运营效果看板。
旧商城体验已补齐主链路：订单详情、订单状态轮询、激活码预检查、自用激活码拒绝、优惠券前台领取、下单抵扣、零元订单自动支付开通权益，且手工支付确认已限制为租户后台 tenant:payment:write 权限。
优惠券商用规则已补齐后端和 Taro 租户后台第一版：租户后台可配置启停/归档、活动分组、最低金额、优惠封顶、单用户限次、首单限制、适用套餐/地区和 metadata；学生领取/下单会由后端复核规则，后台可查核销明细和按活动/日期/券聚合的核销报表。
公共题库商业化基础闭环已完成：平台公共题库可由平台管理员按 SaaS 套餐/指定租户/全部活跃租户授权，并可限制授权地区和科目；租户内容管理员只能看到 question_bank_grants、有效订阅、SaaS 套餐 feature_flags.publicQuestionBanks 和订阅 metadata.publicQuestionBankAccess 同时允许的公共题库。基础版默认单地区 allowlist，专业版默认全国可见；越权公共题库不可见且不可直接采纳。租户可采纳为本租户题库、内容入口、题目集合和题目快照，采纳后可直接进入练习 session；平台题库后续新增/更新题目可通过手动同步 API 或 public-banks worker 进入租户副本，并生成租户内容通知；租户自改题目会返回冲突并保留原内容，后台可查询最近一次冲突明细，并可单条或批量选择采纳平台版本/保留本地版本，冲突处理完成后通知自动 resolved。
租户后台数据看板已完成首版聚合 API：GET /api/tenant-admin/dashboard，支持租户/地区维度的收益、注册、学习、内容、激活码、反馈、趋势、24h 活跃、套餐销量和运营动态，前端可直接联调。
支付/退款补偿 worker 已完成：apps/worker --job commerce 可查询微信/支付宝支付和处理中退款，补偿漏通知订单，支付成功幂等开通权益，退款成功幂等更新退款/订单/支付并在全额退款时撤销订单权益。
资金对账和差错工单闭环已完成：commerce_reconciliation_batches/items 和 /api/commerce/reconciliation/* 支持手工/API 导入供应商账单行、预览差异、生成批次统计、查询异常、租户隔离、权限点 tenant:reconciliation:read/write 和审计日志；commerce_reconciliation_issues/events 支持异常明细创建工单、分配、开始处理、升级、解决、忽略、重开和事件留痕，且不直接修改订单/支付/退款/权益。
微信/支付宝官方账单下载地基已完成：commerce_bill_download_jobs、POST /api/commerce/reconciliation/provider-bills/request、GET /api/commerce/reconciliation/provider-bills/jobs 和 apps/worker --job provider-bills 已接入，worker 负责后端签名申请下载 URL、hash 校验、JSON/CSV/ZIP 账单解析、复用 provider_download 对账导入、任务状态回写和密钥脱敏。
平台 SaaS 自动计费 worker 已完成：apps/worker --job platform-billing 会按 WORKER_PLATFORM_BILLING_DAYS_AHEAD 查找即将到期且未开票的订阅，生成 tenant_invoices/tenant_invoice_items，使用订阅行锁和账单查重防重复，写入 platform.invoice.subscription_auto_created 审计；npm run test:worker:platform-billing 覆盖自动开票、明细、审计和二次运行幂等。
平台 SaaS 用量自动采集 worker 已完成：apps/worker --job platform-usage 默认按上海时区当前月采集，也可用 WORKER_PLATFORM_USAGE_MONTH=YYYY-MM 补跑指定月份；当前会生成 students、active_students、questions、assets、storage_gb、videos、video_plays、video_quota_consumed、paid_orders、paid_order_amount_cents、active_entitlements 11 类指标，写入 tenant_usage_records 和 platform.usage.worker_collected 审计；手工调整用量不被 worker 覆盖，npm run test:worker:platform-usage 覆盖幂等和指标口径。
平台 SaaS 超额账单已完成 API 和 worker：GET /api/platform-admin/invoices/usage-overage-candidates 可按账期预览超出套餐额度的租户，POST /api/platform-admin/invoices/from-usage-overage 支持 dry-run 或正式生成 usage_overage 账单；apps/worker --job platform-usage-overage 默认按上一个自然月自动开票，也可用 WORKER_PLATFORM_USAGE_OVERAGE_MONTH=YYYY-MM 补跑指定月份。后端支持套餐 included_quotas/overage_prices、订阅 metadata 覆盖、重复开票保护、审计和 Taro 平台账务中心第一版操作台；非法账期和执行失败会写入脱敏 platform.invoice.usage_overage_worker_failed 审计，并由 platform-audit-alerts 生成高优先级告警；npm run test:worker:platform-usage-overage 覆盖账单明细、审计、重复运行幂等、失败审计和告警脱敏。
平台 SaaS 逾期催缴 worker 已完成：apps/worker --job platform-dunning 会扫描已过 due_date 且未结清的服务费账单，标记 tenant_invoices.status=overdue、推送租户 billing_status=past_due、生成 tenant_invoice_reminders 内部催缴记录并写审计；POST /api/platform-admin/invoices/process-overdue 支持平台后台 dry-run/执行，GET /api/platform-admin/invoices/reminders 支持查看催缴台账；npm run test:worker:platform-dunning 覆盖逾期标记、催缴幂等和审计。
平台 SaaS 催缴外部通知第一版已完成：platform_dunning_notification_channels/events、GET/PUT /api/platform-admin/dunning-notification-channels、GET /api/platform-admin/dunning-notification-events 和 apps/worker --job platform-dunning-notifications 已接入；支持 generic/钉钉/飞书/企微 webhook、按催缴类型/渠道/级别/租户筛选、发送重试、幂等、防重复、联系方式掩码、payload 脱敏和生产 readiness 阻断 localhost/不安全 webhook。
平台审计告警 worker 已完成：apps/worker --job platform-audit-alerts 会扫描 platform.% 审计日志，根据 platform_audit_alert_rules 把租户状态变更、账务资料变更、批量开票、用量超额开票、worker 失败、逾期处理、手工收款确认、审计导出等高风险平台操作生成内部告警；API 已支持 /api/platform-admin/audit-alert-rules、/api/platform-admin/audit-alerts、/api/platform-admin/audit-alerts/status，Taro 平台工作台可查看开放告警并确认/解决；npm run test:worker:platform-audit-alerts 和 npm run test:worker:platform-usage-overage 覆盖规则匹配、幂等和敏感 details 脱敏。
平台审计告警外部通知第一版已完成：platform_audit_notification_channels/events、GET/PUT /api/platform-admin/audit-notification-channels、GET /api/platform-admin/audit-notification-events 和 apps/worker --job platform-audit-notifications 已接入；支持 generic/钉钉/飞书/企微 webhook、签名密钥 app_private.platform_secrets、发送重试、幂等、防重复、payload 脱敏和生产 readiness 阻断 localhost/不安全 webhook。
异常订单运营台和人工调整凭证已完成后端第一版：/api/commerce/operations/anomalies 聚合未关闭对账工单、失败官方账单任务、支付事件错误、长时间 pending 支付/退款；/api/commerce/adjustment-vouchers* 支持凭证提交、审批、驳回、作废、事件轨迹和复核报表，使用 tenant:reconciliation:review 做独立复核权限，且审批凭证不会直接修改订单、支付、退款或权益。
内容资源复检与安全扫描 worker 已完成：apps/worker --job assets 可复检 content_assets 中的托管对象元数据，并执行内置 metadata_rules 和可选外部 HTTP scanner；正常资源写回复检/扫描证据，异常资源自动置为 failed/skipped + draft 或 security_scan_status=failed，外部 scanner 不可用默认 fail-closed，并写入审计、扫描事件和安全标记。
题库导出 worker 已完成：apps/worker --job exports 可抢占 pdf/docx/daily_practice_zip 导出任务，渲染 PDF/Word、水印或每日一练图片素材包，写入对象存储或本地开发存储，创建 content_assets 并回填 assetId/hash/size；daily_practice 已支持每日一练九宫格 metadata、PDF/Word 基础版式、9 张 PNG/SVG 卡片和拼图 ZIP。
租户后台媒体运营报表已完成：/api/tenant-content/media-analytics/summary、asset-events、video-events 可按 7/30/90 天、资源、视频、用户和水印 traceId 查询资料访问、视频播放、拒绝访问、Top 资源/视频和日趋势；仅开放给 owner/admin/operator 或 content:analytics:read 权限角色，前端不会拿到签名 URL 或播放 token。
本地验证：npm run check:refactor 已通过；三套 Taro H5 已补 index.html 构建模板、发布产物扫描、npm run smoke:taro:h5 静态启动烟测和 npm run smoke:taro:h5:interaction 真实浏览器交互烟测，能验证发布目录、公开 runtime config、history fallback、静态资源、租户解析契约、关键页面 JS 执行和三类角色入口点击。

当前更适合进入前端联调前阅读的总览文档：

docs/refactor/backend-handoff-roadmap.md

后端待补功能

P0 上云测试前必须补齐

生产鉴权
- 已支持 Supabase Auth JWT 和迁移期 tk_ session 双入口；JWT 通过 auth.users.id -> platform_users.auth_user_id -> tenant_memberships 映射业务身份。
- 已覆盖学生、租户管理员、平台管理员、错租户、坏签名、禁用 legacy header 的 API 集成测试。
- 已补自定义角色模板、菜单/模块/字段级配置 API、班级/学生范围权限；已新增 npm run test:rls 本地动态 RLS 深测，覆盖主租户、合作商租户、无租户 claim、平台管理员旁路和跨租户写入拒绝；已新增 npm run smoke:auth:remote 用真实 Supabase access token 验收云端 Auth/JWKS 映射；继续在预生产/生产执行并留档。
- 前端联调时禁止继续使用 x-user-id；x-tenant-id 只作为租户上下文，不能作为身份依据。
- 生产 .env 必须通过 readiness:production：短信 provider 只允许阿里云/腾讯云，禁止 mock/未知值，禁止弱密钥、CORS=* 和 legacy 身份头。生产数据库还必须通过 readiness:production:db，校验租户短信/OAuth/支付 provider 的公开配置、HTTPS 回调、私密 tenant_secrets 和 RLS。
对象存储
- 已接阿里云 OSS、腾讯云 COS、Supabase Storage 的上传/下载签名 provider。
- 已补上传后对象确认接口、托管对象发布前 verified 校验、PDF/图片 inline 预览签名。
- 已补 assets worker 复检，异常托管对象会自动下架并记录审计。
- 已补内容资源安全扫描状态机：确认上传后进入 securityScanStatus=pending，扫描通过后才能发布、下载、预览或视频播放；后台可查 /api/tenant-content/assets/security-scan-events。
- 已补资源访问事件 content_asset_access_events，覆盖上传签名/确认、学生下载/预览、后台下载/预览的 granted/denied、短 TTL、签名模式、IP、UA 和动态水印 traceId。
- 已补签名访问动态水印上下文：学生资料下载/预览、租户后台下载/预览和视频播放都会返回 watermark，并将 traceId 写入访问事件或播放事件。
- 已补 Taro 学生资料页水印容器第一版：预览/下载都先请求后端短签名，展示过期时间、签名模式和 watermark.traceId；强制水印资源不会提供脱离水印容器的外部预览入口。
- 已补租户后台媒体运营报表，支持资料/视频访问汇总、Top 资源/视频和 traceId 回查；大租户后续再把实时查询替换为日/周预聚合。
- 已收紧锁定资源 CDN 边界：members/svip/private 外链默认拒绝，必须显式 provider-managed 才允许；视频绑定资源也复用该策略。
- 已补外部 HTTP 杀毒/内容安全 scanner 接入层、失败关闭、生产 readiness 阻断和动态水印 traceId 审计；继续联调真实扫描服务、转码/CDN 级水印、CDN 刷新和对象生命周期策略。
- 已补 API/worker 生产启动 fail-fast：生产环境会拒绝 local_dev 存储、未知存储 provider、空 bucket、关闭租户前缀、非 HTTPS STORAGE_PUBLIC_BASE_URL、阿里云 OSS 内网直签；worker 会拒绝未接入外部 HTTP scanner 或 fail-open。
- 已补 docs/refactor/object-storage-production-runbook.md，真实云厂商联调必须按 runbook 抽样验收。
- content_assets 继续作为资源台账，不允许前端绕过台账直接访问私有资源。
真实导入 dry-run
- 从 PocketBase 导出现有用户、题库、单词、知识手册、分数线、订单、权益数据。
- 已补 npm run pb:export:sqlite 只读 SQLite 导出工具，默认从 F:\project\参考\旧题库数据库文件\data.db 导出到 .gitignore 覆盖的 pb_export/，并生成 sqlite-export-manifest.json、storage-manifest.json 和脱敏统计。
- 已补 npm run pb:import:dry-run 静态迁移报告工具、--profile=production 生产迁移门禁、关键集合/关键字段覆盖率检查、strict warning 门禁测试和真实数据迁移验收 runbook；真实 SQLite 已导出 58 个业务 collection、248555 条记录，并跑过 production dry-run。
- 当前真实 dry-run 剩余 blocker：30 个订单缺 userId，其中 7 个 paid；22 个知识手册章节缺 subjectId。导入器已补隔离策略：缺用户订单进入财务复核且不自动开权益，缺归属手册章节进入“迁移待复核手册”。正式切换前仍必须人工找回/确认这些记录。
- 已补真实 mapper gap：user_answer_records 85442 条标准化到 answer_records/wrong_questions，mock_exam_configs 48 条标准化到 practice_blueprints，referral_qrcodes 79 条标准化到 referral_qrcodes/referral_codes，commission_settings 1 条标准化到 tenant_commission_settings。
- 真实 pb:import:json 已在干净本地 Supabase 上跑通，248555 条真实记录最近导入约 10 分 11 秒；pb:import:validate 为 0 failures、3 warnings。核心落库计数：3670 用户、74102 题目、85199 旧答题记录、38205 错题、636 订单、447 权益、79 个推广码、1 条租户分佣设置；同时生成 11 个题库入口、2830 个内容节点、1597 个题目合集、82106 条合集题目关系、3102 个顺序/随机练习蓝图，已发布旧题缺入口/节点/合集数为 0。
- 已补 npm run pb:import:sample 真实业务抽样验收，只读检查题库入口、内容节点、题目合集、练习蓝图、题目当前版本、答题记录、错题、收藏、单词、手册、分数线、订单、支付、权益、激活码、资源台账和敏感字段泄露。当前真实迁移库结果为 0 failures、6 warnings、1 skipped、39 passed；warning 均为旧数据人工复核或上线留档项。
- 最新导入 run 剩余 29 个 critical import issues：7 个已支付订单缺用户、22 个手册章节缺所属手册，均为正式切换前人工复核项；旧答题记录空用户或旧用户已删除已降为 warning。
- 处理完 blocker 后再跑 npm run pb:import:dry-run -- --profile=production --json --fail-on-warnings，再跑 pb:import:json、pb:import:validate 和 pb:import:sample。
- 对题目 JSON、单词、知识手册、分数线、视频走后端 preview/import API 做二次验证。
部署配置
- 生产 .env 模板和 npm run readiness:production / npm run readiness:production:db 已补，后续上云必须作为验收 gate。
- Auth/JWKS 上云后必须临时设置 AUTH_SMOKE_* 环境变量并运行 npm run smoke:auth:remote，真实 access token 不得写入仓库、前端配置或日志。
- 本地/预生产必须同时跑 npm run test:rls，它验证运行时 JWT claim 下的租户隔离，和 readiness:production:db 的静态 policy 检查互补。
- 已补 npm run launch:gate 生产上线证据门禁和 docs/refactor/production-launch-evidence.template.json 模板；最终切换前必须把 readiness、远程 Auth、RLS、PostgreSQL 4c16g 严格调参证据、生产 dry-run、导入校验、pb:import:sample 业务抽样、真实数据 API 只读压测、真实数据混合读写压测、API/worker/Taro、运行时审计、security:repo、真实 @codex-security、备份/回滚/真实抽样/生产 provider 等证据填入本地 production-launch-evidence.json 并通过门禁。当前 Codex 环境未暴露可调用的 @codex-security 扫描工具时，该项只能标为待补，不能伪造完成。
- 确认数据库迁移流程、备份恢复、日志、告警。
- 准备 API 容器部署和 Supabase 云端/自托管连接方案。
- 已补 npm run perf:api:local、npm run perf:summary、npm run perf:postgres:evidence、npm run perf:postgres:sql、npm run smoke:launch-persona、npm run smoke:taro:h5、npm run smoke:taro:h5:interaction、node scripts/taro-api-contract-test.js、node scripts/taro-persona-contract-test.js 和 docs/refactor/performance-benchmark-runbook.md，可在本地或云端对真实迁移数据做只读门禁、混合读写容量观察、PostgreSQL 4c16g profile 调参证据、三类后端角色旅程烟测、三类 Taro 前端角色旅程契约、H5 发布目录启动烟测、真实浏览器关键点击烟测和前端 API 契约检查。2026-07-01 05:57 API-only 受限容器复核中，50 worker/60s/10% 写入为 25,157 请求、0 错误、416.54 req/s、P95 215.00ms、P99 292.56ms；2026-07-01 06:26 进一步显式限制 DB 容器为 2 CPU/8G 后，30 worker 只读为 8,029 请求、0 错误、66.50 req/s、P95 1188.62ms，50 worker/60s/10% 写入为 7,088 请求、0 错误、115.82 req/s、P95 905.13ms，均未通过上线延迟门禁。受限容器系列压测曾抓到自动勋章并发发放唯一键冲突，已修复并新增 scripts/auto-badge-concurrency-test.js。当前结论是：本地 API-only 结果只能作为乐观观察，DB 受限未调参结果作为悲观下限；正式容量仍以上云 4 核 16G、PostgreSQL shared-host 调参、真实前端埋点和生产对象存储/CDN 复测为准。
- 当前本地 PostgreSQL evidence 仍提示 jit=on、statement_timeout=0、idle_in_transaction_session_timeout=0、lock_timeout=0；上云后必须按 docs/refactor/postgresql-4c16g-tuning.md 调整参数，执行 PG_TUNING_PROFILE=shared-host npm run perf:postgres:evidence -- --strict --json 并通过后，再按 6/30/50/100 阶梯并发复跑容量报告并归档到本地上线证据。
- 本轮剩余功能和容量复核已经整理到 docs/refactor/backend-open-items-and-capacity-20260701.md。后续不要再把学生头像上传或默认排行榜当作待办；头像只保留男女预设，排行榜仅作为租户显式开启后的活动能力。

P1 商用功能完善

支付
- 已完成微信支付 JSAPI、支付宝 WAP/H5 的创建支付参数和 webhook 幂等开通权益。
- 已完成内部退款状态机、退款申请/审核/处理接口、微信/支付宝发起退款、微信/支付宝退款查询确认、微信/支付宝退款通知 webhook、部分/全额退款状态、全额退款权益撤销和审计事件。
- 已完成支付/退款补偿 worker，可兜底供应商漏通知、处理中退款和重复执行幂等。
- 已完成资金对账手工/API 导入比对、微信/支付宝官方账单下载任务、批次/明细/异常查询、差错工单状态流、异常订单运营台、人工调整凭证和财务复核报表；Taro 租户财务运营台第一版已接退款、官方账单任务、对账异常、差错工单和调整凭证；继续补真实生产账单格式抽样验收和更完整售后体验。
- 租户自有商户收款和平台代收/服务商模式。
国内登录和短信
- 已完成阿里云短信、腾讯云短信 adapter 的后端实现和本地 fake endpoint 测试。
- 已完成微信小程序 code2Session 登录主链路。
- 已完成手机号绑定/换绑、微信网页登录、QQ 登录基础 API；继续补真实生产账号、回调域名和开放平台联调。
- 本地阶段不等待真实密钥，继续用 mock/fake provider 验证验证码、账号合并、登录审计、session 签发和错误处理；真实密钥、合法域名和开放平台错误码等上云后再联调。
- 旧 PocketBase 用户账号和新身份体系的映射/补绑。
导入体系扩展
- 已完成题目、单词、知识手册、分数线、视频的 CSV/Excel 到规范 JSON 解析适配。
- 已完成大批量异步导入 worker、重试、导入后复检和审计。
- 模板下载、字段映射 API、导入任务详情、导入后复检和 PocketBase JSON dry-run 报告工具已补；Taro 租户内容页已接 JSON/CSV/Excel 文件或粘贴内容、模板下载、后端 preview、字段别名覆盖、同步/异步执行、异步 job 轮询和复检结果详情第一版；后端已对字段映射目标做白名单和危险 key 拦截。
- 继续补真实数据执行验收、导入前抽样校验和导入性能压测。
题库导出增强
- 已完成服务端 JSON、paper_json、print_payload 基础导出和导出 job 台账。
- 已完成 PDF/Word 二进制生成 worker、页面水印、导出发布到 content_assets、后台资源签名下载/预览路径，以及每日一练九宫格 metadata、PDF/Word 基础版式和 ZIP 图片素材包。
- 继续补更精细的试卷模板、导出操作台和多模板排版。
公共题库和租户授权
- 已完成平台公共题库/地区题库的基础授权、租户采纳、题目快照复制和手动同步。
- 已完成 public-banks worker 自动同步、失败记录、审计、同步通知、冲突查询 API 和单条/批量冲突处理 API。
- 已完成基础 SaaS 套餐访问边界：starter_yearly 默认 limited_regions + 地区 allowlist，pro_yearly 默认 national；租户订阅 metadata 可进一步限制 allowedRegionIds、allowedSubjectIds、allowedQuestionBankIds。
- 存储、学生数、题量、视频播放量等月度用量已由 platform-usage worker 自动采集；SaaS 套餐额度判定、超额价格计算、usage_overage 账单手动触发生成、platform-usage-overage 自动开票 worker 和失败审计告警已完成。后续继续补套餐配置 UI、平台在线收款和更完整运营后台消息。
- 继续补生产定时调度、平台审计告警升级策略和更完整运营后台消息。
视频会员控制
- 已完成视频 SVIP 权限、播放次数扣减、签名播放和播放日志。
- 已补播放签名动态水印上下文、traceId 事件、播放进度上报和租户后台播放事件查询；继续补深度防盗链、转码级水印和更细观看行为分析。
- 单题视频和通用知识视频混合推荐。
学习统计
- 已完成免费额度、练习访问事件、模考交卷评分报告、练习历史、正确率趋势、题型分布、错题复习计划。
- 已完成单词复习算法、每日计划和复习上报。
- 已完成排行榜主接口并通过租户开关默认关闭；当前产品默认不开启排行榜，避免日常请求压力和防刷复杂度。只有租户明确购买/开启对应活动并完成压测后，再补防刷、日/周榜预聚合、运营后台排名看板和专项压测。
- Taro 已有后端 session detail 续练、本地断点恢复、倒计时和阅读理解/案例分析多小题第一版；继续补复盘体验、长题干/公式图片混排和更细统计口径。
订单和营销体验
- 已完成订单详情、订单状态轮询、激活码预检查、优惠券前台领取、下单抵扣计算、优惠券复杂规则、核销明细/报表和内部退款状态机。
- 已完成支付/退款补偿 worker、官方账单下载 worker、资金对账导入比对、差错工单、异常订单运营台和人工调整凭证复核；Taro 财务运营台第一版已接入；readiness:production:db 已会阻断支付公开配置缺 notifyUrl、回调非 HTTPS、公开配置混入密钥和 active payment 缺私密密钥。本地继续验证回调后业务链路、幂等、审计、权益开通/撤销和密钥不泄露，真实生产账号、回调域名和账单格式抽样验收上云后补齐；继续补学生端售后入口深化、营销活动 UI 和活动效果看板。
积分和反馈增强
- 已完成每日签到、积分流水、反馈提交、租户后台处理、奖励积分幂等。
- 已完成勋章后台维护、手动发放、学生端展示，以及签到连续天数、积分阈值、反馈解决、积分活动、练习次数、单词掌握和模考成绩自动发放。
- 积分兑换、活动任务、优惠券兑换履约、积分风控只读报表、反馈运营聚合报表和站内通知后端第一阶段已完成；Taro 学生个人中心和租户营销中心已接积分任务/兑换第一版，学生独立消息中心已接通知筛选和状态操作，租户营销中心已接 30 天风控摘要和反馈运营摘要；继续补外部订阅消息/短信和更细活动效果看板。
数据看板

已完成首版实时聚合接口，覆盖收益、注册趋势、答题次数、收入趋势、题型分布、科目数量、题目总量、套餐销量、运营动态、24h 活跃度和激活码使用情况。
继续补日/周/月预聚合 worker、缓存策略、慢 SQL 监控和大租户性能压测。
分佣结算和销售/代理转化报表第一版已完成；继续补转化预聚合、真实打款 provider、发票、异常调整单和更细客资跟进效果看板。

销售/代理分佣

已完成租户默认分佣比例、成员分佣比例、激活码批次分佣比例。
已完成订单和激活码两类来源的佣金归因，且只统计客资绑定后的成交。
已完成结算单生成、重复结算拦截、审核、打款状态、已打款锁定、CSV/JSON 导出、打款凭证登记、凭证复核、租户隔离和销售/代理本人范围权限。
已完成销售/代理转化看板第一版，覆盖成交漏斗、成员排行、CRM 失败、跟进积压和近期未成交客资。
继续补真实打款 provider、发票管理、批量凭证上传、销售团队分佣看板、转化预聚合和异常调整单。

学生运营管理

已完成学生列表、学生资料维护、班级分组、教师范围可见、学生批量导入、禁用/恢复、批量分班、学生备注、跟进任务、跟进效果统计和批量 CRM 推送；学生写入口拒绝头像 URL、第三方头像字段和 primaryRole，避免绕过预设头像与租户角色体系。
已完成学习督导自动化第一版：后端按未学习、错题积压、低正确率、单词待复习和超期未完成练习预览风险学生，并幂等生成 learning 跟进任务；教师账号沿用班级范围，手机号按字段权限脱敏，生成动作写审计。
已完成督导规则模板和定时生成 worker：GET/PUT /api/tenant-admin/students/supervision/rules 支持保存手动/每日/每周规则，apps/worker --job student-supervision 复用后端候选计算和幂等生成逻辑，写回 lastResult/nextRunAt 和审计。
已完成 Taro 学生运营页第一版：学生创建/更新、状态禁用/恢复、批量导入、批量分班、备注、跟进任务、完成跟进、跟进看板、学习督导候选预览/生成、保存每日督导规则和 CRM 入队推送。
继续补 CRM/站内通知/企微/飞书/钉钉的触达联动、督导效果归因，以及更细导入模板体验。

AI 择校推荐

已完成 ai_recommendation_reports 报告台账、SVIP 门禁、学生输入 schema、地区/分数线上下文、local_rules 稳定 JSON 输出、报告列表/详情接口、本人报告 Markdown/HTML 导出和 Taro 学生端基础页。
继续补真实 AI provider adapter、租户级 app_private.tenant_secrets(secret_scope='ai') 密钥联调、prompt 版本管理、运营后台配置、报告 PDF worker 渲染和人工复核流程。

P2 运营体验和企业交付

自定义角色
- 已完成租户内角色模板、菜单可见、模块可见、字段级权限和权限变更审计基础 API。
- 已完成班级/教师/学生范围权限 API，教师只能查看自己负责班级的学生。
- 已完成 Taro 租户设置页角色模板可视化配置第一版，支持创建、编辑、停用、权限点、菜单、模块、字段和基础数据范围配置。
- 已完成 Taro 成员绑定模板第一版，支持成员搜索/新建、绑定角色模板、成员状态和额外权限覆盖；工作台已按后端权限矩阵隐藏不可见模块。
- 继续补更细的数据范围 UI，例如地区、题库、销售团队、本人客资、班级学生组合规则，以及成员批量运营和完整后台菜单权限联动。
主题系统
- 已完成平台默认三套主题。
- 已完成租户自定义主色、强调色、Logo、图标集和分享图的草稿预览/发布 API。
- 已完成 Taro 租户设置页主题模板、草稿和发布第一版。
- 继续补素材库、启动图/小程序分享图上传到 content_assets 的后台体验、更多主题模板和更细组件级视觉 token。
CRM worker
- 已完成 apps/worker CRM 队列消费、generic webhook、钉钉、飞书、企业微信机器人 adapter、签名、失败重试和日志。
- 已完成 CRM 配置中的跟进分配策略：none/direct/round_robin/referrer，后端校验候选人必须是当前租户内 active 的销售/代理/运营/教师/管理员，首绑客资后写入 assignedToUserId 并把 assignee 放进 CRM 队列 payload。
- 已完成死信失败池、脱敏日志查看、手动重试/忽略和审计闭环，Taro 租户营销中心已接第一版操作台。
- 销售转化看板第一版已完成；继续补富卡片模板、外部失败告警升级、转化预聚合和更细团队数据范围。
运维
- 后台操作审计报表。
- 定时备份、恢复演练。
- 性能压测、慢 SQL、索引审查；当前已有 API 压测脚本、真实刷题读写闭环和 4 核 16G runbook。API-only 受限结果可作为乐观观察；显式限制 DB 2C/8G 且未调 PostgreSQL 参数时，30 只读和 50 混合读写均 0 错误但未通过延迟门禁。云服务器部署后必须先按 PostgreSQL shared-host profile 调参，再按同一矩阵复跑并输出正式容量报告。

Taro 前端开发 TODO

架构目标

已新建 apps/taro，不要继续在旧 React Web 上堆兼容。
H5 和小程序共用同一套业务 API client。
旧原生小程序前端位于 F:\project\参考\旧题库小程序前端文件，后续 Taro 小程序/H5 交互补齐时只作为交互、页面状态和微信平台能力参考，不继承旧直连 PocketBase 或旧鉴权逻辑。
租户通过域名、小程序配置或启动参数解析。
页面主题、品牌、功能开关都从后端租户配置读取；学生端和后台只消费 /api/tenant/resolve 的已发布 branding.theme/publicAssets，租户后台草稿只通过 /api/tenant-admin/theme 查看。
当前已完成 H5 学生端、租户后台、平台后台三套构建入口和统一 API client；已补 apps/taro/src/index.html 模板，三套 H5 构建都会生成 index.html；已补 scripts/taro-route-contract-test.js、scripts/taro-api-contract-test.js、scripts/taro-persona-contract-test.js、scripts/taro-h5-release-guardrails-test.js 和 scripts/taro-h5-static-smoke.js，分别校验页面路由契约、前端 API 契约、学生/租户/平台三类关键角色旅程、源码/产物/runtime-config 安全边界和 H5 静态启动契约，阻断旧 PocketBase、x-user-id、平台本地 key、数据库连接串、服务端密钥形态、页面路由漂移、API 漂移和关键业务入口误删进入前端产物。学生端、租户后台、平台后台都有第一批真实 API 页面；学生端已补地区选择、刷题答题卡、后端权威断点续练、本地进度恢复、模拟倒计时、主观题后端自评、阅读理解/案例分析多小题、错题/收藏复习、题目反馈、视频解析、练习/模考报告、个人中心学习报告可视化、会员收银台、订单详情、售后入口、独立消息中心、积分任务/兑换/积分明细第一版、男女预设头像选择 UI、题干/选项/解析/知识手册 RichContent 安全渲染、知识手册章节内搜索/安全摘要高亮/目录定位、H5 KaTeX 公式渲染、私有资源 ID 题图短签名渲染、逐题复盘、背单词卡片学习/发音/收藏练习第一版；平台后台已接入创建租户、租户详情、状态变更、账务资料维护、平台员工列表/创建/编辑/禁用恢复、平台审计查询/CSV 导出、开放审计告警展示/确认/解决、审计告警外部通知渠道/事件状态摘要、催缴外部通知渠道/事件摘要、订阅、订阅账单候选/dry-run/批量生成、自动计费生成结果查看、收款、用量和公共题库授权第一版写操作；租户后台已接权限驱动工作台、学生运营操作台、学习督导自动化/每日规则保存、主题模板预览/发布、角色模板、成员绑定、CRM/分佣操作台、积分任务/兑换操作台和用户通知查看第一版；下一步补小程序公式真机验收、题图资源字段化、状态管理、首屏包体优化、更细数据范围 UI、督导触达联动和小程序兼容验证。

第一批页面

租户启动与首页
- 调 /api/tenant/resolve
- 读取品牌、主题、Banner、公告、功能开关
- 展示题库入口、背单词、知识手册、分数线、资料、会员
登录
- 迁移期可先接短信 mock 或临时登录
- 生产接微信小程序登录、短信登录、QQ/微信网页登录真实账号
题库
- content_entries/content_nodes
- question_collections/practice_blueprints
- 顺序刷题、随机刷题、全真模拟
- 答题、解析、错题、收藏、视频解析入口
背单词
- 单元列表、单词列表
- 学习状态、收藏、统计
- 每日新词、复习计划、认识/不认识上报
- Taro 已接学习概览、掌握率、计划拆分、卡片翻转、发音、美/英音切换、收藏练习、单词跳转和本地位置恢复；后续补租户级发音源配置、小程序真机音频兼容验收和更细复习参数
知识手册
- 手册入口、章节、小节、知识点阅读
- RichContent 已支持 Markdown 图片、基础表格、代码、加粗、H5 KaTeX 公式渲染、私有资源 ID 短签名和安全过滤；Taro 已接章节内搜索、安全文本摘要高亮和目录定位第一版；后续补小程序公式真机验收和题图资源字段化
分数线
- 已接院校、专业、年份、动态字段筛选；后端只允许 scoreline_fields.is_filter=true 且字段名安全的动态字段参与查询
- 后续补趋势图增强、院校/专业搜索体验和 AI 择校更细上下文配置
资料下载
- PDF 列表、权限提示、短签名预览、下载确认和动态水印 traceId 展示已接第一版
个人中心
- 会员权益、订单、激活码兑换
- 错题本、收藏夹、学习统计、勋章、站内通知，排行榜仅在租户开启后展示
- 男女预设头像契约和页面二选一 UI 已接；不做用户头像上传，也不要把微信/QQ 返回头像写入学生资料
- Taro 已接学习报告、14 天趋势、题型表现和最近练习第一版；排行榜仅在租户显式开启 enableLeaderboard 并完成压测后进入独立排行榜页或活动页，个人中心默认不请求
- 会员收银台、优惠券领取、下单、支付参数、订单详情、状态轮询和售后入口已接第一版

前端接入原则

不在前端实现最终权限判断，前端只做 UI 可见性控制。
不在前端直接拼接私有资源 URL，统一请求后端签名。
不把旧 PocketBase 字段当成长期模型，优先使用新 API 返回的 entryId/contentNodeId/collectionId/blueprintId。
小程序码、支付、登录等平台能力统一走 provider adapter，不在页面里硬编码租户密钥。

46 KiB Raw Blame History Unescape Escape

后续开发 TODO

当前后端基线

后端待补功能

P0 上云测试前必须补齐

P1 商用功能完善

P2 运营体验和企业交付

Taro 前端开发 TODO

架构目标

第一批页面

前端接入原则

推荐下一步顺序

46 KiB

Raw Blame History