# 衍生工具目录组织设计

> 日期: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),产出可逐步执行的任务清单。