CargoTrace/docs/superpowers/specs/2026-08-10-derivative-tools-organization-design.md

衍生工具目录组织设计

日期:2026-08-10 状态:已确认,待实施

背景

CargoTrace 主仓库(Monorepo + Git Submodule)目前有三类内容:

• apps/pad_scanner(Flutter 端,submodule)
• services/fastapi(后端,submodule)
• 衍生工具:WareShipManifest(装箱单报表,submodule)、attachmentQRCodeGenerator(Excel/VBA 标签工具,游离仓库)

衍生工具存在两个组织问题:

1. 层级不一致:apps/、services/ 是分类目录,而 WareShipManifest 直接躺在根目录,未进任何分类层级。
2. attachmentQRCodeGenerator 三不管:它有自己的 .git,但主仓库不跟踪它(git ls-files --error-unmatch 报错),不在 .gitmodules 中,且无任何 remote。

随着未来工具持续增加,根目录堆放将愈发混乱。需要为衍生工具建立统一的组织约定。

目标

• 为所有衍生工具建立统一的 tools/ 顶层目录与纳入流程。
• 把现有两个工具迁入 tools/,并将游离的 attachmentQRCodeGenerator 纳入版本管理。
• 形成可复用的「新增工具」约定,供后续工具遵循。

决策

经讨论确定两项根本决策:

1. Git 归属:所有衍生工具统一作为 submodule(独立 git 仓库)引入,与现有 apps/、services/ 的 monorepo + submodule 模式一致。主仓库只跟踪版本指针,工具可独立开发与发布。
2. 命名与分层:tools/ 扁平存放,保留各工具原名(不强制 snake_case)。匹配当前规模,迁移成本最低。

目标结构

CargoTrace/
├── apps/pad_scanner/                 (submodule, 不变)
├── services/fastapi/                 (submodule, 不变)
├── tools/                            ← 新增顶层目录
│   ├── README.md                     ← 工具清单 + 纳入流程
│   ├── WareShipManifest/             (submodule, 从根目录迁入)
│   └── attachmentQRCodeGenerator/    (submodule, 游离仓库转正)
├── docs/
└── README.md

所有衍生工具作为 submodule 存于 tools/<原名>/。

迁移方案

WareShipManifest(已是 submodule,迁路径)

• 从根目录 WareShipManifest/ 迁至 tools/WareShipManifest/。
• 性质:submodule 路径变更,需更新 .gitmodules 的 path 字段并同步 git 索引,不是简单 mv。
• ⚠️ URL 隐患:.gitmodules 中该 submodule 的 URL 为 git@gitea.server10086.icu:CargoTrace/WareShipManifest.git,而子仓库实际 remote 指向 git@gitea.misdev.icu:CargoTrace/WareShipManifest.git。实施时需核实两个域名是否指向同一 Gitea 实例,并统一 .gitmodules URL,避免 git submodule update --init 拉错源。
• 子仓库当前默认分支为 main,与 apps/、services/ 的 master 不一致(记录,本次不强改)。

attachmentQRCodeGenerator(游离仓库转正)

• 现状:有独立 .git,主仓库不跟踪,无 remote。
• 三步:
  1. 在 Gitea(CargoTrace 组织下)建独立仓库。
  2. 为本地仓库设 remote,推送现有提交历史。
  3. 在主仓库执行 git submodule add <url> tools/attachmentQRCodeGenerator,纳入管理。
• ⚠️ 备份文件:目录内含 7 个 *.bak.*.xlsm 备份。建仓时需定 .gitignore,建议忽略 .bak 文件,仅纳入当前 压力表标签查询打印_界面预览.xlsm、附件标签-刘洪.btw 以及 VBA-Excel/ 源码。

tools/README.md 约定

新增 tools/README.md,内容包括:

• 工具清单表:名称 / 用途 / 技术栈 / 仓库链接 / 状态。
• 新增工具流程:
  1. Gitea 建独立仓库。
  2. git submodule add <url> tools/<name>。
  3. 在 tools/README.md 登记一行。
• 更新工具:git submodule update --remote tools/<name>,或进入子目录 git pull。
• 工具内部约定:各工具自行维护 .venv / requirements.txt / CLAUDE.md,与 apps/、services/ 子项目一致。

范围边界(YAGNI)

本次不做:

• tools/ 二级分类(扁平结构够用;待工具增至约 8 个再按用途细分)。
• 统一各工具的分支策略(各工具 CLAUDE.md 已有约定,如 pad_scanner/fastapi 用 master + dev)。
• 调整 apps/、services/ 现有结构。

风险与核实项

项	说明	处置
submodule URL 不一致	WareShipManifest 的 .gitmodules URL 与实际 remote 不同	实施前核实 Gitea 域名,统一
游离仓库历史	attachmentQRCodeGenerator 现有 .git 历史是否保留	默认保留并 push;若含敏感信息需先清理
备份文件体积	7 个 .bak xlsm 二进制	.gitignore 忽略 .bak
submodule 路径迁移	直接 mv 会破坏 submodule 登记	用 .gitmodules + 索引同步方式,非 mv

后续

本设计确认后,进入实施计划(writing-plans),产出可逐步执行的任务清单。