docs: add implementation plan for tools/ reorganization

Five-task plan: Gitea URL unification (server10086 -> misdev), tools/ dir + README, WareShipManifest submodule move, attachmentQRCodeGenerator promotion to submodule, root README update. Also refines spec: attachmentQRCodeGenerator .gitignore already ignores bak/xlsm/btw, only VBA-Excel/ source is versioned. Co-Authored-By: Claude <noreply@anthropic.com>
2026-08-10 12:05:13 +08:00
parent 7402b169c6
commit aafc2528a3
2 changed files with 436 additions and 1 deletions
--- a/docs/superpowers/plans/2026-08-10-derivative-tools-organization.md
+++ b/docs/superpowers/plans/2026-08-10-derivative-tools-organization.md
@@ -0,0 +1,434 @@
+# 衍生工具目录组织与 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,无报错。验证后删除临时目录。
--- a/docs/superpowers/specs/2026-08-10-derivative-tools-organization-design.md
+++ b/docs/superpowers/specs/2026-08-10-derivative-tools-organization-design.md
@@ -63,7 +63,8 @@ CargoTrace/
  1. 在 `gitea.misdev.icu`(`CargoTrace` 组织下)建独立仓库 `attachmentQRCodeGenerator`。
  2. 为本地仓库设 remote,推送现有提交历史。
  3. 在主仓库执行 `git submodule add <url> tools/attachmentQRCodeGenerator`,纳入管理。
- ⚠️ **备份文件**:目录内含 7 个 `*.bak.*.xlsm` 备份。建仓时需定 `.gitignore`,建议忽略 `.bak` 文件,仅纳入当前 `压力表标签查询打印_界面预览.xlsm`、`附件标签-刘洪.btw` 以及 `VBA-Excel/` 源码。
+- ℹ️ **版本管理策略(沿用现状)**:该仓库现有 `.gitignore` 已忽略 `*.bak`、`*.xlsm`、`*.btw`,仅版本化 `VBA-Excel/` 纯文本源码 + `.gitignore`(共 7 个跟踪文件,分支 `master`)。转 submodule 时沿用此策略,不改动 `.gitignore`。
+- ⚠️ **后果**:submodule clone 后**不含** `.xlsm` / `.btw` / `.bak`(均被忽略)。这些二进制工作文件需另行保管,是否纳入版本库超出本设计范围。

 ## URL 统一(Gitea 迁移)