topuser
/
nuxt4-demo
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
212 Commits
3 Branches
2 Tags
122 MiB
 
 
 
 
 
Tree: c8b96b2e8c
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'c8b96b2e8c'
${ noResults }
nuxt4-demo/docs/export-feature-recheck-2026...

5.1 KiB
Raw Blame History

导出功能复核与开发指引（2026-04-24）

1. 文档目的

本文件用于后续迭代开发时快速理解“用户数据导出”功能的当前实现状态、行为边界与已知风险，避免重复摸索。

2. 复核范围

本次复核覆盖：

  • 后端 API：创建 / 列表 / 下载 / 删除
  • 服务层：任务状态机、任务删除与目录清理、导出执行流程
  • 导出产物：data/、files/、manifest.json
  • 前端导出中心交互：创建、刷新、下载、删除、重新导出
  • 关键测试可执行性

3. 关键代码位置

  • API
    • server/api/me/export/request.post.ts
    • server/api/me/export/tasks.get.ts
    • server/api/me/export/tasks/[id]/download.get.ts
    • server/api/me/export/tasks/[id].delete.ts
  • 服务层
    • server/service/export/jobs.ts
    • server/service/export/run.ts
    • server/service/export/build-data.ts
    • server/service/export/build-files.ts
    • server/service/export/build-manifest.ts
  • 前端
    • app/pages/me/export/index.vue
    • app/types/export.ts
  • 测试
    • server/service/export/jobs.test.ts
    • server/service/export/build-manifest.test.ts
    • server/utils/me-export-request-body.test.ts

4. 当前功能状态（复核结论）

4.1 已实现并可用

  • 任务生命周期

    • 支持 queued -> running -> succeeded/failed/expired
    • 同一用户存在 queued/running 任务时，禁止再次创建（409）

  • 导出产物构建

    • 导出目录结构：
      • manifest.json
      • data/*.json
      • files/*
    • manifest 包含：
      • schemaVersion
      • exportedAt/exportCutoffAt
      • maskPolicy
      • stats
      • checksums.data/files

  • 下载完整包

    • 下载接口返回完整压缩包（tar.gz）
    • 通过 tar -czf - 流式返回，不落地额外压缩文件

  • 任务列表自愈

    • 刷新任务列表时会检查已完成任务的导出文件可用性
    • 缺失/过期会自动标记为 expired 并写入错误信息

  • 任务删除

    • DELETE /api/me/export/tasks/:id
    • 非 running 任务可删
    • 删除时尝试清理对应 .tmp/exports 目录，并做路径边界保护

  • 前端交互

    • 支持创建、刷新、下载、删除
    • expired 任务显示“重新导出”按钮

5. 实测结果（本地复核）

执行命令：

bun test server/service/export/jobs.test.ts
bun test server/service/export/build-manifest.test.ts
bun test server/utils/me-export-request-body.test.ts

结果：

  • server/service/export/jobs.test.ts：通过（12 pass）
  • server/service/export/build-manifest.test.ts：通过（1 pass）
  • server/utils/me-export-request-body.test.ts：失败（Cannot find package 'h3'）

6. 已知问题与风险

R1（中）：me-export-request-body 单测依赖问题

  • 现象：测试环境无法解析 h3，导致 server/utils/me-export-request-body.test.ts 失败。
  • 影响：该 util 的单测在当前环境不稳定，CI/新开发机可能复现。
  • 建议：
    • 方案 A：me-export-request-body.ts 改为抛项目通用错误对象（{ statusCode, statusMessage }），不直接依赖 h3。
    • 方案 B：明确把 h3 作为可解析依赖并固定版本，确保测试环境一致。

R2（中）：下载包格式依赖系统 tar

  • 当前下载使用子进程 tar 打包，依赖运行环境存在 tar 命令。
  • 建议：
    • 在部署文档里明确依赖项；
    • 或改为 Node 库打包，避免系统命令依赖。

R3（中）：下载失败时状态修正为 expired 的语义边界

  • 当前将“文件缺失/打包失败/过期”统一落到 expired。
  • 建议：
    • 若需更细粒度运维排障，可新增状态或错误码区分（如 EXPORT_MISSING、EXPORT_PACKAGE_FAILED）。

7. 对外接口行为（当前版本）

7.1 创建任务

  • POST /api/me/export/request
  • body：{ "maskPolicy": "masked" | "raw" }（可省略，默认 masked）
  • 返回：taskId, status

7.2 获取任务列表

  • GET /api/me/export/tasks
  • 返回当前用户任务
  • 返回前会自动做“已完成任务文件存在性检查”，必要时改为 expired

7.3 下载任务产物

  • GET /api/me/export/tasks/:id/download
  • 仅允许下载本人且 succeeded 的任务
  • 返回完整 tar.gz 包
  • 常见错误：
    • 409：任务未完成
    • 410：任务过期或文件丢失（并同步标记为 expired）

7.4 删除任务

  • DELETE /api/me/export/tasks/:id
  • 仅允许删除本人任务
  • running 任务返回 409

8. 后续开发建议（按优先级）

  1. 修复 R1：先解决 h3 解析导致的单测不稳定。
  2. 补 API 级测试：增加 request/tasks/download/delete 的集成测试。
  3. 下载格式可配置：支持 zip（前端兼容性更好）或可选 tar.gz/zip。
  4. 导出清理任务：增加后台任务，定期清理已过期目录与旧任务数据。
  5. 更细状态与错误码：提高运维可观测性。

9. 最终结论

  • 功能可用性：通过（可用于后续开发迭代）
  • 工程稳定性：有条件通过（需优先修复 R1）