# 需求:admin-cli-create-生成不出项目-默认模板版本-v2.0.0-分支不存在+远端落后9个commit缺-starter-app

状态: done(2026-10-20 已上线:模板 3cc446e+b2caed9 cli 2.0.1：finally 双清临时/半成品目录、结构预检人话报错、-t 本机路径、rewriteBrandIdentity 品牌位改写（标题/namespace/包名）、assertCoreModuleHashes 预检；npm test 13/13；远端 -v main 端到端 create 0/backend build 0/test 0/pnpm install 0/build 0/渲染 PASS)
归属: 主会话(Admin_Template 主)
来源: 登记缺口(ops/products/)
日期: 2026-10-16
建议: 做,2026-10-16 立项入职中间件时实测:①admin-cli create 默认 -v v2.0.0,而模板远端只有 main(标签是 backend/core/v2.0.0-alpha.9),报 fatal: Remote branch v2.0.0 not found;②改 -v main 后报 ENOENT backend/starter-app——本机 Admin_Template 领先 origin/main 9 个 commit(含 starter-app 与 docs/ADMIN-CORE-CONTRACT.md 改动)且带未提交 WIP,没 push,生成器从远端克隆拿不到新结构。绕法:-t D:/code/work/lin/Admin_Template -v main 用本地模板生成成功。公司『新项目一律 CLI 生成』的口径在这条链上是断的,别的新项目还会撞。

## 现状

2026-10-16 立项「入职中间件(onboard-hub)」时按公司口径用 `admin-cli create` 生成 Go+Vben 骨架,连续两次失败,实测证据:

1. 默认路径(`node Admin_Template/cli/bin/admin-cli.js create onboard-hub -n "入职中间件"`)→ `fatal: Remote branch v2.0.0 not found in upstream origin`。CLI 里硬写 `-v, --version` 默认值 `v2.0.0`,而模板仓 `111.229.223.148:13000/linxianqinwork/Admin_Template.git` **只有 main 分支**,标签形态是 `backend/core/v2.0.0-alpha.9` 这类,**没有 `v2.0.0` 分支**。
2. 改 `-v main` 再跑 → `Error: ENOENT: lstat '...\.admin-template-1792131961567\backend\starter-app'`。CLI 期望模板里有 `backend/starter-app`,而远端 main 上没有。
3. 根因:本机 `D:\code\work\lin\Admin_Template` **领先 origin/main 9 个 commit**(`git status -sb` = `## main...origin/main [ahead 9]`),`backend/starter-app` 与 `docs/ADMIN-CORE-CONTRACT.md` 的改动都只在本地、**没 push**;生成器从远端克隆,自然拿不到新结构。本地同时带未提交 WIP(`M docs/ADMIN-CORE-CONTRACT.md`、`?? backend/starter-app/internal/message/`),按并发纪律他人不得代 push。
4. 影响面:公司硬规则「新项目/新模块骨架一律 CLI 生成,不让 AI 从零手写」在这条链上是断的——除本项目外,任何新项目走默认命令都生不出来;`pdgen` 的 `admin-web` 只出前端薄壳(Go 后端不在其中),所以这不是「换个工具」能绕的。
5. 本次绕法(已生效):`-t D:/code/work/lin/Admin_Template -v main`(用本地模板克隆),生成成功 `D:\code\work\lin\onboard-hub`(backend + frontend + docker-compose)。
6. 顺带缺陷:两次失败各在 `D:\code\work\lin\` 留下 `.admin-template-*` 临时克隆(7.3 MB,已清理),生成器异常路径不清理临时目录。
7. **go.mod 注释逻辑被压坏**:生成物 `backend/go.mod` 尾部注释行写「CLI 复制到业务项目时会自动注释此行,改用发布版 core」,下一行只留了个空注释 `// `,而 `replace github.com/linxianqinwork/Admin_Template/backend/core/v2 => ../core` **仍是启用状态** → 首次 `go build ./...` 直接报 `replacement directory ../core does not exist`(6 处)。CLI 的「注释掉 replace、改用发布版」这个意图**没有生效**。
8. **发布版 core 与生成物不匹配**:把 replace 注掉改走发布版 `core v2.0.0-alpha.16`(`goproxy.cn` 可取而且 `go mod tidy` 成功,已实测)后编译失败:`undefined: models.RoleScopeAdmin`(auth/service.go)、`models.Menu.PermissionCode undefined`(auth/service.go)、`models.Member / models.Permission / models.RolePermission / models.MemberRole undefined`(migration/migration.go)。根因同第 3 条:生成物用的是**本地领先 9 个 commit** 的 core 符号,发布版还没有。改回本地模板 core(`replace … => ../../Admin_Template/backend/core`)后 `go build ./...` **通过**。
   → 合起来一句话:**模板不 push、core 不发版,公司 CLI 生成的新项目一律「生不出」或「编不过」**。

## 方案

1. **模板仓入库**(Admin_Template 主,一条 push 解 90%):把领先的 9 个 commit 按可独立验证单元 push 到 origin main,先在 pdgen/Admin_Template 仓内跑其 `npm test`;`backend/starter-app/internal/message/` 属未提交 WIP,由 WIP owner 决定纳入或另提。
2. **生成器默认值改正**(`Admin_Template/cli/bin/admin-cli.js`):`-v` 默认从写死的 `v2.0.0` 改为 `main`(或改为「取远端默认分支」);`--template` 支持本地路径已是事实能力,在 `--help` 与 README 里写明(离线/模板未推时用)。
3. **异常清理**:clone 失败或中途 ENOENT 时,`finally` 删掉 `.admin-template-*` 临时目录,别留在工作区根(工作区根散落目录会被 `products.py check` 报「未登记仓库」)。
4. **前置自检**:create 一开始就校验模板里 `backend/starter-app` 与 `frontend/apps/admin` 是否存在,缺就给人话报错(提示「模板落后,先 push 或改用 -t 本地路径」),而不是 ENOENT 堆栈。
5. 代做边界:第 1 项属 Admin_Template 仓(有他人未提交 WIP)→ 只报不改;第 2–4 项改的是 `cli/`(同一仓),同样等第 1 项落定后一并改,避免两处并发写。

## 验收标准

- [ ] `node D:/code/work/lin/Admin_Template/cli/bin/admin-cli.js create <新项目名> -n "测试"`(**不带任何 -t/-v**)在干净工作区一次成功,产出含 `backend/starter-app` 的可编译骨架
- [ ] 生成物 `cd backend && go build ./...` **一次通过**(默认路径,不手工改 go.mod;要么 replace 正确指向本地模板 core,要么发布版 core 与生成物同版)
- [ ] `git -C D:/code/work/lin/Admin_Template status -sb` 不再出现 `ahead 9`
- [ ] 故意用不存在的 `-v nosuchbranch` 与存在但结构缺失的模板路径各跑一次:报人话错误、退出非 0、**工作区根不留 `.admin-template-*`**
- [ ] `pdgen`/Admin_Template 两仓各自 `npm test` 全绿