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

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

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 配置到各子仓库

git submodule sync

• Step 6: 修正 pad_scanner / fastapi 子仓库本地 remote

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

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:

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)

git fetch origin
git submodule foreach 'git fetch origin'

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

• Step 9: Commit .gitmodules 改动

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

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

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

写入以下完整内容:

# 衍生工具(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

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 路径

git mv WareShipManifest tools/WareShipManifest

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

• Step 2: 同步 submodule 配置

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:

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 文件可能仍指向旧相对路径。修复:

# 查看当前 .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

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):

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

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 到远端

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: 把根目录游离仓库移作备份

mv attachmentQRCodeGenerator attachmentQRCodeGenerator.localbak

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

• Step 7: 作为 submodule 加入 tools/

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

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

• Step 8: 验证 submodule 与 .gitmodules

Run:

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:

diff -r attachmentQRCodeGenerator.localbak/VBA-Excel tools/attachmentQRCodeGenerator/VBA-Excel

Expected:无差异输出。

• Step 10: 删除本地备份

rm -rf attachmentQRCodeGenerator.localbak

• Step 11: Commit + Push

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:

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

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:

git clone --recurse-submodules git@gitea.misdev.icu:admin/CargoTrace.git /tmp/CargoTrace-verify

Expected:成功 clone 主仓库 + 4 个 submodule,无报错。验证后删除临时目录。