fago-cli 功能规划

版本 v1.29，2026-10-28。代码生成预览/比较工具可用，R2.4受限tenant-crud-v1本地工程基线通过。旧记录中的“已覆盖”仅证明脚本或参考实现存在，不能替代同一生成包的真实 CRUD、迁移、页面与租户权限验收。

返回分期与验收 · 配置与数据安全

2026-10-28：按用户要求将CLI及完整Git历史并入fago，module改为 fago.local/fago/apps/fago-cli；二进制/命令与脚本入口不变，旧独立仓库不再作为项目依赖。以下历史分期记录保留原实施背景。

合仓验证通过：23模块workspace race/vet与新缓存独立验证、CLI单测/race/vet、MySQL/PostgreSQL/DM三种实际构建、双库CLI导入校验与原生SSO独立子进程五组专项。外层树之外新克隆后端完成CLI构建/版本/帮助；本地模块代理同时保留8份嵌入模板及原MIT许可，使用全新缓存下载构建通过。原CLI历史通过Git父提交完整保留；本轮未重跑M5完整应用套件，也没有改变schema v26。结构化记录为 docs/evidence/2026-10-28-cli-monorepo.json。

2026-10-28 后续：前后端统一到fago仓库，后端workspace位于 fago/fago-server/，前端位于 fago/fago-vben5/；CLI模块逻辑路径不变，外层不再有独立前端子模块。

1. 定位

fago-cli 是 Fago 唯一官方命令行入口，源码位于后端仓库 fago/fago-server/apps/fago-cli/，与 fago-api、fago-worker 同仓维护、独立模块构建、同包发布（manifest.json 三二进制）。

类别	说明	典型运行环境
运维（ops）	迁移、初始化、加密密钥；依赖 APP_DATABASE_* 与构建时 fago_mysql/fago_postgres tag	部署机、CI 准备库、本地开发库
工具链（toolchain）	环境诊断、测试/检查编排、本地 dev、OpenAPI、构建验证；需识别外层编排仓根目录（含 fago/、api/openapi.yaml）	开发者本机、外层 CI

不做的事：不替代 fago-api 运行时；不提供绕过认证/权限的「管理后门」；不把 bootstrap 口令作为 CLI 位置参数；不在日志或标准输出打印 DSN、token、PEM 私钥或完整请求体。

2. 与现有入口的关系

现有入口	目标态
fago/fago-server/apps/fago-server/cmd/cli	删除；逻辑位于 fago/fago-server/apps/fago-cli
scripts/fago.sh	保留薄封装：api/worker 仍 go run server；migrate 等转发 fago-cli
scripts/*.sh、check-*.py/mjs	首期由 CLI 编排调用；逐步把稳定逻辑迁入 Go，脚本保留为 CI 兼容层
scripts/build-go.sh	api/worker 在 fago 构建；fago-cli 在后端应用模块构建后写入 .cache/release/

2.1 主仓依赖（必须先于 ops 迁入）

fago-cli 不得 import fago-server/internal/*。主仓需先提供公开模块（建议名 modules/fago-ops）：

• 从 internal/app 抽出 仅业务库 的 OpenDatabase（无 Redis），供 CLI migrate/bootstrap 与 server 共用。
• 将 internal/bootstrap 迁入 fago-ops 或已有公开模块，暴露租户/平台初始化入口。

gen-encryption-key 仅依赖 fago-framework/config 与 fago-security，位于同仓 apps/fago-cli 应用。

3. 命令树（目标）

fago-cli
├── migrate                          # ops
├── migrate status                   # ops；只读 schema 版本与 dirty
├── bootstrap                        # ops
├── gen-encryption-key               # ops
├── version                          # ops + 源码树：模块/schema/OpenAPI 摘要
├── auth native                      # R2 原生SSO有限验收，HTTP/系统浏览器、内存凭据
│
├── env doctor                       # toolchain
├── env print                        # toolchain；脱敏后的有效环境摘要
│
├── dev up | dev down                # toolchain
├── dev run api|worker|web           # toolchain；web 委托 scripts/web.sh
│
├── test unit                        # toolchain → test-backend.sh 等
├── test integration                 # toolchain → integration.sh
├── test smoke [--suite …]           # toolchain → smoke-*.mjs
├── test codegen                     # toolchain → smoke-codegen.mjs
│
├── check all                        # toolchain
├── check contract|modules|baseline|web-bundle|database-bundle
├── check workspace                  # toolchain；逐 go.work 模块说明
│
├── openapi lint | diff              # toolchain
├── openapi gen types                # toolchain；对齐前端类型与 live contracts
│
├── build release [mysql|postgres]   # toolchain → build-go.sh（或等价）
├── build verify-db-profiles         # toolchain → test-database-profiles.sh
│
├── scaffold module new              # toolchain；R2 前可只做骨架
├── scaffold migration new           # toolchain
│
├── poc database|oidc|…              # toolchain；封装 poc 脚本，输出「试验」边界
├── doc sync|check|dev               # toolchain；委托 fago-doc npm 脚本
│
└── codegen preview|export|import|verify|diff|pipeline # R2；pipeline 编排 smoke/DB/岗位 HTTP E2E

全局约定：--json 供自动化（含 codegen verify 的 gates 列表）；FAGO_REPO_ROOT 可覆盖外层仓根；退出码 0 成功、2 用法错误、1 业务/依赖失败（与现 cmd/cli 一致）。

4. 分期与里程碑对齐

阶段	路线图	交付子集	退出条件
C0 基座	M4 前置	fago-ops 主仓合并；apps/fago-cli/cmd/fago-cli + cobra（或等价）；build-go.sh 从同仓应用产出 fago-cli；fago.sh 转发	行为与现 cmd/cli 一致；go test 覆盖 gen-key 解析；双库 migrate/bootstrap 集成测仍绿
C1 诊断	M4	env doctor、env print、version	能检出未初始化子模块、驱动/tag 不一致、缺 Docker 端口；文档列出修复步骤
C2 质量门	M4	test unit、test integration、check contract、check all	外层 CI 可用一条 fago-cli check all 替代分散脚本入口（脚本仍可被直接调用）
C3 开发编排	M4	dev run、dev up/down、test smoke、build release、build verify-db-profiles	README 快速启动可改为以 fago-cli 为主路径
C4 合同与脚手架	M4+/R2	openapi *、scaffold migration new、scaffold module new	OpenAPI lint 失败阻断 PR；migration 新文件符合 fago-migrations 规范
C5 平台工具	R2.4	codegen（预览/下载包，不覆盖树内文件）	与 分期 §8 R2.4 代码生成器退出条件一致
C6 运维增强	R1+	migrate status、备份/恢复辅助（若 ADR 明确 CLI 边界）	仅只读或显式确认的危险操作；等保相关须对照 二级等保

未列入上表的能力（远程生产调试、任意 SQL、批量改密）不在 R1 范围。

5. 子命令说明（摘要）

5.1 运维

命令	行为	配置与约束
migrate	执行 fago-migrations.Run，失败保留 dirty	APP_DATABASE_*；构建 tag 与驱动一致
bootstrap	租户或平台首管；BOOTSTRAP_REALM 区分	口令仅环境变量；最短 14 字符等规则不变
gen-encryption-key	-suite rsa-aes\|sm2-sm4、-output、-force	不连库；suite 规则见 配置与数据安全
migrate status	打印当前版本、dirty、目标版本	只读；非零退出表示不可服务

5.2 环境

命令	行为
env doctor	Go 1.27.3、GOPROXY/module proxy、fago/fago/fago-vben5 子模块与同仓CLI入口、compose 端口、Redis/MySQL 可达性
env print	输出 FAGO_DATABASE_BUILD、APP_DATABASE_DRIVER（脱敏 DSN）、有效 go env 摘要

5.3 测试与检查

命令	编排目标（首期）
test unit	scripts/test-backend.sh、scripts/test-independent.sh
test integration	scripts/integration.sh（FAGO_INTEGRATION 说明）
test smoke	smoke-api.mjs、smoke-m1-contract.mjs 等，按 --suite 选择
test codegen	smoke-codegen.mjs（R2 离线预览门禁）
check contract	check-contract.mjs、check-live-contracts.mjs
check modules	check-modules.py
check baseline	check-baseline.py
check web-bundle	check-web-bundle.mjs
check database-bundle	check-database-bundle.py（常与 release 构建联用）
check all	上述按 M4 门禁顺序执行，首败即停或 --keep-going

5.4 开发与构建

命令	行为
dev up	docker compose 起依赖 + 提示执行 migrate
dev run api\|worker	等价 fago.sh api\|worker
dev run web	调用 scripts/web.sh
build release	调用 build-go.sh；三二进制 + manifest
build verify-db-profiles	test-database-profiles.sh

5.5 脚手架与 PoC

命令	行为
scaffold module new <name>	生成 fago-<name> 模块骨架、go.mod 模板；go.work 变更需 --apply 或人工
scaffold migration new <slug>	下一序号迁移文件、嵌入说明注释
poc database / poc oidc	包装 db-poc.sh、run-oidc-poc.sh；stdout 标明 试验/未认证

5.6 R2 代码生成

fago-cli codegen 子树：导入表元数据 → 配置 → 预览 → 导出 zip；含 handler/service/repo 片段、migration、权限/菜单种子、OpenAPI 路径片段、Vben API/页面模板。与 数据模型 § 代码生成 中 codegen_* 表一致；禁止默认覆盖工作区已有文件。

R2.4 退出核对（2026-10-25 按实际执行链重新审计）

项	当前实现与证据边界	状态
元数据导入与租户键	修复logical_type映射，双库实际CLI导入→显式分类→同字节ZIP；配置不猜测归属/公开分类	目录导入及双库并发一致快照通过，外层事务明确拒绝
配置→ZIP→离线门禁	tenant-crud-v1显式配置/原包私有宿主构建；旧pipeline只作兼容证据	受限模板同包全链路通过
二次生成显示差异	codegen diff --before old.zip --after new.zip；忽略旧生成时间，稳定顺序、正文与 SHA、有界截断报告	本轮实现并验证
不覆盖现有文件	preview/export/import 共用排他创建；已有目标及叶级符号链接拒绝，文件权限0600	本轮实现并验证
模板/包边界	记录实际 crud-v0/tenant-crud-v1 与生成器版本；未知模板/类型、危险路径、重复条目、超限解压和终端控制拒绝	本轮实现并验证
参考岗位合同与HTTP	当前 OpenAPI 对齐和 TestIntegrationOrganization 针对手写岗位实现	不能证明生成资源
生成迁移与权限种子	tenant-crud-v1原ZIP的双方言业务表/权限/菜单在私有下一版迁移实际执行，正式v19不变	目录夹具双库通过
生成后端接入运行入口	tenant-crud-v1原ZIP的正式handler/service/repository在私有宿主挂载并构建实际API入口	目录夹具双库通过
生成页面与类型/构建	tenant-crud-v1真实API/列表/表单在私有Vben副本登记并检查/构建；旧crud-v0门禁已迁至逐表私有副本	同包双库真实页面与类型/构建通过
同一生成资源双租户/权限E2E	原ZIP目录夹具在双库三协议验证两租户、四类撤权、CAS/软删/审计回滚及144条真实响应合同	双库三协议HTTP及双库真实浏览器/数据库读回通过

当前新增受限可执行模板和同ZIP真实双库验收，详见 M5增量。类型矩阵、一致快照和旧门禁私有化已验证；最终同一份ZIP在MySQL/PostgreSQL物化生成迁移、实际HTTP处理器和页面，CRUD读回、分页、版本冲突、删除不可见、两租户访问拒绝及四类权限撤销通过，受限模板本地工程退出条件已满足。仅允许装配 DI、路由、菜单，不能用手写业务替换生成产物。历史 r2-codegen-pipeline.json 保留为当时证据，不据其绿色状态扩大当前支持范围。

5.6.1 双轨退出条件

轨道	对应路线图	退出判定	证据
W8-CLI	17-fago-cli C5 / W8	§3 命令树 codegen 与 test codegen 可用；m0.yml 跑通 smoke + 双工作区门禁；codegen verify/pipeline --json 可供自动化	docs/evidence/w8-fago-cli-codegen-gates.json
R2.4-平台	08-roadmap §8 R2.4	§5.6受限模板的实际生成产物、双库迁移/双租户权限及页面退出条件通过；不扩展为任意资源或生产认证	docs/evidence/m5-codegen-browser-progress.json

C5 阶段行仍写「与 R2.4 退出一致」：指 R2.4-平台 全绿；W8-CLI 可先行验收，不阻塞继续开发平台合入项。

6. 发布包策略

策略	说明
推荐（A）	发布二进制含全部子命令；需要源码编排的命令在非源码树失败（退出码2），只读两个本地ZIP的 codegen diff 不需要源码树
备选（B）	releasecli 构建 tag 裁剪 toolchain，仅保留 ops + version；源码树默认全功能

R1 采用 A，待二进制体积或依赖面成为问题再评估 B。

7. 非功能要求

• 安全：ops 路径使用 RedactingHandler；Oops 错误码与 HTTP 公开码一致策略；禁止在属性中放敏感配置。
• 可观测：toolchain 子命令打印正在执行的脚本路径（相对仓根）；--verbose 透传子进程。
• 测试：同仓CLI模块单测 + 依赖 fago 集成测；编排层用表驱动测试退出码与参数解析。
• 文档：读者向步骤进手册；本规划进规划备查；fago/fago-server/apps/fago-cli/README.md 保持简短并链到本文。

8. 工作包清单（实施顺序）

编号	工作	负责仓	验收
W1	新增 fago-ops，server 改引用	fago	已完成：集成测无回归
W2	迁入 migrate/bootstrap/gen-key + 测试	fago-cli	已完成：与 W1 联调
W3	删 cmd/cli；更新手册与 fago.sh/build-go.sh	fago + demo	已完成：release 三件套通过 bundle 检查
W4	C1 env/version	fago-cli	已完成：doctor 覆盖文档列出的 5 类失败
W5	C2 check/test 编排	fago-cli + demo	已完成：m0.yml 已用 fago.sh
W6	C3 dev/build	fago-cli	已完成：见 fago-cli 常用命令
W7	C4 openapi/scaffold	fago-cli	已完成：PR 门禁脚本可经 CLI 调用
W8	C5 codegen	fago + fago-cli + 前端	W8-CLI 可验收（§5.6.1）；R2.4-平台受限模板本地基线通过，见§5.6

9. 不在范围内

• 替代 Ansible/K8s 编排或 deploy/ 内生产拓扑。
• 连接生产库执行未评审的 DML/DDL（除已发布的 migrate）。
• 内置交互式 REPL 或 SQL 客户端。
• 在未立项前承诺 Oracle/SQL Server/DM 的 cli 构建变体（仍由 数据库适配 与 PoC 结论驱动）。

---

变更记录：v1.0 初稿，与子模块 fago-cli 及分仓 CLI 决策对齐。

原生SSO客户端增量

已接入独立 auth native 命令，不加载运维数据库配置。使用系统浏览器/S256 PKCE和先绑定随机端口的loopback接收器，默认完成本人/设备读取、刷新及本地退出；支持有限wait/实际API拒绝和RP发起步骤。操作与边界见原生SSO手册，真实IdP与测试记录见M5记录。本增量不替代认证模式、Vben入口或双应用统一退出验收。