fix: resolve routing, i18n, user management, UI, and OpenAPI/frontend configuration issues

frontend/package.json

@@ -9,6 +9,7 @@
     "build": "vite build",
     "preview": "vite preview",
     "gen:openapi": "node scripts/openapi/generate-api.mjs",
+    "gen:openapi:check": "node scripts/openapi/check-stale.mjs",
     "gen:auth": "bash scripts/openapi/generate-auth.sh",
     "lint": "eslint \"src/**/*.{ts,tsx}\""
   },

frontend/scripts/openapi/.openapi-cache.json

@@ -1,4 +1,4 @@
 {
-  "auth": "27df6cab73622bababdbb3d8c166683b8ca3c232db32f0527c96442d1a4ff3ad",
-  "core": "9aa8fdf2c9ed71836a76ff4d9ce9d68ea6d1920609e6b008f297c2e364f91ee6"
+  "auth": "2680796ccf979bf8380ecf6c0e23ccb62524d789bdd2dd1938df302a802051d9",
+  "core": "e01780c02a6ab9bfa83339df603979277ab13aa0d03484a0245a5fcbd3f24df2"
 }

frontend/scripts/openapi/README.md

@@ -4,7 +4,7 @@
 
 
 
-本地维护的 OpenAPI 规范文件位于：
+当前前端生成链路的权威输入位于：
 ```
 scripts/openapi/specs/auth-openapi.yaml
 scripts/openapi/specs/core.yaml
@@ -39,6 +39,8 @@ npm run gen:openapi auth
 npm run gen:openapi core
 
 npm run gen:openapi
+
+npm run gen:openapi:check
 ```
 
 
@@ -66,6 +68,8 @@ npm run gen:openapi your-service
 ```
 
 
+- `scripts/openapi/openapi-manifest.mjs`: OpenAPI 输入/输出清单
+- `scripts/openapi/check-stale.mjs`: 检查 spec 与已生成 client 是否一致
 - `scripts/openapi/generate-api.mjs`: 主生成脚本
 - `scripts/openapi/generate-auth.sh`: 批量生成 auth 与 core 接口（依赖系统 `PATH` 中的 `java`）
 - `scripts/openapi/openapi-generator-config.json`: OpenAPI Generator 配置
@@ -98,6 +102,14 @@ java -version
 1. OpenAPI YAML 文件格式是否正确
 2. Java 环境是否配置正确
 3. 网络连接是否正常（首次运行需要下载 OpenAPI Generator）
+4. 先执行 `npm run gen:openapi:check`，确认是否存在 stale 的 spec/client
+
+
+当前行为说明：
+
+- 如果本地没有 Java 且 spec 没变，`npm run dev` 会跳过生成并继续启动。
+- 如果本地没有 Java 且 spec 已变，脚本会直接报错并阻止启动，避免继续使用过期 client。
+- 如确需临时跳过 stale 检查，可使用 `OPENAPI_ALLOW_STALE=1 npm run dev`，但这只是临时兜底，不建议长期使用。
 
 
 - **OpenAPI Generator CLI**: v2.20.2+

frontend/scripts/openapi/check-stale.mjs

@@ -0,0 +1,55 @@
+import fs from "fs";
+import {
+  getOpenApiApis,
+  getOpenApiCacheFilePath,
+  hashFile,
+} from "./openapi-manifest.mjs";
+
+const cwdPath = process.cwd();
+const apis = getOpenApiApis(cwdPath);
+const cacheFilePath = getOpenApiCacheFilePath(cwdPath);
+const args = new Set(process.argv.slice(2));
+const jsonOutput = args.has("--json");
+const quiet = args.has("--quiet");
+
+let cache = {};
+if (fs.existsSync(cacheFilePath)) {
+  try {
+    const raw = fs.readFileSync(cacheFilePath, "utf-8").trim();
+    cache = raw ? JSON.parse(raw) : {};
+  } catch {
+    cache = {};
+  }
+}
+
+const statuses = apis.map((api) => {
+  const exists = fs.existsSync(api.input);
+  const currentHash = exists ? hashFile(api.input) : "";
+  const cachedHash = cache[api.name] || "";
+
+  return {
+    name: api.name,
+    input: api.input,
+    exists,
+    currentHash,
+    cachedHash,
+    stale: exists && currentHash !== cachedHash,
+  };
+});
+
+if (jsonOutput) {
+  process.stdout.write(`${JSON.stringify(statuses, null, 2)}\n`);
+} else if (!quiet) {
+  statuses.forEach((status) => {
+    const state = !status.exists
+      ? "missing"
+      : status.stale
+        ? "stale"
+        : "fresh";
+    process.stdout.write(`${status.name}: ${state}\n`);
+  });
+}
+
+if (statuses.some((status) => status.stale || !status.exists)) {
+  process.exit(1);
+}

frontend/scripts/openapi/generate-api.mjs

@@ -6,28 +6,18 @@
 import { execSync } from "child_process";
 import path from "path";
 import fs from "fs";
-import { createHash } from "crypto";
 import { fileURLToPath } from "url";
+import {
+  getOpenApiApis,
+  getOpenApiCacheFilePath,
+  hashFile,
+} from "./openapi-manifest.mjs";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
 const cwdPath = process.cwd();
-const outputDirname = path.resolve(cwdPath, "src/api/generated");
-const localSpecsDir = path.resolve(cwdPath, "scripts/openapi/specs");
-
-const apis = [
-  {
-    name: "auth",
-    input: path.resolve(localSpecsDir, "auth-openapi.yaml"),
-    output: path.resolve(outputDirname, "auth-client"),
-  },
-  {
-    name: "core",
-    input: path.resolve(localSpecsDir, "core.yaml"),
-    output: path.resolve(outputDirname, "core-client"),
-  },
-];
+const apis = getOpenApiApis(cwdPath);
 
 const args = process.argv.slice(2);
 const flags = new Set(args.filter((arg) => arg.startsWith("--")));
@@ -44,19 +34,51 @@ if (target && selectedApis.length === 0) {
   process.exit(1);
 }
 
-const cacheFilePath = path.resolve(
-  cwdPath,
-  "scripts/openapi/.openapi-cache.json",
-);
+const cacheFilePath = getOpenApiCacheFilePath(cwdPath);
 let cache = {};
 if (!skipCache && fs.existsSync(cacheFilePath)) {
   cache = JSON.parse(fs.readFileSync(cacheFilePath, "utf-8"));
 }
 
-function hashFile(filePath) {
-  if (!fs.existsSync(filePath)) return "";
-  const content = fs.readFileSync(filePath);
-  return createHash("sha256").update(content).digest("hex");
+function resolveOpenApiGeneratorCommand() {
+  const binaryName =
+    process.platform === "win32"
+      ? "openapi-generator-cli.cmd"
+      : "openapi-generator-cli";
+  const localBinary = path.resolve(cwdPath, "node_modules", ".bin", binaryName);
+
+  if (fs.existsSync(localBinary)) {
+    return `"${localBinary}"`;
+  }
+
+  if (commandExists("pnpm")) {
+    return "pnpm exec openapi-generator-cli";
+  }
+
+  if (commandExists("npm")) {
+    return "npm exec -- openapi-generator-cli";
+  }
+
+  if (commandExists("npx")) {
+    return "npx --no-install openapi-generator-cli";
+  }
+
+  console.error(
+    "❌ openapi-generator-cli not found. Run `npm install` in frontend first, or install pnpm/npm/npx on PATH.",
+  );
+  process.exit(1);
+}
+
+function commandExists(command) {
+  try {
+    execSync(`${process.platform === "win32" ? "where" : "command -v"} ${command}`, {
+      stdio: "ignore",
+      cwd: cwdPath,
+    });
+    return true;
+  } catch {
+    return false;
+  }
 }
 
 /**
@@ -80,6 +102,7 @@ function patchBasePath(outputDir) {
 }
 
 let updated = false;
+const openApiGeneratorCommand = resolveOpenApiGeneratorCommand();
 for (const api of selectedApis) {
   if (!fs.existsSync(api.input)) {
     console.warn(
@@ -100,7 +123,7 @@ for (const api of selectedApis) {
 
   try {
     execSync(
-      `pnpm exec openapi-generator-cli generate --skip-validate-spec -c scripts/openapi/openapi-generator-config.json -i "${api.input}" -o "${api.output}"`,
+      `${openApiGeneratorCommand} generate --skip-validate-spec -c scripts/openapi/openapi-generator-config.json -i "${api.input}" -o "${api.output}"`,
       { stdio: "inherit", cwd: cwdPath },
     );
     patchBasePath(api.output);

frontend/scripts/openapi/generate-auth.sh

@@ -2,9 +2,25 @@
 
 set -e
 
-if ! command -v java >/dev/null 2>&1; then
-  echo 'Error: java not found. Install JDK 17+ and ensure it is on PATH (e.g. JAVA_HOME/bin).' >&2
-  exit 1
+if ! command -v java >/dev/null 2>&1 || ! java -version >/dev/null 2>&1; then
+  if [ -n "${CI:-}" ] || [ "${OPENAPI_GENERATE_STRICT:-}" = "1" ]; then
+    echo 'Error: java not found. Install JDK 17+ and ensure it is on PATH (e.g. JAVA_HOME/bin).' >&2
+    exit 1
+  fi
+
+  STALE_APIS=$(node scripts/openapi/check-stale.mjs --json | node -e "const fs=require('fs');const items=JSON.parse(fs.readFileSync(0,'utf8'));process.stdout.write(items.filter(item=>item.stale || !item.exists).map(item=>item.name).join(','));" || true)
+
+  echo '⚠️  Java runtime not found. Skipping OpenAPI generation and using checked-in API clients.' >&2
+  if [ -n "${STALE_APIS}" ]; then
+    if [ "${OPENAPI_ALLOW_STALE:-}" != "1" ]; then
+      echo "   Error: generated client is stale for: ${STALE_APIS}." >&2
+      echo '   Install JDK 17+ and rerun `npm run gen:auth`, or set OPENAPI_ALLOW_STALE=1 to bypass temporarily.' >&2
+      exit 1
+    fi
+    echo "   Warning: spec changed but generated client was not refreshed for: ${STALE_APIS}." >&2
+  fi
+  echo '   To regenerate locally, install JDK 17+ and rerun `node scripts/openapi/generate-api.mjs auth`.' >&2
+  exit 0
 fi
 
 node scripts/openapi/generate-api.mjs auth

frontend/scripts/openapi/openapi-manifest.mjs

@@ -0,0 +1,32 @@
+import fs from "fs";
+import path from "path";
+import { createHash } from "crypto";
+
+export function getOpenApiApis(cwdPath = process.cwd()) {
+  const outputDirname = path.resolve(cwdPath, "src/api/generated");
+  const localSpecsDir = path.resolve(cwdPath, "scripts/openapi/specs");
+
+  return [
+    {
+      name: "auth",
+      input: path.resolve(localSpecsDir, "auth-openapi.yaml"),
+      output: path.resolve(outputDirname, "auth-client"),
+    },
+    {
+      name: "core",
+      input: path.resolve(localSpecsDir, "core.yaml"),
+      output: path.resolve(outputDirname, "core-client"),
+    },
+  ];
+}
+
+export function getOpenApiCacheFilePath(cwdPath = process.cwd()) {
+  return path.resolve(cwdPath, "scripts/openapi/.openapi-cache.json");
+}
+
+export function hashFile(filePath) {
+  if (!fs.existsSync(filePath)) return "";
+  const content = fs.readFileSync(filePath);
+  return createHash("sha256").update(content).digest("hex");
+}
+