From aafc2528a3e6f9c02a8ab6b16f5f37f504ffa223 Mon Sep 17 00:00:00 2001 From: Misaka_Company Date: Mon, 10 Aug 2026 12:05:13 +0800 Subject: [PATCH] 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 --- ...026-08-10-derivative-tools-organization.md | 434 ++++++++++++++++++ ...10-derivative-tools-organization-design.md | 3 +- 2 files changed, 436 insertions(+), 1 deletion(-) create mode 100644 docs/superpowers/plans/2026-08-10-derivative-tools-organization.md diff --git a/docs/superpowers/plans/2026-08-10-derivative-tools-organization.md b/docs/superpowers/plans/2026-08-10-derivative-tools-organization.md new file mode 100644 index 0000000..90c9dc9 --- /dev/null +++ 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/.git`。 +- 衍生工具一律作为 submodule 放 `tools/<原名>/`,保留原名(方案 C)。 +- 所有命令在主仓库根目录 `D:\projects\CargoTrace` 执行;子仓库操作用 `git -C `。 +- 每步的「验证」命令必须通过后再进入下一步。 +- 子项目分支约定: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,无报错。验证后删除临时目录。 diff --git a/docs/superpowers/specs/2026-08-10-derivative-tools-organization-design.md b/docs/superpowers/specs/2026-08-10-derivative-tools-organization-design.md index b94e9dd..9193436 100644 --- 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 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 迁移)