StoreX 品牌统一与核心稳健性改进（详版）

StoreX Flutter Go 桌面 Windows 上传 下载
January 9, 2026
2 min read
By devshan

Table of Contents

This is a list of all the sections in this post. Click on any of them to jump to that section.

背景与问题

  • 品牌残留：旧代号 “E2E Pan/E2EPan” 仍存在于核心启动 banner、Flutter 入口类名、默认下载目录命名，导致对外展示不一致。
  • 心跳处理粗暴：心跳超时直接 os.Exit，未优雅关闭 HTTP/Gin，可能导致日志/元数据未刷盘。
  • 上传进度泄漏：上传完成/取消后进度记录长期存留在内存 map，长时间运行易积累。
  • 日志目录截取风险：SetLogFilePath 用字符串切片推导目录，路径分隔符变化时可能出错。
  • 构建警告/失败：新增改动后 os 未使用导致 Go 构建失败（Windows 发布脚本暴露）。

本次改动

  • 品牌统一
    • 核心启动 banner 更名为 “StoreX server starting …”（core/internal/api/server.go）。
    • Flutter 入口类从 E2EPanApp 改为 StoreXApp，runApp 调用同步调整（client/lib/main.dart）。
    • 默认下载/文档目录命名从 E2EPan 改为 StoreX（client/lib/core/state/app_state.dart）。
  • 日志路径安全
    • SetLogFilePath 使用 filepath.Dir 计算日志目录，避免手工截字符串的边界问题（core/internal/api/server.go）。
  • 心跳优雅退出
    • 用自建 http.Server 包裹 Gin；Run 改为 ListenAndServe/Shutdown 模式。
    • 心跳超时时调用 shutdownGracefully 进行优雅关闭，停止 ticker，不再直接 os.Exit（core/internal/api/server.go）。
  • 上传进度生命周期
    • 抽出 scheduleUploadProgressCleanup，上传 goroutine 退出后延迟 5 分钟自动删除进度记录，避免 map 堆积（core/internal/api/server.go、core/internal/api/files.go）。
  • 构建修复
    • 移除未使用的 os 引用，Windows release 构建恢复通过（core/internal/api/server.go）。

行为变化

  • 心跳超时：核心会尝试优雅关停 HTTP 服务；客户端需重新拉起或等待桌面端自动重启策略。
  • 上传进度查询：任务完成/取消 5 分钟后，/files/upload-progress/:taskId 将返回未找到。
  • 品牌展示：CLI/日志、客户端类名、默认下载目录均显示 “StoreX”。

风险与待补

  • 优雅关闭仅涵盖 HTTP；若心跳发生在上传中途，后台 goroutine 可能被强制终止（需后续补充上下文取消/资源释放）。
  • 上传进度清理延迟仍固定 5 分钟，可考虑根据任务状态缩短或配置化。
  • 仍缺少自动化测试：心跳超时流程、上传进度生命周期、品牌文案回归。

验证建议

  1. 启动核心并断开心跳，确认日志出现 “shutting down…” 且 HTTP 停止监听。
  2. 执行一次上传，完成后立即查询进度，确认 5 分钟后进度被清理。
  3. 检查客户端默认下载目录、应用标题及核心启动 banner 均为 “StoreX”。
  4. 跑 scripts/bat/build_windows.bat 确认构建无错误。

相关文件

  • core/internal/api/server.go：日志目录处理、HTTP server、心跳优雅退出、上传进度清理工具。
  • core/internal/api/files.go：上传任务生命周期，延迟清理进度。
  • client/lib/main.dart、client/lib/core/state/app_state.dart：品牌命名统一。