mirror of
https://github.com/vastsa/FileCodeBox.git
synced 2026-11-20 21:57:02 +08:00
Compare commits
1
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
1ec397af0c |
No files matched your search
@@ -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"
|
||||
```
|
||||
@@ -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. 等测试保护到位后,再拆分管理文件模块。
|
||||
|
||||
结论:下一阶段以“取件预览接线 + 测试体系建设”为主线,先修用户可见断点,再提升长期维护质量。
|
||||
@@ -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:发送结果页增强`
|
||||
|
||||
这四项组合能同时修正服务端边界和公开用户体验,为后续上传恢复、管理工作台优化打基础。
|
||||
@@ -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))
|
||||
@@ -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)
|
||||
Reference in new issue
Block a user