aafc2528a3
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 <noreply@anthropic.com>
124 lines
6.4 KiB
Markdown
124 lines
6.4 KiB
Markdown
# 衍生工具目录组织设计
|
||
|
||
> 日期: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),产出可逐步执行的任务清单。
|