@oj-module/cli 0.2.48 → 0.2.50

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oj-module/cli",
   "type": "module",
-  "version": "0.2.48",
+  "version": "0.2.50",
   "description": "React Antd 模块工程命令行工具（含预构建宿主 shell-dist）",
   "license": "MIT",
   "exports": {
@@ -49,7 +49,7 @@
   ],
   "dependencies": {
     "@faker-js/faker": "^10.4.0",
-    "@oj-module/runtime": "0.2.48",
+    "@oj-module/runtime": "0.2.50",
     "@redocly/cli": "^2.51.0",
     "@tailwindcss/vite": "^4.3.0",
     "cac": "^6.7.14",

package/shell-dist/assets/runtime.js

@@ -304,10 +304,10 @@ function getAppInfo() {
 	return {
 		"pkg": {
 			"name": "@oj-module/runtime",
-			"version": "0.2.48",
+			"version": "0.2.50",
 			"license": "MIT"
 		},
-		"lastBuildTime": "2026-11-01 10:19:28"
+		"lastBuildTime": "2026-11-01 22:25:12"
 	};
 }
 var init_get_app_info = __esmMin((() => {}));

package/shell-dist/index.html

@@ -5,9 +5,9 @@
 		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
 		<link rel="icon" href="/favicon.ico" />
 		<title>React Antd Admin · Shell</title>
-		<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'self' https://modules.cdn.example.com 'wasm-unsafe-eval' 'nonce-3nM+tS10yKYnXNwkhSrSkw=='; script-src-attr 'none'; connect-src 'self' data: https://modules.cdn.example.com; style-src 'self' https://modules.cdn.example.com 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:; frame-src https://ant.design https://react.dev https://condorheroblog.github.io; form-action 'none'; base-uri 'none'; object-src 'none'; upgrade-insecure-requests" />
+		<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'self' https://modules.cdn.example.com 'wasm-unsafe-eval' 'nonce-milCmNXuFsJqtDXLlLdu/g=='; script-src-attr 'none'; connect-src 'self' data: https://modules.cdn.example.com; style-src 'self' https://modules.cdn.example.com 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:; frame-src https://ant.design https://react.dev https://condorheroblog.github.io; form-action 'none'; base-uri 'none'; object-src 'none'; upgrade-insecure-requests" />
 
-		<script type="importmap" nonce="3nM+tS10yKYnXNwkhSrSkw==">{
+		<script type="importmap" nonce="milCmNXuFsJqtDXLlLdu/g==">{
   "imports": {
     "react": "/assets/react.js",
     "react/jsx-runtime": "/assets/jsx-runtime.js",

package/shell-dist/versions.json

@@ -7,9 +7,9 @@
   "react-router": "7.18.2",
   "react-router/dom": "7.18.2",
   "@tanstack/react-query": "5.102.8",
-  "@oj-module/runtime": "0.2.48",
-  "@oj-module/runtime/contract": "0.2.48",
-  "@oj-module/runtime/contract/errors": "0.2.48",
+  "@oj-module/runtime": "0.2.50",
+  "@oj-module/runtime/contract": "0.2.50",
+  "@oj-module/runtime/contract/errors": "0.2.50",
   "@plane/kit": "0.1.20",
   "@plane/editor": "0.1.20",
   "antd": "6.6.1",

package/src/__tests__/build-backend.test.ts

@@ -116,3 +116,83 @@ describe("given module-root 布局 When ojm build 后端", () => {
 		expect(existsSync(join(root, "dist", "api"))).toBe(false);
 	});
 });
+
+/**
+ * 假 oj：`secret open` 按 openOk 成败（失败时复述 oj 的真实 stderr），`build` 记 argv 后成功。
+ * 只记非 secret 调用，便于断言「预检之后 build 是否真的跑了」。
+ */
+function fakeOjSeal(projectRoot: string, openOk: boolean): void {
+	mkdirSync(join(projectRoot, "bin"), { recursive: true });
+	const bin = join(projectRoot, "bin", "oj");
+	writeFileSync(bin, [
+		"#!/bin/sh",
+		"if [ \"$1\" = \"secret\" ]; then",
+		...(openOk ? [] : ["  echo 'oj secret open: aes-gcm open failed (sealed value tampered?): aead::Error' >&2"]),
+		`  exit ${openOk ? 0 : 1}`,
+		"fi",
+		"printf '%s\\n' \"$*\" >> \"$(dirname \"$0\")/invoked\"",
+		"exit 0",
+		"",
+	].join("\n"), { mode: 0o755 });
+}
+
+/** flat 布局 + 已密封的 config（路径照 ojm init 的产物写） */
+function newSealedProject(): string {
+	const root = newProject();
+	writeFileSync(
+		join(root, "api", "config.yaml"),
+		"auth:\n  jwt_secret: \"ENC[AgE0ZMU2aDKo5CHab4Kl_TtJduXQLwheLVczTPcvm2g]\"\n"
+		+ "secrets:\n  private_key_path: ./config/secrets-private.pem\n",
+		"utf-8",
+	);
+	return root;
+}
+
+describe("given config 含密封值 When ojm build 后端", () => {
+	// oj build 读不动 config 时只 warn 两行、退出码 0，继续出包时 sql_guard 是关掉的。
+	// ojm 必须在把 oj 叫起来之前就停下，否则「没跑过 tenant 校验的包」会流到部署机上。
+	it("then 解不开就停在出包前，不当成一次成功构建", async () => {
+		const root = newSealedProject();
+		fakeOjSeal(root, false);
+
+		await expect(buildBackend(root)).rejects.toThrow(/密封值解不开/);
+		await expect(buildBackend(root)).rejects.toThrow(/secrets-private\.pem/);
+		expect(existsSync(join(root, "bin", "invoked"))).toBe(false); // 没跑 oj build
+	});
+
+	it("then 解不开时把 oj 的原话带上（排障不用再跑一遍）", async () => {
+		const root = newSealedProject();
+		fakeOjSeal(root, false);
+
+		await expect(buildBackend(root)).rejects.toThrow(/aes-gcm open failed/);
+	});
+
+	it("then 能解开就照常出包", async () => {
+		const root = newSealedProject();
+		fakeOjSeal(root, true);
+
+		expect(await buildBackend(root)).toBe(true);
+		expect(readFileSync(join(root, "bin", "invoked"), "utf-8")).toContain("build -c ");
+	});
+
+	it("then config 无密封值时不额外调用 oj（预检零成本）", async () => {
+		const root = newProject(); // config 只有 server.port
+		fakeOjSeal(root, false);
+
+		expect(await buildBackend(root)).toBe(true);
+		expect(readFileSync(join(root, "bin", "invoked"), "utf-8")).not.toContain("secret");
+	});
+
+	it("then 注释掉的旧密文不算数（不因一行 `#` 挡住构建）", async () => {
+		const root = newProject();
+		writeFileSync(
+			join(root, "api", "config.yaml"),
+			"# auth:\n#   jwt_secret: \"ENC[AgE0ZMU2aDKo5CHab4Kl_TtJduXQLwheLVczTPcvm2g]\"\nserver:\n  port: 9778\n",
+			"utf-8",
+		);
+		fakeOjSeal(root, false);
+
+		expect(await buildBackend(root)).toBe(true);
+		expect(readFileSync(join(root, "bin", "invoked"), "utf-8")).not.toContain("secret");
+	});
+});

package/src/build.ts

@@ -584,6 +584,9 @@ export async function buildBackend(projectRoot: string): Promise<boolean> {
 	// v0.1.85：`--module-root <dir>` 与 `-d` 互斥（都是「源码树根」）。新布局给 src，
 	// oj 在子树内递归找 manifest.yaml（命中 src/<name>/api/manifest.yaml 即停）。
 	const sourceArgs = layout?.moduleRoot ? ["--module-root", layout.moduleRoot] : ["-d", apiSrc];
+	// 出包前先自己确认 config 能读：读不动时 oj build 会静默关掉 sql_guard（见函数注释）
+	if (configArgs.length)
+		assertSealedValuesOpenable(oj, configPath);
 	execFileSync(oj, [
 		"build",
 		...configArgs,
@@ -604,6 +607,53 @@ export async function buildBackend(projectRoot: string): Promise<boolean> {
 	return true;
 }
 
+/**
+ * config 里的密封值（`oj secret seal` 产物）在 build 前试解一把——fail-closed。
+ *
+ * **为什么不能只信 oj 的 warn**：实测（oj 0.1.115）config 读不动时 `oj build` **退出码仍是 0**，
+ * 只往 stderr 甩两行「读配置失败 → 镜像目录回落默认 tasks / 本次 build 按 sql_guard=off 处理」，
+ * 然后照常出包。那两行夹在模块清单里极易被忽略，而关掉的 `sql_guard` 正是 tenant 声明校验
+ * （跨模块 SQL 的唯一守卫）——包看起来完好，检查其实没跑。
+ *
+ * 探法就是 oj 自己的排障命令 `oj secret open`：它和 `oj serve` / `oj build` 用同一套密钥解析
+ * （`OJ_SECRET_KEY` → `OJ_SECRET_KEY_FILE` → config 的 `secrets.private_key_path`），
+ * 解不开就非零退出。明文只可能出现在它的 stdout，这里直接丢弃，不落终端也不落日志。
+ */
+function assertSealedValuesOpenable(oj: string, configPath: string): void {
+	// 注释行不算：config 里留着注释掉的旧密文很常见，naive 匹配会让 build 因为一行 `#` 而失败
+	const live = fs.readFileSync(configPath, "utf-8")
+		.split("\n")
+		.filter(line => !line.trimStart().startsWith("#"))
+		.join("\n");
+	const sealed = [...new Set(live.match(/ENC\[[^\]\n]+\]/g) ?? [])];
+	for (const value of sealed) {
+		try {
+			execFileSync(oj, ["secret", "open", "-c", configPath, value], { stdio: ["ignore", "ignore", "pipe"] });
+		}
+		catch (e) {
+			const stderr = String((e as { stderr?: unknown }).stderr ?? "").trim();
+			const detail = stderr || (e as Error).message;
+			throw new Error(
+				`[ojm] config 里的密封值解不开，已停在出包前：${configPath}\n`
+				+ `      oj 说：${detail}\n`
+				+ "\n"
+				+ "不能放行：oj build 遇到读不动的 config 不会失败（退出码 0），只 warn 两行就继续——\n"
+				+ "tasks 镜像目录回落默认值，sql_guard（tenant 声明校验）直接关掉。那种包看着正常，\n"
+				+ "跨模块 SQL 的守卫却没跑过。\n"
+				+ "\n"
+				+ "两类原因，都修得了：\n"
+				+ "  1) 本机加载的私钥与密封时用的公钥不是一对——最常见是换机器/换部署目录时只带了\n"
+				+ "     config.yaml，没带 config/secrets-private.pem；\n"
+				+ "  2) 密文被改过——手工编辑、复制被截断、编辑器把长行折了。\n"
+				+ "\n"
+				+ "单独验一条：oj secret open -c <config> '<那个 ENC[...] 值>'（成功=这条没问题，失败=就是它）\n"
+				+ "修法：把配对私钥带到本机（OJ_SECRET_KEY / OJ_SECRET_KEY_FILE / config 的 secrets.private_key_path\n"
+				+ "      三选一）；密钥确实换了，就在本机重新 oj secret seal 覆写该值（明文走 stdin，别上命令行）。",
+			);
+		}
+	}
+}
+
 /**
  * 全站合并（仅 `ojm build` 调用，设计 §5）：清场后拷 shell dist 全量，
  * 再由模块构建写入 modules.json 与 modules/。清场防旧哈希资产无限累积

package/src/init.ts

@@ -193,10 +193,11 @@ export async function initProject(destDir: string, opts: InitOptions = {}): Prom
 	if (fs.existsSync(path.join(cliDevkit, "SKILL.md"))) {
 		const ojmSkillDir = path.join(destDir, ".claude/skills/ojm-module-dev");
 		fs.mkdirSync(ojmSkillDir, { recursive: true });
-		// `wecom-daikaifa.md`（企业微信代开发：凭据清单 + 用户/开发/部署三视角）
-		// 随之分发——它讲的是「怎么把一个已经写好的连接器接上真实套件」，
-		// 业务工程拿到模板后自助完成对接要用，不能只留本仓。
-		for (const name of ["SKILL.md", "manual.md", "README.md", "wecom-daikaifa.md"])
+		// 企微两本手册随之分发——它们讲的是「怎么把一个已经写好的连接器接上真实企业」，
+		// 业务工程拿到模板后自助完成对接要用，不能只留本仓：
+		//   · `wecom-daikaifa.md`  企业微信代开发（服务商模板）：凭据清单 + 用户/开发/部署三视角；
+		//   · `wecom-internal-app.md` 企业内部应用（自建）：五项 corp 凭据 + 验证并接入 + 共存。
+		for (const name of ["SKILL.md", "manual.md", "README.md", "wecom-daikaifa.md", "wecom-internal-app.md"])
 			copyIfAbsent(path.join(cliDevkit, name), path.join(ojmSkillDir, name), report);
 	}
 	else {

package/templates/config.yaml

@@ -56,8 +56,13 @@ vars:
   # 故意不读请求头 Host（防伪造 Host 牵引出站）：不配 = fail-closed，不会替你猜。
   # canonical_origin: "https://your-site.example.com"
 
-  # ---- 企业微信代开发（服务商侧，部署级常量）----
-  # 一个部署 = 一个服务商账号下的一套代开发模板，所以这 8 个值是「部署」维度，不进 DB。
+  # ---- 企业微信（部署级常量，不进 DB）----
+  # 两种应用来源，**可同时启用**（docs/plans/20261101-2044-wecom-internal-app-plan.md）：
+  #   · 代开发（suite）：一套代开发模板，企业扫码授权即接入，一套部署可服务多家企业；
+  #   · 企业内部应用 / 自建应用（corp）：企业自建应用，一套部署只服务一家企业。
+  # 两套的企业侧数据链路相同（permanent_code 就是当 corpsecret 用的），差别只在凭据来源与回调。
+  # 从代开发迁到自建时请把旧的 suite 变量清空；两套同时生效须显式开 wecom_allow_coexist。
+  # 一个部署 = 一个服务商账号下的一套代开发模板（或一家企业的自建应用），所以这些值是「部署」维度，不进 DB。
   # 「哪个企业装了哪个应用」不写在这里：企微 create_auth 回调推 AuthCode → 换永久授权码 →
   # 落 wecom_app_profile（主键含 agent_id，同一企业测试/正式两个应用天然并存），
   # 新增企业只需企业管理员扫码授权，**不改配置、不重启**。
@@ -74,18 +79,35 @@ vars:
   #   wecom_provider_id       服务商的 corpid（服务商自己的，不是企业 corpid）；**位置：服务商后台「服务商信息」页显示的 CorpID**
   #   wecom_provider_secret   服务商 provider_secret；**位置：服务商后台 → 应用管理 → 通用开发参数（点「编辑」）→ ProviderSecret 字段**，
   #                           **不在「服务商信息」页**（那里只显示 CorpID），也**不是** suite_secret（suite 那个是另一套）。
-  #   wecom_callback_token    「Token」（回调验签用）
-  #   wecom_encoding_aes_key  「EncodingAESKey」（43 字符，回调解密用）
-  #   wecom_enc_key           permanent_code 落库加密密钥（hex/base64，16 或 32 字节；建议 oj secret keygen）
+  #   wecom_callback_token    代开发「指令回调」的 Token（回调验签用）
+  #   wecom_encoding_aes_key  代开发「指令回调」的 EncodingAESKey（43 字符，回调解密用）
+  #   wecom_enc_key           permanent_code / 应用 Secret 的落库加密密钥（hex/base64，16 或 32 字节；建议 oj secret keygen）
   #   wecom_base_url          连接器基址（绝对地址，无尾斜杠，**这是基址、不是回调 URL**），如 https://site.example.com/api/auth/wecom
-  #                           → 企微后台「指令回调URL」填 <base>/event（必须带 /event，裸 <base> 无 handler 会 404）；
+  #                           → 回调 URL 填 <base>/event（必须带 /event，裸 <base> 无 handler 会 404）；
   #                             网页授权 redirect_uri 用 <base>/callback
+  #
+  # 企业内部应用（corp）——一套部署一家企业：
+  #   wecom_corp_id                 企微后台「我的企业 → 企业信息 → 企业ID」；同时是租户键
+  #   wecom_corp_secret             应用详情页「Secret」；**换过后必须到 /system/wecom 重新「验证并接入」**
+  #   wecom_corp_agent_id           应用详情页「AgentId」
+  #   wecom_corp_callback_token     「管理工具 → 通讯录同步 → 接收事件服务器」的 Token（可选；不配 = 不做事件增量）
+  #   wecom_corp_encoding_aes_key   同上 → EncodingAESKey（可选）
+  #   ⚠ 自建应用**收不到**成员通讯录变更事件（官方 90970），事件增量只能靠上面这组「通讯录同步」回调，
+  #     且企微要求该 URL 在企业主体域名下——所以它只适用于私有化单企业部署。
+  #
+  #   wecom_allow_coexist  两套凭据都配齐时必须显式写 'true' 才允许共存（否则 fail-fast）
   wecom_suite_id: ''
   wecom_suite_secret: ''
   wecom_provider_id: ''
   wecom_provider_secret: ''
   wecom_callback_token: ''
   wecom_encoding_aes_key: ''
+  wecom_corp_id: ''
+  wecom_corp_secret: ''
+  wecom_corp_agent_id: ''
+  wecom_corp_callback_token: ''
+  wecom_corp_encoding_aes_key: ''
+  wecom_allow_coexist: ''
   wecom_enc_key: ''
   wecom_base_url: ''
 

package/templates/openapi.json

@@ -1771,7 +1771,8 @@
 													"status",
 													"auth_mode",
 													"installed_at",
-													"update_time"
+													"update_time",
+													"credential_kind"
 												],
 												"properties": {
 													"suite_id": {
@@ -1802,6 +1803,13 @@
 															"disabled"
 														]
 													},
+													"credential_kind": {
+														"type": "string",
+														"enum": [
+															"suite",
+															"corp"
+														]
+													},
 													"auth_mode": {
 														"type": "number"
 													},
@@ -1960,6 +1968,151 @@
 				}
 			}
 		},
+		"/api/auth/wecom/admin/overview": {
+			"get": {
+				"operationId": "auth_wecom_admin_overview_get",
+				"summary": "GET api/auth/wecom/admin/overview",
+				"x-oj-file": "auth/wecom/admin/api.ts",
+				"tags": [
+					"auth"
+				],
+				"responses": {
+					"200": {
+						"description": "OK",
+						"x-oj-response-enforced": false,
+						"content": {
+							"application/json": {
+								"schema": {
+									"type": "object",
+									"required": [
+										"code",
+										"msg",
+										"data"
+									],
+									"properties": {
+										"code": {
+											"type": "integer"
+										},
+										"msg": {
+											"type": "string"
+										},
+										"data": {
+											"type": "object",
+											"required": [
+												"kinds",
+												"configError",
+												"callbackUrl",
+												"corpId",
+												"agentId",
+												"corpCallbackConfigured"
+											],
+											"properties": {
+												"kinds": {
+													"type": "array",
+													"items": {
+														"type": "string",
+														"enum": [
+															"suite",
+															"corp"
+														]
+													}
+												},
+												"configError": {
+													"type": [
+														"string",
+														"null"
+													]
+												},
+												"callbackUrl": {
+													"type": [
+														"string",
+														"null"
+													]
+												},
+												"corpId": {
+													"type": [
+														"string",
+														"null"
+													]
+												},
+												"agentId": {
+													"type": [
+														"string",
+														"null"
+													]
+												},
+												"corpCallbackConfigured": {
+													"type": "boolean"
+												}
+											}
+										}
+									}
+								}
+							}
+						}
+					}
+				}
+			}
+		},
+		"/api/auth/wecom/admin/connect": {
+			"post": {
+				"operationId": "auth_wecom_admin_connect_post",
+				"summary": "POST api/auth/wecom/admin/connect",
+				"x-oj-file": "auth/wecom/admin/api.ts",
+				"tags": [
+					"auth"
+				],
+				"responses": {
+					"200": {
+						"description": "OK",
+						"x-oj-response-enforced": false,
+						"content": {
+							"application/json": {
+								"schema": {
+									"type": "object",
+									"required": [
+										"code",
+										"msg",
+										"data"
+									],
+									"properties": {
+										"code": {
+											"type": "integer"
+										},
+										"msg": {
+											"type": "string"
+										},
+										"data": {
+											"type": "object",
+											"required": [
+												"corpId",
+												"agentId",
+												"departments",
+												"members"
+											],
+											"properties": {
+												"corpId": {
+													"type": "string"
+												},
+												"agentId": {
+													"type": "string"
+												},
+												"departments": {
+													"type": "number"
+												},
+												"members": {
+													"type": "number"
+												}
+											}
+										}
+									}
+								}
+							}
+						}
+					}
+				}
+			}
+		},
 		"/api/auth/wecom/login": {
 			"get": {
 				"operationId": "auth_wecom_login_get",
@@ -4888,7 +5041,9 @@
 												"errDetail",
 												"startedAt",
 												"finishedAt",
-												"updateTime"
+												"updateTime",
+												"agentId",
+												"credentialKind"
 											],
 											"properties": {
 												"connected": {
@@ -4998,6 +5153,23 @@
 												},
 												"updateTime": {
 													"type": "number"
+												},
+												"agentId": {
+													"type": [
+														"string",
+														"null"
+													]
+												},
+												"credentialKind": {
+													"type": [
+														"string",
+														"null"
+													],
+													"enum": [
+														"suite",
+														"corp",
+														null
+													]
 												}
 											}
 										}

package/templates/src/auth/api/_shared/wecom/admin.ts

@@ -1,19 +1,19 @@
-// 代开发后台（服务商运营面）的领域逻辑：企业应用清单、启停、开通入口。
+// 企微后台（服务商运营面 + 自建应用接入面）：企业应用清单、启停、开通入口、验证并接入。
 //
-// 三个反常识点，都是踩过的坑：
+// 四个反常识点，都是踩过的坑：
 //   1. **不读部署常量也能停用**：`wecom_base_url` 配错时正是最需要「先把这个企业停掉」的时刻，
-//      所以清单与启停都不依赖 `readWecomConfig`，只有开通入口要（它得调企微换预授权码）。
+//      所以清单与启停都不依赖 `readSuiteConfig`，只有开通入口要（它得调企微换预授权码）。
 //   2. **不能用 `asTenant` 清会话**：管理员请求自带自己的租户头（多半是 `default`），
 //      而 `asTenant` 只能在「请求还没有租户」时调用，否则抛错。故吊销目标企业会话走带
 //      `tenant_id = ?` 的裸 SQL（守卫是 check-on-miss，带了租户条件即放行）。
 //   3. **停用单个应用 ≠ 停用企业**：会话是按租户（= 企业）发的，一个企业可能有测试/正式两个应用。
 //      只有该企业**再没有启用中的应用**时才吊销会话——否则停用测试应用会把正式环境的人踢下线。
 import type { WecomClient } from "./client";
-import type { WecomConfig } from "./config";
+import type { WecomConfig, WecomCorpConfig, WecomKind } from "./config";
 import type { WecomStoreDeps } from "./store";
 import { invalidateAllUsers } from "#/_platform/_shared/service/infra/access";
 import { assertProviderConfig, eventUrlOf } from "./config";
-import { corpScope, revokeTenantSessions, tenantOfCorp } from "./store";
+import { corpScope, revokeTenantSessions, saveProfile, tenantOfCorp } from "./store";
 
 export interface WecomAdminDeps {
 	client: WecomClient
@@ -29,7 +29,9 @@ export interface AppRow {
 	env: string
 	corp_name: string | null
 	status: string
-	/** 0=管理员授权 / 1=成员授权：成员授权下这家企业的应用做不了组织架构同步（§2.3） */
+	/** 应用来源：suite=代开发 / corp=企业内部应用（自建） */
+	credential_kind: WecomKind
+	/** 0=管理员授权 / 1=成员授权：成员授权下这家企业的应用做不了组织架构同步（§2.3）；自建行恒 0 */
 	auth_mode: number
 	installed_at: number
 	update_time: number
@@ -37,7 +39,7 @@ export interface AppRow {
 
 export async function listApps(): Promise<AppRow[]> {
 	const rows = await db.table("wecom_app_profile")
-		.select(["suite_id", "corp_id", "agent_id", "auth_corp_id", "env", "corp_name", "status", "auth_mode", "installed_at", "update_time"])
+		.select(["suite_id", "corp_id", "agent_id", "auth_corp_id", "env", "corp_name", "status", "credential_kind", "auth_mode", "installed_at", "update_time"])
 		.all() as unknown as AppRow[];
 	// 稳定序：先按企业、再按应用；同企业多环境并排，运维一眼能看出「哪两个是同一家」
 	return rows.sort((a, b) => a.corp_id.localeCompare(b.corp_id) || a.agent_id.localeCompare(b.agent_id));
@@ -117,3 +119,81 @@ export async function createInstall(
 		expiresIn: auth.expiresIn,
 	};
 }
+
+/** 接入校验最多探多少个部门找人（顶层部门常只有子部门，只看第一个会误判「读不到人」） */
+const CONNECT_SAMPLE_DEPTS = 10;
+
+export interface ConnectResult {
+	corpId: string
+	agentId: string
+	/** 应用可见范围内的部门数 */
+	departments: number
+	/** 示例部门里的直属成员数（>0 才说明通讯录权限真的通了） */
+	members: number
+}
+
+/**
+ * 自建应用「验证并接入」：**四步全过才落库**（plan §4.3）。
+ *
+ * 为什么不能启动时自动写一行：自检失败会变成启动失败，而自建模式最常见的失败是客户还没加可信 IP、
+ * 可见范围没配——那是运营动作，不该让服务起不来。所以这一步放在人点的按钮后面。
+ *
+ * 顺序有讲究：
+ *   1. 先**作废 token 缓存**再换 token。换过 Secret 的部署若命中旧缓存，校验会「通过」，
+ *      而真正的问题（旧 secret 已失效）会在下一个登录请求上以 40001 冒出来。
+ *   2. gettoken 验 secret、department/simplelist 验通讯录读权限、user/simplelist 验能读到人——
+ *      这三件事对应三个最容易配错的开关（Secret 抄错 / 可见范围空 / 通讯录权限没给）。
+ */
+export async function connectCorp(cfg: WecomCorpConfig, client: WecomClient, deps: WecomStoreDeps): Promise<ConnectResult> {
+	await client.invalidateCorpToken(cfg.corpId, cfg.agentId);
+	await client.corpAccessToken(cfg.corpId, cfg.agentId, cfg.corpSecret);
+
+	const depts = await client.departmentChildren(cfg.corpId, cfg.agentId, cfg.corpSecret);
+	if (!depts.length)
+		throw Object.assign(new Error("接入校验失败：应用可见范围里没有任何部门（把「应用可见范围」设为全公司，或至少包含一个部门）"), { status: 400 });
+
+	// 顶层部门常常只有子部门、没有直属成员，所以往后再看几个再下结论
+	let members = 0;
+	for (const d of depts.slice(0, CONNECT_SAMPLE_DEPTS)) {
+		members = (await client.deptMembers(cfg.corpId, cfg.agentId, cfg.corpSecret, d.id)).length;
+		if (members)
+			break;
+	}
+	if (!members)
+		throw Object.assign(new Error("接入校验失败：可见范围内读不到成员（请把应用可见范围扩大到至少一名成员）"), { status: 400 });
+
+	await saveProfile({
+		// corp 行没有套件：suite_id 用空串（主键第一段），来源由 credential_kind 表达
+		suiteId: "",
+		corpId: cfg.corpId,
+		authCorpId: cfg.corpId,
+		agentId: cfg.agentId,
+		env: "prod",
+		corpName: null,
+		credentialKind: "corp",
+		permanentCode: cfg.corpSecret,
+		// 自建应用没有「管理员授权 / 成员授权」之分：恒 0，同步闸门据此直接放行
+		authMode: 0,
+	}, deps);
+
+	// 换过 AgentId 的部署会留下旧应用的活跃行：旧行的 secret 已不可用，留着只会让
+	// 「同一企业多应用」的分辨逻辑误判，故随本次接入一并停用。
+	const stale = await db.table("wecom_app_profile").select(["agent_id"]).where({
+		and: [
+			corpScope(cfg.corpId),
+			{ field: "credential_kind", op: "eq", value: "corp" },
+			{ field: "status", op: "eq", value: "active" },
+		],
+	}).all() as Array<{ agent_id: string }>;
+	for (const r of stale) {
+		const old = String(r.agent_id);
+		if (old === cfg.agentId)
+			continue;
+		await db.table("wecom_app_profile").update({ status: "disabled", update_time: deps.now() }).where({
+			and: [corpScope(cfg.corpId), { field: "agent_id", op: "eq", value: old }],
+		}).run();
+		await client.invalidateCorpToken(cfg.corpId, old);
+	}
+	invalidateAllUsers();
+	return { corpId: cfg.corpId, agentId: cfg.agentId, departments: depts.length, members };
+}