Compare commits

...
Author SHA1 Message Date
Lan 1ec397af0c test: add presigned upload flow coverage 2026-06-07 14:43:04 +08:00
5 changed files with 1527 additions and 0 deletions

No files matched your search

+196
View File
@@ -0,0 +1,196 @@
# 本轮开发交付报告
生成日期:2026-06-06
本文档记录 `feature/development-plan` 分支本轮开发完成情况、验证结果和后续处理建议。
## 分支状态
当前工作区包含两个独立 Git 仓库,均已切换到本轮开发分支:
- 后端仓库:`FileCodeBox`
- 前端仓库:`FileCodeBoxFronted`
- 当前分支:`feature/development-plan`
本轮变更尚未提交。
## 开发目标
本轮目标是根据 `docs/development-plan.md` 完成下一阶段的优先开发项:
1. 补齐取件文件预览链路。
2. 建立前端最小测试体系。
3. 加固后端预签名上传回归测试。
4. 区分前端检查脚本和自动修复脚本。
5. 拆分管理文件模块的部分纯函数、状态逻辑和批量操作 UI。
## 完成范围
### P0:取件文件预览链路
已在取件页完成文件预览接线:
- `RetrievewFileView.vue` 绑定文件详情弹窗的 `preview-file` 事件。
- 取件页渲染并控制 `MediaPreviewModal`。
- 取件详情中的可预览文件现在可以打开媒体预览弹窗。
### P0:前端最小测试体系
已建立 Vitest 测试基础:
- 新增 `vitest.config.ts`。
- 新增 `package.json` 的 `test` 脚本。
- 引入 `vitest`、`@vue/test-utils`、`jsdom` 等测试依赖。
- 更新 `pnpm-lock.yaml`。
首批测试覆盖:
- 文件类型规则。
- 下载动作解析。
- 内容预览处理。
- 发送记录工具逻辑。
- 预签名上传相关流程。
- 上传策略分支。
- 管理文件摘要、视图预设和批量选择逻辑。
### P1:后端上传回归加固
已补充后端预签名上传流程测试:
- 新增 `tests/conftest.py`,固定测试导入路径。
- 新增 `tests/test_presign_upload_flow.py`。
覆盖场景包括:
- `init` 直传模式。
- `init` 代理上传模式。
- `confirm` 成功创建文件记录。
- `confirm` 拒绝缺失的直传文件。
- `proxy` 上传大小不一致校验。
- `cancel` 取消并清理已上传对象。
- 过期上传会话自动删除并拒绝继续操作。
### P1:质量脚本调整
已区分自动修复和只检查命令:
```json
{
"lint": "eslint . --fix",
"lint:check": "eslint ."
}
```
同时,架构检查脚本已忽略测试文件,避免测试代码影响前端分层规则检查。
### P2:管理文件模块拆分
已完成第一轮低风险拆分:
- 新增 `admin-file-view-preset.ts`,承载管理文件视图预设规则。
- 新增 `admin-file-summary.ts`,承载管理文件摘要计算逻辑。
- 新增 `useAdminFileSelection.ts`,承载批量选择状态逻辑。
- 新增 `AdminBatchActionBar.vue`,承载管理页批量操作栏 UI。
- `FileManageView.vue` 已接入新的批量操作栏组件。
本轮拆分优先处理纯函数和单一职责状态逻辑,避免一次性重构整个管理页。
## 关键设计决策
1. 优先补用户可见断点,再推进模块拆分。
2. 先给工具函数和 composable 补测试,再扩大重构范围。
3. `lint` 保留自动修复语义,新增 `lint:check` 用于 CI 和人工验证。
4. 管理文件页拆分采用渐进方式,每次只抽离职责清晰、影响边界可控的模块。
5. 后端上传测试使用替身对象和临时状态,避免依赖真实网络、真实 S3 或污染运行数据目录。
## 验证记录
本轮已完成以下验证:
```bash
cd FileCodeBoxFronted
pnpm test
pnpm check:architecture
pnpm type-check
pnpm lint:check
pnpm build
cd ../FileCodeBox
pytest
git diff --check
```
验证结果:
- 前端 `pnpm test`:9 files / 27 tests passed。
- 前端 `pnpm check:architecture`:通过。
- 前端 `pnpm type-check`:通过。
- 前端 `pnpm lint:check`:通过。
- 前端 `pnpm build`:通过。
- 后端 `pytest`:21 passed,仅存在 Tortoise ORM deprecation warnings。
- 前后端 `git diff --check`:通过。
## 当前未提交文件
### 后端仓库
新增文件:
- `docs/development-plan.md`
- `docs/development-delivery-report.md`
- `tests/conftest.py`
- `tests/test_presign_upload_flow.py`
### 前端仓库
修改文件:
- `package.json`
- `pnpm-lock.yaml`
- `scripts/check-architecture.mjs`
- `src/composables/useAdminFiles.ts`
- `src/composables/useSendFlow.ts`
- `src/utils/download-action.ts`
- `src/views/RetrievewFileView.vue`
- `src/views/manage/FileManageView.vue`
- `tsconfig.app.json`
新增文件:
- `src/components/common/AdminBatchActionBar.vue`
- `src/composables/useAdminFileSelection.ts`
- `src/composables/useAdminFileSelection.test.ts`
- `src/composables/usePresignedUpload.test.ts`
- `src/services/upload-strategy.test.ts`
- `src/utils/admin-file-summary.ts`
- `src/utils/admin-file-summary.test.ts`
- `src/utils/admin-file-view-preset.ts`
- `src/utils/admin-file-view-preset.test.ts`
- `src/utils/content-preview.test.ts`
- `src/utils/download-action.test.ts`
- `src/utils/file-type.ts`
- `src/utils/file-type.test.ts`
- `src/utils/send-record.test.ts`
- `vitest.config.ts`
## 后续建议
1. 提交前再次执行前后端验证命令,确保工作区未被其他改动影响。
2. 分别在两个仓库创建提交,避免跨仓库状态混淆。
3. 下一轮继续拆分管理文件模块时,优先处理筛选栏、详情侧栏和元数据编辑逻辑。
4. 后端可继续补充 `allowed_file_types`、S3 `file_exists` 降级、主题资源路径穿越保护等测试。
## 推荐提交信息
后端仓库:
```bash
git commit -m "test: add presign upload flow coverage"
```
前端仓库:
```bash
git commit -m "feat: add retrieve preview and frontend tests"
```
+211
View File
@@ -0,0 +1,211 @@
# 下一步开发计划
本文档记录 FileCodeBox 下一阶段开发优先级、并行拆分方式、验收标准和质量门禁。
## 背景
当前工作区包含两个独立仓库:
- `FileCodeBox`:FastAPI 后端,包含接口、存储、管理后台 API、文档和后端测试。
- `FileCodeBoxFronted`:Vue 3 + Vite 前端,包含公开取件/发件页和管理后台界面。
近期提交主要集中在 S3 存储、取件码归一化、文件类型限制、主题资源加载、前端管理页和上传下载体验。
下一阶段应优先处理用户可见断点和自动化回归保护,再推进大模块拆分。
## 优先级总览
### P0:补齐取件文件预览链路
目标:打通前端已存在但尚未完整接线的文件预览能力。
涉及模块:
- `RetrievewFileView.vue`
- `FileDetailModal.vue`
- `MediaPreviewModal.vue`
- `useRetrieveFlow.ts`
主要工作:
1. 在取件详情弹窗中绑定文件预览事件。
2. 在取件页渲染媒体预览弹窗。
3. 确认图片、视频、音频、PDF 等可预览文件能正常打开。
4. 保持关闭、下载、错误提示等状态行为一致。
验收标准:
```bash
pnpm check:architecture
pnpm build
```
手工验收:
1. 上传非文本文件并获取取件码。
2. 取件后打开详情弹窗。
3. 点击预览,确认弹窗可打开。
4. 确认关闭和下载动作正常。
### P0:建立最小前端测试体系
目标:为核心前端流程建立可持续的自动化回归保护。
现状:
- 前端暂无测试目录。
- `package.json` 中暂无 `test` 脚本。
- 最近改动涉及上传、下载、Markdown 预览、配置表单等高风险路径。
建议引入:
```bash
vitest
@vue/test-utils
jsdom
```
首批测试范围:
- 文件类型限制规则。
- 过期时间限制校验。
- Markdown 渲染和 HTML 清洗。
- 下载动作解析。
- 预签名上传与分片上传提交分支。
验收标准:
```bash
pnpm test
```
要求:
- 测试能在 60 秒内完成。
- 核心工具函数至少具备首批单元测试。
- 测试脚本不修改源码文件。
### P1:后端上传与存储回归加固
目标:把近期修复沉淀为后端测试,降低存储和上传链路回归风险。
涉及模块:
- `apps/base/views.py`
- `core/storage.py`
- `main.py`
- `tests/`
优先测试场景:
1. 预签名上传 `init` / `confirm` / `cancel`。
2. 代理上传文件大小校验。
3. `allowed_file_types` 的扩展名、MIME、通配规则。
4. S3 `file_exists` 的 `head_object` 失败降级逻辑。
5. 主题资源路径穿越保护。
验收标准:
```bash
pytest
```
要求:
- 测试使用临时目录和替身对象,避免污染 `data/`。
- 外部存储相关测试不依赖真实网络或真实 S3。
- 异常路径和边界值必须覆盖。
### P1:调整质量脚本
目标:区分“检查”和“自动修复”,避免 CI 或验证命令改写源码。
当前问题:
```json
"lint": "eslint . --fix"
```
建议调整:
```json
{
"lint": "eslint . --fix",
"lint:check": "eslint ."
}
```
推荐前端验证顺序:
```bash
pnpm check:architecture
pnpm type-check
pnpm lint:check
pnpm test
pnpm build
```
### P2:拆分管理文件模块
目标:降低管理文件页面和业务 composable 的维护复杂度。
现状:
- `FileManageView.vue` 体量较大。
- `useAdminFiles.ts` 同时承载列表、筛选、视图预设、批量操作、详情、元数据、下载和预览等职责。
拆分顺序:
1. 抽纯函数:筛选参数归一化、视图预设归一化、摘要计算、详情视图模型转换。
2. 抽 composable:批量操作、详情弹窗、元数据编辑、视图预设。
3. 抽 UI 子组件:批量工具栏、筛选栏、详情侧栏、预设选择器。
约束:
- 每次只拆一块。
- 拆分前后行为保持一致。
- 先给纯函数补测试,再推进 UI 拆分。
## 并行开发安排
第一轮可并行拆分为四个互不冲突的任务:
1. 前端 A:接线取件文件预览。
2. 前端 B:搭建 Vitest 与首批工具函数测试。
3. 后端 C:补充上传和存储回归测试。
4. 工程 D:新增 `lint:check` 并整理验证命令。
合并前统一验证:
```bash
cd FileCodeBoxFronted
pnpm check:architecture
pnpm type-check
pnpm lint:check
pnpm test
pnpm build
cd ../FileCodeBox
pytest
```
## 质量门禁
每个开发任务完成时必须记录:
- 改动范围。
- 关键设计决策。
- 执行过的验证命令。
- 未覆盖风险和后续事项。
涉及上传、删除、存储、认证、配置等功能时,必须补充异常路径测试。
## 推荐执行顺序
1. 先完成 P0 的取件预览接线。
2. 同步建立前端最小测试体系。
3. 补齐后端上传和存储回归测试。
4. 调整前端质量脚本。
5. 等测试保护到位后,再拆分管理文件模块。
结论:下一阶段以“取件预览接线 + 测试体系建设”为主线,先修用户可见断点,再提升长期维护质量。
+843
View File
@@ -0,0 +1,843 @@
# 功能与用户体验提升规划
生成日期:2026-06-06
本文档承接 `development-plan.md` 和 `development-delivery-report.md`,用于规划下一轮“功能增强 + 用户体验提升”开发。重点不是重做界面,而是让发送、取件和管理流程更清楚、更可恢复、更适合反复使用。
## 当前基线
当前工作区包含两个独立仓库:
- `FileCodeBox`:FastAPI 后端,提供分享、取件、分片上传、预签名上传、管理后台、配置和本地文件管理接口。
- `FileCodeBoxFronted`:Vue 3 + Vite 前端,提供公开取件页、发件页、登录页、管理仪表盘、文件管理和系统设置。
本轮已完成的基础能力:
- 取件文件预览链路已接通。
- 前端 Vitest 测试体系已建立。
- 后端预签名上传流程已有回归测试。
- 管理文件页已抽出部分纯函数、批量选择逻辑和批量操作栏。
下一轮应把重点从“能用”推进到“好用、稳定、可解释”。
## 体验目标
1. 发送流程要让用户明确知道当前文件是否可发、发到哪一步、失败后如何继续。
2. 取件流程要避免误消耗取件次数,先展示文件摘要,再由用户确认下载或预览。
3. 管理后台要提高高频操作效率,减少大页面内工具堆叠和重复确认成本。
4. 所有危险操作要有清晰影响范围,避免误删、误批量修改和不可逆操作。
5. 错误提示要从“发生错误”升级为“原因 + 可执行下一步”。
## 规划依据
本轮规划基于前后端只读审阅结果:
- 前端主流程已完整,但取件前确认、上传取消/重试、发送成功结果区和后台强确认仍不足。
- 后端接口能力较全,但取件扣次数、下载票据、预签名直传确认、错误响应和审计追踪仍需要加固。
- 下一轮应优先处理“安全边界 + 关键路径体验”,再扩展管理效率和长期产品能力。
## P0:取件扣次数与下载票据一致性
目标:确保取件次数只在真实授权动作中消耗,并且旧下载地址不能绕过过期或次数限制。
### 现状问题
- `/share/select/` 当前会调用 `update_file_usage()`,取件前缺少确认时容易误消耗次数。
- `/share/download` 使用 `check=False` 获取文件记录,已生成的下载地址存在被继续复用的窗口。
- 下载票据由 `get_select_token()` 生成,缺少明确的短期过期语义和服务端状态绑定。
### 建议实现
1. 将“查看元数据”和“确认取件授权”严格分离。
2. 为确认取件生成短期下载票据:
- 票据绑定取件码。
- 票据包含过期时间。
- 票据校验时重新检查文件是否过期、次数是否耗尽。
3. 并发场景下保证 `expired_count=1` 只能成功一次。
4. 下载接口拒绝已过期、次数耗尽或票据失效的请求。
5. 响应中明确返回剩余次数和下一步动作。
### 涉及模块
- `apps/base/views.py`
- `core/utils.py`
- `apps/base/models.py`
- `tests/`
### 数据模型影响
第一阶段可先使用签名票据,不强制新增表。
如果要做更完整审计,后续新增:
- `DownloadTicket`
- `FileAccessLog`
### 验收标准
1. 元数据查询不消耗下载次数。
2. 确认取件后才消耗次数并返回下载票据。
3. `expired_count=1` 并发取件时只能成功一次。
4. 旧下载地址在文件过期或次数耗尽后不可继续下载。
5. 后端测试覆盖票据过期、次数耗尽和并发边界。
## P0:公开取件体验升级
目标:取件码输入后先确认内容,再执行会消耗次数的取件动作。
### 现状问题
- `RetrievewFileView.vue` 在取件码长度达到 5 位时直接调用 `handleSubmit()`。
- `handleSubmit()` 调用 `/share/select/`,会执行 `update_file_usage()`,可能消耗下载次数。
- `useRetrieveFlow.ts` 已有 `inspectCode()` 和 `inspectedFile`,但页面当前未形成完整的“预检查确认”体验。
### 建议实现
1. 输入 5 位取件码后调用 `inspectCode()`,请求 `/share/metadata/`。
2. 页面展示文件摘要卡片:
- 文件名或文本类型。
- 文件大小。
- 过期时间。
- 剩余下载次数。
- 是否可预览。
3. 用户点击“取件”后再调用 `handleSubmit()`。
4. 如果文件已过期或次数耗尽,直接展示不可取原因,不再进入下载动作。
5. 查询参数 `?code=xxxxx` 进入页面时,也走同样的预检查流程。
6. 与服务端下载票据机制配合,确认取件后再获得可下载地址。
### 涉及模块
- `RetrievewFileView.vue`
- `RetrieveForm.vue`
- `useRetrieveFlow.ts`
- `FileDetailModal.vue`
- `download-action.ts`
- `src/i18n/locales/zh-CN.ts`
- `src/i18n/locales/en-US.ts`
### 验收标准
```bash
cd FileCodeBoxFronted
pnpm test
pnpm check:architecture
pnpm type-check
pnpm lint:check
pnpm build
```
手工验收:
1. 输入有效取件码,只展示摘要,不立即消耗下载次数。
2. 点击确认取件后,才新增取件记录并打开详情或预览。
3. 输入过期取件码时展示明确原因。
4. 从 `?code=xxxxx` 访问时能自动展示摘要。
## P0:发送结果页增强
目标:发送成功后让用户更快完成复制、分享、复查和再次发送。
### 现状问题
- `useSendFlow.ts` 发送成功后会自动复制链接并打开记录详情。
- 用户能看到结果,但结果区域更像历史详情,不像一次明确的“发送完成”状态。
- 多文件、文本、单文件的结果反馈可以更聚焦。
### 建议实现
1. 新增发送成功结果面板,替代只依赖记录详情弹窗:
- 取件码大号展示。
- 一键复制取件码。
- 一键复制链接。
- 二维码展示入口。
- 重新发送按钮。
2. 明确自动复制结果:
- 复制成功展示“链接已复制”。
- 复制失败展示“请手动复制”。
3. 多文件上传成功后展示文件数量和压缩包/批量记录说明。
4. 文本发送成功后提供“预览文本”和“复制原文”。
### 涉及模块
- `SendFileView.vue`
- `SentRecordDetailModal.vue`
- `SentRecordList.vue`
- `useSendFlow.ts`
- `sent-record-actions.ts`
- `send-record.ts`
### 验收标准
1. 单文件、文本、多文件发送成功后都有明确完成态。
2. 复制取件码、复制链接、二维码入口可用。
3. 发送成功后再次选择文件或文本不会残留上一次进度。
4. 自动复制失败时有人工复制路径。
## P0:上传失败恢复与取消
目标:上传过程可中断、可重试、可解释。
### 现状问题
- 前端已有上传进度、速度和预签名上传封装。
- 用户在上传中无法主动取消。
- 失败后缺少保留文件并重试的明确路径。
- 预签名上传会话存在后端取消接口,但前端体验还可以更完整。
### 建议实现
1. 上传中展示取消按钮。
2. 取消时调用对应取消逻辑:
- 预签名上传:`DELETE /presign/upload/{upload_id}`。
- 分片上传:`DELETE /chunk/upload/{upload_id}`。
3. 失败后保留已选择文件,提供“重试”按钮。
4. 错误提示按类型分层:
- 文件过大。
- 文件类型不允许。
- 网络中断。
- 服务端拒绝。
- 上传会话过期。
5. 上传过程中离开页面时提示用户确认。
### 涉及模块
- `FileUploadArea.vue`
- `SendFileView.vue`
- `useSendFlow.ts`
- `useSendSubmit.ts`
- `usePresignedUpload.ts`
- `upload-strategy.ts`
- `FileService`
### 验收标准
1. 上传中可以取消,后端临时会话或分片状态被清理。
2. 网络失败后可以直接重试,不需要重新选择文件。
3. 取消上传后进度归零,按钮状态恢复。
4. 页面跳转或关闭前有上传中提示。
## P0:预签名直传确认加固
目标:直传文件确认不只检查“对象存在”,还要确认大小、状态和失败原因。
### 现状问题
- `presign_upload_confirm()` 当前主要依赖 `file_exists()`。
- 直传对象大小不符、上传中断、对象异常时,服务端难以给出准确原因。
- `PresignUploadSession` 当前缺少状态字段,前端只能通过接口错误推断上传阶段。
### 建议实现
1. 存储接口增加对象元信息读取能力:
- `stat_file(save_path)`
- 返回是否存在、实际大小、更新时间和存储后端错误。
2. `presign_upload_confirm()` 校验实际大小与声明大小一致。
3. 上传会话状态响应补充原因:
- `pending`
- `uploading`
- `uploaded`
- `confirmed`
- `expired`
- `cancelled`
- `failed`
4. 失败时返回明确错误码和可展示文案。
5. 取消或失败后清理可清理的临时对象。
### 涉及模块
- `apps/base/views.py`
- `apps/base/models.py`
- `core/storage.py`
- `src/composables/usePresignedUpload.ts`
- `src/services/presign-upload.ts`
- `tests/test_presign_upload_flow.py`
### 数据模型影响
建议为 `PresignUploadSession` 增加:
- `status`
- `actual_size`
- `error_message`
第一阶段如果不做迁移,也可以先在状态接口中计算并返回原因。
### 验收标准
1. 直传对象不存在时返回明确错误。
2. 直传对象大小不符时拒绝创建分享记录。
3. 会话过期、取消、确认成功均有稳定状态。
4. 前端能展示初始化、上传中、确认中、失败、成功状态。
5. 后端测试覆盖对象不存在、大小不符、取消清理和会话过期。
## P0:统一错误响应与请求追踪
目标:让前端能稳定识别业务错误、网络错误和权限错误,并展示可执行下一步。
### 现状问题
- 部分接口抛出 `HTTPException`,部分接口返回 `APIResponse(code=404)`。
- 客户端难以稳定区分上传超限、类型不允许、取件码不存在、会话过期等业务失败。
- 缺少请求 ID,线上排查问题时难以关联日志和用户反馈。
### 建议实现
1. 统一错误响应结构:
- `code`
- `message`
- `error_code`
- `request_id`
- `detail`
2. 增加全局异常处理中间件或异常处理器。
3. 上传、取件、登录、配置保存等关键接口返回稳定错误码。
4. 前端错误提示按 `error_code` 映射文案和建议动作。
### 涉及模块
- `core/response.py`
- `main.py`
- `apps/base/views.py`
- `apps/admin/views.py`
- `src/utils/common.ts`
- `src/services/client.ts`
### 验收标准
1. 上传超限、类型不允许、取件码不存在、登录失败返回统一结构。
2. 前端提示包含原因和下一步动作。
3. 日志中可按 `request_id` 定位请求。
4. 后端测试覆盖全局错误响应格式。
## P0:管理高风险操作确认升级
目标:删除、批量修改、批量策略等不可逆操作必须让管理员清楚知道影响范围。
### 现状问题
- `useAdminFiles.ts` 中多处仍使用 `window.confirm()`。
- 批量删除、批量更新和批量策略操作缺少文件样例、影响数量和不可逆提示。
- 视图预设删除、单文件删除和批量删除的确认体验不统一。
### 建议实现
1. 替换 `window.confirm()` 为统一确认弹窗。
2. 确认弹窗展示:
- 操作类型。
- 影响文件数量。
- 文件样例。
- 是否不可逆。
- 操作执行后可能的结果。
3. 操作执行中禁用确认按钮和相关批量按钮。
4. 操作完成后展示成功数量、失败数量和失败原因。
5. 删除本地浏览器记录时明确提示“不删除服务器文件”。
### 涉及模块
- `FileManageView.vue`
- `AdminBatchActionBar.vue`
- `BaseModal.vue`
- `useAdminFiles.ts`
- `SentRecordList.vue`
- `FileRecordList.vue`
### 验收标准
1. 单文件删除、批量删除、批量更新、批量策略动作均使用统一确认弹窗。
2. 批量删除前可看到选中数量和至少 3 个文件样例。
3. 操作中按钮禁用,避免重复提交。
4. 取消操作不会改变选中状态。
5. 操作结果能区分全部成功、部分成功和全部失败。
## P0:配置保存强校验
目标:把配置错误拦在保存阶段,而不是等用户上传或下载时才暴露。
### 现状问题
- 配置存储在 `KeyValue` 中,更新入口需要更强字段校验。
- 存储后端切换、上传限制、过期策略、文件类型规则等配置一旦错误,会直接影响公开流程。
- 前端设置页有未保存状态,但配置变更风险没有形成统一摘要。
### 建议实现
1. 后端保存配置前做字段级校验:
- `file_storage` 必须是支持的存储后端。
- 上传大小、限流和保存时长不能为负数。
- `expireStyle` 必须属于允许枚举。
- S3、WebDAV、OpenDAL、OneDrive 的必填项按存储类型校验。
2. 前端保存前展示变更摘要:
- 已变更字段。
- 是否影响现有上传。
- 是否需要管理员复查。
3. 高风险配置显示明确提示:
- 公开上传。
- 允许全部文件类型。
- 永久保存。
- 默认管理员口令。
4. 设置页离开、刷新、切换后台页面时提示保存或放弃。
### 涉及模块
前端:
- `SystemSettingsView.vue`
- `useSystemConfig.ts`
- `router/index.ts`
- `config-storage.ts`
后端:
- `apps/admin/services.py`
- `apps/admin/views.py`
- `core/settings.py`
### 验收标准
1. 非法配置会被后端拒绝,并返回具体字段原因。
2. 前端保存前展示变更摘要。
3. 未保存配置离开页面会触发确认。
4. 默认管理员口令、公开上传、允许所有文件类型会有高风险提示。
## P1:管理文件页信息架构优化
目标:把管理页从“功能堆在一个表格上”调整为更适合高频扫描和批量处理的工作台。
### 现状问题
- `FileManageView.vue` 仍承担较多职责。
- 筛选、预设、批量操作、表格、详情、编辑弹窗集中在同一个页面。
- 单行操作按钮较多,在窄屏或大量数据时容易拥挤。
### 建议实现
1. 拆分筛选区组件:
- `AdminFileFilterBar.vue`
- 负责关键词、状态、健康度、类型、排序和预设入口。
2. 拆分详情侧栏:
- `AdminFileDetailDrawer.vue`
- 替代过重弹窗,保留复制、下载、编辑、预览入口。
3. 表格行操作收敛为主操作 + 更多菜单:
- 详情作为主操作。
- 下载、编辑、删除进入更多菜单。
4. 增加快捷筛选:
- 即将过期。
- 从未取件。
- 已耗尽次数。
- 存储异常。
5. 表格空状态提供可执行动作:
- 清空筛选。
- 创建视图预设。
- 返回全部文件。
### 涉及模块
- `FileManageView.vue`
- `AdminBatchActionBar.vue`
- `useAdminFiles.ts`
- `admin-file-summary.ts`
- `admin-file-view-preset.ts`
- `src/i18n/locales/zh-CN.ts`
- `src/i18n/locales/en-US.ts`
### 验收标准
1. 筛选区、批量操作区、表格区职责清晰。
2. 窄屏下表格行操作不溢出。
3. 快捷筛选能正确改变请求参数并刷新数据。
4. 已有批量选择、批量删除、批量策略动作不回归。
## P1:管理后台操作反馈增强
目标:让管理员明确知道批量操作影响了哪些文件、哪些成功、哪些失败。
### 现状能力
- 后端已有批量删除、批量更新、策略动作和活动记录。
- 前端已有批量操作栏。
- 后端 `FileService` 已具备管理活动记录能力。
### 建议实现
1. 批量操作执行前展示影响摘要:
- 选中文件数。
- 即将修改的字段。
- 不可逆风险。
2. 批量操作完成后展示结果摘要:
- 成功数量。
- 失败数量。
- 跳过原因。
3. 活动记录支持从文件详情进入:
- 展示该文件最近操作。
- 展示操作者、动作和时间。
4. 危险操作确认文案包含文件名或数量,而不是只问“是否删除”。
### 涉及模块
前端:
- `AdminBatchActionBar.vue`
- `FileManageView.vue`
- `useAdminFiles.ts`
- `DashboardView.vue`
后端:
- `apps/admin/views.py`
- `apps/admin/services.py`
### 验收标准
1. 批量删除和批量更新前有明确影响摘要。
2. 批量操作结果能展示部分失败,不只显示统一成功或失败。
3. 操作记录能按文件或关键词过滤。
4. 后端测试覆盖活动记录过滤和批量操作结果结构。
## P1:下载与预览体验统一
目标:用户在公开页和管理页面对“文本、图片、视频、音频、PDF、未知文件”时,操作路径一致。
### 建议实现
1. 抽统一文件能力判断工具:
- 是否可文本预览。
- 是否可媒体预览。
- 是否建议下载。
- 是否可复制内容。
2. 统一公开取件和管理页的预览入口文案。
3. PDF、图片、音视频预览失败时提供下载兜底。
4. 文本预览支持复制、下载为 `.txt`、查看原始内容。
### 涉及模块
- `MediaPreviewModal.vue`
- `ContentPreviewModal.vue`
- `FileDetailModal.vue`
- `FileManageView.vue`
- `content-preview.ts`
- `download-action.ts`
- `file-type.ts`
### 验收标准
1. 同一文件类型在公开页和管理页展示一致。
2. 预览失败时始终能回退到下载。
3. 文本内容复制和导出行为一致。
4. 文件类型判断工具具备单元测试。
## P1:上传前文件清单与限制提示
目标:多文件或大文件上传前,让用户提前知道会发生什么,减少上传中途失败。
### 现状问题
- 多文件上传会先打包为 zip,但用户只看到“正在打包文件”。
- 文件清单、总大小、超限原因和打包后行为没有在提交前集中展示。
- `FileUploadArea.vue` 已支持更多上传状态,但页面当前只传入 `uploading` 和 `idle`。
### 建议实现
1. 多文件选择后展示文件清单:
- 文件数量。
- 总大小。
- 最大文件。
- 不允许类型或超限文件。
2. 明确提示多文件将被打包为 zip。
3. 打包阶段展示独立状态,避免和上传阶段混淆。
4. 提交前对所有文件逐项校验,并返回具体失败原因。
### 涉及模块
- `FileUploadArea.vue`
- `SendFileView.vue`
- `useSendFlow.ts`
- `useSendSubmit.ts`
- `ExpirationSelector.vue`
- `file-type.ts`
### 验收标准
1. 多文件选择后可看到数量、总大小和打包提示。
2. 超限文件能逐项展示原因。
3. 打包中、上传中、确认中三个阶段状态不同。
4. 文件清单在取消或重新选择后正确重置。
## P1:服务端状态字段与可操作能力
目标:为前端展示更清楚的状态和主操作提供稳定数据,减少前端重复推断。
### 建议实现
1. 分享记录增加明确状态字段:
- `active`
- `expired`
- `download_limit_exhausted`
- `storage_missing`
2. 公开元数据接口补充可操作能力:
- `canPreview`
- `canDownload`
- `canCopy`
- `primaryAction`
3. 管理列表支持快捷筛选参数:
- `expiringSoon`
- `neverUsed`
- `exhausted`
- `storageIssue`
4. 后端响应保留必要的 snake_case 和 camelCase 兼容。
### 涉及模块
- `apps/base/views.py`
- `apps/base/schemas.py`
- `apps/admin/views.py`
- `apps/admin/services.py`
- `src/types/file.ts`
- `src/services/file.ts`
- `tests/`
### 验收标准
1. 元数据接口能直接告诉前端主操作是什么。
2. 管理文件列表能按快捷状态筛选。
3. 状态字段有后端测试覆盖。
4. 前端不再依赖 `filename === 'Text'` 这类脆弱判断。
## P1:审计日志表化
目标:让上传、下载、删除、配置变更等关键动作可追踪、可过滤、可定位。
### 现状问题
- 管理活动当前主要保存在 `KeyValue` 中,容量和查询能力有限。
- 活动记录缺少 IP、User-Agent、请求 ID、结果状态等排障信息。
- 批量操作失败时,缺少逐项结果追踪。
### 建议实现
1. 新增审计日志模型,记录:
- 动作类型。
- 操作者。
- IP。
- User-Agent。
- 请求 ID。
- 目标类型和目标 ID。
- 执行结果。
- 元数据。
- 创建时间。
2. `/admin/activities` 支持分页和筛选:
- 动作。
- 对象类型。
- 关键词。
- 时间范围。
- 结果状态。
3. 文件详情中展示该文件最近操作。
4. 配置变更记录变更摘要,不记录密钥明文。
### 涉及模块
- `apps/admin/services.py`
- `apps/admin/views.py`
- `apps/base/models.py`
- `tests/`
### 数据模型影响
建议新增:
- `AuditLog`
### 验收标准
1. 删除、批量更新、配置变更会写入审计日志。
2. 审计列表支持分页和筛选。
3. 日志不泄露 Token、密码、密钥。
4. 后端测试覆盖写入、过滤和敏感字段脱敏。
## P1:管理查询性能优化
目标:让后台在千级、万级文件记录下仍能稳定分页、筛选和统计。
### 现状问题
- 文件列表和仪表盘部分统计、过滤、排序在 Python 内存中完成。
- 数据量增加后,后台打开、筛选和统计会逐渐变慢。
### 建议实现
1. 文件列表筛选和排序尽量下推到数据库。
2. 仪表盘统计改为聚合查询。
3. 为高频字段补索引:
- `created_at`
- `expired_at`
- `suffix`
- `is_chunked`
- `used_count`
- `file_hash`
4. 大量记录下避免一次性加载所有文件再过滤。
### 涉及模块
- `apps/admin/views.py`
- `apps/admin/services.py`
- `apps/base/models.py`
- `tests/`
### 验收标准
1. 千级和万级记录下分页耗时稳定。
2. 仪表盘统计结果与现有结果一致。
3. 筛选、排序、分页返回结构保持兼容。
4. 后端测试覆盖主要过滤组合。
## P2:取件与发送记录体验增强
目标:让浏览器本地记录更适合长期使用。
### 建议实现
1. 记录支持搜索:
- 取件码。
- 文件名。
- 类型。
2. 记录支持分组:
- 今天。
- 最近 7 天。
- 更早。
3. 记录详情展示来源:
- 手动输入。
- 链接打开。
- 历史记录。
4. 支持清空记录前二次确认,并说明只清理本地记录,不删除服务器文件。
5. 支持导出发送记录为 JSON。
### 涉及模块
- `SideDrawer.vue`
- `SentRecordList.vue`
- `FileRecordList.vue`
- `fileData` store
- `send-record.ts`
- `download-action.ts`
### 验收标准
1. 本地记录超过 20 条时仍易于查找。
2. 清空记录不会误导用户以为删除了服务器文件。
3. 导出的记录可重新导入或至少可人工读取。
## P2:系统设置体验增强
目标:在强校验之外,给管理员提供配置自检、连接测试和修复建议。
### 建议实现
1. 设置页增加配置自检:
- 当前存储后端是否可用。
- 上传大小限制是否合理。
- 允许文件类型是否能被正确解析。
- 管理地址是否公开。
2. 存储配置增加测试连接按钮:
- S3。
- WebDAV。
- OpenDAL。
- OneDrive。
3. 自检结果返回修复建议:
- 缺少必填项。
- 存储连接失败。
- 上传限制过宽。
- 管理地址暴露。
4. 支持导出当前非敏感配置快照,便于排障。
### 涉及模块
前端:
- `SystemSettingsView.vue`
- `config-storage.ts`
- `config` types
后端:
- `apps/admin/views.py`
- `apps/admin/services.py`
- `core/storage.py`
- `core/settings.py`
### 验收标准
1. 保存设置前能看到变更摘要。
2. 错误配置不会只在上传时暴露。
3. 存储连接失败能返回可理解原因。
4. 配置自检接口有后端测试覆盖。
## 并行开发拆分
第一轮建议拆成四个互不冲突任务,先处理会影响安全边界和关键体验的事项:
1. 后端 A:取件扣次数与下载票据一致性。
2. 前端 B:取件前确认卡片和查询参数自动预检查。
3. 后端 C:统一错误响应和请求追踪。
4. 前端 D:发送成功结果面板和复制反馈。
第二轮在第一轮稳定后推进:
1. 后端 E:预签名直传确认加固和上传会话状态原因。
2. 前端 F:上传取消、失败重试和离页确认。
3. 前端 G:管理高风险操作确认弹窗。
4. 后端 H:配置保存强校验。
第三轮推进管理效率和长期维护:
1. 前端 I:管理文件筛选区、详情侧栏和行操作收敛。
2. 后端 J:服务端状态字段、快捷筛选和管理查询性能优化。
3. 后端 K:审计日志表化。
4. 前端 L:记录搜索、分组、导出和国际化补齐。
## 推荐执行顺序
1. 先做 P0 取件票据和扣次数一致性,修正服务端安全边界。
2. 接着做 P0 取件前确认卡片,避免用户误消耗次数。
3. 同步推进统一错误响应,让前端能展示稳定错误文案。
4. 再做发送成功结果区,提升公开用户最常见路径。
5. 然后做上传取消/重试和预签名直传确认加固。
6. 管理页按强确认、筛选拆分、详情侧栏的顺序渐进推进。
## 质量门禁
前端每轮合并前执行:
```bash
cd FileCodeBoxFronted
pnpm test
pnpm check:architecture
pnpm type-check
pnpm lint:check
pnpm build
```
后端每轮合并前执行:
```bash
cd FileCodeBox
pytest
```
涉及上传、删除、配置、权限和批量操作时,必须补充异常路径测试。
## 风险与注意事项
1. 取件预检查不能调用会消耗次数的接口。
2. 上传取消需要确认不同上传策略的清理路径一致。
3. 管理页组件拆分必须保持现有批量操作行为不变。
4. 配置自检不能泄露密钥、Token 或内部路径。
5. 本地记录增强只影响浏览器存储,不应让用户误解为服务端记录。
## 下一步建议
下一轮优先实现:
1. `P0:取件扣次数与下载票据一致性`
2. `P0:公开取件体验升级`
3. `P0:统一错误响应与请求追踪`
4. `P0:发送结果页增强`
这四项组合能同时修正服务端边界和公开用户体验,为后续上传恢复、管理工作台优化打基础。
+6
View File
@@ -0,0 +1,6 @@
import sys
from pathlib import Path
PROJECT_ROOT = Path(__file__).resolve().parents[1]
if str(PROJECT_ROOT) not in sys.path:
sys.path.insert(0, str(PROJECT_ROOT))
+271
View File
@@ -0,0 +1,271 @@
import asyncio
import unittest
from datetime import timedelta
from types import SimpleNamespace
from fastapi import HTTPException
import apps.base.views as views
from apps.base.schemas import PresignUploadInitRequest
from core.settings import settings
from core.utils import get_now
class SettingsOverrideMixin:
def setUp(self):
self._original_user_config = dict(settings.user_config)
def tearDown(self):
settings.user_config = self._original_user_config
class FakeUploadLimiter:
def __init__(self):
self.added_ips = []
def add_ip(self, ip):
self.added_ips.append(ip)
class FakeUploadFile:
def __init__(self, size):
self.size = size
self.filename = "upload.txt"
self.content_type = "text/plain"
class FakeStorage:
def __init__(self, presigned_url=None, exists=True):
self.presigned_url = presigned_url
self.exists = exists
self.saved = []
self.deleted = []
async def generate_presigned_upload_url(self, save_path, expires_in):
self.last_presign_request = (save_path, expires_in)
return self.presigned_url
async def save_file(self, file, save_path):
self.saved.append((file, save_path))
async def file_exists(self, save_path):
self.last_exists_path = save_path
return self.exists
async def delete_file(self, file_code):
self.deleted.append(file_code)
class FakeSession:
def __init__(self, mode="direct", file_size=12, expired=False):
self.upload_id = "upload-1"
self.file_name = "upload.txt"
self.file_size = file_size
self.save_path = "share/data/2026/06/06/upload-1/upload.txt"
self.mode = mode
self.expire_value = 2
self.expire_style = "day"
self.created_at = None
self.expires_at = None
self.expired = expired
self.deleted = False
async def is_expired(self):
return self.expired
async def delete(self):
self.deleted = True
class FakeSessionQuery:
def __init__(self, session):
self.session = session
async def first(self):
return self.session
class FakePresignUploadSession:
created_payload = None
session = None
@classmethod
async def create(cls, **kwargs):
cls.created_payload = kwargs
return SimpleNamespace(**kwargs)
@classmethod
def filter(cls, **kwargs):
cls.filter_kwargs = kwargs
return FakeSessionQuery(cls.session)
class FakeFileUploadService:
created_records = []
@staticmethod
async def generate_file_path(file_name, upload_id=None):
filename = file_name.strip()
return (
f"share/data/2026/06/06/{upload_id}",
".txt",
"upload",
filename,
f"share/data/2026/06/06/{upload_id}/{filename}",
)
@classmethod
async def create_file_record(
cls, file_name, file_size, file_path, expire_value, expire_style, **extra_fields
):
cls.created_records.append(
{
"file_name": file_name,
"file_size": file_size,
"file_path": file_path,
"expire_value": expire_value,
"expire_style": expire_style,
**extra_fields,
}
)
return "12345"
class PresignUploadFlowTests(SettingsOverrideMixin, unittest.TestCase):
def setUp(self):
super().setUp()
self._original_storages = dict(views.storages)
self._original_session_model = views.PresignUploadSession
self._original_file_upload_service = views.FileUploadService
self._original_upload_limiter = views.ip_limit["upload"]
self.storage = FakeStorage()
views.storages = {"local": lambda: self.storage}
views.PresignUploadSession = FakePresignUploadSession
views.FileUploadService = FakeFileUploadService
views.ip_limit["upload"] = FakeUploadLimiter()
FakePresignUploadSession.created_payload = None
FakePresignUploadSession.session = None
FakeFileUploadService.created_records = []
settings.file_storage = "local"
settings.uploadSize = 1024
settings.allowed_file_types = ["*"]
settings.expireStyle = ["day", "hour", "minute", "forever", "count"]
def tearDown(self):
views.storages = self._original_storages
views.PresignUploadSession = self._original_session_model
views.FileUploadService = self._original_file_upload_service
views.ip_limit["upload"] = self._original_upload_limiter
super().tearDown()
def test_init_returns_proxy_urls_when_storage_has_no_presigned_url(self):
response = asyncio.run(
views.presign_upload_init(
PresignUploadInitRequest(
file_name="upload.txt",
file_size=12,
expire_value=2,
expire_style="day",
),
ip="127.0.0.1",
)
)
detail = response.detail
self.assertEqual(detail["mode"], "proxy")
self.assertEqual(detail["upload_url"], detail["proxy_upload_url"])
self.assertEqual(detail["legacy_proxy_upload_url"], f"/api{detail['proxy_upload_url']}")
self.assertEqual(FakePresignUploadSession.created_payload["file_name"], "upload.txt")
self.assertEqual(FakePresignUploadSession.created_payload["file_size"], 12)
self.assertEqual(views.ip_limit["upload"].added_ips, ["127.0.0.1"])
def test_init_returns_direct_url_when_storage_supports_presigned_upload(self):
self.storage.presigned_url = "https://storage.example/upload"
response = asyncio.run(
views.presign_upload_init(
PresignUploadInitRequest(file_name="upload.txt", file_size=12),
ip="127.0.0.1",
)
)
self.assertEqual(response.detail["mode"], "direct")
self.assertEqual(response.detail["upload_url"], "https://storage.example/upload")
self.assertNotIn("proxy_upload_url", response.detail)
def test_init_rejects_disallowed_expiration_style(self):
with self.assertRaises(HTTPException) as error:
asyncio.run(
views.presign_upload_init(
PresignUploadInitRequest(
file_name="upload.txt",
file_size=12,
expire_style="week",
),
ip="127.0.0.1",
)
)
self.assertEqual(error.exception.status_code, 400)
def test_confirm_requires_uploaded_direct_file_before_creating_record(self):
FakePresignUploadSession.session = FakeSession(mode="direct")
self.storage.exists = True
response = asyncio.run(views.presign_upload_confirm("upload-1", ip="127.0.0.1"))
self.assertEqual(response.detail, {"code": "12345", "name": "upload.txt"})
self.assertTrue(FakePresignUploadSession.session.deleted)
self.assertEqual(FakeFileUploadService.created_records[0]["file_size"], 12)
self.assertEqual(
FakeFileUploadService.created_records[0]["file_path"],
"share/data/2026/06/06/upload-1",
)
def test_confirm_rejects_missing_uploaded_direct_file(self):
FakePresignUploadSession.session = FakeSession(mode="direct")
self.storage.exists = False
with self.assertRaises(HTTPException) as error:
asyncio.run(views.presign_upload_confirm("upload-1", ip="127.0.0.1"))
self.assertEqual(error.exception.status_code, 404)
self.assertFalse(FakePresignUploadSession.session.deleted)
self.assertEqual(FakeFileUploadService.created_records, [])
def test_proxy_upload_rejects_size_mismatch_before_saving_file(self):
FakePresignUploadSession.session = FakeSession(mode="proxy", file_size=10)
with self.assertRaises(HTTPException) as error:
asyncio.run(
views.presign_upload_proxy(
"upload-1",
file=FakeUploadFile(size=2048),
ip="127.0.0.1",
)
)
self.assertEqual(error.exception.status_code, 403)
self.assertEqual(self.storage.saved, [])
def test_cancel_direct_session_removes_uploaded_object_when_present(self):
FakePresignUploadSession.session = FakeSession(mode="direct")
self.storage.exists = True
response = asyncio.run(views.presign_upload_cancel("upload-1"))
self.assertEqual(response.detail, {"message": "上传会话已取消"})
self.assertTrue(FakePresignUploadSession.session.deleted)
self.assertEqual(len(self.storage.deleted), 1)
self.assertEqual(self.storage.deleted[0].file_path, "share/data/2026/06/06/upload-1")
self.assertEqual(self.storage.deleted[0].uuid_file_name, "upload.txt")
def test_expired_session_is_deleted_and_rejected(self):
FakePresignUploadSession.session = FakeSession(mode="direct", expired=True)
FakePresignUploadSession.session.expires_at = asyncio.run(get_now()) - timedelta(seconds=1)
with self.assertRaises(HTTPException) as error:
asyncio.run(views.presign_upload_confirm("upload-1", ip="127.0.0.1"))
self.assertEqual(error.exception.status_code, 404)
self.assertTrue(FakePresignUploadSession.session.deleted)