Files
FileCodeBox/docs/ux-improvement-plan.md

26 KiB
Raw Permalink Blame History

功能与用户体验提升规划

生成日期: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

验收标准

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. 管理页按强确认、筛选拆分、详情侧栏的顺序渐进推进。

质量门禁

前端每轮合并前执行:

cd FileCodeBoxFronted
pnpm test
pnpm check:architecture
pnpm type-check
pnpm lint:check
pnpm build

后端每轮合并前执行:

cd FileCodeBox
pytest

涉及上传、删除、配置、权限和批量操作时,必须补充异常路径测试。

风险与注意事项

  1. 取件预检查不能调用会消耗次数的接口。
  2. 上传取消需要确认不同上传策略的清理路径一致。
  3. 管理页组件拆分必须保持现有批量操作行为不变。
  4. 配置自检不能泄露密钥、Token 或内部路径。
  5. 本地记录增强只影响浏览器存储,不应让用户误解为服务端记录。

下一步建议

下一轮优先实现:

  1. P0:取件扣次数与下载票据一致性
  2. P0:公开取件体验升级
  3. P0:统一错误响应与请求追踪
  4. P0:发送结果页增强

这四项组合能同时修正服务端边界和公开用户体验,为后续上传恢复、管理工作台优化打基础。