From 7f2e2718368eb46fe1e572e1f6350731658c9b68 Mon Sep 17 00:00:00 2001 From: lovefyf Date: Fri, 14 Aug 2026 04:54:22 +0800 Subject: [PATCH] =?UTF-8?q?docs(env):=20keycloak-setup-log=20=E8=83=8C?= =?UTF-8?q?=E4=B9=A6=E6=94=B9=E5=A6=82=E5=AE=9E=E6=8E=AA=E8=BE=9E(?= =?UTF-8?q?=E8=AE=B0=E6=9C=89=E7=AB=99=E7=82=B9=E5=9C=B0=E5=9D=80=E4=B8=8E?= =?UTF-8?q?=20realm=20=E5=90=8D);=E6=B5=8B=E8=AF=95=E7=BA=AA=E5=BE=8B?= =?UTF-8?q?=E8=AE=A1=E6=95=B0=E8=AE=A2=E6=AD=A3;runbook=20=E8=A1=A5?= =?UTF-8?q?=E6=96=B0=E4=BA=BA=E7=AC=AC=E4=B8=80=E6=AD=A5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 评审 Important + Minor 1 + Minor 3。 Co-Authored-By: Claude Fable 5 --- docs/开发环境册.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/开发环境册.md b/docs/开发环境册.md index 30a05c2..2c6126c 100644 --- a/docs/开发环境册.md +++ b/docs/开发环境册.md @@ -50,7 +50,8 @@ NATS 不可达 → SSE 推送停摆、`/health` 照实报 fail，但代理/上 `requireService(['api-gateway'])`——只认网关。`src/shared/service-token.ts` 用 `config.keycloak.clientId` ＋ `KEYCLOAK_CLIENT_SECRET` 换 `client_credentials` token， 两者必须是**同一个 client** 的。相关的 realm 角色与 audience mapper 配置记录见 -`docs/keycloak-setup-log.md`（该文只记对象名与操作结果，同样不含密钥值）。 +`docs/keycloak-setup-log.md`——**该文不含任何密钥值**（它自己在开头也声明"不含任何 secret、 +密码或完整 token"），**但记有 Keycloak 站点地址与 realm 名**，引用或外发时注意范围。 `.env` / `.env.*` 已在 `.gitignore`（`!.env.example` 例外）。收尾核验里 `git log --all --oneline --diff-filter=A -- .env | wc -l` 必须为 `0`。 @@ -59,8 +60,12 @@ NATS 不可达 → SSE 推送停摆、`/health` 照实报 fail，但代理/上 ## 3. 端口与运行 +**新人第一步**：本仓 `package.json` 的 `engines` 声明 **Node ≥ 22**；包管理器用 **pnpm** +（仓内有 `pnpm-lock.yaml` 与 `pnpm-workspace.yaml`，别用 npm/yarn 装）。 + ```bash pnpm i # 装依赖 +cp .env.example .env # 照 §2.2 逐项填；真值向共享设施的凭证发放渠道索取，不要向别人的 .env 复制 pnpm dev # tsx watch，读 .env，起在 :8800 pnpm gates # typecheck + lint + test ``` @@ -91,7 +96,7 @@ fake-agent 桩 8901（在 Task 仓 `tools/fake-agent.ts`，Activity 仓交付真 ## 5. 测试纪律 本仓无库，共享库那套 `zz_test_` 前缀 / `afterAll` 谓词清理 / LIKE 下划线转义 / 生产扫描排除 -的纪律**在本仓无直接落点**，但两条相关的仍适用： +的纪律**在本仓无直接落点**，但三条相关的仍适用： 1. **集成用例打的是共享 Keycloak 与共享 NATS**，不许起本地替身；不可达就如实跳过或失败。 2. **`test/support/token.ts` 是三仓同一性文件**（逐字节相同）——改它要同步三仓并重跑同一性脚本。