From 8499de27e6b2e1a7eed744ea49117f04ced6443e Mon Sep 17 00:00:00 2001
From: yeuimu <2197651308@qq.com>
Date: Wed, 23 Sep 2026 05:43:13 +0000
Subject: [PATCH] =?UTF-8?q?docs(skill):=20swagger=20is=20a=20curated=20reg?=
 =?UTF-8?q?istry=20=E2=80=94=20audit-verified=20gaps=20both=20ways?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Cross-diff of all @Controller routes vs docs-json (486 vs 438 after shape
normalization): real undocumented routes include the entire authority-matrix
family (live 200, 0 doc entries), select-visibility, plugin runtime/proxy,
ShareDB socket internals, oauth-server, health; ~27 doc entries belong to
the enterprise backend and 404 on this CE instance. Completeness check =
controller grep, docs-json alone is not exhaustive.
---
 .../inkreach-teable/api-reference/rest-api.md | 29 ++++++++++++++++++-
 1 file changed, 28 insertions(+), 1 deletion(-)

diff --git a/skills/inkreach-teable/api-reference/rest-api.md b/skills/inkreach-teable/api-reference/rest-api.md
index cc684b2..ac1337e 100644
--- a/skills/inkreach-teable/api-reference/rest-api.md
+++ b/skills/inkreach-teable/api-reference/rest-api.md
@@ -177,6 +177,32 @@ curl -s "$BASE/docs-json" | python3 -c "import json,sys; [print(m.upper(), p) fo
 ssh -L 3003:localhost:3003 <backend-host>   # then use http://localhost:3003/docs-json
 ```
 
+### ⚠️ Swagger is a curated registry, NOT an auto-scan (audited 2026-09-23)
+
+The doc is generated from an explicit `registerRoutes()` registry
+(`packages/openapi/src/generate.schema.ts`), so any controller never
+registered there is **invisible in /docs**. Cross-diffing every
+`@Controller` route in the backend source against docs-json found gaps in
+BOTH directions:
+
+- **Real routes missing from swagger** (controller-verified, several
+  live-200): the whole **authority-matrix** family
+  (`/api/base/{bid}/authority-matrix*` — the 4-layer permission system, see
+  `docs/authority-matrix.md` in the app repo); **select-visibility**
+  (`GET /api/table/{tid}/select-visibility/{rid}/{fid}`); plugin runtime
+  (`/api/plugin/{pid}/runtime*`, `upload-bundle`, `bridge`, `plugin-proxy/*`,
+  `csp-origins`); ShareDB internals (`…/socket/doc-ids`,
+  `…/socket/snapshot-bulk`); oauth-server (`/api/oauth/authorize`,
+  `/decision`, `/access_token`); import status; admin ops
+  (performance-cache, heap-snapshot); `/health` + `/health/memory`
+  (backend origin only — the domain 404s them).
+- **Doc entries with no controller on this CE instance** (~27: `/user-integrations*`,
+  `/unsubscribe/*`, `/billing/*`, `/admin/enterprise-license/*`…): registered
+  by the shared openapi package but served by the enterprise backend —
+  they 404 here.
+
+So the completeness check is the **controller grep**, not docs-json.
+
 Route groups NOT detailed in this guide (see docs-json for shapes):
 `/api/auth/*` (session signin/signout, password/email flows, oauth),
 `/api/user/*` (profile, lang, timezone, avatar), `/api/space/*` +
@@ -193,7 +219,8 @@ automation webhook route), plugin UI endpoints (`/api/plugin/*` panels,
 chart, proxy), `/api/v2/integrity`, `/api/v1/ai-proxy`.
 
 When you use one of these, verify the exact param shape before calling —
-from docs-json (backend origin / ssh tunnel), or from the backend source:
+from docs-json (backend origin / domain / ssh tunnel), or from the backend
+source:
 `grep -rh "@Controller(\|@Get(\|@Post(\|@Patch(\|@Put(\|@Delete(" apps/nestjs-backend/src/features --include='*.controller.ts'`
 in the inkreach-teable app repo. Do not guess key names (the automation
 contract lesson applies instance-wide).