From 9a3d0d440f43deab66c1f8a4a08cdbfc6f9d73eb Mon Sep 17 00:00:00 2001
From: Jesse_Chen <chen.yue@mevixaga.com>
Date: Thu, 6 Aug 2026 21:20:12 +0800
Subject: [PATCH] fix(frontend): declare admin users runtime locally

---
 docs/BUG_HISTORY.md                         | 13 +++++++++++++
 frontend/src/app/api/admin/users/route.ts   |  4 +++-
 frontend/tests/admin-users-contract.test.ts |  4 +++-
 3 files changed, 19 insertions(+), 2 deletions(-)

diff --git a/docs/BUG_HISTORY.md b/docs/BUG_HISTORY.md
index d705dc07..24af0bee 100644
--- a/docs/BUG_HISTORY.md
+++ b/docs/BUG_HISTORY.md
@@ -2256,3 +2256,16 @@
 - 相关记录：BUG-124
 - 复发自：BUG-124
 - 修复版本：待提交（本地可测）
+
+## BUG-131 | Admin users route config re-export blocks Turbopack quality gate
+
+- 状态：resolved（local）
+- 首次发现：2026-08-06
+- 最近更新：2026-08-06
+- 影响面：`frontend/src/app/api/admin/users/route.ts` 与 Next.js 16 Turbopack production build。
+- 用户现象：Gitea quality gate 的默认 `next build` 无法解析 `/api/admin/users` route config。
+- 根因：别名 route 从 `../customers/route` re-export `runtime`；Next/Turbopack 要求 route config 在 route 文件内静态本地导出。
+- 修复：在 users route 本地声明 `export const runtime = "nodejs"`，仅 re-export HTTP handlers；扫描全部 route 后未发现其他 `runtime`、`dynamic` 或 `revalidate` re-export。
+- 验证：admin users contract、`tsc --noEmit`、默认 Turbopack `next build`、`next build --webpack` 与 `git diff --check`。
+- 防复发：route config 必须在各自 route 文件内静态声明，别名 route 只能 re-export handlers。
+- 修复版本：本提交（本地已验证）
diff --git a/frontend/src/app/api/admin/users/route.ts b/frontend/src/app/api/admin/users/route.ts
index f5a5737b..a12fc55f 100644
--- a/frontend/src/app/api/admin/users/route.ts
+++ b/frontend/src/app/api/admin/users/route.ts
@@ -1 +1,3 @@
-export { DELETE, GET, PATCH, POST, PUT, runtime } from "../customers/route";
+export const runtime = "nodejs";
+
+export { DELETE, GET, PATCH, POST, PUT } from "../customers/route";
diff --git a/frontend/tests/admin-users-contract.test.ts b/frontend/tests/admin-users-contract.test.ts
index d42941fc..99d8e55c 100644
--- a/frontend/tests/admin-users-contract.test.ts
+++ b/frontend/tests/admin-users-contract.test.ts
@@ -39,5 +39,7 @@ test("admin_users migration is service-role-only and auditable", () => {
 });
 
 test("legacy admin users route aliases the guarded customer resource", () => {
-  assert.match(usersSource, /export \{ DELETE, GET, PATCH, POST, PUT, runtime \} from "\.\.\/customers\/route"/);
+  assert.match(usersSource, /export const runtime = "nodejs"/);
+  assert.match(usersSource, /export \{ DELETE, GET, PATCH, POST, PUT \} from "\.\.\/customers\/route"/);
+  assert.doesNotMatch(usersSource, /export \{[^}]*\bruntime\b[^}]*\} from/);
 });