feat: add spreadsheet async imports

2026-06-29 08:00:17 +08:00
parent 78a26d1df2
commit eee21f6eed
27 changed files with 2972 additions and 267 deletions
--- a/docs/refactor/api-structure.md
+++ b/docs/refactor/api-structure.md
@@ -74,4 +74,4 @@ types.ts                   仅本领域使用的类型
 - `learning` 创建练习 session 时必须保存 `question_ids` 快照，避免随机刷题和模考过程中题目集合变化导致答题记录无法复盘。
 - 排行榜必须由后端按租户、地区、班级和可信用户上下文聚合，前端不能自行扫描答题记录、积分流水或单词进度后排名；后续高流量场景再通过 worker/materialized view 做日榜、周榜和防刷。
 - 资料、PDF、视频等对象存储资源必须先进入 `content_assets` 台账，再通过 API/Edge Function 做权限校验和签名 URL 下发；前端不能直接拼 OSS/COS/Supabase Storage 私有地址。
- 批量导入必须先写 `content_import_jobs/items/issues`，保留原始 payload、规范化 payload、逐行问题和审计记录；同步 API 当前支持题目 JSON，Excel/CSV 和其它内容类型应接入同一管线。
+- 批量导入必须先写 `content_import_jobs/items/issues`，保留原始 payload、规范化 payload、逐行问题和审计记录；题目、单词、知识手册、分数线和视频 JSON/CSV/Excel 都应进入同一管线，复杂大批量导入通过 `executionMode=async` 交给 imports worker 消费。
--- a/docs/refactor/backend-capability-status.md
+++ b/docs/refactor/backend-capability-status.md
@@ -163,8 +163,8 @@
 | 知识手册 JSON preview/import | 可联调 | 支持书籍/章节/小节/知识点归一化 |
 | 分数线 JSON preview/import | 可联调 | 支持 `fields/schools/majors/records` 分桶或 `items` 列表，后端校验租户地区和院校/专业引用 |
 | 视频 JSON preview/import | 可联调 | 支持 `videos/items`，后端校验题目、科目、资源引用，导入后写入 `question_videos` |
-| Excel/CSV 导入 | 待补齐 | 应复用 `content_import_jobs` 管线 |
-| 大批量异步导入 | 待补齐 | 需要 `apps/worker` |
+| Excel/CSV 导入 | 可联调 | 题目、单词、知识手册、分数线、视频已支持 CSV 和 `.xlsx` 解析，解析后复用 `content_import_jobs/items/issues` 管线并保留 `parser_metadata` |
+| 大批量异步导入 | 可联调 | `executionMode=async` 会将 preview job 置为 `pending`；`apps/worker --job imports` 抢占 queued job，复用 API 导入 executor，支持重试、清锁和审计；导入后复检待补 |
 | 公共题库版本同步 | 待补齐 | 当前采纳为快照复制；后续需 worker 做增量同步、冲突处理、版本升级通知和租户自改保护 |

 ## 当前验证
@@ -174,6 +174,7 @@
 ```bash
 npm audit
 npm run check:refactor
+npm run test:worker:imports
 ```

 `check:refactor` 包含：
--- a/docs/refactor/backend-handoff-roadmap.md
+++ b/docs/refactor/backend-handoff-roadmap.md
@@ -14,7 +14,7 @@
 - 销售/代理/CRM 已经有邀请码、扫码/分享事件、首绑客资保护、团队关系、统计、CRM 配置和入队能力。
 - 旧题库 JSON、单词模板、知识手册嵌套模板、分数线 JSON 和视频绑定 JSON 已经进入后端 preview/import 管线，由后端负责规范化、校验、幂等、审计和租户隔离。

-因此，后端现在已经具备进入 Taro 前端第一阶段联调的基础。需要注意的是，它还不是完整生产交付状态，真实云端鉴权、对象存储生产安全、支付/短信生产账号、微信网页登录/QQ 登录、真实数据 dry-run 迁移和大批量异步导入仍需要继续补齐或联调。
+因此，后端现在已经具备进入 Taro 前端第一阶段联调的基础。需要注意的是，它还不是完整生产交付状态，真实云端鉴权、对象存储生产安全、支付/短信生产账号、微信网页登录/QQ 登录、真实数据 dry-run 迁移、导入后复检和模板字段映射仍需要继续补齐或联调。

 ## 后端模块进度

@@ -23,16 +23,16 @@
 | 多租户底座 | 可联调 | 租户、域名、品牌、设置、RLS 基础、审计、Supabase JWT/API 身份映射 | 真实云端 Auth/JWKS 回归、生产 RLS 深测 |
 | 平台后台 | 基础完成 | 租户、套餐、订阅、账单、服务费、用量、公共题库授权 | 自动计费、平台审计、公共题库版本同步 |
 | 租户后台 | 可联调 | 品牌、域名、支付账户、登录配置、密钥掩码、活动、兑换码、优惠券、勋章管理/发放、成员权限、角色模板、菜单/模块/字段权限配置 API、班级/教师/学生范围权限 | 前端权限 UI、更细的数据范围组合 |
-| 题库与练习 | 可联调 | 内容入口、任意深度分类、题目集合、顺序/随机/全真模拟蓝图、组卷快照、答题、错题、收藏、模考报告、排行榜、公共题库采纳快照 | 专项策略、公共题库版本同步、Excel 导入、排行榜防刷/预聚合 |
-| 背单词 | 可联调 | 单元、单词、进度、收藏、统计、每日计划、JSON 导入、排行榜 | Excel 导入、更细复习参数 |
-| 知识手册 | 可联调 | 科目、章节、条目、Markdown 内容、嵌套 JSON 导入 | 富文本资源、版本管理、附件/PDF 关联 |
-| 分数线 | 可联调 | 院校、专业、动态字段、记录、年份、趋势、后台维护、JSON 导入 | 复杂筛选、AI 择校上下文 |
-| 视频解析 | 可联调 | 单题视频、批量查询、后台视频绑定、JSON 导入、会员播放权限、播放次数扣减、签名 URL 和播放日志 | 深度防盗链、动态水印、播放统计 |
+| 题库与练习 | 可联调 | 内容入口、任意深度分类、题目集合、顺序/随机/全真模拟蓝图、组卷快照、答题、错题、收藏、模考报告、排行榜、公共题库采纳快照 | 专项策略、公共题库版本同步、排行榜防刷/预聚合 |
+| 背单词 | 可联调 | 单元、单词、进度、收藏、统计、每日计划、JSON/CSV/Excel 导入、排行榜 | 更细复习参数 |
+| 知识手册 | 可联调 | 科目、章节、条目、Markdown 内容、嵌套 JSON/CSV/Excel 导入 | 富文本资源、版本管理、附件/PDF 关联 |
+| 分数线 | 可联调 | 院校、专业、动态字段、记录、年份、趋势、后台维护、JSON/CSV/Excel 导入 | 复杂筛选、AI 择校上下文 |
+| 视频解析 | 可联调 | 单题视频、批量查询、后台视频绑定、JSON/CSV/Excel 导入、会员播放权限、播放次数扣减、签名 URL 和播放日志 | 深度防盗链、动态水印、播放统计 |
 | 资料下载 | 部分完成 | 资源台账、SVIP 权限校验、`local_dev`/阿里云 OSS/腾讯 COS/Supabase Storage 上传下载签名、上传确认、PDF/图片预览签名、assets worker 复检异常下架 | PDF 渲染、CDN 防盗链、杀毒扫描、视频水印 |
 | 会员与订单 | 可联调 | 下单、订单详情/状态轮询、优惠券领取/抵扣、零元订单自动开通、手工确认权限保护、激活码预检查/兑换、微信支付、支付宝、微信/支付宝发起退款、微信/支付宝退款查询确认、微信/支付宝退款通知 webhook、支付/退款补偿 worker、权益发放 | 完整资金流水对账、异常订单运营台 |
 | 登录认证 | 可联调 | 短信 mock、阿里云/腾讯云短信 adapter、迁移期 session、Supabase Auth JWT、微信小程序登录、OAuth 配置表 | 微信网页登录、QQ 登录、手机号换绑、真实生产账号联调 |
 | 销售/代理/CRM | 基础完成 | 邀请码、首绑保护、团队关系、销售统计、CRM 入队 | 小程序码真实生成、分佣结算、钉钉/飞书/企微 worker |
-| 内容导入 | 可联调 | 题目、单词、知识手册、分数线、视频 JSON preview/import、issue、job、审计、幂等 | Excel/CSV 解析、大批量异步 worker、导入后复检 |
+| 内容导入 | 可联调 | 题目、单词、知识手册、分数线、视频 JSON/CSV/Excel preview/import、issue、job、审计、幂等、`executionMode=async` 和 imports worker | 导入后复检、模板下载/字段映射 |
 | 数据看板 | 可联调 | 租户 dashboard 聚合接口，收益、注册、学习、内容、激活码、反馈、趋势、24h 活跃、套餐销量和运营动态 | 预聚合 worker、缓存、慢 SQL 监控和销售转化看板 |
 | AI 择校推荐 | 未开始 | 暂无 | 数据上下文、AI JSON schema、报告渲染、PDF 生成 |
 | Taro 前端 | 未开始 | 旧 Web 已有新 API 适配雏形 | `apps/taro`、跨端 API client、H5/小程序页面和端到端测试 |
@@ -87,7 +87,7 @@
 - XPay 或其它实际支付网关 adapter。
 - 阿里云/腾讯云短信、微信小程序登录、微信网页登录、QQ 登录。
 - 公共题库/地区题库版本同步，租户按 SaaS 套餐购买地区、科目和题库范围的更细计费策略。
- Excel/CSV 解析、大批量异步导入和导入后复检。
+- 导入后复检和导入模板/字段映射 UI；大批量导入已支持 `executionMode=async`，前端按 job 状态轮询。
 - 视频深度防盗链、动态水印和播放统计。
 - 数据看板 API：收益、注册趋势、答题次数、收入趋势、题型分布、题目总量、套餐销量、24h 活跃。

--- a/docs/refactor/backend-progress.md
+++ b/docs/refactor/backend-progress.md
@@ -32,6 +32,8 @@
 - 已新增 commerce worker 和 `npm run test:worker:commerce`，用于补偿查询微信/支付宝支付、处理中退款和漏通知场景；支付成功会幂等更新订单/支付并开通权益，退款成功会幂等更新退款/订单/支付并在全额退款时撤销订单权益，测试覆盖密钥不泄露和重复执行不重复开通。
 - 已新增 assets worker 和 `npm run test:worker:assets`，用于复检 `content_assets` 托管对象元数据；正常资源会写入复检证据，异常资源会自动下架为 `draft`、标记 `upload_status=failed`，并记录审计与安全标记。
 - 已新增分数线/视频 JSON 导入接口和集成测试：分数线支持字段、院校、专业、记录、动态字段值；视频支持视频元数据、资源引用、访问模式和题目绑定，全部复用 `content_import_jobs/items/issues` 管线。
+- 已新增 CSV/Excel 导入解析层：题目、单词、知识手册、分数线和视频都可通过 `sourceFormat=csv/excel` 先解析为规范 payload，再进入同一套 preview/import、逐行 issue、幂等和审计管线；分数线支持多 Sheet Excel。
+- 已新增 imports worker 和 `npm run test:worker:imports`：确认导入时可传 `executionMode=async`，API 将 preview job 排队为 `pending`，worker 复用同一导入 executor 消费任务，支持抢占锁、attempt/backoff、失败重试、清锁和审计。

 ## 已验证接口

@@ -251,11 +253,11 @@ GET  /api/tenant-admin/audit-logs
 - 内容资源当前完成台账、租户后台维护、学生端 SVIP 下载权限，以及 `local_dev`、阿里云 OSS、腾讯 COS、Supabase Storage 的上传/下载签名 provider；上传确认和 assets worker 已支持对象元数据校验/复检。PDF 预览渲染、防盗链、水印和安全扫描仍需继续补。
 - 题库内容导航当前以 `content_entries/content_nodes` 为主模型，可表达“入口 -> 多级分类 -> 院校/专业/学科/销售意向标记”；题目集合和练习方式由 `question_collections/practice_blueprints` 管理，练习 session 会保存当次题目 ID 快照。
 - 练习访问控制由 `content_entries/content_nodes/question_collections/practice_blueprints` 的 `accessRules` 合并决定；普通用户消耗 `practice_daily_usage`，事件写入 `practice_access_events`，SVIP/staff 不消耗免费额度。
- 批量导入当前支持题目、单词、知识手册、分数线、视频 JSON 预览、逐行 issue、job/item 台账、执行导入、幂等跳过，并可落到新内容入口、分类节点、分数线表或题目视频绑定。旧单词模板的 `vocabulary_units_示例数据` / `vocabulary_示例数据`、知识手册的书籍/章节/小节/知识点嵌套结构都由后端规范化。Excel/CSV 和大批量异步导入会继续复用同一套 `content_import_jobs` 管线。
+- 批量导入当前支持题目、单词、知识手册、分数线、视频 JSON/CSV/Excel 预览、逐行 issue、job/item 台账、同步执行或 `executionMode=async` 异步执行、幂等跳过，并可落到新内容入口、分类节点、分数线表或题目视频绑定。旧单词模板的 `vocabulary_units_示例数据` / `vocabulary_示例数据`、知识手册的书籍/章节/小节/知识点嵌套结构都由后端规范化。导入后复检、模板下载和字段映射 UI 后续补齐。

 ## 下一步

-1. 完善内容导入和文件上传：Excel/CSV 解析、大批量异步导入、导入后复检，PDF 预览渲染、防盗链、杀毒扫描和视频水印。
+1. 完善内容导入和文件上传：导入后复检、模板下载/字段映射 UI，PDF 预览渲染、防盗链、杀毒扫描和视频水印。
 2. 接入真实短信 provider：阿里云/腾讯云，密钥放 `app_private.tenant_secrets` 或生产 Vault。
 3. 接入真实 OAuth provider：微信网页、微信小程序、QQ，并处理旧 PocketBase 身份映射。
 4. 补完整资金流水对账、异常订单运营台和优惠券核销报表；支付/退款补偿、退款查询确认和退款通知主链路已完成。
@@ -269,5 +271,6 @@ npm run test:api
 npm run test:worker:crm
 npm run test:worker:commerce
 npm run test:worker:assets
+npm run test:worker:imports
 npm run check:refactor
 ```
--- a/docs/refactor/blueprint-coverage.md
+++ b/docs/refactor/blueprint-coverage.md
@@ -18,9 +18,9 @@
 | 平台超级管理员 | 部分完成 | 租户管理、SaaS 套餐、订阅、账单、服务费收款、用量记录 | 公共题库披露策略、地区/全国套餐权限、平台侧主题模板库、平台审计 |
 | 租户品牌和域名 | 基础完成 | 品牌、Logo、主题 JSON、公开资源、域名、租户公开配置 | 三套默认主题、主题可视化编辑、图标/图片上传 |
 | 租户成员权限 | 可联调 | owner/admin/operator/teacher/sales/agent/student，权限矩阵，成员启停，角色模板、菜单/模块/字段权限、班级/学生范围权限和审计查询 | 前端权限 UI、更细的数据范围组合 |
-| 题库内容维护 | 可联调 | 内容入口、任意深度分类树、院校/专业/学科/销售意向标记、题目集合、顺序/随机/全真模拟练习蓝图、题目录入/更新、题目/单词/知识手册/分数线/视频 JSON 预览导入、视频绑定、分数线、单词、知识手册后台 API、公共题库授权和采纳快照 | Excel/CSV 批量导入、公共题库版本同步、可视化拖拽排序前端 |
+| 题库内容维护 | 可联调 | 内容入口、任意深度分类树、院校/专业/学科/销售意向标记、题目集合、顺序/随机/全真模拟练习蓝图、题目录入/更新、题目/单词/知识手册/分数线/视频 JSON/CSV/Excel 预览导入、`executionMode=async` 导入 worker、视频绑定、分数线、单词、知识手册后台 API、公共题库授权和采纳快照 | 导入后复检、模板/字段映射、公共题库版本同步、可视化拖拽排序前端 |
 | 学生刷题 | 基础完成 | 内容入口、分类树、题目集合、顺序刷题、随机刷题、全真模拟 session 题目快照、答题、错题本、收藏夹、模考交卷评分报告、错题复习计划、排行榜 | 专项练习策略、题型统计深度分析、排行榜防刷/预聚合 |
-| 背单词 | 基础完成 | 单词单元、单词、进度、收藏、统计、每日复习计划、旧模板/新模板 JSON 预览导入、内容导航绑定、排行榜 | Excel 导入、更细复习参数 |
+| 背单词 | 基础完成 | 单词单元、单词、进度、收藏、统计、每日复习计划、旧模板/新模板 JSON/CSV/Excel 预览导入、内容导航绑定、排行榜 | 更细复习参数 |
 | 知识手册 | 基础完成 | 科目、章节、条目只读与后台维护、书籍/章节/小节/知识点嵌套 JSON 预览导入、内容导航绑定 | 富文本资源、版本管理、附件/PDF 关联、Excel/Markdown 批量解析 |
 | 分数线 | 可联调 | 字段、院校、专业、记录、趋势、年份、JSON 批量导入 | 复杂动态筛选、AI 择校数据上下文 |
 | 视频解析会员 | 可联调 | 题目视频、批量查询、后台绑定、视频 JSON 导入、SVIP 权限、播放次数扣减、签名 URL、播放日志 | 深度防盗链、动态水印、播放统计 |
@@ -36,7 +36,7 @@

 ## 接下来优先级

-1. 完善内容导入和对象存储：Excel/CSV 解析、大批量异步导入、导入后复检、CDN 防盗链、杀毒扫描和视频水印。
+1. 完善内容导入和对象存储：导入后复检、模板下载/字段映射 UI、CDN 防盗链、杀毒扫描和视频水印。
 2. 公共题库/地区题库授权：已完成披露和采纳快照；继续补版本同步、租户自改冲突处理和按 SaaS 套餐限制地区。
 3. 学习统计增强：排行榜防刷/预聚合、断点续练、专项练习策略和更细题型分析。
 4. 视频会员控制：深度防盗链、水印和播放统计。
--- a/docs/refactor/content-import-contract.md
+++ b/docs/refactor/content-import-contract.md
@@ -50,6 +50,59 @@ GET  /api/tenant-content/imports/issues
 - `content_import_issues`
 - `audit_logs`

+## 格式支持
+
+当前题目、单词、知识手册、分数线和视频导入均支持：
+
+- `sourceFormat=json`：直接提交规范 JSON 或兼容旧模板。
+- `sourceFormat=csv`：提交 `csvText`、`fileContent`、`payload` 或 `fileBase64`，后端按表头归一化。
+- `sourceFormat=excel`：提交 `.xlsx` 的 `fileBase64`，可选 `sheetName` 或 `sheetIndex`；多 Sheet 会被解析进同一个 `content_import_jobs`。
+- 同步导入默认在 API 请求内完成；大批量导入可在确认导入时传 `executionMode=async`，API 会把 job 置为 `pending`，由 imports worker 后台消费。
+
+表格导入安全边界：
+
+- 单文件最大 8MB。
+- 单次最多解析 5000 行、160 列。
+- 单个单元格最多保留 100000 字符。
+- 后端只保存解析后的原始行和规范化 payload，不把 `fileBase64` 长期写入数据库。
+- 任务列表会返回 `sourceFormat`、`executionMode` 和 `parserMetadata`，前端可展示解析器、Sheet、行数等信息。
+
+异步导入调用方式：
+
+```json
+{
+  "previewJobId": "uuid",
+  "executionMode": "async",
+  "allowPartial": false
+}
+```
+
+异步导入状态流：
+
+```text
+preview -> pending -> importing -> completed
+preview -> pending -> importing -> completed_with_errors
+preview -> pending -> failed
+```
+
+worker 命令：
+
+```bash
+npm --workspace @tiku-saas/worker run imports:once
+```
+
+前端提交异步导入后不要重复同步执行同一 job；只需要轮询 `GET /api/tenant-content/imports` 并用 `GET /api/tenant-content/imports/issues` 展示问题行。worker 会按 `attempt_count/max_attempts` 记录重试，失败时写入 `errorMessage` 和审计日志。
+
+推荐 CSV/Excel 表头：
+
+| 类型 | 常用表头 |
+| --- | --- |
+| 题目 | `legacyId`、`题型/type`、`题干/content`、`选项A`-`选项H`、`答案`、`解析`、`难度`、`标签` |
+| 单词 | `unitLegacyId`、`unitName`、`wordLegacyId`、`word`、`phonetic`、`meaning`、`example`、`difficulty`、`tags` |
+| 知识手册 | `subjectLegacyId`、`subjectName`、`chapterLegacyId`、`chapterName`、`sectionName`、`entryLegacyId`、`title`、`content`、`summary`、`tags` |
+| 分数线 | 多 Sheet 推荐 `fields`、`schools`、`majors`、`records`；记录 Sheet 可包含任意动态字段列 |
+| 视频 | `legacyId`、`title`、`videoUrl`、`thumbnailUrl`、`durationSeconds`、`subjectId`、`questionId` 或 `legacyQuestionId`、`accessMode` |
+
 ## 单词导入

 推荐新格式：
@@ -262,5 +315,5 @@ GET  /api/tenant-content/imports/issues

 ## 下一步

- 增加 Excel/CSV 解析入口，但解析后仍进入同一套 preview/import 管线。
- 增加异步 worker，处理大批量导入、重试和导入后校验。
+- 增加导入后校验/复检，确认导入行数、目标表记录、题目集合绑定和视频绑定一致。
+- 增加导入模板下载接口和后台可视化字段映射器。
--- a/docs/refactor/frontend-handoff-index.md
+++ b/docs/refactor/frontend-handoff-index.md
@@ -1,6 +1,6 @@
 # 前端交接索引

-更新时间：2026-06-28
+更新时间：2026-06-29

 这份文件是给 Taro/H5/小程序前端同事的入口。当前仓库的前端重构建议从 `apps/taro` 新建工程开始，不再把旧 React/Vite 前端搬回根目录继续开发。

@@ -45,7 +45,7 @@
 - 不要把“Supabase 支持前端 Data API”误解为“本项目所有业务表都由 Taro 直写”；订单、支付、权益、租户后台、导入、CRM、私有资源必须走 RPC、`apps/api`、Edge Function 或 worker 这类后端命令层。
 - 真实短信、微信登录、QQ 登录、微信支付、支付宝支付 provider 还未正式接完。
 - 对象存储已完成签名 provider、上传后校验、PDF/图片预览和资源复检 worker，但 CDN 防盗链、视频水印和杀毒扫描还要补。
- 分数线/视频 JSON 导入已可联调；大批量 Excel/CSV 解析和异步导入 worker 还未完成。
+- 题目/单词/知识手册/分数线/视频 JSON/CSV/Excel 导入已可联调；大批量导入可传 `executionMode=async` 交给 imports worker，前端还要补上传预览、排队轮询、问题行展示、模板下载和字段映射 UI。
 - 数据看板、分佣结算和勋章手动发放基础 API 已可联调；勋章自动发放、分佣真实打款/导出/凭证、AI 择校、主题模板市场等仍是后续商用增强项。

 ## 前后端协作建议
--- a/docs/refactor/implementation-status.md
+++ b/docs/refactor/implementation-status.md
@@ -4,7 +4,7 @@

 ## 当前结论

-当前重构已经完成了 Supabase/PostgreSQL 多租户底座、核心业务表、PocketBase 数据导入器雏形、学生端核心 API、租户后台 API、平台后台 SaaS 账务 API、内容资产/题目/单词/知识手册/分数线/视频 JSON 批量导入基础闭环、题库入口/任意深度分类/题目集合/练习蓝图/组卷快照基础闭环，以及本地 Docker/API 构建验证。
+当前重构已经完成了 Supabase/PostgreSQL 多租户底座、核心业务表、PocketBase 数据导入器雏形、学生端核心 API、租户后台 API、平台后台 SaaS 账务 API、内容资产/题目/单词/知识手册/分数线/视频 JSON/CSV/Excel 批量导入基础闭环、异步导入 worker、题库入口/任意深度分类/题目集合/练习蓝图/组卷快照基础闭环，以及本地 Docker/API 构建验证。

 但这还不是完整商用交付状态，也不能说旧项目核心功能已经全部重构完成。现在更准确的状态是：后端商用架构骨架已经立住，核心业务正在按模块补齐。部分功能已经有可调用 API，部分功能只有数据模型和导入映射，部分功能还没有前端/自动化测试闭环。

@@ -24,7 +24,7 @@
 | 模块 | 数据模型 | PocketBase 导入 | API | 自动化测试 | 当前状态 |
 | --- | --- | --- | --- | --- | --- |
 | 多租户隔离 | 已建 `tenants`、`tenant_domains`、`tenant_branding`、`tenant_settings`、RLS 基础 | 部分支持 | 租户解析、品牌、域名、支付账户、登录 provider、平台建租户已实现 | 核心 API 集成测试含租户隔离断言 | 基础可用，正式 JWT/RLS 权限闭环未完成 |
-| 刷题题库 | 已建题库、题目、题目版本、内容入口、任意深度分类树、考试意向标记、题目集合、练习蓝图、导入任务台账、公共题库授权/采纳表 | 已支持核心映射，JSON 导入可落到新入口/节点/集合 | 题目列表、内容入口、分类树、集合题目、顺序/随机/全真模拟 session、答题提交、租户后台题目录入/更新、JSON 预览/导入、平台公共题库授权、租户采纳快照已实现 | 核心 API 集成测试含导航、组卷、导入、公共题库授权和采纳后组卷断言 | 新题库导航和组卷基础闭环可跑，公共题库采纳快照可联调；Excel 导入、公共题库全量/增量版本同步仍需补齐 |
+| 刷题题库 | 已建题库、题目、题目版本、内容入口、任意深度分类树、考试意向标记、题目集合、练习蓝图、导入任务台账、公共题库授权/采纳表 | 已支持核心映射，JSON/CSV/Excel 导入可落到新入口/节点/集合 | 题目列表、内容入口、分类树、集合题目、顺序/随机/全真模拟 session、答题提交、租户后台题目录入/更新、JSON/CSV/Excel 预览/导入、异步导入 worker、平台公共题库授权、租户采纳快照已实现 | 核心 API 集成测试含导航、组卷、导入、公共题库授权和采纳后组卷断言 | 新题库导航和组卷基础闭环可跑，公共题库采纳快照可联调；公共题库全量/增量版本同步、导入后复检仍需补齐 |
 | 错题本 | 已建 `wrong_questions` | 已支持旧错题归一化 | 错题列表、答题自动入错题、移出错题已实现 | 仅烟测 | 基础功能已实现，复习计划和统计未完成 |
 | 收藏夹 | 已建 `favorite_questions` | 已支持旧收藏归一化 | 收藏/取消收藏、收藏列表已实现 | 仅烟测 | 基础功能已实现 |
 | 用户订阅/题库会员/SVIP | 已建 `orders`、`payments`、`entitlements`、`svip_plans`、激活码 | 已映射旧 SVIP/会员权益 | 下单、订单详情/状态轮询、手工支付确认权限保护、微信/支付宝支付、微信/支付宝发起退款、微信/支付宝退款查询确认、微信/支付宝退款通知 webhook、激活码预检查/兑换、优惠券抵扣、零元订单自动开通、权益查询已实现 | API 集成测试 | 商城主链路可联调，对账、支付补偿和异常订单自动处理待补 |
@@ -36,7 +36,7 @@
 | 个人中心 | 已建 `student_profiles`、会员权益、订单、练习记录、`badges/user_badges` | 已支持部分用户资料和勋章导入 | 个人资料、目标院校/专业、会员状态、最近练习、统计聚合、签到积分、题目反馈、考试倒计时、勋章 API 已实现 | API 集成测试 | 学生端基础个人中心已实现，账号绑定/换绑、学习报告可视化和更细任务系统待补 |
 | 活动/优惠 | 已建优惠券、激活码、激活码批次、banner、FAQ、公告、勋章等基础表 | 部分支持 | banner/FAQ/公告只读与租户后台维护、激活码预检查/兑换、激活码批次、批量生成激活码、优惠券维护、前台领取/下单抵扣、勋章维护和手动发放已实现 | 核心 API 集成测试 | 基础运营后台可用，勋章自动发放、复杂活动规则、营销自动化、核销报表待补 |
 | 销售/代理客资追踪 | 已建推荐码、首绑客资、团队关系、小程序码缓存、CRM 队列 | 旧 `referral_tracks` 已有映射基础 | 邀请码、扫码/分享事件、首绑保护、销售统计、客资明细、手动补绑、团队关系、CRM 配置/队列、CRM worker 推送已实现 | 核心 API 集成测试、CRM worker 集成测试 | 增长链路基础可用，真实微信小程序码、CRM 分配策略、富卡片和销售转化看板待补 |
-| 租户后台 | 已建品牌、域名、设置、支付账户、登录 provider、私密密钥表、成员、审计日志、资源台账、导入台账、内容导航台账 | 不适用 | 概览、品牌、设置、域名、支付账户、登录配置、密钥掩码、活动内容、兑换码/优惠券、成员管理、权限矩阵、审计查询、内容入口/分类树/题目集合/练习蓝图维护、资源管理、题目/单词/知识手册/分数线/视频 JSON 导入已实现 | 核心 API 集成测试含角色/权限/租户隔离/密钥不泄露/导航/组卷/资源与导入断言 | 租户配置与运营闭环可用，前端权限 UI、Excel/CSV 导入和大批量异步导入待补 |
+| 租户后台 | 已建品牌、域名、设置、支付账户、登录 provider、私密密钥表、成员、审计日志、资源台账、导入台账、内容导航台账 | 不适用 | 概览、品牌、设置、域名、支付账户、登录配置、密钥掩码、活动内容、兑换码/优惠券、成员管理、权限矩阵、审计查询、内容入口/分类树/题目集合/练习蓝图维护、资源管理、题目/单词/知识手册/分数线/视频 JSON/CSV/Excel 同步/异步导入已实现 | 核心 API 集成测试含角色/权限/租户隔离/密钥不泄露/导航/组卷/资源与导入断言 | 租户配置与运营闭环可用，前端权限 UI、导入后复检和字段映射操作台待补 |
 | 平台后台 | 已建 SaaS 套餐、订阅、账单、服务费、用量 | 不适用 | 租户管理、账单、收款确认、用量记录、平台管理员 Supabase JWT 鉴权已实现 | API 集成测试 | 平台收费链路骨架可用，平台审计报表/自动计费待补 |
 | 登录认证 | 已建短信验证码、会话、OAuth provider 配置表，并支持 `auth_user_id` 映射 | 旧用户映射已预留 | 短信 mock 登录、迁移期 session、Supabase JWT 验签映射、微信小程序登录主链路已实现 | API 集成测试 | H5 Supabase Auth 可联调；真实短信/微信网页/QQ 登录生产联调待补 |
 | 数据导入 | 已建立 importer、risk report、validate | 已覆盖多类旧集合 | 命令行导入/校验 | `pb:import:validate` | 基础工具可用，需用真实完整数据做多轮 dry-run |
@@ -268,7 +268,7 @@ platform-admin:
 1. 正式鉴权：API 已支持 Supabase Auth JWT；生产前继续做真实云端 Auth/JWKS 回归、RLS 深测，并关闭 `x-user-id`、`x-platform-admin-key` 兼容入口。
 2. 国内能力接入：短信、微信小程序登录、微信支付、支付宝支付、发起退款、退款查询确认和退款通知 webhook 的租户级配置入口与本地 provider 验证已具备；微信网页登录、QQ 登录、真实生产账号联调、对账和支付补偿仍需实现。
 3. 核心缺口 API：学生端个人中心、分数线、题目视频详情、背单词进度/收藏、签到积分、题目反馈和勋章已补基础 API；下一步重点是账号绑定、学习报告可视化、后台统计和真实业务验收。
-4. 后台能力：题库录入、题目/单词/知识手册/分数线/视频 JSON 批量导入、资源台账、视频绑定、知识手册维护、分数线维护、品牌/商户/登录/活动/兑换码配置、销售客资、CRM 队列、成员权限、审计查询已补 API；Excel/CSV 导入、大批量异步导入和前端操作台待补。
+4. 后台能力：题库录入、题目/单词/知识手册/分数线/视频 JSON/CSV/Excel 同步/异步批量导入、资源台账、视频绑定、知识手册维护、分数线维护、品牌/商户/登录/活动/兑换码配置、销售客资、CRM 队列、成员权限、审计查询已补 API；导入后复检、模板下载/字段映射和前端操作台待补。
 5. 自动化测试：已建立核心 API、租户隔离、权限矩阵、后台维护、资源/导入、微信/支付宝支付 webhook、优惠券/激活码/订单状态集成测试；仍需真实数据导入回归、退款对账和前端端到端测试。
 6. Taro 前端：建立 `apps/taro` 或等价跨端应用，把 H5 和小程序统一走同一套 API client。
 7. 运维交付：生产环境变量、备份恢复、日志监控、异常告警、数据库迁移流程、灰度发布、回滚预案。
@@ -277,7 +277,7 @@ platform-admin:

 为了先把旧项目核心业务补齐，再进入支付/短信等商用关键模块，建议按下面顺序继续：

-1. 完善内容导入和文件上传：Excel/CSV 解析、大批量异步导入、导入后复检、CDN 防盗链、杀毒扫描，并把 JSON 导入扩展为异步 worker。
+1. 完善内容导入和文件上传：导入后复检、模板下载/字段映射 UI、CDN 防盗链、杀毒扫描。
 2. 补公共题库版本同步 worker、租户套餐地区/科目/题库范围限制、主题模板系统。
 3. 补学习统计增强：排行榜防刷/预聚合、断点续练、专项练习策略和更细题型分析。
 4. 补视频商用控制：深度防盗链、动态水印和播放统计。
--- a/docs/refactor/legacy-feature-gap-matrix.md
+++ b/docs/refactor/legacy-feature-gap-matrix.md
@@ -58,7 +58,7 @@
 | 优惠券 | 已覆盖 | 后台配置、前台领取、同用户同券幂等、下单抵扣、全额优惠自动开通权益已有；复杂活动规则和核销报表待补 |
 | 激活码 | 已覆盖 | 批次、生成、预检查、兑换、自用码拒绝、地区校验主链路已有 |
 | 勋章管理 | 部分覆盖 | 后台勋章维护、手动发放、重复发放幂等、学生端勋章展示和权限隔离已覆盖；自动发放规则、积分活动联动和前端运营 UI 待补 |
-| 题库录入 | 已覆盖 | 单题创建/更新、题目/单词/知识手册/分数线/视频 JSON 导入、集合/蓝图已有；Excel/CSV 和异步大批量导入待补 |
+| 题库录入 | 已覆盖 | 单题创建/更新、题目/单词/知识手册/分数线/视频 JSON/CSV/Excel 同步/异步导入、集合/蓝图已有；导入后复检、模板下载和字段映射 UI 待补 |
 | 题库导出 PDF/Word/JSON | 未覆盖 | 旧前端有导出组件；新后端需决定服务端导出、导出水印和权限审计 |
 | 题型分组/模拟卷配置 | 部分覆盖 | question_type_groups 表和 blueprint 有基础；后台配置体验待补 |
 | 背单词维护 | 已覆盖 | 单元/单词 CRUD 和导入已有 |
@@ -98,7 +98,7 @@
 1. 排行榜增强：刷题、模考、背单词、积分排行榜主接口已有；还需防刷、日/周榜预聚合、运营后台排名看板。
 2. 账号设置完整流：头像上传、绑定/更换手机号、微信/QQ 账号合并、密码/邮箱能力。
 3. 题库导出：PDF/Word/JSON 导出、水印、导出审计和权限控制。
-4. 导入扩展：分数线/视频 JSON 导入已补齐；仍缺 Excel/CSV 解析、大批量异步 worker 和导入后复检。
+4. 导入扩展：题目/单词/知识手册/分数线/视频已支持 JSON、CSV 和 Excel 预览导入，并可用 `executionMode=async` 进入 imports worker；仍缺导入后复检和模板下载/字段映射 UI。
 5. 公共题库商业化：平台公共/地区题库授权和租户快照采纳已完成基础闭环；还需版本同步、租户自改冲突处理和运营后台 UI。
 6. CRM/销售结算：CRM worker、分佣规则、结算单、审核和打款状态基础闭环已完成；仍缺轮询/定向分配、打款导出、凭证和销售结算看板。
 7. 题目反馈增强：处理通知、消息提醒、问题聚合统计和内容修复闭环。
@@ -117,7 +117,7 @@

 1. 微信/支付宝支付和 webhook 幂等。
 2. 对象存储 PDF 预览、视频深度防盗链、动态水印。
-3. Excel/CSV 解析、大批量异步导入和导入后复检。
+3. 导入后复检、模板下载和字段映射 UI。
 4. 数据看板预聚合 worker、销售/代理转化看板和分佣结算。
 5. 公共题库版本同步、租户采纳后的更新策略和同步 worker。

--- a/docs/refactor/next-development-todo.md
+++ b/docs/refactor/next-development-todo.md
@@ -16,7 +16,7 @@
 - 练习组卷：`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 预览、校验、导入、幂等、审计。
+- 内容导入：题目、单词、知识手册、分数线、视频 JSON/CSV/Excel 预览、校验、导入、幂等、审计。
 - 租户组织范围：班级、班级成员、教师/班主任/助教/学生分组，教师按负责班级查看学生，字段权限可脱敏学生手机号。
 - 学生运营管理：学生批量 upsert、禁用/恢复、批量分班、备注、跟进任务已完成接口和集成测试；后续补批量 CRM 推送和自动学习督导。
 - 旧题库运营缺口已补一批：考试日期/倒计时、题目反馈/纠错处理、每日签到积分和积分流水、学习排行榜已完成接口和集成测试。
@@ -75,9 +75,9 @@
   - 旧 PocketBase 用户账号和新身份体系的映射/补绑。

 3. 导入体系扩展
-   - Excel/CSV 导入。
-   - 分数线/视频导入已完成 JSON preview/import；继续补 Excel/CSV 到规范 JSON 的解析适配。
-   - 大批量导入异步 worker、重试、导入后校验。
+   - 已完成题目、单词、知识手册、分数线、视频的 CSV/Excel 到规范 JSON 解析适配。
+   - 继续补大批量导入异步 worker、重试、导入后校验。
+   - 继续补模板下载、字段映射 UI 和导入前抽样校验。

 4. 公共题库和租户授权
   - 已完成平台公共题库/地区题库的基础授权、租户采纳和题目快照复制。
@@ -206,5 +206,5 @@
 2. 云服务器部署 Supabase/PostgreSQL 和 API，配置对象存储生产环境变量，跑 `check:refactor` 的远程等价测试。
 3. 导出现有 PocketBase 数据，做完整 dry-run 迁移。
 4. 开始 `apps/taro`，先接租户解析、首页、题库、背单词、知识手册。
-5. 并行补对象存储、真实登录、完整资金流水对账和公共题库版本同步 worker。
+5. 并行补对象存储、真实登录、完整资金流水对账、题库导出和公共题库版本同步 worker。
 6. 前后端联调通过后，再做支付、权限、数据导入、资料下载、视频播放的商用验收。
--- a/docs/refactor/taro-frontend-integration.md
+++ b/docs/refactor/taro-frontend-integration.md
@@ -713,7 +713,7 @@ content_entries

 ## 租户内容导入对接

-租户后台导入统一使用 preview -> issues -> import 流程，前端不要直接写 Supabase 表或绕过 `apps/api`。
+租户后台导入统一使用 preview -> issues -> import 流程，前端不要直接写 Supabase 表或绕过 `apps/api`。当前 JSON、CSV 和 Excel 都进入同一套后端规范化、逐行 issue、幂等和审计管线。

 当前可联调：

@@ -734,14 +734,63 @@ GET  /api/tenant-content/imports/issues

 前端流程：

-1. 上传或粘贴 JSON，先调用对应 preview。
+1. 上传或粘贴 JSON/CSV/Excel，先调用对应 preview。
 2. 展示 `job.totalCount/validCount/errorCount/warningCount`。
-3. 展示逐行 `issues`，错误行必须让运营修正；如果后端允许 `allowPartial`，也要二次确认。
-4. 用户确认后调用 import；导入完成后刷新内容列表、分数线列表或题目视频列表。
+3. 展示 `job.sourceFormat`、`job.parserMetadata`、逐行 `issues`，错误行必须让运营修正；如果后端允许 `allowPartial`，也要二次确认。
+4. 小批量确认后直接调用 import；大批量确认时传 `executionMode=async` 排队，前端轮询 job 状态。
+5. 导入完成后刷新内容列表、分数线列表或题目视频列表。
+
+CSV 请求示例：
+
+```json
+{
+  "sourceFormat": "csv",
+  "sourceName": "questions.csv",
+  "csvText": "legacyId,题型,题干,选项A,选项B,答案\nq1,choice,题干,A,B,B",
+  "subjectId": "...",
+  "categoryId": "...",
+  "entryId": "...",
+  "contentNodeId": "...",
+  "collectionId": "..."
+}
+```
+
+Excel 请求示例：
+
+```json
+{
+  "sourceFormat": "excel",
+  "sourceName": "scoreline.xlsx",
+  "fileBase64": "<xlsx base64>",
+  "sheetName": "records",
+  "regionId": "..."
+}
+```
+
+异步确认导入示例：
+
+```json
+{
+  "previewJobId": "uuid",
+  "executionMode": "async",
+  "allowPartial": false
+}
+```
+
+异步导入状态：
+
+```text
+pending/importing：展示处理中，不允许重复同步执行同一 job。
+completed：刷新目标内容列表。
+completed_with_errors：刷新成功内容，并提示查看 issues。
+failed/rejected：展示 errorMessage 和 issues，允许运营修正后重新 preview。
+```
+
+前端文件限制应与后端一致：单文件最大 8MB，最多 5000 行、160 列。后端不会保存原始 `fileBase64`，但前端仍不要把含隐私的导入文件写入长期缓存。

 分数线导入前端注意：

- 后端支持 `fields/schools/majors/records` 分桶，也支持 `items` 列表。
+- 后端支持 `fields/schools/majors/records` 分桶，也支持 `items` 列表；Excel 可用 `fields`、`schools`、`majors`、`records` 多 Sheet。
 - 页面筛选字段仍以 `/api/scoreline/fields` 为准，不要从导入 JSON 临时生成筛选 UI。
 - `record` 至少需要 `schoolId`、`schoolLegacyId` 或 `schoolName`，否则 preview 会返回 issue。

@@ -1081,7 +1130,7 @@ ACTIVATION_CODE_REGION_MISMATCH
 - 角色模板：`GET/PUT /api/tenant-admin/role-templates`、`POST /api/tenant-admin/role-templates/disable`
 - 内容入口/分类树/题目集合/练习蓝图
 - 题目/单词/知识手册/分数线/视频维护
- 题目/单词/知识手册/分数线/视频 JSON 导入 preview/import/issues
+- 题目/单词/知识手册/分数线/视频 JSON/CSV/Excel 导入 preview/import/issues
 - Banner/FAQ/公告/激活码/优惠券
 - 勋章：`GET/PUT /api/tenant-admin/badges`、`GET/POST /api/tenant-admin/badge-grants`
 - 考试日期：`GET/PUT /api/tenant-admin/exam-dates`