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 已确认统一:Gitea 已整体从 gitea.server10086.icu 迁移至 gitea.misdev.icu,旧域名弃用(详见「URL 统一」节)。WareShipManifest 子仓库 remote 已指向 misdev,.gitmodules 待同步。
• 子仓库当前默认分支为 main,与 apps/、services/ 的 master 不一致(记录,本次不强改)。

attachmentQRCodeGenerator(游离仓库转正)

• 现状:有独立 .git,主仓库不跟踪,无 remote。
• 三步:
  1. 在 gitea.misdev.icu(CargoTrace 组织下)建独立仓库 attachmentQRCodeGenerator。
  2. 为本地仓库设 remote,推送现有提交历史。
  3. 在主仓库执行 git submodule add <url> tools/attachmentQRCodeGenerator,纳入管理。
• ℹ️ 版本管理策略(沿用现状):该仓库现有 .gitignore 已忽略 *.bak、*.xlsm、*.btw,仅版本化 VBA-Excel/ 纯文本源码 + .gitignore(共 7 个跟踪文件,分支 master)。转 submodule 时沿用此策略,不改动 .gitignore。
• ⚠️ 后果:submodule clone 后不含 .xlsm / .btw / .bak(均被忽略)。这些二进制工作文件需另行保管,是否纳入版本库超出本设计范围。

URL 统一(Gitea 迁移)

旧域名 gitea.server10086.icu 已弃用,全仓库 Gitea URL 统一迁移至 gitea.misdev.icu。只换域名,仓库路径与组织不变。

需修改的对象:

对象	当前	目标
主仓库 origin	git@gitea.server10086.icu:admin/CargoTrace.git	git@gitea.misdev.icu:admin/CargoTrace.git
.gitmodules · pad_scanner	git@gitea.server10086.icu:CargoTrace/pad_scanner.git	…@gitea.misdev.icu:CargoTrace/pad_scanner.git
.gitmodules · fastapi	git@gitea.server10086.icu:CargoTrace/fastAPI.git	…@gitea.misdev.icu:CargoTrace/fastAPI.git
.gitmodules · WareShipManifest	git@gitea.server10086.icu:CargoTrace/WareShipManifest.git	…@gitea.misdev.icu:CargoTrace/WareShipManifest.git
pad_scanner 本地 remote	gitea.server10086.icu	git -C apps/pad_scanner remote set-url origin <misdev>
fastapi 本地 remote	gitea.server10086.icu	git -C services/fastapi remote set-url origin <misdev>
WareShipManifest 本地 remote	已是 gitea.misdev.icu ✓	无需改
attachmentQRCodeGenerator	新建	git@gitea.misdev.icu:CargoTrace/attachmentQRCodeGenerator.git

说明:改 .gitmodules 只影响新 clone 的来源;已 checkout 的子仓库需另行 git remote set-url。换 URL 不改变 submodule 指向的 commit,无内容风险。

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)

本次纳入:

• 全仓库 Gitea URL 统一到 gitea.misdev.icu(旧域 gitea.server10086.icu 已弃用)。见「URL 统一」节。

本次不做:

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

风险与核实项

项	说明	处置
submodule URL 旧域弃用	全仓库仍引用 gitea.server10086.icu(已弃用)	统一改为 gitea.misdev.icu,见「URL 统一」节
游离仓库历史	attachmentQRCodeGenerator 现有 .git 历史是否保留	默认保留并 push;若含敏感信息需先清理
备份文件体积	7 个 .bak xlsm 二进制	.gitignore 忽略 .bak
submodule 路径迁移	直接 mv 会破坏 submodule 登记	用 .gitmodules + 索引同步方式,非 mv

后续

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