mirror of
https://github.com/vastsa/FileCodeBox.git
synced 2026-11-21 22:47:13 +08:00
212 lines
4.9 KiB
Markdown
212 lines
4.9 KiB
Markdown
# 下一步开发计划
|
||
|
||
本文档记录 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. 等测试保护到位后,再拆分管理文件模块。
|
||
|
||
结论:下一阶段以“取件预览接线 + 测试体系建设”为主线,先修用户可见断点,再提升长期维护质量。
|