后续开发 TODO

更新时间：2026-06-30

当前后端基线

后端已经完成可本地验证的商用 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、分佣和优惠券规则/核销报表第一版操作台。
内容导航：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-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 把租户状态变更、账务资料变更、批量开票、逾期处理、手工收款确认、审计导出等高风险平台操作生成内部告警；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 覆盖规则匹配、幂等和敏感 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 已通过。

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

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 只作为租户上下文，不能作为身份依据。
对象存储
- 已接阿里云 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 存储、空 bucket、关闭租户前缀；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、生产 dry-run、导入校验、pb:import:sample 业务抽样、真实数据 API 读路径压测、API/worker/Taro、运行时审计、@codex-security、备份/回滚/真实抽样/生产 provider 等证据填入本地 production-launch-evidence.json 并通过门禁。
- 确认数据库迁移流程、备份恢复、日志、告警。
- 准备 API 容器部署和 Supabase 云端/自托管连接方案。
- 已补 npm run perf:api:local 和 docs/refactor/performance-benchmark-runbook.md，可在本地或云端对真实迁移数据做只读混合压测；4 核 16G 正式容量报告需上云后按 6/30/50/100 阶梯并发复跑并归档到本地上线证据。

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。
- 继续补存储、学生数、题量、视频播放量等更多套餐用量限制和超额计费策略。
- 继续补生产定时调度、失败告警和更完整运营后台消息。
视频会员控制
- 已完成视频 SVIP 权限、播放次数扣减、签名播放和播放日志。
- 已补播放签名动态水印上下文、traceId 事件、播放进度上报和租户后台播放事件查询；继续补深度防盗链、转码级水印和更细观看行为分析。
- 单题视频和通用知识视频混合推荐。
学习统计
- 已完成免费额度、练习访问事件、模考交卷评分报告、练习历史、正确率趋势、题型分布、错题复习计划。
- 已完成单词复习算法、每日计划和复习上报。
- 已完成排行榜主接口并通过租户开关默认关闭；当前产品默认不开启排行榜，避免日常请求压力和防刷复杂度。只有租户明确购买/开启对应活动并完成压测后，再补防刷、日/周榜预聚合、运营后台排名看板和专项压测。
- Taro 已有后端 session detail 续练、本地断点恢复、倒计时和阅读理解/案例分析多小题第一版；继续补复盘体验、长题干/公式图片混排和更细统计口径。
订单和营销体验
- 已完成订单详情、订单状态轮询、激活码预检查、优惠券前台领取、下单抵扣计算、优惠券复杂规则、核销明细/报表和内部退款状态机。
- 已完成支付/退款补偿 worker、官方账单下载 worker、资金对账导入比对、差错工单、异常订单运营台和人工调整凭证复核；Taro 财务运营台第一版已接入；本地继续验证回调后业务链路、幂等、审计、权益开通/撤销和密钥不泄露，真实生产账号、回调域名和账单格式抽样验收上云后补齐；继续补学生端售后入口深化、营销活动 UI 和活动效果看板。
积分和反馈增强
- 已完成每日签到、积分流水、反馈提交、租户后台处理、奖励积分幂等。
- 已完成勋章后台维护、手动发放、学生端展示，以及签到连续天数、积分阈值、反馈解决、积分活动、练习次数、单词掌握和模考成绩自动发放。
- 积分兑换、活动任务、优惠券兑换履约、积分风控只读报表、反馈运营聚合报表和站内通知后端第一阶段已完成；Taro 学生个人中心和租户营销中心已接积分任务/兑换第一版，租户营销中心已接 30 天风控摘要和反馈运营摘要；继续补独立消息中心增强、外部订阅消息/短信和更细活动效果看板。
数据看板

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

销售/代理分佣

已完成租户默认分佣比例、成员分佣比例、激活码批次分佣比例。
已完成订单和激活码两类来源的佣金归因，且只统计客资绑定后的成交。
已完成结算单生成、重复结算拦截、审核、打款状态、已打款锁定、CSV/JSON 导出、打款凭证登记、凭证复核、租户隔离和销售/代理本人范围权限。
继续补真实打款 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 输出、报告列表/详情接口和 Taro 学生端基础页。
继续补真实 AI provider adapter、租户级 app_private.tenant_secrets(secret_scope='ai') 密钥联调、prompt 版本管理、运营后台配置、报告 PDF 渲染和人工复核流程。

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。
- 继续补富卡片模板、失败告警、死信运营后台和更细销售转化看板。
运维
- 后台操作审计报表。
- 定时备份、恢复演练。
- 性能压测、慢 SQL、索引审查；当前已有 API 压测脚本和 4 核 16G runbook，待云服务器部署后输出正式容量报告。

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；学生端、租户后台、平台后台都有第一批真实 API 页面；学生端已补地区选择、刷题答题卡、后端权威断点续练、本地进度恢复、模拟倒计时、主观题后端自评、阅读理解/案例分析多小题、错题/收藏复习、题目反馈、视频解析、练习/模考报告、个人中心学习报告可视化、会员收银台、订单详情、售后入口、站内消息中心第一版、积分任务/兑换/积分明细第一版、预设头像契约、题干/选项/解析/知识手册 RichContent 安全渲染、H5 KaTeX 公式渲染、私有资源 ID 题图短签名渲染、逐题复盘、背单词卡片学习/发音/收藏练习第一版；平台后台已接入创建租户、租户详情、状态变更、账务资料维护、平台员工列表/创建/编辑/禁用恢复、平台审计查询/CSV 导出、开放审计告警展示/确认/解决、审计告警外部通知渠道/事件状态摘要、催缴外部通知渠道/事件摘要、订阅、订阅账单候选/dry-run/批量生成、自动计费生成结果查看、收款、用量和公共题库授权第一版写操作；租户后台已接权限驱动工作台、学生运营操作台、学习督导自动化/每日规则保存、主题模板预览/发布、角色模板、成员绑定、CRM/分佣操作台、积分任务/兑换操作台和用户通知查看第一版；下一步补男女预设头像选择 UI、小程序公式真机验收、题图资源字段化、独立消息中心增强、状态管理、更细数据范围 UI、督导触达联动和小程序兼容验证。

第一批页面

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

前端接入原则

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

38 KiB Raw Blame History Unescape Escape

后续开发 TODO

当前后端基线

后端待补功能

P0 上云测试前必须补齐

P1 商用功能完善

P2 运营体验和企业交付

Taro 前端开发 TODO

架构目标

第一批页面

前端接入原则

推荐下一步顺序

38 KiB

Raw Blame History