From f86f61863a0aeb2bfa08527557dd06bda98473ae Mon Sep 17 00:00:00 2001
From: Misaka_Company <pengqiangqiang0@gmail.com>
Date: Mon, 10 Aug 2026 12:25:49 +0800
Subject: [PATCH] docs: add tools/ directory and registry for derivative tools

Co-Authored-By: Claude <noreply@anthropic.com>
---
 tools/README.md | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)
 create mode 100644 tools/README.md

diff --git a/tools/README.md b/tools/README.md
new file mode 100644
index 0000000..5c2a2d4
--- /dev/null
+++ b/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/` 子项目一致。