26 KiB
功能与用户体验提升规划
生成日期:2026-06-06
本文档承接 development-plan.md 和 development-delivery-report.md,用于规划下一轮“功能增强 + 用户体验提升”开发。重点不是重做界面,而是让发送、取件和管理流程更清楚、更可恢复、更适合反复使用。
当前基线
当前工作区包含两个独立仓库:
FileCodeBox:FastAPI 后端,提供分享、取件、分片上传、预签名上传、管理后台、配置和本地文件管理接口。FileCodeBoxFronted:Vue 3 + Vite 前端,提供公开取件页、发件页、登录页、管理仪表盘、文件管理和系统设置。
本轮已完成的基础能力:
- 取件文件预览链路已接通。
- 前端 Vitest 测试体系已建立。
- 后端预签名上传流程已有回归测试。
- 管理文件页已抽出部分纯函数、批量选择逻辑和批量操作栏。
下一轮应把重点从“能用”推进到“好用、稳定、可解释”。
体验目标
- 发送流程要让用户明确知道当前文件是否可发、发到哪一步、失败后如何继续。
- 取件流程要避免误消耗取件次数,先展示文件摘要,再由用户确认下载或预览。
- 管理后台要提高高频操作效率,减少大页面内工具堆叠和重复确认成本。
- 所有危险操作要有清晰影响范围,避免误删、误批量修改和不可逆操作。
- 错误提示要从“发生错误”升级为“原因 + 可执行下一步”。
规划依据
本轮规划基于前后端只读审阅结果:
- 前端主流程已完整,但取件前确认、上传取消/重试、发送成功结果区和后台强确认仍不足。
- 后端接口能力较全,但取件扣次数、下载票据、预签名直传确认、错误响应和审计追踪仍需要加固。
- 下一轮应优先处理“安全边界 + 关键路径体验”,再扩展管理效率和长期产品能力。
P0:取件扣次数与下载票据一致性
目标:确保取件次数只在真实授权动作中消耗,并且旧下载地址不能绕过过期或次数限制。
现状问题
/share/select/当前会调用update_file_usage(),取件前缺少确认时容易误消耗次数。/share/download使用check=False获取文件记录,已生成的下载地址存在被继续复用的窗口。- 下载票据由
get_select_token()生成,缺少明确的短期过期语义和服务端状态绑定。
建议实现
- 将“查看元数据”和“确认取件授权”严格分离。
- 为确认取件生成短期下载票据:
- 票据绑定取件码。
- 票据包含过期时间。
- 票据校验时重新检查文件是否过期、次数是否耗尽。
- 并发场景下保证
expired_count=1只能成功一次。 - 下载接口拒绝已过期、次数耗尽或票据失效的请求。
- 响应中明确返回剩余次数和下一步动作。
涉及模块
apps/base/views.pycore/utils.pyapps/base/models.pytests/
数据模型影响
第一阶段可先使用签名票据,不强制新增表。
如果要做更完整审计,后续新增:
DownloadTicketFileAccessLog
验收标准
- 元数据查询不消耗下载次数。
- 确认取件后才消耗次数并返回下载票据。
expired_count=1并发取件时只能成功一次。- 旧下载地址在文件过期或次数耗尽后不可继续下载。
- 后端测试覆盖票据过期、次数耗尽和并发边界。
P0:公开取件体验升级
目标:取件码输入后先确认内容,再执行会消耗次数的取件动作。
现状问题
RetrievewFileView.vue在取件码长度达到 5 位时直接调用handleSubmit()。handleSubmit()调用/share/select/,会执行update_file_usage(),可能消耗下载次数。useRetrieveFlow.ts已有inspectCode()和inspectedFile,但页面当前未形成完整的“预检查确认”体验。
建议实现
- 输入 5 位取件码后调用
inspectCode(),请求/share/metadata/。 - 页面展示文件摘要卡片:
- 文件名或文本类型。
- 文件大小。
- 过期时间。
- 剩余下载次数。
- 是否可预览。
- 用户点击“取件”后再调用
handleSubmit()。 - 如果文件已过期或次数耗尽,直接展示不可取原因,不再进入下载动作。
- 查询参数
?code=xxxxx进入页面时,也走同样的预检查流程。 - 与服务端下载票据机制配合,确认取件后再获得可下载地址。
涉及模块
RetrievewFileView.vueRetrieveForm.vueuseRetrieveFlow.tsFileDetailModal.vuedownload-action.tssrc/i18n/locales/zh-CN.tssrc/i18n/locales/en-US.ts
验收标准
cd FileCodeBoxFronted
pnpm test
pnpm check:architecture
pnpm type-check
pnpm lint:check
pnpm build
手工验收:
- 输入有效取件码,只展示摘要,不立即消耗下载次数。
- 点击确认取件后,才新增取件记录并打开详情或预览。
- 输入过期取件码时展示明确原因。
- 从
?code=xxxxx访问时能自动展示摘要。
P0:发送结果页增强
目标:发送成功后让用户更快完成复制、分享、复查和再次发送。
现状问题
useSendFlow.ts发送成功后会自动复制链接并打开记录详情。- 用户能看到结果,但结果区域更像历史详情,不像一次明确的“发送完成”状态。
- 多文件、文本、单文件的结果反馈可以更聚焦。
建议实现
- 新增发送成功结果面板,替代只依赖记录详情弹窗:
- 取件码大号展示。
- 一键复制取件码。
- 一键复制链接。
- 二维码展示入口。
- 重新发送按钮。
- 明确自动复制结果:
- 复制成功展示“链接已复制”。
- 复制失败展示“请手动复制”。
- 多文件上传成功后展示文件数量和压缩包/批量记录说明。
- 文本发送成功后提供“预览文本”和“复制原文”。
涉及模块
SendFileView.vueSentRecordDetailModal.vueSentRecordList.vueuseSendFlow.tssent-record-actions.tssend-record.ts
验收标准
- 单文件、文本、多文件发送成功后都有明确完成态。
- 复制取件码、复制链接、二维码入口可用。
- 发送成功后再次选择文件或文本不会残留上一次进度。
- 自动复制失败时有人工复制路径。
P0:上传失败恢复与取消
目标:上传过程可中断、可重试、可解释。
现状问题
- 前端已有上传进度、速度和预签名上传封装。
- 用户在上传中无法主动取消。
- 失败后缺少保留文件并重试的明确路径。
- 预签名上传会话存在后端取消接口,但前端体验还可以更完整。
建议实现
- 上传中展示取消按钮。
- 取消时调用对应取消逻辑:
- 预签名上传:
DELETE /presign/upload/{upload_id}。 - 分片上传:
DELETE /chunk/upload/{upload_id}。
- 预签名上传:
- 失败后保留已选择文件,提供“重试”按钮。
- 错误提示按类型分层:
- 文件过大。
- 文件类型不允许。
- 网络中断。
- 服务端拒绝。
- 上传会话过期。
- 上传过程中离开页面时提示用户确认。
涉及模块
FileUploadArea.vueSendFileView.vueuseSendFlow.tsuseSendSubmit.tsusePresignedUpload.tsupload-strategy.tsFileService
验收标准
- 上传中可以取消,后端临时会话或分片状态被清理。
- 网络失败后可以直接重试,不需要重新选择文件。
- 取消上传后进度归零,按钮状态恢复。
- 页面跳转或关闭前有上传中提示。
P0:预签名直传确认加固
目标:直传文件确认不只检查“对象存在”,还要确认大小、状态和失败原因。
现状问题
presign_upload_confirm()当前主要依赖file_exists()。- 直传对象大小不符、上传中断、对象异常时,服务端难以给出准确原因。
PresignUploadSession当前缺少状态字段,前端只能通过接口错误推断上传阶段。
建议实现
- 存储接口增加对象元信息读取能力:
stat_file(save_path)- 返回是否存在、实际大小、更新时间和存储后端错误。
presign_upload_confirm()校验实际大小与声明大小一致。- 上传会话状态响应补充原因:
pendinguploadinguploadedconfirmedexpiredcancelledfailed
- 失败时返回明确错误码和可展示文案。
- 取消或失败后清理可清理的临时对象。
涉及模块
apps/base/views.pyapps/base/models.pycore/storage.pysrc/composables/usePresignedUpload.tssrc/services/presign-upload.tstests/test_presign_upload_flow.py
数据模型影响
建议为 PresignUploadSession 增加:
statusactual_sizeerror_message
第一阶段如果不做迁移,也可以先在状态接口中计算并返回原因。
验收标准
- 直传对象不存在时返回明确错误。
- 直传对象大小不符时拒绝创建分享记录。
- 会话过期、取消、确认成功均有稳定状态。
- 前端能展示初始化、上传中、确认中、失败、成功状态。
- 后端测试覆盖对象不存在、大小不符、取消清理和会话过期。
P0:统一错误响应与请求追踪
目标:让前端能稳定识别业务错误、网络错误和权限错误,并展示可执行下一步。
现状问题
- 部分接口抛出
HTTPException,部分接口返回APIResponse(code=404)。 - 客户端难以稳定区分上传超限、类型不允许、取件码不存在、会话过期等业务失败。
- 缺少请求 ID,线上排查问题时难以关联日志和用户反馈。
建议实现
- 统一错误响应结构:
codemessageerror_coderequest_iddetail
- 增加全局异常处理中间件或异常处理器。
- 上传、取件、登录、配置保存等关键接口返回稳定错误码。
- 前端错误提示按
error_code映射文案和建议动作。
涉及模块
core/response.pymain.pyapps/base/views.pyapps/admin/views.pysrc/utils/common.tssrc/services/client.ts
验收标准
- 上传超限、类型不允许、取件码不存在、登录失败返回统一结构。
- 前端提示包含原因和下一步动作。
- 日志中可按
request_id定位请求。 - 后端测试覆盖全局错误响应格式。
P0:管理高风险操作确认升级
目标:删除、批量修改、批量策略等不可逆操作必须让管理员清楚知道影响范围。
现状问题
useAdminFiles.ts中多处仍使用window.confirm()。- 批量删除、批量更新和批量策略操作缺少文件样例、影响数量和不可逆提示。
- 视图预设删除、单文件删除和批量删除的确认体验不统一。
建议实现
- 替换
window.confirm()为统一确认弹窗。 - 确认弹窗展示:
- 操作类型。
- 影响文件数量。
- 文件样例。
- 是否不可逆。
- 操作执行后可能的结果。
- 操作执行中禁用确认按钮和相关批量按钮。
- 操作完成后展示成功数量、失败数量和失败原因。
- 删除本地浏览器记录时明确提示“不删除服务器文件”。
涉及模块
FileManageView.vueAdminBatchActionBar.vueBaseModal.vueuseAdminFiles.tsSentRecordList.vueFileRecordList.vue
验收标准
- 单文件删除、批量删除、批量更新、批量策略动作均使用统一确认弹窗。
- 批量删除前可看到选中数量和至少 3 个文件样例。
- 操作中按钮禁用,避免重复提交。
- 取消操作不会改变选中状态。
- 操作结果能区分全部成功、部分成功和全部失败。
P0:配置保存强校验
目标:把配置错误拦在保存阶段,而不是等用户上传或下载时才暴露。
现状问题
- 配置存储在
KeyValue中,更新入口需要更强字段校验。 - 存储后端切换、上传限制、过期策略、文件类型规则等配置一旦错误,会直接影响公开流程。
- 前端设置页有未保存状态,但配置变更风险没有形成统一摘要。
建议实现
- 后端保存配置前做字段级校验:
file_storage必须是支持的存储后端。- 上传大小、限流和保存时长不能为负数。
expireStyle必须属于允许枚举。- S3、WebDAV、OpenDAL、OneDrive 的必填项按存储类型校验。
- 前端保存前展示变更摘要:
- 已变更字段。
- 是否影响现有上传。
- 是否需要管理员复查。
- 高风险配置显示明确提示:
- 公开上传。
- 允许全部文件类型。
- 永久保存。
- 默认管理员口令。
- 设置页离开、刷新、切换后台页面时提示保存或放弃。
涉及模块
前端:
SystemSettingsView.vueuseSystemConfig.tsrouter/index.tsconfig-storage.ts
后端:
apps/admin/services.pyapps/admin/views.pycore/settings.py
验收标准
- 非法配置会被后端拒绝,并返回具体字段原因。
- 前端保存前展示变更摘要。
- 未保存配置离开页面会触发确认。
- 默认管理员口令、公开上传、允许所有文件类型会有高风险提示。
P1:管理文件页信息架构优化
目标:把管理页从“功能堆在一个表格上”调整为更适合高频扫描和批量处理的工作台。
现状问题
FileManageView.vue仍承担较多职责。- 筛选、预设、批量操作、表格、详情、编辑弹窗集中在同一个页面。
- 单行操作按钮较多,在窄屏或大量数据时容易拥挤。
建议实现
- 拆分筛选区组件:
AdminFileFilterBar.vue- 负责关键词、状态、健康度、类型、排序和预设入口。
- 拆分详情侧栏:
AdminFileDetailDrawer.vue- 替代过重弹窗,保留复制、下载、编辑、预览入口。
- 表格行操作收敛为主操作 + 更多菜单:
- 详情作为主操作。
- 下载、编辑、删除进入更多菜单。
- 增加快捷筛选:
- 即将过期。
- 从未取件。
- 已耗尽次数。
- 存储异常。
- 表格空状态提供可执行动作:
- 清空筛选。
- 创建视图预设。
- 返回全部文件。
涉及模块
FileManageView.vueAdminBatchActionBar.vueuseAdminFiles.tsadmin-file-summary.tsadmin-file-view-preset.tssrc/i18n/locales/zh-CN.tssrc/i18n/locales/en-US.ts
验收标准
- 筛选区、批量操作区、表格区职责清晰。
- 窄屏下表格行操作不溢出。
- 快捷筛选能正确改变请求参数并刷新数据。
- 已有批量选择、批量删除、批量策略动作不回归。
P1:管理后台操作反馈增强
目标:让管理员明确知道批量操作影响了哪些文件、哪些成功、哪些失败。
现状能力
- 后端已有批量删除、批量更新、策略动作和活动记录。
- 前端已有批量操作栏。
- 后端
FileService已具备管理活动记录能力。
建议实现
- 批量操作执行前展示影响摘要:
- 选中文件数。
- 即将修改的字段。
- 不可逆风险。
- 批量操作完成后展示结果摘要:
- 成功数量。
- 失败数量。
- 跳过原因。
- 活动记录支持从文件详情进入:
- 展示该文件最近操作。
- 展示操作者、动作和时间。
- 危险操作确认文案包含文件名或数量,而不是只问“是否删除”。
涉及模块
前端:
AdminBatchActionBar.vueFileManageView.vueuseAdminFiles.tsDashboardView.vue
后端:
apps/admin/views.pyapps/admin/services.py
验收标准
- 批量删除和批量更新前有明确影响摘要。
- 批量操作结果能展示部分失败,不只显示统一成功或失败。
- 操作记录能按文件或关键词过滤。
- 后端测试覆盖活动记录过滤和批量操作结果结构。
P1:下载与预览体验统一
目标:用户在公开页和管理页面对“文本、图片、视频、音频、PDF、未知文件”时,操作路径一致。
建议实现
- 抽统一文件能力判断工具:
- 是否可文本预览。
- 是否可媒体预览。
- 是否建议下载。
- 是否可复制内容。
- 统一公开取件和管理页的预览入口文案。
- PDF、图片、音视频预览失败时提供下载兜底。
- 文本预览支持复制、下载为
.txt、查看原始内容。
涉及模块
MediaPreviewModal.vueContentPreviewModal.vueFileDetailModal.vueFileManageView.vuecontent-preview.tsdownload-action.tsfile-type.ts
验收标准
- 同一文件类型在公开页和管理页展示一致。
- 预览失败时始终能回退到下载。
- 文本内容复制和导出行为一致。
- 文件类型判断工具具备单元测试。
P1:上传前文件清单与限制提示
目标:多文件或大文件上传前,让用户提前知道会发生什么,减少上传中途失败。
现状问题
- 多文件上传会先打包为 zip,但用户只看到“正在打包文件”。
- 文件清单、总大小、超限原因和打包后行为没有在提交前集中展示。
FileUploadArea.vue已支持更多上传状态,但页面当前只传入uploading和idle。
建议实现
- 多文件选择后展示文件清单:
- 文件数量。
- 总大小。
- 最大文件。
- 不允许类型或超限文件。
- 明确提示多文件将被打包为 zip。
- 打包阶段展示独立状态,避免和上传阶段混淆。
- 提交前对所有文件逐项校验,并返回具体失败原因。
涉及模块
FileUploadArea.vueSendFileView.vueuseSendFlow.tsuseSendSubmit.tsExpirationSelector.vuefile-type.ts
验收标准
- 多文件选择后可看到数量、总大小和打包提示。
- 超限文件能逐项展示原因。
- 打包中、上传中、确认中三个阶段状态不同。
- 文件清单在取消或重新选择后正确重置。
P1:服务端状态字段与可操作能力
目标:为前端展示更清楚的状态和主操作提供稳定数据,减少前端重复推断。
建议实现
- 分享记录增加明确状态字段:
activeexpireddownload_limit_exhaustedstorage_missing
- 公开元数据接口补充可操作能力:
canPreviewcanDownloadcanCopyprimaryAction
- 管理列表支持快捷筛选参数:
expiringSoonneverUsedexhaustedstorageIssue
- 后端响应保留必要的 snake_case 和 camelCase 兼容。
涉及模块
apps/base/views.pyapps/base/schemas.pyapps/admin/views.pyapps/admin/services.pysrc/types/file.tssrc/services/file.tstests/
验收标准
- 元数据接口能直接告诉前端主操作是什么。
- 管理文件列表能按快捷状态筛选。
- 状态字段有后端测试覆盖。
- 前端不再依赖
filename === 'Text'这类脆弱判断。
P1:审计日志表化
目标:让上传、下载、删除、配置变更等关键动作可追踪、可过滤、可定位。
现状问题
- 管理活动当前主要保存在
KeyValue中,容量和查询能力有限。 - 活动记录缺少 IP、User-Agent、请求 ID、结果状态等排障信息。
- 批量操作失败时,缺少逐项结果追踪。
建议实现
- 新增审计日志模型,记录:
- 动作类型。
- 操作者。
- IP。
- User-Agent。
- 请求 ID。
- 目标类型和目标 ID。
- 执行结果。
- 元数据。
- 创建时间。
/admin/activities支持分页和筛选:- 动作。
- 对象类型。
- 关键词。
- 时间范围。
- 结果状态。
- 文件详情中展示该文件最近操作。
- 配置变更记录变更摘要,不记录密钥明文。
涉及模块
apps/admin/services.pyapps/admin/views.pyapps/base/models.pytests/
数据模型影响
建议新增:
AuditLog
验收标准
- 删除、批量更新、配置变更会写入审计日志。
- 审计列表支持分页和筛选。
- 日志不泄露 Token、密码、密钥。
- 后端测试覆盖写入、过滤和敏感字段脱敏。
P1:管理查询性能优化
目标:让后台在千级、万级文件记录下仍能稳定分页、筛选和统计。
现状问题
- 文件列表和仪表盘部分统计、过滤、排序在 Python 内存中完成。
- 数据量增加后,后台打开、筛选和统计会逐渐变慢。
建议实现
- 文件列表筛选和排序尽量下推到数据库。
- 仪表盘统计改为聚合查询。
- 为高频字段补索引:
created_atexpired_atsuffixis_chunkedused_countfile_hash
- 大量记录下避免一次性加载所有文件再过滤。
涉及模块
apps/admin/views.pyapps/admin/services.pyapps/base/models.pytests/
验收标准
- 千级和万级记录下分页耗时稳定。
- 仪表盘统计结果与现有结果一致。
- 筛选、排序、分页返回结构保持兼容。
- 后端测试覆盖主要过滤组合。
P2:取件与发送记录体验增强
目标:让浏览器本地记录更适合长期使用。
建议实现
- 记录支持搜索:
- 取件码。
- 文件名。
- 类型。
- 记录支持分组:
- 今天。
- 最近 7 天。
- 更早。
- 记录详情展示来源:
- 手动输入。
- 链接打开。
- 历史记录。
- 支持清空记录前二次确认,并说明只清理本地记录,不删除服务器文件。
- 支持导出发送记录为 JSON。
涉及模块
SideDrawer.vueSentRecordList.vueFileRecordList.vuefileDatastoresend-record.tsdownload-action.ts
验收标准
- 本地记录超过 20 条时仍易于查找。
- 清空记录不会误导用户以为删除了服务器文件。
- 导出的记录可重新导入或至少可人工读取。
P2:系统设置体验增强
目标:在强校验之外,给管理员提供配置自检、连接测试和修复建议。
建议实现
- 设置页增加配置自检:
- 当前存储后端是否可用。
- 上传大小限制是否合理。
- 允许文件类型是否能被正确解析。
- 管理地址是否公开。
- 存储配置增加测试连接按钮:
- S3。
- WebDAV。
- OpenDAL。
- OneDrive。
- 自检结果返回修复建议:
- 缺少必填项。
- 存储连接失败。
- 上传限制过宽。
- 管理地址暴露。
- 支持导出当前非敏感配置快照,便于排障。
涉及模块
前端:
SystemSettingsView.vueconfig-storage.tsconfigtypes
后端:
apps/admin/views.pyapps/admin/services.pycore/storage.pycore/settings.py
验收标准
- 保存设置前能看到变更摘要。
- 错误配置不会只在上传时暴露。
- 存储连接失败能返回可理解原因。
- 配置自检接口有后端测试覆盖。
并行开发拆分
第一轮建议拆成四个互不冲突任务,先处理会影响安全边界和关键体验的事项:
- 后端 A:取件扣次数与下载票据一致性。
- 前端 B:取件前确认卡片和查询参数自动预检查。
- 后端 C:统一错误响应和请求追踪。
- 前端 D:发送成功结果面板和复制反馈。
第二轮在第一轮稳定后推进:
- 后端 E:预签名直传确认加固和上传会话状态原因。
- 前端 F:上传取消、失败重试和离页确认。
- 前端 G:管理高风险操作确认弹窗。
- 后端 H:配置保存强校验。
第三轮推进管理效率和长期维护:
- 前端 I:管理文件筛选区、详情侧栏和行操作收敛。
- 后端 J:服务端状态字段、快捷筛选和管理查询性能优化。
- 后端 K:审计日志表化。
- 前端 L:记录搜索、分组、导出和国际化补齐。
推荐执行顺序
- 先做 P0 取件票据和扣次数一致性,修正服务端安全边界。
- 接着做 P0 取件前确认卡片,避免用户误消耗次数。
- 同步推进统一错误响应,让前端能展示稳定错误文案。
- 再做发送成功结果区,提升公开用户最常见路径。
- 然后做上传取消/重试和预签名直传确认加固。
- 管理页按强确认、筛选拆分、详情侧栏的顺序渐进推进。
质量门禁
前端每轮合并前执行:
cd FileCodeBoxFronted
pnpm test
pnpm check:architecture
pnpm type-check
pnpm lint:check
pnpm build
后端每轮合并前执行:
cd FileCodeBox
pytest
涉及上传、删除、配置、权限和批量操作时,必须补充异常路径测试。
风险与注意事项
- 取件预检查不能调用会消耗次数的接口。
- 上传取消需要确认不同上传策略的清理路径一致。
- 管理页组件拆分必须保持现有批量操作行为不变。
- 配置自检不能泄露密钥、Token 或内部路径。
- 本地记录增强只影响浏览器存储,不应让用户误解为服务端记录。
下一步建议
下一轮优先实现:
P0:取件扣次数与下载票据一致性P0:公开取件体验升级P0:统一错误响应与请求追踪P0:发送结果页增强
这四项组合能同时修正服务端边界和公开用户体验,为后续上传恢复、管理工作台优化打基础。