Merge main into theme-2 and resolve conflicts for desktop architecture

scripts/ensure-port-free.mjs

@@ -1,7 +1,7 @@
 import { execSync } from 'node:child_process';
-import { resolveApiDevPort } from './dev-api-target.mjs';
+import { resolveDevApiPort } from './resolve-dev-api-target.mjs';
 
-const port = process.argv[2] ?? resolveApiDevPort();
+const port = process.argv[2] ?? resolveDevApiPort();
 
 function killWindows(portNum) {
   let out = '';

scripts/resolve-dev-api-target.mjs

@@ -0,0 +1,17 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const envPath = resolve(root, 'apps/api/.env');
+
+/** 读取 apps/api/.env 的 PORT，供 Vite 代理与 dev 脚本共用 */
+export function resolveDevApiPort(fallback = '3000') {
+  if (!existsSync(envPath)) return fallback;
+  const match = readFileSync(envPath, 'utf8').match(/^PORT=(\d+)/m);
+  return match?.[1] ?? fallback;
+}
+
+export function resolveDevApiTarget(fallbackPort = '3000') {
+  return `http://127.0.0.1:${resolveDevApiPort(fallbackPort)}`;
+}