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,3 +17,6 @@ Thumbs.db
 # AI Agents
 .claude/
 .sisyphus/
+.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,16 +8,21 @@
 
 ### 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`
+
 ## 项目结构
 
 ```
@@ -26,8 +31,9 @@ CargoTrace/
 │   └── pad_scanner/                # Flutter Android 应用
 ├── services/                        # 后端服务子模块
 │   └── fastapi/                    # FastAPI 后端服务
-├── shared/            # 共享代码/库（待添加）
-├── infra/             # 基础设施（待添加）
+├── tools/                           # 衍生工具子模块
+│   ├── WareShipManifest/           # 装箱单/签收单报表与打印
+│   └── attachmentQRCodeGenerator/  # 压力表标签查询打印
 └── docs/                            # 项目文档
 ```
 

docs/plans/2026-05-12-work-order-no-display.md

@@ -2,9 +2,9 @@
 
 > **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
 
-**Goal:** 在装箱编号模块的信息区增加工令号（work_order_no）显示，采用"字段名称一行、实际值一行"的两行布局，排产号和工令号并排展示。
+**Goal:** 在装箱编号模块的信息区增加工令号（work_order_no）显示。信息区不显示字段名称，只并排显示排产号和工令号的具体值，并通过更大字号和加粗突出关键信息；装箱详情页也同步显示工令号。
 
-**Architecture:** 后端从 ERP 视图 `vw_productionContractData` 额外查询 `工令号` 列，通过已有的 `/box/info` 接口返回给前端。Flutter 端解析后渲染为两行布局（标签行 + 值行）。
+**Architecture:** 后端从 ERP 视图 `vw_productionContractData` 额外查询 `工令号` 列，通过已有的 `/box/info` 接口返回给前端。Flutter 端解析后，在装箱主页面信息区和装箱详情页中展示。
 
 **Tech Stack:** FastAPI + SQLAlchemy (后端), Flutter (前端), PostgreSQL (连接 ERP 视图)
 
@@ -126,8 +126,8 @@ def test_box_info_success(client: TestClient):
     data = resp.json()
     assert data["zongpai_no"] == "26BW0011"
     assert data["paichan_no"] == "W00009"
-    assert data["work_order_no"] is not None
-    assert isinstance(data["work_order_no"], str)
+    assert "work_order_no" in data
+    assert data["work_order_no"] is None or isinstance(data["work_order_no"], str)
     assert data["quantity"] == 80
     assert "existing_boxes" in data
     assert "max_box_no" in data
@@ -142,7 +142,7 @@ source ../../.venv/Scripts/activate  # 或项目虚拟环境
 pytest tests/test_box_api.py -v
 ```
 
-预期：`test_box_info_success` 通过，`work_order_no` 有值。
+预期：`test_box_info_success` 通过，响应中包含 `work_order_no` 字段。
 
 **Step 3: 格式化代码**
 
@@ -202,7 +202,7 @@ class BoxInfoResult {
       success: true,
       zongpaiNo: json['zongpai_no'] as String?,
       paichanNo: json['paichan_no'] as String?,
-      workOrderNo: json['work_order_no'] as String?,
+      workOrderNo: json['work_order_no']?.toString(),
       quantity: json['quantity'] as int?,
       existingBoxes: boxes,
       maxBoxNo: json['max_box_no'] as int? ?? 0,
@@ -270,7 +270,7 @@ setState(() {
 
 ---
 
-### Task 6: 重写信息区 UI — 两行布局
+### Task 6: 重写信息区 UI — 仅显示值并突出关键信息
 
 **Files:**
 - Modify: `apps/pad_scanner/lib/pages/boxing_page.dart` (`_buildInfoArea` 方法，约第 659-744 行)
@@ -278,57 +278,41 @@ setState(() {
 **Step 1: 用新布局替换整个 `_buildInfoArea` 方法**
 
 将原来的 `排产号标签 → 排产号值 → 已有箱数/最大箱号` 布局，改为：
-- 第一行：`排产号：` + `工令号：`（标签行）
-- 第二行：`W00009` + `6-1(7)`（值行）
-- 第三行：`已有箱数：3箱  最大箱号：3` + `详情 →`（不变）
+- 第一行：只显示具体值，`W00009` 和 `6-1(7)` 两列并排，不显示 `排产号：`、`工令号：` 字段名称
+- 排产号和工令号都使用更大字号、加粗，等待状态显示 `--`
+- 第二行：`已有箱数：3箱  最大箱号：3` + `详情 →`（不变）
 
 ```dart
 Widget _buildInfoArea(bool isWaiting, ColorScheme colorScheme) {
     final grey = isWaiting;
+    final paichanText = grey ? '--' : (_paichanNo ?? '--');
+    final workOrderText = grey ? '--' : (_workOrderNo ?? '--');
 
     return Column(
       crossAxisAlignment: CrossAxisAlignment.start,
       children: [
-        // 字段名称行：排产号 + 工令号
-        Row(
-          children: [
-            Text(
-              '排产号：',
-              style: TextStyle(
-                fontSize: 13,
-                color: grey ? Colors.grey : Colors.black54,
-              ),
-            ),
-            const SizedBox(width: 24),
-            Text(
-              '工令号：',
-              style: TextStyle(
-                fontSize: 13,
-                color: grey ? Colors.grey : Colors.black54,
-              ),
-            ),
-          ],
-        ),
-        const SizedBox(height: 2),
-        // 实际值行
+        // 排产号 + 工令号：只显示值，突出关键信息
         Row(
           children: [
             Expanded(
               child: Text(
-                _paichanNo ?? '--',
+                paichanText,
                 style: TextStyle(
-                  fontSize: 16,
-                  fontWeight: FontWeight.w600,
+                  fontSize: 20,
+                  fontWeight: FontWeight.w700,
                   color: grey ? Colors.grey : Colors.black87,
                 ),
                 overflow: TextOverflow.ellipsis,
               ),
             ),
+            const SizedBox(width: 12),
             Expanded(
               child: Text(
-                _workOrderNo ?? '--',
+                workOrderText,
+                textAlign: TextAlign.right,
                 style: TextStyle(
-                  fontSize: 14,
+                  fontSize: 18,
+                  fontWeight: FontWeight.w700,
                   color: grey ? Colors.grey : Colors.black87,
                 ),
                 overflow: TextOverflow.ellipsis,
@@ -336,7 +320,7 @@ Widget _buildInfoArea(bool isWaiting, ColorScheme colorScheme) {
             ),
           ],
         ),
-        const SizedBox(height: 8),
+        const SizedBox(height: 10),
 
         // 已有箱数 + 最大箱号 + 详情按钮（不变）
         Row(
@@ -415,7 +399,102 @@ flutter analyze lib/pages/boxing_page.dart
 
 ---
 
-### Task 7: 构建、安装并手动验证
+### Task 7: 在装箱详情页显示工令号
+
+**Files:**
+- Modify: `apps/pad_scanner/lib/pages/boxing_page.dart` (`_openDetail` 方法)
+- Modify: `apps/pad_scanner/lib/pages/boxing_detail_page.dart`
+
+**Step 1: 给 `BoxingDetailPage` 增加工令号参数**
+
+在 `BoxingDetailPage` 中新增 `workOrderNo` 字段，并在构造函数中要求传入：
+
+```dart
+class BoxingDetailPage extends StatelessWidget {
+  final String paichanNo;
+  final String workOrderNo;
+  final List<BoxDetailData> existingBoxes;
+
+  const BoxingDetailPage({
+    super.key,
+    required this.paichanNo,
+    required this.workOrderNo,
+    required this.existingBoxes,
+  });
+```
+
+**Step 2: 在详情页标题区域显示排产号和工令号**
+
+将 AppBar 标题中的单个 `paichanNo` 文本改成更紧凑的两行展示：
+
+```dart
+appBar: AppBar(
+  title: Row(
+    children: [
+      const Text('装箱详情'),
+      const SizedBox(width: 12),
+      Expanded(
+        child: Column(
+          crossAxisAlignment: CrossAxisAlignment.start,
+          mainAxisSize: MainAxisSize.min,
+          children: [
+            Text(
+              paichanNo,
+              style: const TextStyle(
+                fontSize: 14,
+                fontWeight: FontWeight.w600,
+              ),
+              overflow: TextOverflow.ellipsis,
+            ),
+            Text(
+              workOrderNo,
+              style: const TextStyle(
+                fontSize: 12,
+                fontWeight: FontWeight.w500,
+              ),
+              overflow: TextOverflow.ellipsis,
+            ),
+          ],
+        ),
+      ),
+    ],
+  ),
+),
+```
+
+如果工令号为空，传入方应使用 `--`，避免详情页出现空白。
+
+**Step 3: 从装箱主页面传入工令号**
+
+修改 `_openDetail`：
+
+```dart
+void _openDetail() {
+  Navigator.push(
+    context,
+    MaterialPageRoute(
+      builder: (_) => BoxingDetailPage(
+        paichanNo: _paichanNo ?? '',
+        workOrderNo: _workOrderNo ?? '--',
+        existingBoxes: _existingBoxes,
+      ),
+    ),
+  );
+}
+```
+
+**Step 4: 验证编译和静态分析**
+
+```bash
+cd apps/pad_scanner
+flutter analyze lib/pages/boxing_page.dart lib/pages/boxing_detail_page.dart
+```
+
+预期：无错误。
+
+---
+
+### Task 8: 构建、安装并手动验证
 
 **Step 1: 构建 APK**
 
@@ -434,16 +513,18 @@ adb install -r build/app/outputs/flutter-apk/app-release.apk
 
 在设备上操作：
 1. 进入装箱编号页面
-2. 确认等待状态下信息区显示 `排产号：` 和 `工令号：` 标签并排，值均为 `--`
+2. 确认等待状态下信息区不显示字段名称，只显示两个并排的 `--`
 3. 扫描一个真实的执行卡（如 `26BW0011`）
 4. 确认信息区显示：
-   - 标签行：`排产号：` | `工令号：`
-   - 值行：`W00009`（加粗）| `6-1(7)`（常规）
-5. 在三种模式下分别测试确认布局正确
+   - `W00009` 和 `6-1(7)` 两个值并排
+   - 两个值都比原信息区更醒目，并且加粗
+   - 不显示 `排产号：`、`工令号：` 标签
+5. 点击 `详情 →`，确认装箱详情页显示排产号和工令号
+6. 在三种模式下分别测试确认布局正确
 
 **Step 4: 提交**
 
 ```bash
-git add apps/pad_scanner/lib/services/api_service.dart apps/pad_scanner/lib/pages/boxing_page.dart
-git commit -m "feat(boxing): display work order number in info area with two-row layout"
+git add apps/pad_scanner/lib/services/api_service.dart apps/pad_scanner/lib/pages/boxing_page.dart apps/pad_scanner/lib/pages/boxing_detail_page.dart
+git commit -m "feat(boxing): display work order number in boxing views"
 ```

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/` 子项目一致。