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

# 衍生工具目录组织与 Gitea URL 迁移 Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 把 `WareShipManifest` 与 `attachmentQRCodeGenerator` 两个衍生工具统一收纳到 `tools/` 下作为 submodule,并把全仓库 Gitea URL 从弃用的 `gitea.server10086.icu` 迁到 `gitea.misdev.icu`。

**Architecture:** 纯 Git 仓库结构操作,无代码逻辑变更。先统一 URL(让 push/fetch 可用),再建 `tools/` 目录与约定 README,然后把已存在的 `WareShipManifest` submodule 迁入 `tools/`,最后把游离的 `attachmentQRCodeGenerator` 仓库推上 Gitea 并作 submodule 加入 `tools/`。每个 task 以 git 状态命令作为验证(等价于本类任务的测试环节)。

**Tech Stack:** Git(主仓库 + submodule)、Gitea(`gitea.misdev.icu`)、SSH。

## Global Constraints

- 新 Gitea 域名:`gitea.misdev.icu`(旧域 `gitea.server10086.icu` 已弃用,完成后不得再出现于任何 remote 或 `.gitmodules`)。
- 仅替换域名,仓库路径与组织保持不变:主仓库 `admin/CargoTrace.git`,子项目 `CargoTrace/<name>.git`。
- 衍生工具一律作为 submodule 放 `tools/<原名>/`,保留原名(方案 C)。
- 所有命令在主仓库根目录 `D:\projects\CargoTrace` 执行;子仓库操作用 `git -C <path>`。
- 每步的「验证」命令必须通过后再进入下一步。
- 子项目分支约定:pad_scanner / fastapi 用 master + dev;attachmentQRCodeGenerator 当前在 master。本 plan 不改任何分支策略。

---

### Task 1: 统一 Gitea URL 到 gitea.misdev.icu

**Files:**
- Modify: `.gitmodules`(3 个 submodule 的 url)
- Modify: 主仓库 origin(`git remote set-url`)
- Modify: `apps/pad_scanner/.git/config`、`services/fastapi/.git/config`(子仓库 origin)

**Interfaces:**
- Produces: 主仓库与所有 submodule 的 fetch/push 均指向 `gitea.misdev.icu`。后续 task 的 `git push`、`git submodule update` 依赖此结果。

- [ ] **Step 1: 改主仓库 origin**

```bash
git remote set-url origin git@gitea.misdev.icu:admin/CargoTrace.git
```

- [ ] **Step 2: 验证主仓库 origin**

Run: `git remote -v`
Expected:
```
origin	git@gitea.misdev.icu:admin/CargoTrace.git (fetch)
origin	git@gitea.misdev.icu:admin/CargoTrace.git (push)
```

- [ ] **Step 3: 改 .gitmodules 三个 submodule URL**

```bash
git config --file .gitmodules submodule."apps/pad_scanner".url git@gitea.misdev.icu:CargoTrace/pad_scanner.git
git config --file .gitmodules submodule."services/fastapi".url git@gitea.misdev.icu:CargoTrace/fastAPI.git
git config --file .gitmodules submodule."WareShipManifest".url git@gitea.misdev.icu:CargoTrace/WareShipManifest.git
```

- [ ] **Step 4: 验证 .gitmodules URL 全为 misdev**

Run: `git config --file .gitmodules --list | grep url`
Expected:三行均含 `gitea.misdev.icu`,无 `server10086`。

- [ ] **Step 5: 同步 submodule 配置到各子仓库**

```bash
git submodule sync
```

- [ ] **Step 6: 修正 pad_scanner / fastapi 子仓库本地 remote**

(WareShipManifest 本地 remote 已是 misdev,跳过。)

```bash
git -C apps/pad_scanner remote set-url origin git@gitea.misdev.icu:CargoTrace/pad_scanner.git
git -C services/fastapi remote set-url origin git@gitea.misdev.icu:CargoTrace/fastAPI.git
```

- [ ] **Step 7: 验证三个子仓库 remote**

Run:
```bash
git -C apps/pad_scanner remote -v
git -C services/fastapi remote -v
git -C WareShipManifest remote -v
```
Expected:三组均只含 `gitea.misdev.icu`,无 `server10086`。

- [ ] **Step 8: 验证 misdev 可达(fetch)**

```bash
git fetch origin
git submodule foreach 'git fetch origin'
```
Expected:无报错。若 SSH 首次连接提示 host key,输入 `yes`(misdev.icu 已被 WareShipManifest 连过,known_hosts 多半已有)。

- [ ] **Step 9: Commit .gitmodules 改动**

```bash
git add .gitmodules
git commit -m "chore: migrate Gitea submodule URLs to gitea.misdev.icu"
```

- [ ] **Step 10: Push(此时 origin 已是 misdev,前两次 spec commit 一并推上)**

```bash
git push origin master
```
Expected:推送成功。若卡在 SSH 交互,改在终端手动:`! git push origin master`。

---

### Task 2: 创建 tools/ 目录与工具清单 README

**Files:**
- Create: `tools/README.md`

**Interfaces:**
- Produces: `tools/` 目录存在,后续 task 把 submodule 放入其中。

- [ ] **Step 1: 创建 tools/README.md**

写入以下完整内容:

````markdown
# 衍生工具(tools/)

本目录收纳 CargoTrace 主仓库的衍生工具,每个工具作为一个 Git Submodule 独立维护。

## 工具清单

| 工具 | 路径 | 用途 | 技术栈 | 仓库 |
|---|---|---|---|---|
| WareShipManifest | `tools/WareShipManifest/` | 装箱单 / 签收单 PDF 报表与打印服务 | Python + reportbro-lib + FastAPI | `gitea.misdev.icu:CargoTrace/WareShipManifest` |
| attachmentQRCodeGenerator | `tools/attachmentQRCodeGenerator/` | 压力表标签查询打印(VBA 导出代码) | VBA / Excel | `gitea.misdev.icu:CargoTrace/attachmentQRCodeGenerator` |

各工具的详细说明见各自目录下的 `README.md`。

## 新增工具流程

1. 在 `gitea.misdev.icu`(`CargoTrace` 组织下)建独立空仓库 `<工具名>`(不要初始化 README/.gitignore)。
2. 在主仓库执行:`git submodule add git@gitea.misdev.icu:CargoTrace/<工具名>.git tools/<工具名>`
3. 在本文件「工具清单」表登记一行。
4. `git add .gitmodules tools/<工具名> && git commit -m "chore: add <工具名> as submodule under tools/"`

## 更新工具到最新提交

```bash
# 单个工具
git submodule update --remote tools/<工具名>

# 或进入子目录直接操作
git -C tools/<工具名> pull
```

更新后需在主仓库提交 submodule 指针变化:`git add tools/<工具名> && git commit -m "chore: bump <工具名>"`。

## 工具内部约定

各工具自行维护 `.venv` / `requirements.txt` / `CLAUDE.md`,与 `apps/`、`services/` 子项目一致。
````

- [ ] **Step 2: 验证文件**

Run: `cat tools/README.md`
Expected:含工具清单表(两行)+ 新增 / 更新流程。

- [ ] **Step 3: Commit + Push**

```bash
git add tools/README.md
git commit -m "docs: add tools/ directory and registry for derivative tools"
git push origin master
```

---

### Task 3: 迁移 WareShipManifest 到 tools/

**Files:**
- Modify: `.gitmodules`(submodule "WareShipManifest" 的 path: `WareShipManifest` → `tools/WareShipManifest`)
- Move: gitlink `WareShipManifest` → `tools/WareShipManifest`

**Interfaces:**
- Consumes: Task 1(WareShipManifest remote 已是 misdev);Task 2(`tools/` 目录已存在)。
- Produces: `tools/WareShipManifest/` 作为可用 submodule;根目录 `WareShipManifest/` 不再存在。

- [ ] **Step 1: 用 git mv 迁移 submodule 路径**

```bash
git mv WareShipManifest tools/WareShipManifest
```

说明:`git mv` 会移动工作树、更新 `.gitmodules` 的 `path` 字段并调整 gitlink。

- [ ] **Step 2: 同步 submodule 配置**

```bash
git submodule sync
```

- [ ] **Step 3: 验证 .gitmodules path 已更新**

Run: `git config --file .gitmodules --list | grep WareShipManifest`
Expected:
```
submodule.WareShipManifest.path=tools/WareShipManifest
submodule.WareShipManifest.url=git@gitea.misdev.icu:CargoTrace/WareShipManifest.git
```

- [ ] **Step 4: 验证 submodule 在新路径可用**

Run:
```bash
git submodule status tools/WareShipManifest
git -C tools/WareShipManifest rev-parse HEAD
```
Expected:`git submodule status` 显示 `tools/WareShipManifest` + commit hash;`rev-parse HEAD` 正常输出 hash。

- [ ] **Step 5: 故障分支——若 Step 4 报 "not a git repository" 或 gitdir 指针断**

submodule 内部 `.git` 文件可能仍指向旧相对路径。修复:

```bash
# 查看当前 .git 指针
cat tools/WareShipManifest/.git
# 重写为正确相对路径(tools/WareShipManifest → 根 .git/modules/WareShipManifest 是上两级)
echo "gitdir: ../../.git/modules/WareShipManifest" > tools/WareShipManifest/.git
# 再次验证
git -C tools/WareShipManifest rev-parse HEAD
```

- [ ] **Step 6: 验证旧路径已不存在**

Run: `ls WareShipManifest 2>&1 || echo gone`
Expected:`gone`。

- [ ] **Step 7: Commit + Push**

```bash
git add -A
git commit -m "chore: move WareShipManifest submodule into tools/"
git push origin master
```

---

### Task 4: attachmentQRCodeGenerator 转 tools/ 下 submodule

**Files:**
- Create: gitea 仓库 `CargoTrace/attachmentQRCodeGenerator`(在 `gitea.misdev.icu`)
- Modify: 本地 `attachmentQRCodeGenerator/`(remote add + push)
- Create: `.gitmodules` 新增 `tools/attachmentQRCodeGenerator` 条目(由 `git submodule add` 自动产生)
- Move: 根目录 `attachmentQRCodeGenerator/` 移除,内容由 submodule 重新 clone

**Interfaces:**
- Consumes: Task 1(misdev 可达);Task 2(`tools/` 目录已存在)。
- Produces: `tools/attachmentQRCodeGenerator/` 作为 submodule;根目录游离仓库清除。

**前置事实(已核实):**
- 本地 `attachmentQRCodeGenerator` 是独立 git 仓库,分支 `master`,无 remote。
- 现有 `.gitignore` 已忽略 `*.bak`、`*.xlsm`、`*.btw`;仅版本化 `VBA-Excel/` 纯文本源码 + `.gitignore`(共 7 个跟踪文件)。**沿用此策略,本 task 不改动 `.gitignore`。**
- ⚠️ 后果:submodule clone 后**不含** `.xlsm` / `.btw` / `.bak`(均被忽略)。这些二进制工作文件需另行保管,不在本 plan 范围。

- [ ] **Step 1: 在 gitea.misdev.icu 建空仓库**

在 `gitea.misdev.icu` → 组织 `CargoTrace` → 新建仓库 `attachmentQRCodeGenerator`(**空仓库,不要初始化 README/.gitignore**,避免与本地 push 冲突)。

方式二选一:
- 手动:Gitea Web 界面操作。
- API(需对 misdev 有效的 `GITEA_TOKEN`):

```bash
curl -X POST "https://gitea.misdev.icu/api/v1/orgs/CargoTrace/repos" \
  -H "Authorization: token $GITEA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"attachmentQRCodeGenerator","private":true,"auto_init":false}'
```

- [ ] **Step 2: 给本地仓库设 remote**

```bash
git -C attachmentQRCodeGenerator remote add origin git@gitea.misdev.icu:CargoTrace/attachmentQRCodeGenerator.git
```

- [ ] **Step 3: 验证工作区干净**

Run: `git -C attachmentQRCodeGenerator status`
Expected:`nothing to commit, working tree clean`。若有改动,先在子仓库 commit 再继续。

- [ ] **Step 4: Push master 到远端**

```bash
git -C attachmentQRCodeGenerator push -u origin master
```
Expected:推送成功(远端创建 master 分支)。

- [ ] **Step 5: 验证远端可达**

Run: `git -C attachmentQRCodeGenerator ls-remote origin`
Expected:列出 `refs/heads/master` 及其 commit hash。

- [ ] **Step 6: 把根目录游离仓库移作备份**

```bash
mv attachmentQRCodeGenerator attachmentQRCodeGenerator.localbak
```

说明:备份保留本地未跟踪的 `.xlsm` / `.btw` / `.bak` 工作文件;待验证通过后再删。

- [ ] **Step 7: 作为 submodule 加入 tools/**

```bash
git submodule add git@gitea.misdev.icu:CargoTrace/attachmentQRCodeGenerator.git tools/attachmentQRCodeGenerator
```

说明:clone 到 `tools/attachmentQRCodeGenerator`,自动写入 `.gitmodules` + gitlink。

- [ ] **Step 8: 验证 submodule 与 .gitmodules**

Run:
```bash
git submodule status tools/attachmentQRCodeGenerator
git config --file .gitmodules --list | grep attachmentQRCodeGenerator
ls tools/attachmentQRCodeGenerator/VBA-Excel
```
Expected:status 显示 commit hash;.gitmodules 含 `tools/attachmentQRCodeGenerator` 条目且 url 为 misdev;`VBA-Excel/` 目录存在。

- [ ] **Step 9: 验证跟踪内容与备份一致**

Run:
```bash
diff -r attachmentQRCodeGenerator.localbak/VBA-Excel tools/attachmentQRCodeGenerator/VBA-Excel
```
Expected:无差异输出。

- [ ] **Step 10: 删除本地备份**

```bash
rm -rf attachmentQRCodeGenerator.localbak
```

- [ ] **Step 11: Commit + Push**

```bash
git add .gitmodules tools/attachmentQRCodeGenerator
git commit -m "chore: add attachmentQRCodeGenerator as submodule under tools/"
git push origin master
```

---

### Task 5: 更新根 README 并做全局收尾验证

**Files:**
- Modify: `README.md`(「项目结构」与「子仓库」章节加入 `tools/`)

**Interfaces:**
- Consumes: Task 1–4 全部完成。

- [ ] **Step 1: 更新 README.md 的项目结构树**

把 `README.md` 中:

```
├── apps/              # 应用层子模块
│   └── pad_scanner/  # Flutter Android 应用
├── services/          # 后端服务子模块
│   └── fastapi/      # FastAPI 后端服务
├── shared/            # 共享代码/库（待添加）
├── infra/             # 基础设施（待添加）
└── docs/              # 项目文档
```

替换为:

```
├── apps/                            # 应用层子模块
│   └── pad_scanner/                # Flutter Android 应用
├── services/                        # 后端服务子模块
│   └── fastapi/                    # FastAPI 后端服务
├── tools/                           # 衍生工具子模块
│   ├── WareShipManifest/           # 装箱单/签收单报表与打印
│   └── attachmentQRCodeGenerator/  # 压力表标签查询打印
└── docs/                            # 项目文档
```

- [ ] **Step 2: 在「子仓库」章节新增衍生工具小节**

在 README「子仓库」章节末尾(`attachmentQRCodeGenerator` 相关内容之前的位置,即 `## 项目结构` 之前)插入:

```
### 衍生工具 (tools/)
- **WareShipManifest**: `tools/WareShipManifest/` — 装箱单/签收单 PDF 报表与打印服务(Python + reportbro-lib)
- **attachmentQRCodeGenerator**: `tools/attachmentQRCodeGenerator/` — 压力表标签查询打印(VBA 导出代码)
- 详见 `tools/README.md`
```

- [ ] **Step 3: 验证 README**

Run: `grep -n "tools/" README.md`
Expected:命中多处,含 `tools/` 目录与两个工具条目。

- [ ] **Step 4: 全局验证——submodule 清单**

Run: `git submodule status`
Expected:四行,路径分别为 `apps/pad_scanner`、`services/fastapi`、`tools/WareShipManifest`、`tools/attachmentQRCodeGenerator`,全部无 `server10086`。

- [ ] **Step 5: 全局验证——所有 URL 为 misdev**

Run:
```bash
git remote -v
git config --file .gitmodules --list | grep url
```
Expected:全部 `gitea.misdev.icu`,无 `server10086`。

- [ ] **Step 6: 全局验证——根目录无游离工具目录**

Run: `ls -d WareShipManifest attachmentQRCodeGenerator 2>&1`
Expected:两者均 `No such file or directory`(已迁入 tools/)。

- [ ] **Step 7: Commit + Push**

```bash
git add README.md
git commit -m "docs: document tools/ directory and migrated submodules in README"
git push origin master
```

- [ ] **Step 8(可选,高级):全新 clone 验证**

在临时目录验证 `--recurse-submodules` 可正常拉取全部 submodule:

```bash
git clone --recurse-submodules git@gitea.misdev.icu:admin/CargoTrace.git /tmp/CargoTrace-verify
```
Expected:成功 clone 主仓库 + 4 个 submodule,无报错。验证后删除临时目录。