chore: bump pad_scanner for release signing config

pad_scanner now signs release builds with a dedicated keystore (see apps/pad_scanner). Fixes cross-host signature mismatch.

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

.gitignore

@@ -17,4 +17,6 @@ Thumbs.db
 # AI Agents
 .claude/
 .sisyphus/
-.agents/
+.agents/
+
+tmp/

.gitmodules

@@ -1,6 +1,12 @@
 [submodule "apps/pad_scanner"]
 	path = apps/pad_scanner
-	url = git@gitea.server10086.icu:CargoTrace/pad_scanner.git
+	url = git@gitea.misdev.icu:CargoTrace/pad_scanner.git
 [submodule "services/fastapi"]
 	path = services/fastapi
-	url = git@gitea.server10086.icu:CargoTrace/fastAPI.git
+	url = git@gitea.misdev.icu:CargoTrace/fastAPI.git
+[submodule "WareShipManifest"]
+	path = tools/WareShipManifest
+	url = git@gitea.misdev.icu:CargoTrace/WareShipManifest.git
+[submodule "tools/attachmentQRCodeGenerator"]
+	path = tools/attachmentQRCodeGenerator
+	url = git@gitea.misdev.icu:CargoTrace/attachmentQRCodeGenerator.git

README.md

@@ -8,27 +8,33 @@
 
 ### Android 端 (Flutter)
 - **路径**: `apps/pad_scanner`
-- **仓库**: `git@gitea.server10086.icu:admin/pad_scanner.git`
+- **仓库**: `git@gitea.misdev.icu:CargoTrace/pad_scanner.git`
 - **技术栈**: Flutter
 - **说明**: 基于 Flutter 框架的安卓应用，用于货物扫描和追踪
 
 ### 后端服务 (FastAPI)
 - **路径**: `services/fastapi`
-- **仓库**: `git@gitea.server10086.icu:CargoTrace/fastAPI.git`
+- **仓库**: `git@gitea.misdev.icu:CargoTrace/fastAPI.git`
 - **技术栈**: FastAPI (Python)
 - **说明**: 后端 API 服务
 
+### 衍生工具 (tools/)
+- **WareShipManifest** (`tools/WareShipManifest/`): 装箱单/签收单 PDF 报表与打印服务,Python + reportbro-lib,仓库 `gitea.misdev.icu:CargoTrace/WareShipManifest`
+- **attachmentQRCodeGenerator** (`tools/attachmentQRCodeGenerator/`): 压力表标签查询打印,VBA 导出代码,仓库 `gitea.misdev.icu:CargoTrace/attachmentQRCodeGenerator`
+- 详见 `tools/README.md`
+
 ## 项目结构
 
 ```
 CargoTrace/
-├── apps/              # 应用层子模块
-│   └── pad_scanner/  # Flutter Android 应用
-├── services/          # 后端服务子模块
-│   └── fastapi/      # FastAPI 后端服务
-├── shared/            # 共享代码/库（待添加）
-├── infra/             # 基础设施（待添加）
-└── docs/              # 项目文档
+├── apps/                            # 应用层子模块
+│   └── pad_scanner/                # Flutter Android 应用
+├── services/                        # 后端服务子模块
+│   └── fastapi/                    # FastAPI 后端服务
+├── tools/                           # 衍生工具子模块
+│   ├── WareShipManifest/           # 装箱单/签收单报表与打印
+│   └── attachmentQRCodeGenerator/  # 压力表标签查询打印
+└── docs/                            # 项目文档
 ```
 
 ## 开发指南

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,无报错。验证后删除临时目录。

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

@@ -0,0 +1,123 @@
+# 衍生工具目录组织设计
+
+> 日期: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 已确认统一**:Gitea 已整体从 `gitea.server10086.icu` 迁移至 `gitea.misdev.icu`,旧域名弃用(详见「URL 统一」节)。WareShipManifest 子仓库 remote 已指向 misdev,`.gitmodules` 待同步。
+- 子仓库当前默认分支为 `main`,与 `apps/`、`services/` 的 `master` 不一致(记录,本次不强改)。
+
+### attachmentQRCodeGenerator(游离仓库转正)
+
+- 现状:有独立 `.git`,主仓库不跟踪,无 remote。
+- 三步:
+  1. 在 `gitea.misdev.icu`(`CargoTrace` 组织下)建独立仓库 `attachmentQRCodeGenerator`。
+  2. 为本地仓库设 remote,推送现有提交历史。
+  3. 在主仓库执行 `git submodule add <url> tools/attachmentQRCodeGenerator`,纳入管理。
+- ℹ️ **版本管理策略(沿用现状)**:该仓库现有 `.gitignore` 已忽略 `*.bak`、`*.xlsm`、`*.btw`,仅版本化 `VBA-Excel/` 纯文本源码 + `.gitignore`(共 7 个跟踪文件,分支 `master`)。转 submodule 时沿用此策略,不改动 `.gitignore`。
+- ⚠️ **后果**:submodule clone 后**不含** `.xlsm` / `.btw` / `.bak`(均被忽略)。这些二进制工作文件需另行保管,是否纳入版本库超出本设计范围。
+
+## URL 统一(Gitea 迁移)
+
+> 旧域名 `gitea.server10086.icu` 已弃用,全仓库 Gitea URL 统一迁移至 `gitea.misdev.icu`。**只换域名**,仓库路径与组织不变。
+
+需修改的对象:
+
+| 对象 | 当前 | 目标 |
+|---|---|---|
+| 主仓库 origin | `git@gitea.server10086.icu:admin/CargoTrace.git` | `git@gitea.misdev.icu:admin/CargoTrace.git` |
+| `.gitmodules` · pad_scanner | `git@gitea.server10086.icu:CargoTrace/pad_scanner.git` | `…@gitea.misdev.icu:CargoTrace/pad_scanner.git` |
+| `.gitmodules` · fastapi | `git@gitea.server10086.icu:CargoTrace/fastAPI.git` | `…@gitea.misdev.icu:CargoTrace/fastAPI.git` |
+| `.gitmodules` · WareShipManifest | `git@gitea.server10086.icu:CargoTrace/WareShipManifest.git` | `…@gitea.misdev.icu:CargoTrace/WareShipManifest.git` |
+| pad_scanner 本地 remote | `gitea.server10086.icu` | `git -C apps/pad_scanner remote set-url origin <misdev>` |
+| fastapi 本地 remote | `gitea.server10086.icu` | `git -C services/fastapi remote set-url origin <misdev>` |
+| WareShipManifest 本地 remote | 已是 `gitea.misdev.icu` ✓ | 无需改 |
+| attachmentQRCodeGenerator | 新建 | `git@gitea.misdev.icu:CargoTrace/attachmentQRCodeGenerator.git` |
+
+说明:改 `.gitmodules` 只影响新 clone 的来源;已 checkout 的子仓库需另行 `git remote set-url`。换 URL 不改变 submodule 指向的 commit,无内容风险。
+
+## 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)
+
+本次**纳入**:
+
+- 全仓库 Gitea URL 统一到 `gitea.misdev.icu`(旧域 `gitea.server10086.icu` 已弃用)。见「URL 统一」节。
+
+本次**不做**:
+
+- `tools/` 二级分类(扁平结构够用;待工具增至约 8 个再按用途细分)。
+- 统一各工具的分支策略(各工具 CLAUDE.md 已有约定,如 pad_scanner/fastapi 用 master + dev)。
+- 调整 `apps/`、`services/` 现有结构。
+
+## 风险与核实项
+
+| 项 | 说明 | 处置 |
+|---|---|---|
+| submodule URL 旧域弃用 | 全仓库仍引用 `gitea.server10086.icu`(已弃用) | 统一改为 `gitea.misdev.icu`,见「URL 统一」节 |
+| 游离仓库历史 | attachmentQRCodeGenerator 现有 `.git` 历史是否保留 | 默认保留并 push;若含敏感信息需先清理 |
+| 备份文件体积 | 7 个 `.bak` xlsm 二进制 | `.gitignore` 忽略 `.bak` |
+| submodule 路径迁移 | 直接 `mv` 会破坏 submodule 登记 | 用 `.gitmodules` + 索引同步方式,非 `mv` |
+
+## 后续
+
+本设计确认后,进入实施计划(writing-plans),产出可逐步执行的任务清单。

tools/README.md

@@ -0,0 +1,35 @@
+# 衍生工具(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/` 子项目一致。