docs: add spec for organizing derivative tools under tools/

Establishes a tools/ top-level directory for derivative tooling (WareShipManifest, attachmentQRCodeGenerator) as submodules, with a README convention for adding future tools.

Co-Authored-By: Claude <noreply@anthropic.com>

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

@@ -0,0 +1,99 @@
+# 衍生工具目录组织设计
+
+> 日期: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),产出可逐步执行的任务清单。