forked from wangziqi/gongxue-base
272 lines
44 KiB
Markdown
272 lines
44 KiB
Markdown
# 后续开发 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 上云测试前必须补齐
|
||
|
||
1. 生产鉴权
|
||
- 已支持 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` 只作为租户上下文，不能作为身份依据。
|
||
|
||
2. 对象存储
|
||
- 已接阿里云 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` 继续作为资源台账，不允许前端绕过台账直接访问私有资源。
|
||
|
||
3. 真实导入 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 做二次验证。
|
||
|
||
4. 部署配置
|
||
- 生产 `.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` 并通过门禁。当前 Codex 环境未暴露可调用的 `@codex-security` 扫描工具时，该项只能标为待补，不能伪造完成。
|
||
- 确认数据库迁移流程、备份恢复、日志、告警。
|
||
- 准备 API 容器部署和 Supabase 云端/自托管连接方案。
|
||
- 已补 `npm run perf:api:local`、`npm run perf:summary`、`npm run perf:postgres:evidence`、`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 调参证据、三类后端角色旅程烟测、三类 Taro 前端角色旅程契约、H5 发布目录启动烟测、真实浏览器关键点击烟测和前端 API 契约检查。2026-07-01 本地真实迁移库只读 30 worker/120s 为 108336 请求、0 错误、897.04 req/s、P95 68.32ms、P99 84.50ms；最新混合读写复测 100 worker/120s/8% 写入为 84694 请求、0 错误、699.54 req/s、P95 265.11ms、P99 337.82ms；150 worker/120s/6% 写入为 74209 请求、0 错误、612.19 req/s、P95 446.37ms、P99 579.39ms。当前本机 Docker 舒适区暂按 100 个无停顿 worker 估算，150 worker 已是压力区；按单学生 0.05 到 0.2 req/s 粗略折算约为 3500 到 14000 名活跃在线学生的吞吐观察区间，正式容量仍以上云 4 核 16G 复测为准。
|
||
- 当前本地 PostgreSQL evidence 仍提示 `jit=on`、`statement_timeout=0`、`idle_in_transaction_session_timeout=0`、`lock_timeout=0`；上云后必须按 `docs/refactor/postgresql-4c16g-tuning.md` 调整参数并复跑 evidence。4 核 16G 正式容量报告需上云后按 6/30/50/100 阶梯并发复跑并归档到本地上线证据。
|
||
|
||
### P1 商用功能完善
|
||
|
||
1. 支付
|
||
- 已完成微信支付 JSAPI、支付宝 WAP/H5 的创建支付参数和 webhook 幂等开通权益。
|
||
- 已完成内部退款状态机、退款申请/审核/处理接口、微信/支付宝发起退款、微信/支付宝退款查询确认、微信/支付宝退款通知 webhook、部分/全额退款状态、全额退款权益撤销和审计事件。
|
||
- 已完成支付/退款补偿 worker，可兜底供应商漏通知、处理中退款和重复执行幂等。
|
||
- 已完成资金对账手工/API 导入比对、微信/支付宝官方账单下载任务、批次/明细/异常查询、差错工单状态流、异常订单运营台、人工调整凭证和财务复核报表；Taro 租户财务运营台第一版已接退款、官方账单任务、对账异常、差错工单和调整凭证；继续补真实生产账单格式抽样验收和更完整售后体验。
|
||
- 租户自有商户收款和平台代收/服务商模式。
|
||
|
||
2. 国内登录和短信
|
||
- 已完成阿里云短信、腾讯云短信 adapter 的后端实现和本地 fake endpoint 测试。
|
||
- 已完成微信小程序 `code2Session` 登录主链路。
|
||
- 已完成手机号绑定/换绑、微信网页登录、QQ 登录基础 API；继续补真实生产账号、回调域名和开放平台联调。
|
||
- 本地阶段不等待真实密钥，继续用 mock/fake provider 验证验证码、账号合并、登录审计、session 签发和错误处理；真实密钥、合法域名和开放平台错误码等上云后再联调。
|
||
- 旧 PocketBase 用户账号和新身份体系的映射/补绑。
|
||
|
||
3. 导入体系扩展
|
||
- 已完成题目、单词、知识手册、分数线、视频的 CSV/Excel 到规范 JSON 解析适配。
|
||
- 已完成大批量异步导入 worker、重试、导入后复检和审计。
|
||
- 模板下载、字段映射 API、导入任务详情、导入后复检和 PocketBase JSON dry-run 报告工具已补；Taro 租户内容页已接 JSON/CSV/Excel 文件或粘贴内容、模板下载、后端 preview、字段别名覆盖、同步/异步执行、异步 job 轮询和复检结果详情第一版；后端已对字段映射目标做白名单和危险 key 拦截。
|
||
- 继续补真实数据执行验收、导入前抽样校验和导入性能压测。
|
||
|
||
4. 题库导出增强
|
||
- 已完成服务端 JSON、`paper_json`、`print_payload` 基础导出和导出 job 台账。
|
||
- 已完成 PDF/Word 二进制生成 worker、页面水印、导出发布到 `content_assets`、后台资源签名下载/预览路径，以及每日一练九宫格 metadata、PDF/Word 基础版式和 ZIP 图片素材包。
|
||
- 继续补更精细的试卷模板、导出操作台和多模板排版。
|
||
|
||
5. 公共题库和租户授权
|
||
- 已完成平台公共题库/地区题库的基础授权、租户采纳、题目快照复制和手动同步。
|
||
- 已完成 `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、平台在线收款和更完整运营后台消息。
|
||
- 继续补生产定时调度、平台审计告警升级策略和更完整运营后台消息。
|
||
|
||
6. 视频会员控制
|
||
- 已完成视频 SVIP 权限、播放次数扣减、签名播放和播放日志。
|
||
- 已补播放签名动态水印上下文、traceId 事件、播放进度上报和租户后台播放事件查询；继续补深度防盗链、转码级水印和更细观看行为分析。
|
||
- 单题视频和通用知识视频混合推荐。
|
||
|
||
7. 学习统计
|
||
- 已完成免费额度、练习访问事件、模考交卷评分报告、练习历史、正确率趋势、题型分布、错题复习计划。
|
||
- 已完成单词复习算法、每日计划和复习上报。
|
||
- 已完成排行榜主接口并通过租户开关默认关闭；当前产品默认不开启排行榜，避免日常请求压力和防刷复杂度。只有租户明确购买/开启对应活动并完成压测后，再补防刷、日/周榜预聚合、运营后台排名看板和专项压测。
|
||
- Taro 已有后端 session detail 续练、本地断点恢复、倒计时和阅读理解/案例分析多小题第一版；继续补复盘体验、长题干/公式图片混排和更细统计口径。
|
||
|
||
8. 订单和营销体验
|
||
- 已完成订单详情、订单状态轮询、激活码预检查、优惠券前台领取、下单抵扣计算、优惠券复杂规则、核销明细/报表和内部退款状态机。
|
||
- 已完成支付/退款补偿 worker、官方账单下载 worker、资金对账导入比对、差错工单、异常订单运营台和人工调整凭证复核；Taro 财务运营台第一版已接入；本地继续验证回调后业务链路、幂等、审计、权益开通/撤销和密钥不泄露，真实生产账号、回调域名和账单格式抽样验收上云后补齐；继续补学生端售后入口深化、营销活动 UI 和活动效果看板。
|
||
|
||
9. 积分和反馈增强
|
||
- 已完成每日签到、积分流水、反馈提交、租户后台处理、奖励积分幂等。
|
||
- 已完成勋章后台维护、手动发放、学生端展示，以及签到连续天数、积分阈值、反馈解决、积分活动、练习次数、单词掌握和模考成绩自动发放。
|
||
- 积分兑换、活动任务、优惠券兑换履约、积分风控只读报表、反馈运营聚合报表和站内通知后端第一阶段已完成；Taro 学生个人中心和租户营销中心已接积分任务/兑换第一版，学生独立消息中心已接通知筛选和状态操作，租户营销中心已接 30 天风控摘要和反馈运营摘要；继续补外部订阅消息/短信和更细活动效果看板。
|
||
|
||
10. 数据看板
|
||
- 已完成首版实时聚合接口，覆盖收益、注册趋势、答题次数、收入趋势、题型分布、科目数量、题目总量、套餐销量、运营动态、24h 活跃度和激活码使用情况。
|
||
- 继续补日/周/月预聚合 worker、缓存策略、慢 SQL 监控和大租户性能压测。
|
||
- 分佣结算和销售/代理转化报表第一版已完成；继续补转化预聚合、真实打款 provider、发票、异常调整单和更细客资跟进效果看板。
|
||
|
||
11. 销售/代理分佣
|
||
- 已完成租户默认分佣比例、成员分佣比例、激活码批次分佣比例。
|
||
- 已完成订单和激活码两类来源的佣金归因，且只统计客资绑定后的成交。
|
||
- 已完成结算单生成、重复结算拦截、审核、打款状态、已打款锁定、CSV/JSON 导出、打款凭证登记、凭证复核、租户隔离和销售/代理本人范围权限。
|
||
- 已完成销售/代理转化看板第一版，覆盖成交漏斗、成员排行、CRM 失败、跟进积压和近期未成交客资。
|
||
- 继续补真实打款 provider、发票管理、批量凭证上传、销售团队分佣看板、转化预聚合和异常调整单。
|
||
|
||
12. 学生运营管理
|
||
- 已完成学生列表、学生资料维护、班级分组、教师范围可见、学生批量导入、禁用/恢复、批量分班、学生备注、跟进任务、跟进效果统计和批量 CRM 推送；学生写入口拒绝头像 URL、第三方头像字段和 `primaryRole`，避免绕过预设头像与租户角色体系。
|
||
- 已完成学习督导自动化第一版：后端按未学习、错题积压、低正确率、单词待复习和超期未完成练习预览风险学生，并幂等生成 `learning` 跟进任务；教师账号沿用班级范围，手机号按字段权限脱敏，生成动作写审计。
|
||
- 已完成督导规则模板和定时生成 worker：`GET/PUT /api/tenant-admin/students/supervision/rules` 支持保存手动/每日/每周规则，`apps/worker --job student-supervision` 复用后端候选计算和幂等生成逻辑，写回 `lastResult/nextRunAt` 和审计。
|
||
- 已完成 Taro 学生运营页第一版：学生创建/更新、状态禁用/恢复、批量导入、批量分班、备注、跟进任务、完成跟进、跟进看板、学习督导候选预览/生成、保存每日督导规则和 CRM 入队推送。
|
||
- 继续补 CRM/站内通知/企微/飞书/钉钉的触达联动、督导效果归因，以及更细导入模板体验。
|
||
|
||
13. 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 运营体验和企业交付
|
||
|
||
1. 自定义角色
|
||
- 已完成租户内角色模板、菜单可见、模块可见、字段级权限和权限变更审计基础 API。
|
||
- 已完成班级/教师/学生范围权限 API，教师只能查看自己负责班级的学生。
|
||
- 已完成 Taro 租户设置页角色模板可视化配置第一版，支持创建、编辑、停用、权限点、菜单、模块、字段和基础数据范围配置。
|
||
- 已完成 Taro 成员绑定模板第一版，支持成员搜索/新建、绑定角色模板、成员状态和额外权限覆盖；工作台已按后端权限矩阵隐藏不可见模块。
|
||
- 继续补更细的数据范围 UI，例如地区、题库、销售团队、本人客资、班级学生组合规则，以及成员批量运营和完整后台菜单权限联动。
|
||
|
||
2. 主题系统
|
||
- 已完成平台默认三套主题。
|
||
- 已完成租户自定义主色、强调色、Logo、图标集和分享图的草稿预览/发布 API。
|
||
- 已完成 Taro 租户设置页主题模板、草稿和发布第一版。
|
||
- 继续补素材库、启动图/小程序分享图上传到 `content_assets` 的后台体验、更多主题模板和更细组件级视觉 token。
|
||
|
||
3. CRM worker
|
||
- 已完成 `apps/worker` CRM 队列消费、generic webhook、钉钉、飞书、企业微信机器人 adapter、签名、失败重试和日志。
|
||
- 已完成 CRM 配置中的跟进分配策略：`none/direct/round_robin/referrer`，后端校验候选人必须是当前租户内 active 的销售/代理/运营/教师/管理员，首绑客资后写入 `assignedToUserId` 并把 assignee 放进 CRM 队列 payload。
|
||
- 已完成死信失败池、脱敏日志查看、手动重试/忽略和审计闭环，Taro 租户营销中心已接第一版操作台。
|
||
- 销售转化看板第一版已完成；继续补富卡片模板、外部失败告警升级、转化预聚合和更细团队数据范围。
|
||
|
||
4. 运维
|
||
- 后台操作审计报表。
|
||
- 定时备份、恢复演练。
|
||
- 性能压测、慢 SQL、索引审查；当前已有 API 压测脚本、真实刷题读写闭环和 4 核 16G runbook，本地真实迁移数据已完成 30/50/100/150 并发阶梯压测，云服务器部署后还要按同一矩阵复跑并输出正式容量报告。
|
||
|
||
## 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、督导触达联动和小程序兼容验证。
|
||
|
||
### 第一批页面
|
||
|
||
1. 租户启动与首页
|
||
- 调 `/api/tenant/resolve`
|
||
- 读取品牌、主题、Banner、公告、功能开关
|
||
- 展示题库入口、背单词、知识手册、分数线、资料、会员
|
||
|
||
2. 登录
|
||
- 迁移期可先接短信 mock 或临时登录
|
||
- 生产接微信小程序登录、短信登录、QQ/微信网页登录真实账号
|
||
|
||
3. 题库
|
||
- `content_entries/content_nodes`
|
||
- `question_collections/practice_blueprints`
|
||
- 顺序刷题、随机刷题、全真模拟
|
||
- 答题、解析、错题、收藏、视频解析入口
|
||
|
||
4. 背单词
|
||
- 单元列表、单词列表
|
||
- 学习状态、收藏、统计
|
||
- 每日新词、复习计划、认识/不认识上报
|
||
- Taro 已接学习概览、掌握率、计划拆分、卡片翻转、发音、美/英音切换、收藏练习、单词跳转和本地位置恢复；后续补租户级发音源配置、小程序真机音频兼容验收和更细复习参数
|
||
|
||
5. 知识手册
|
||
- 手册入口、章节、小节、知识点阅读
|
||
- RichContent 已支持 Markdown 图片、基础表格、代码、加粗、H5 KaTeX 公式渲染、私有资源 ID 短签名和安全过滤；Taro 已接章节内搜索、安全文本摘要高亮和目录定位第一版；后续补小程序公式真机验收和题图资源字段化
|
||
|
||
6. 分数线
|
||
- 已接院校、专业、年份、动态字段筛选；后端只允许 `scoreline_fields.is_filter=true` 且字段名安全的动态字段参与查询
|
||
- 后续补趋势图增强、院校/专业搜索体验和 AI 择校更细上下文配置
|
||
|
||
7. 资料下载
|
||
- PDF 列表、权限提示、短签名预览、下载确认和动态水印 traceId 展示已接第一版
|
||
|
||
8. 个人中心
|
||
- 会员权益、订单、激活码兑换
|
||
- 错题本、收藏夹、学习统计、勋章、站内通知，排行榜仅在租户开启后展示
|
||
- 男女预设头像契约和页面二选一 UI 已接；不做用户头像上传，也不要把微信/QQ 返回头像写入学生资料
|
||
- Taro 已接学习报告、14 天趋势、题型表现和最近练习第一版；排行榜仅在租户显式开启 `enableLeaderboard` 并完成压测后进入独立排行榜页或活动页，个人中心默认不请求
|
||
- 会员收银台、优惠券领取、下单、支付参数、订单详情、状态轮询和售后入口已接第一版
|
||
|
||
### 前端接入原则
|
||
|
||
- 不在前端实现最终权限判断，前端只做 UI 可见性控制。
|
||
- 不在前端直接拼接私有资源 URL，统一请求后端签名。
|
||
- 不把旧 PocketBase 字段当成长期模型，优先使用新 API 返回的 `entryId/contentNodeId/collectionId/blueprintId`。
|
||
- 小程序码、支付、登录等平台能力统一走 provider adapter，不在页面里硬编码租户密钥。
|
||
|
||
## 推荐下一步顺序
|
||
|
||
1. 补租户后台写操作台：公共题库采纳/同步、冲突查看、单条/批量冲突采纳平台或保留本地、导入问题、模板预览/下载、上传/粘贴 preview/import、字段映射编辑、异步导入轮询、导入后复检详情、权限驱动工作台、学生创建/更新/批量导入/批量分班/备注/跟进、角色模板配置、成员绑定模板、CRM 配置/队列/跟进分配策略、分佣规则/成员比例/结算生成审核打款/导出/凭证复核已接第一版；继续补成员批量运营、更细数据范围 UI、真实打款 provider 和发票。
|
||
2. 继续补 Taro 学生端旧体验：地区选择、刷题答题卡、后端权威断点续练、本地进度恢复、模拟倒计时、主观题后端自评、阅读理解/案例分析多小题、视频播放、反馈、模考报告、逐题复盘、错题/收藏专题、个人中心学习报告、男女预设头像选择、收银台、订单详情、售后入口、独立消息中心、积分任务/兑换/积分明细、题干/解析/知识手册 RichContent 安全渲染、知识手册章节内搜索/安全摘要高亮/目录定位、H5 KaTeX 公式渲染、私有资源 ID 题图短签名、背单词学习概览/卡片学习/发音/收藏练习、资料短签名水印预览/下载确认已接第一版；继续补小程序公式真机验收、题图资源字段化、小程序支付容器、分享场景和状态管理。前端不得实现头像上传、头像裁剪或第三方头像同步。
|
||
3. 补平台后台增强：租户基础资料编辑增强、平台审计告警升级策略、平台催缴通知配置操作台细节和平台在线收款。
|
||
4. 云服务器部署 Supabase/PostgreSQL 和 API，配置对象存储生产环境变量，跑 `check:refactor` 的远程等价测试。
|
||
5. 三套 H5 上云前必须在目标目录补真实公开 `runtime-config.json`，先执行 `npm run smoke:taro:h5`、`npm run smoke:taro:h5:interaction` 和 `node scripts/taro-h5-release-guardrails-test.js --require-dist` 做本地发布目录烟测、真实浏览器交互烟测和发布守卫；写入生产上线证据时必须执行 `npm --silent run smoke:taro:h5 -- --json`、`npm --silent run smoke:taro:h5:interaction -- --json` 和 `node scripts/taro-h5-release-guardrails-test.js --require-dist --require-runtime-config --json`，确保 warning 为 0。随后人工打开学生端/租户后台/平台后台域名，确认入口、租户解析、登录态和 `Authorization + x-tenant-id` 请求正常。当前构建仍有 webpack 体积 warning，后续做首屏拆包、按入口拆页面和 Supabase client 引入优化。
|
||
6. 使用 `F:\project\参考\旧题库数据库文件` 中的真实 PocketBase 数据，按 `docs/refactor/pocketbase-real-data-migration-runbook.md` 继续做人工复核和抽样验收；当前 dry-run/导入/校验链路已跑通，下一步重点是 7 个已支付缺用户订单、22 个待复核手册章节、2533 道旧分类缺失题目和 5298 条引用已删除题目的答题记录的运营处理结论。导入过程中发现的字段污染、跨集合引用断裂、敏感字段和旧权限问题都要沉淀到 importer mapper 或修复脚本，不手工临时修库。
|
||
7. 并行补真实登录、真实生产账单格式验收、异常订单运营台、对象存储真实 AV/内容安全服务联调、转码/CDN 级水印/生命周期、题库导出模板精排/操作台、公共题库生产定时调度和失败告警。
|
||
8. 前后端联调通过后，再做支付、权限、数据导入、资料下载、视频播放的商用验收。
|