docs: add spec for organizing derivative tools under tools/
Establishes a tools/ top-level directory for derivative tooling (WareShipManifest, attachmentQRCodeGenerator) as submodules, with a README convention for adding future tools. Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Misaka_Company
@@ -0,0 +1,99 @@
|
||||
# 衍生工具目录组织设计
|
||||
|
||||
> 日期: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 隐患**:`.gitmodules` 中该 submodule 的 URL 为 `git@gitea.server10086.icu:CargoTrace/WareShipManifest.git`,而子仓库实际 remote 指向 `git@gitea.misdev.icu:CargoTrace/WareShipManifest.git`。实施时需核实两个域名是否指向同一 Gitea 实例,并统一 `.gitmodules` URL,避免 `git submodule update --init` 拉错源。
|
||||
- 子仓库当前默认分支为 `main`,与 `apps/`、`services/` 的 `master` 不一致(记录,本次不强改)。
|
||||
|
||||
### attachmentQRCodeGenerator(游离仓库转正)
|
||||
|
||||
- 现状:有独立 `.git`,主仓库不跟踪,无 remote。
|
||||
- 三步:
|
||||
1. 在 Gitea(`CargoTrace` 组织下)建独立仓库。
|
||||
2. 为本地仓库设 remote,推送现有提交历史。
|
||||
3. 在主仓库执行 `git submodule add <url> tools/attachmentQRCodeGenerator`,纳入管理。
|
||||
- ⚠️ **备份文件**:目录内含 7 个 `*.bak.*.xlsm` 备份。建仓时需定 `.gitignore`,建议忽略 `.bak` 文件,仅纳入当前 `压力表标签查询打印_界面预览.xlsm`、`附件标签-刘洪.btw` 以及 `VBA-Excel/` 源码。
|
||||
|
||||
## 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)
|
||||
|
||||
本次**不做**:
|
||||
|
||||
- `tools/` 二级分类(扁平结构够用;待工具增至约 8 个再按用途细分)。
|
||||
- 统一各工具的分支策略(各工具 CLAUDE.md 已有约定,如 pad_scanner/fastapi 用 master + dev)。
|
||||
- 调整 `apps/`、`services/` 现有结构。
|
||||
|
||||
## 风险与核实项
|
||||
|
||||
| 项 | 说明 | 处置 |
|
||||
|---|---|---|
|
||||
| submodule URL 不一致 | WareShipManifest 的 `.gitmodules` URL 与实际 remote 不同 | 实施前核实 Gitea 域名,统一 |
|
||||
| 游离仓库历史 | attachmentQRCodeGenerator 现有 `.git` 历史是否保留 | 默认保留并 push;若含敏感信息需先清理 |
|
||||
| 备份文件体积 | 7 个 `.bak` xlsm 二进制 | `.gitignore` 忽略 `.bak` |
|
||||
| submodule 路径迁移 | 直接 `mv` 会破坏 submodule 登记 | 用 `.gitmodules` + 索引同步方式,非 `mv` |
|
||||
|
||||
## 后续
|
||||
|
||||
本设计确认后,进入实施计划(writing-plans),产出可逐步执行的任务清单。
|
||||
Reference in New Issue
Block a user