mirror of
https://github.com/vastsa/FileCodeBox.git
synced 2026-11-21 22:47:13 +08:00
4.9 KiB
4.9 KiB
下一步开发计划
本文档记录 FileCodeBox 下一阶段开发优先级、并行拆分方式、验收标准和质量门禁。
背景
当前工作区包含两个独立仓库:
FileCodeBox:FastAPI 后端,包含接口、存储、管理后台 API、文档和后端测试。FileCodeBoxFronted:Vue 3 + Vite 前端,包含公开取件/发件页和管理后台界面。
近期提交主要集中在 S3 存储、取件码归一化、文件类型限制、主题资源加载、前端管理页和上传下载体验。
下一阶段应优先处理用户可见断点和自动化回归保护,再推进大模块拆分。
优先级总览
P0:补齐取件文件预览链路
目标:打通前端已存在但尚未完整接线的文件预览能力。
涉及模块:
RetrievewFileView.vueFileDetailModal.vueMediaPreviewModal.vueuseRetrieveFlow.ts
主要工作:
- 在取件详情弹窗中绑定文件预览事件。
- 在取件页渲染媒体预览弹窗。
- 确认图片、视频、音频、PDF 等可预览文件能正常打开。
- 保持关闭、下载、错误提示等状态行为一致。
验收标准:
pnpm check:architecture
pnpm build
手工验收:
- 上传非文本文件并获取取件码。
- 取件后打开详情弹窗。
- 点击预览,确认弹窗可打开。
- 确认关闭和下载动作正常。
P0:建立最小前端测试体系
目标:为核心前端流程建立可持续的自动化回归保护。
现状:
- 前端暂无测试目录。
package.json中暂无test脚本。- 最近改动涉及上传、下载、Markdown 预览、配置表单等高风险路径。
建议引入:
vitest
@vue/test-utils
jsdom
首批测试范围:
- 文件类型限制规则。
- 过期时间限制校验。
- Markdown 渲染和 HTML 清洗。
- 下载动作解析。
- 预签名上传与分片上传提交分支。
验收标准:
pnpm test
要求:
- 测试能在 60 秒内完成。
- 核心工具函数至少具备首批单元测试。
- 测试脚本不修改源码文件。
P1:后端上传与存储回归加固
目标:把近期修复沉淀为后端测试,降低存储和上传链路回归风险。
涉及模块:
apps/base/views.pycore/storage.pymain.pytests/
优先测试场景:
- 预签名上传
init/confirm/cancel。 - 代理上传文件大小校验。
allowed_file_types的扩展名、MIME、通配规则。- S3
file_exists的head_object失败降级逻辑。 - 主题资源路径穿越保护。
验收标准:
pytest
要求:
- 测试使用临时目录和替身对象,避免污染
data/。 - 外部存储相关测试不依赖真实网络或真实 S3。
- 异常路径和边界值必须覆盖。
P1:调整质量脚本
目标:区分“检查”和“自动修复”,避免 CI 或验证命令改写源码。
当前问题:
"lint": "eslint . --fix"
建议调整:
{
"lint": "eslint . --fix",
"lint:check": "eslint ."
}
推荐前端验证顺序:
pnpm check:architecture
pnpm type-check
pnpm lint:check
pnpm test
pnpm build
P2:拆分管理文件模块
目标:降低管理文件页面和业务 composable 的维护复杂度。
现状:
FileManageView.vue体量较大。useAdminFiles.ts同时承载列表、筛选、视图预设、批量操作、详情、元数据、下载和预览等职责。
拆分顺序:
- 抽纯函数:筛选参数归一化、视图预设归一化、摘要计算、详情视图模型转换。
- 抽 composable:批量操作、详情弹窗、元数据编辑、视图预设。
- 抽 UI 子组件:批量工具栏、筛选栏、详情侧栏、预设选择器。
约束:
- 每次只拆一块。
- 拆分前后行为保持一致。
- 先给纯函数补测试,再推进 UI 拆分。
并行开发安排
第一轮可并行拆分为四个互不冲突的任务:
- 前端 A:接线取件文件预览。
- 前端 B:搭建 Vitest 与首批工具函数测试。
- 后端 C:补充上传和存储回归测试。
- 工程 D:新增
lint:check并整理验证命令。
合并前统一验证:
cd FileCodeBoxFronted
pnpm check:architecture
pnpm type-check
pnpm lint:check
pnpm test
pnpm build
cd ../FileCodeBox
pytest
质量门禁
每个开发任务完成时必须记录:
- 改动范围。
- 关键设计决策。
- 执行过的验证命令。
- 未覆盖风险和后续事项。
涉及上传、删除、存储、认证、配置等功能时,必须补充异常路径测试。
推荐执行顺序
- 先完成 P0 的取件预览接线。
- 同步建立前端最小测试体系。
- 补齐后端上传和存储回归测试。
- 调整前端质量脚本。
- 等测试保护到位后,再拆分管理文件模块。
结论:下一阶段以“取件预览接线 + 测试体系建设”为主线,先修用户可见断点,再提升长期维护质量。