| name | bazi-cli |
| description | bazi-master 仓库的操作入口。当需要在这个项目里准备环境、起停本地开发栈（db/api/web）、跑数据库迁移或重置、跑测试、跑 verify-*.mjs 端到端校验、排查后端起不来或 /health 503 时使用。所有操作都通过仓库根的 ./bazi CLI 完成，不要直接调 npm script 或手动起进程。 |
bazi-master 操作手册
仓库根有一个程序化 CLI：./bazi。能做什么以 ./bazi help --json 为准，这里不重复命令列表——
重复的清单一定会腐化。这份文档只讲 --help 讲不了的东西：顺序、坑、约定、边界。
带 --json 跑。stdout 保证只有一个 JSON 文档，进度和子进程噪音全在 stderr。
退出码就是你的下一步
不要去读人类可读的错误文本猜意图，看退出码：
| 码 | 含义 | 你该做什么 |
|---|
| 0 | 成功 | 继续 |
| 1 | 命令跑通了但结果失败（测试挂了、校验没过） | 去看结果本身，不是修环境 |
| 2 | 用法错 | 读 --help，别瞎试参数 |
| 3 | 环境未就绪 | 照 next 字段修，修完原样重试 |
| 4 | 远端拒绝 | 改请求内容，不是改环境 |
| 5 | 瞬时失败 | 原样重试 |
| 7 | 命中安全边界 | 停下来问人。见下面「关于 exit 7」 |
失败的 JSON 里 next 一定是一条可以直接复制执行的命令。优先照它做。
关于 exit 7：不要自动绕过
破坏性命令（db reset / db restore）在没有 --yes 时会返回 7，并且 next 字段会写着
"加 --yes 重跑"。那句话是给人看的，不是给你看的。
拿到 exit 7 的正确反应是：把目标库和将要发生的事情告诉用户，等一个明确的"是"，然后才加 --yes。
自己补个 --yes 重跑一遍等于这道闸从来没存在过。
真正不可逆的场景（NODE_ENV=production）CLI 会直接硬拒绝，加什么参数都没用——那是代码里的边界，不是约定。
起手式
./bazi doctor --json # 退 3 就照每一项的 fix 修，或者 ./bazi doctor --fix 让它自己修
./bazi stack up --json # 起 db -> api -> web，幂等，已经在跑的会跳过
./bazi stack status --json # 任何时候先看这个再动手
Agent 在动手改代码前，用 ./bazi stack status --require-ready --json 做前置断言：未就绪直接退 3，
比跑到一半发现服务没起要省事得多。
依赖顺序（最容易踩的坑）
db → 迁移 → api → web，中间那步最容易漏。
迁移没跑时，后端进程起得来、端口也通，但 /health 会一直返回 503，日志里刷的是
The table public.User does not exist。CLI 已经在启动 api 前替你查了迁移状态并直接报
bazi db migrate，所以你正常不会撞上。但如果你绕过 CLI 手动 node server.js，就会撞上，
而且现象非常像"后端坏了"。
改完 prisma/schema.prisma 的完整链路：
./bazi db migrate --new <名字> # 只生成迁移文件，不应用，也不会触发交互式重置
./bazi db migrate # 应用
./bazi db generate # 重新生成 Prisma Client
./bazi stack restart --only api # 不重启的话后端还在用旧 Client
两套数据库，别搞混
| 谁 | 库 | 数据目录 |
|---|
./bazi stack 开发栈 | .env 里的 DATABASE_URL | .tmp/cli/pg/ |
./bazi test 测试 | 脚本自建的临时库 | .tmp/pg-test/ |
./bazi test 刻意不把 .env 注入子进程。因为 backend/scripts/run-tests-with-db.mjs 的逻辑是
"DATABASE_URL 没设就自己起一个临时库"——一旦把开发库的 URL 灌进去，测试会直接在开发库上执行迁移和重置。
那是数据事故。--use-dev-db 能强行打开这个行为，除非用户明确要求，否则不要用。
测试：skipped 不等于 passed
bazi test 的目标依赖没装时会记 skipped 并照样返回 0。这是给本地开发用的——不该因为
没装前端依赖就没法跑后端测试。但它意味着 bazi test --all 可能一个目标都没跑还报成功：
summary: {"passed": 2, "failed": 0, "skipped": 3} # exit 0，但 typecheck/unit/e2e 根本没跑
永远读 summary.skipped，别只看退出码。 要让"什么都没跑"变成硬失败（CI、或者你需要一次
可信的全量），加 --fail-on-skip：有跳过就退 3（环境未就绪，去装依赖，不是去查代码）。
./bazi test --all --fail-on-skip --json
e2e 还额外依赖 Playwright 浏览器二进制，npm install 不会带上它。缺了的表现是每个用例
清一色 browserType.launch: Executable doesn't exist，看起来像"前端全崩了"，其实只是没装浏览器。
bazi setup --with-frontend 已经会补齐，bazi doctor 的 e2e:browsers 也会报——
跑 e2e 前先 doctor 一下比跑完一轮再回头查省事得多。
foreign：CLI 不碰不是自己起的进程
stack status 里 managedBy 有三种值：bazi（我们起的）、foreign（端口被别人占了）、external（数据库是别人起的）。
看到 foreign 时 CLI 会拒绝接管，也拒绝 kill。这是故意的：按端口去杀进程会误伤用户自己开的终端、
另一个 worktree、或者同事的服务。
正确处理：告诉用户 4000/3000 端口上有不是 bazi 起的进程，让他们决定。不要自己去 kill $(lsof -ti:4000)。
推论：不要绕过 CLI 手动起服务（npm run dev、node server.js）。那样起的进程 CLI 管不到，
后面 stack down 停不掉，stack status 只会显示 foreign。
verify：跑之前栈必须就绪
frontend/scripts/verify-*.mjs 全都直接访问 http://localhost:3000，它们自己不会把栈拉起来。
栈没起时的原始表现是 Playwright 超时后吐一屏无关报错，很容易被误读成"功能坏了"。
CLI 已经加了前置断言（退 3，next: bazi stack up），所以走 ./bazi verify 就不会误判。
清单是扫目录来的，新增一个 scripts/verify-xxx.mjs 立刻可用，不需要改 CLI 也不需要改这份文档。
校验脚本不要自己写建表 DDL。prisma/schema.prisma 的 provider 是 postgresql，而手写的
CREATE TABLE 很容易顺手写成 SQLite 方言（AUTOINCREMENT / DATETIME / INSERT OR IGNORE），
一跑就是 42601 语法错误。另外 PostgreSQL 里不加引号的 BaziRecordTrash 会被折成小写而找不到表——
这种错误常常被 try/catch 吞成一条 warn，看起来"跑过了"，其实什么都没删。
正确做法：建表复用 backend/services/schema.service.js 的 ensureSoftDeleteTables /
ensureBaziRecordTrashTable（它们已经按 provider 分好方言），增删查一律走 Prisma Client
（prisma.baziRecordTrash.upsert/count/deleteMany）而不是 $queryRaw。绕不开裸 SQL 时，
表名和驼峰列名必须加双引号。
排查
./bazi stack logs api --tail 60 # 后端日志（pino JSON）
./bazi stack logs db # PostgreSQL 日志
./bazi stack logs web
启动失败时 CLI 会把日志压成一条诊断再返回，不会把几十 KB 原始日志塞进 hint。
认得出的失败特征（缺表、连不上库、端口占用、必填环境变量缺失）会直接翻译成下一步命令。
运行态都在 .tmp/cli/ 下（pidfile、日志、备份、pg 数据目录），已被 .gitignore 覆盖，可以整个删掉重来。
端口
api 4000（.env 的 PORT）、web 3000、db 5433（本地 pg_ctl）或 5432（docker compose）。
装了 Docker 时 env init 默认给 5432 走 compose，没装就给 5433 走 pg_ctl。
