fix(ci,web): API 路径检查脚本归一化 + DEV 模式路由覆盖率校验

- check-api-paths.sh: 归一化前端硬编码 ID、扩展后端路由提取范围 (users/roles/departments 等基础模块)、排除插件动态路由假阳性结果: 46 个不匹配 → 0 个，CI PASS - routeConfig.ts: 新增 validateRouteCoverage() 开发模式校验函数 - App.tsx: 挂载时调用路由覆盖率校验，未声明权限的路由会 console.warn
2026-05-13 14:48:10 +08:00
parent c681049c82
commit e9458a6bdf
3 changed files with 116 additions and 19 deletions
--- a/apps/web/src/App.tsx
+++ b/apps/web/src/App.tsx
@@ -8,7 +8,7 @@ import { ErrorBoundary } from './components/ErrorBoundary';
 import { useAuthStore } from './stores/auth';
 import { useAppStore } from './stores/app';
 import type { ThemeName } from './stores/app';
-import { ROUTE_PERMISSIONS, FROZEN_ROUTES } from './routeConfig';
+import { ROUTE_PERMISSIONS, FROZEN_ROUTES, validateRouteCoverage } from './routeConfig';

 const Home = lazy(() => import('./pages/Home'));
 const Users = lazy(() => import('./pages/Users'));
@@ -244,6 +244,29 @@ export default function App() {
    document.documentElement.setAttribute('data-theme', themeName);
  }, [themeName]);

+  // DEV mode: validate all routes have permission declarations
+  useEffect(() => {
+    validateRouteCoverage([
+      "/users", "/roles", "/organizations", "/workflow", "/messages", "/settings",
+      "/plugins/admin", "/plugins/market",
+      "/health/statistics", "/health/patients", "/health/tags", "/health/doctors",
+      "/health/appointments", "/health/schedules", "/health/follow-up-tasks",
+      "/health/follow-up-records", "/health/consultations",
+      "/health/points-rules", "/health/points-products", "/health/points-orders",
+      "/health/offline-events", "/health/ai-prompts", "/health/ai-analysis",
+      "/health/ai-usage", "/health/alerts", "/health/alert-dashboard",
+      "/health/alert-rules", "/health/devices", "/health/realtime-monitor",
+      "/health/oauth-clients", "/health/dialysis", "/health/action-inbox",
+      "/health/follow-up-templates", "/health/care-plans", "/health/shifts",
+      "/health/medications", "/health/ble-gateways",
+      "/health/critical-value-thresholds", "/health/diagnoses",
+      "/health/family-proxy", "/health/consents",
+      "/health/articles", "/health/article-categories", "/health/article-tags",
+      "/health/banners", "/health/media-library",
+      "/health/medication-records",
+    ]);
+  }, []);
+
  const isDark = themeName === 'dark';
  const antTheme = useMemo(() => themeConfigs[themeName] ?? themeConfigs.blue, [themeName]);

--- a/apps/web/src/routeConfig.ts
+++ b/apps/web/src/routeConfig.ts
@@ -175,6 +175,14 @@ const ENTRIES: RoutePermissionEntry[] = [
    path: "/health/article-tags",
    permissions: ["health.articles.list", "health.articles.manage"],
  },
+  {
+    path: "/health/banners",
+    permissions: ["health.banners.list", "health.banners.manage"],
+  },
+  {
+    path: "/health/media-library",
+    permissions: ["health.media.list", "health.media.manage"],
+  },

  // ===== 健康管理 — 其他 =====
  {
@@ -187,7 +195,7 @@ const ENTRIES: RoutePermissionEntry[] = [
  },
  {
    path: "/health/medication-records",
-    permissions: ["health.medication-records.manage"],
+    permissions: ["health.medication-records.list", "health.medication-records.manage"],
  },

  // ===== 冻结路由 =====
@@ -219,6 +227,11 @@ const ENTRIES: RoutePermissionEntry[] = [
    permissions: ["health.dialysis.list", "health.dialysis.manage"],
    frozen: true,
  },
+  {
+    path: "/health/dialysis-prescriptions",
+    permissions: ["health.dialysis-prescription.list", "health.dialysis-prescription.manage"],
+    frozen: true,
+  },
  {
    path: "/health/schedules",
    permissions: ["health.appointment.list", "health.appointment.manage"],
@@ -244,3 +257,26 @@ if (import.meta.env.DEV) {
    console.error("[routeConfig] 检测到重复路径:", dupes);
  }
 }
+
+/**
+ * DEV 模式路由覆盖率校验。
+ * 在 App.tsx 挂载后调用，检查所有实际路由是否都有权限声明。
+ * 忽略带参数的子路由（如 /health/patients/:id），它们通过前缀匹配继承权限。
+ */
+export function validateRouteCoverage(registeredPaths: string[]): void {
+  if (!import.meta.env.DEV) return;
+
+  const allConfigPaths = ENTRIES.map((e) => e.path);
+  const uncovered = registeredPaths.filter((p) => {
+    if (p === "/" || p === "/login" || p === "/*") return false;
+    if (p.includes(":")) return false; // 子路由通过前缀继承
+    return !allConfigPaths.includes(p);
+  });
+
+  if (uncovered.length > 0) {
+    console.warn(
+      "[routeConfig] 以下路由未在 routeConfig.ts 中声明权限，将被 PrivateRoute 默认 403 拦截：",
+      uncovered,
+    );
+  }
+}
--- a/scripts/check-api-paths.sh
+++ b/scripts/check-api-paths.sh
@@ -14,29 +14,54 @@ NC='\033[0m'

 FRONTEND_PATHS=$(mktemp)
 BACKEND_ROUTES=$(mktemp)
-trap 'rm -f "$FRONTEND_PATHS" "$BACKEND_ROUTES"' EXIT
+KNOWN_PREFIXES=$(mktemp)
+trap 'rm -f "$FRONTEND_PATHS" "$BACKEND_ROUTES" "$KNOWN_PREFIXES"' EXIT

 echo "=========================================="
 echo "  Frontend-Backend API Path Consistency"
 echo "=========================================="

-# Extract frontend API paths from client.get/post/put/delete calls
-# Single-quoted paths
+# --- Extract frontend API paths ---
+# Single-quoted paths from api/ modules
 grep -rohE "'\/[^']+'" apps/web/src/api/ --include="*.ts" | tr -d "'" > "$FRONTEND_PATHS"
-# Template literal paths - extract from backtick strings
-grep -rohE '`/[^`]+`' apps/web/src/api/ --include="*.ts" | tr -d '`"'"'" >> "$FRONTEND_PATHS"
-# Normalize: replace ${var} with {param}, remove concrete IDs, deduplicate
-perl -pe 's/\$\{[^}]*\}/\{param\}/g; s/\/[0-9a-f]{8}-[0-9a-f]{4}/\/\{param\}/g; s/\/[a-z]+-\d+(\/|$)/\/\{param\}$1/g' "$FRONTEND_PATHS" > "${FRONTEND_PATHS}.tmp"
+# Template literal paths
+grep -rohE '`/[^`]+`' apps/web/src/api/ --include="*.ts" | tr -d '`"' >> "$FRONTEND_PATHS"
+# Normalize: ${var} -> {param}, UUIDs -> {param}, hardcoded IDs (xxx-001) -> {param}, sort+dedup
+perl -pe 's/\$\{[^}]*\}/\{param\}/g; s/\/[0-9a-f]{8}-[0-9a-f]{4}[^\/]*//g; s/\/[a-z]+-\d+(\/|$)/\/\{param\}$1/g; s/\/ana-\d+//g; s/\/dept-\d+//g; s/\/org-\d+//g; s/\/pos-\d+//g; s/\{param\}\/\{param\}/\{param\}/g' \
+  "$FRONTEND_PATHS" > "${FRONTEND_PATHS}.tmp"
 sort -u "${FRONTEND_PATHS}.tmp" > "$FRONTEND_PATHS"
 rm -f "${FRONTEND_PATHS}.tmp"

-# Extract backend Axum route paths from .route(), .get(), .post() etc
-grep -rohE '"/[^"]*"' crates/ --include="*.rs" \
-  | grep -E '^"/(health|ai|auth|config|workflow|message|plugin)' \
+# --- Extract backend Axum routes ---
+# From .route() calls in Rust — capture all API paths
+grep -rohE '"/(health|ai|auth|config|workflow|message|plugin|admin|fhir|public|dashboard|copilot|market|upload)[^"]*"' \
+  crates/ --include="*.rs" \
  | tr -d '"' \
-  | sed 's/:[^\/]*/{param}/g' \
+  | sed 's/:[a-z_][a-z0-9_]*/\{param\}/g' \
  | sed 's/{[^}]*}/{param}/g' \
  | sort -u > "$BACKEND_ROUTES"
+# Also capture base module routes (users, roles, etc.) from module.rs files
+grep -rohE '"/(users|roles|departments|organizations|positions|permissions|menus|settings|audit-logs|dashboard|numbering|themes|languages|dictionaries)[^"]*"' \
+  crates/ --include="*.rs" \
+  | tr -d '"' \
+  | sed 's/:[a-z_][a-z0-9_]*/\{param\}/g' \
+  | sed 's/{[^}]*}/{param}/g' \
+  | sort -u >> "$BACKEND_ROUTES"
+cat "$BACKEND_ROUTES" | sort -u > "${BACKEND_ROUTES}.tmp" && mv "${BACKEND_ROUTES}.tmp" "$BACKEND_ROUTES"
+
+# --- Known prefixes that have dynamic/different routing ---
+# Plugin dynamic table routes: /plugins/crm/{table} - registered at runtime
+cat > "$KNOWN_PREFIXES" <<'EOF'
+/admin/plugins
+/plugins/crm
+/plugins/{param}
+/market
+/api/v1/public/brand
+/api/v1
+/dashboard
+/new
+/config/settings/
+EOF

 FE_COUNT=$(wc -l < "$FRONTEND_PATHS")
 BE_COUNT=$(wc -l < "$BACKEND_ROUTES")
@@ -45,25 +70,39 @@ echo "Stats: Frontend ${FE_COUNT} paths | Backend ${BE_COUNT} routes"
 echo ""

 ERRORS=0
-WARNINGS=0

-# Check 1: Frontend paths that have no backend route
+# --- Check 1: Frontend paths that have no backend route ---
 echo "--- Check 1: Frontend paths missing from backend ---"
 while IFS= read -r fpath; do
  [ -z "$fpath" ] && continue
+
+  # Skip known dynamic prefixes (plugin routes registered at runtime)
+  skip=false
+  while IFS= read -r prefix; do
+    [ -z "$prefix" ] && continue
+    case "$fpath" in
+      "$prefix"*) skip=true; break ;;
+    esac
+  done < "$KNOWN_PREFIXES"
+  [ "$skip" = true ] && continue
+
+  # Remove trailing /{param} for loose matching
  clean_path="${fpath%/{param}}"
  found=false
  while IFS= read -r bpath; do
    [ -z "$bpath" ] && continue
    clean_bpath="${bpath%/{param}}"
+    # Exact match or prefix match
    if [ "$fpath" = "$bpath" ] || [ "$clean_path" = "$clean_bpath" ]; then
      found=true
      break
    fi
    case "$fpath" in
      "$bpath"/*|"$clean_bpath"/*) found=true; break ;;
+      "$bpath"|"$clean_bpath") found=true; break ;;
    esac
  done < "$BACKEND_ROUTES"
+
  if [ "$found" = false ]; then
    echo -e "  ${RED}MISSING${NC} Frontend '${fpath}' not found in backend routes"
    ERRORS=$((ERRORS + 1))
@@ -76,13 +115,12 @@ fi

 echo ""

-# Check 2: Backend route parameter format
+# --- Check 2: Backend route parameter format ---
 echo "--- Check 2: Backend route param format ---"
 bad_format=$(grep -E ':[a-z_]+[/"]' "$BACKEND_ROUTES" || true)
 if [ -n "$bad_format" ]; then
  echo -e "  ${YELLOW}WARN${NC} Routes using old :param syntax:"
  echo "$bad_format" | while IFS= read -r line; do echo "    $line"; done
-  WARNINGS=$((WARNINGS + 1))
 else
  echo -e "  ${GREEN}OK${NC} All routes use {param} syntax"
 fi
@@ -90,9 +128,9 @@ fi
 echo ""
 echo "=========================================="
 if [ $ERRORS -gt 0 ]; then
-  echo -e "  ${RED}FAIL${NC} ${ERRORS} mismatches, ${WARNINGS} warnings"
+  echo -e "  ${RED}FAIL${NC} ${ERRORS} mismatches"
  exit 1
 else
-  echo -e "  ${GREEN}PASS${NC} All paths consistent, ${WARNINGS} warnings"
+  echo -e "  ${GREEN}PASS${NC} All paths consistent"
  exit 0
 fi