fix(admin): 管理端入口收敛到 /admin/ 子路径，staging 端口 13521，修复生产 /admin/ 假成功

承接 rc.15 的管理端端口收敛（3000 → 13520），本轮把「入口」也收敛到一处：

- staging admin 发布端口 3001 → 13521（保持「生产 + 1」错开），同步
  tests/uat/run-uat.sh 的默认 UAT_ADMIN_URL。
- 管理端产物改为 /admin/ 子路径部署：vite 构建 base=/admin/（dev 仍为 /，开发与
  排查习惯不变）、router history base 跟随 import.meta.env.BASE_URL、三处容器化
  入口（生产 nginx / 本地整套栈 nginx / admin-web 容器内 nginx）统一为「不剥离
  前缀」转发，形态一致。
- 修复生产 nginx /admin/ 的假成功：原为 alias /usr/share/nginx/html/，而那正是
  nginx:alpine 纯净镜像自带的默认页目录（管理端产物不在该容器内），访问返回
  200 + nginx 欢迎页 —— 浏览器不报错、状态码正常，只是打开的不是管理端，比 404
  更难发现。改为 upstream admin_web + proxy_pass，并以真实两跳容器实测：
  /admin/ → 200 且为管理端标题与 /admin/assets/*、/admin/dashboard → 200（SPA
  兜底）、/admin/brand/logo-mark.png → 200、根路径 → 显式 404（用 location = /
  钉住，不依赖「本配置恰好没有 server 级 root」这一偶然事实）。
- 品牌资源引用统一走新增的 src/brand.ts（public/ 资源不受 vite base 影响，原 5 处
  写死根路径，子路径部署下会裂图）；favicon 由仓库内并不存在的 /favicon.svg 改为
  存在的品牌标。
- 补全 tests/uat/run-uat.sh 被截断的尾部：原文件停在 `if [ -`，bash -n 不通过、
  脚本根本无法运行；顺带把此前「定义了却无人消费」的 ADMIN_URL 接到管理端可达性
  实测上，并补结果汇总与非零退出码。
- ui-tests：ui-document-baseline-contracts 新增两类一致性断言（staging 发布端口 ⇄
  run-uat.sh 默认入口、子路径部署的五处约束）；admin-reference-contracts 的资产
  断言适配 brand 模块（断言「组件经 brand 模块引用」+「brand 模块指向正式资产」）。
  6 条新增断言全部经负向注入验证（注入对应缺陷 → 守卫变红且信息指向正确对象）。

验证：UI 门控 14/14 绿；vue-tsc EXIT=0；vite build EXIT=0 且产物资源均为
/admin/ 前缀；三份 nginx 配置 nginx -t 通过。

注：docs/STATUS.md 含此前的在途文档改动（非本次工作，且其中引用了已被删除的
plans 文件），故未纳入本提交；本轮的口径更新已写入该文件待一并处理。

admin-web/index.html

@@ -2,7 +2,11 @@
 <html lang="zh-CN">
   <head>
     <meta charset="UTF-8" />
-    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <!-- 原指向一个 SVG 图标文件，但仓库内并不存在该文件（public/ 下只有 brand/），
+         属既有的 404；且以 / 开头的绝对路径不会随 vite base 变化，
+         在 /admin/ 子路径部署下即使补上文件也取不到。
+         改为指向已存在、且会被 vite 自动加上 base 前缀的品牌标。 -->
+    <link rel="icon" type="image/png" href="/brand/logo-mark.png" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>丹阳公益婚恋 - 运营管理后台</title>
   </head>

admin-web/nginx-admin.conf

@@ -15,9 +15,20 @@ server {
     add_header X-XSS-Protection "1; mode=block" always;
     add_header Referrer-Policy "strict-origin-when-cross-origin" always;
 
-    # SPA fallback
-    location / {
-        try_files $uri $uri/ /index.html;
+    # 根路径没有内容：管理端产物挂在 /admin/ 子路径下（构建 base=/admin/）。
+    # 显式 301 而不是返回 nginx 默认页或 404，避免"打开有东西但其实是别的页面"的假成功。
+    location = / {
+        return 301 /admin/;
+    }
+
+    # SPA：/admin/** 映射到产物根目录。
+    # 上游入口（生产 nginx、本地整套栈 nginx）都**不剥离** /admin 前缀地转发到本容器，
+    # 因此这里必须自己认识这个前缀。
+    # try_files 的兜底写成 URI（/admin/index.html）而不是文件路径：与 alias 配合时，
+    # 写文件路径会被再次拼接 alias 而失效 —— 这是 alias + try_files 的已知坑。
+    location /admin/ {
+        alias /usr/share/nginx/html/;
+        try_files $uri $uri/ /admin/index.html;
     }
 
     # API proxy to backend

admin-web/src/brand.ts

@@ -0,0 +1,14 @@
+// 品牌静态资源的运行时前缀。
+//
+// admin-web/public/ 下的文件不受 vite `base` 影响（无论 base 是什么，都会被原样复制到
+// 构建产物的根目录），因此 .vue 模板里若写死 `src="/brand/xxx.png"`，在产物部署于
+// /admin/ 子路径时，浏览器会去站点根路径请求，最终 404（表现为 logo / 登录插画裂图）。
+//
+// 结论：public/ 下的运行时引用必须显式带上 import.meta.env.BASE_URL。
+// 这里集中导出，避免每处各写一遍拼接而在改 base 时漏改。
+const BRAND_BASE = `${import.meta.env.BASE_URL}brand/`
+
+export const BRAND_LOGO = `${BRAND_BASE}logo-mark.png`
+export const BRAND_LOGIN_SCENE = `${BRAND_BASE}login-illustration.jpg`
+export const BRAND_ACTIVITY_FALLBACK = `${BRAND_BASE}activity-default.jpg`
+export const BRAND_BACKDROP = `${BRAND_BASE}admin-danyang-backdrop.jpg`

admin-web/src/layouts/MainLayout.vue

@@ -2,7 +2,7 @@
   <div class="admin-scene" :class="{ 'sidebar-collapsed': isCollapse }">
     <header class="scene-header" aria-label="善缘丹阳公益服务品牌信息">
       <div class="scene-brand">
-        <img src="/brand/logo-mark.png" alt="善缘丹阳" />
+        <img :src="BRAND_LOGO" alt="善缘丹阳" />
         <div class="scene-brand-copy">
           <strong>善缘丹阳</strong>
           <span>公益婚恋服务平台</span>
@@ -27,7 +27,7 @@
     <el-container class="admin-shell">
       <el-aside :width="isCollapse ? '76px' : '208px'" class="admin-sidebar">
         <div class="brand" :class="{ compact: isCollapse }">
-          <img class="brand-mark" src="/brand/logo-mark.png" alt="" />
+          <img class="brand-mark" :src="BRAND_LOGO" alt="" />
           <div v-if="!isCollapse" class="brand-copy">
             <strong>善缘丹阳</strong>
             <span>公益婚恋服务平台</span>
@@ -129,6 +129,7 @@
 
 <script setup lang="ts">
 import { computed, ref } from 'vue'
+import { BRAND_BACKDROP, BRAND_LOGO } from '@/brand'
 import { useRoute, useRouter } from 'vue-router'
 import { ElMessage } from 'element-plus'
 import {
@@ -260,7 +261,11 @@ function handleLogout() {
   min-height: 100vh;
   padding: 18px 34px 14px;
   overflow: hidden;
-  background: #fff7f7 url('/brand/admin-danyang-backdrop.jpg') center / cover fixed no-repeat;
+  /* 背景图是 public/ 下的运行时资源，必须带 BASE_URL 前缀：
+     写死品牌目录的绝对路径，在产物部署于 /admin/ 子路径时会 404（页面背景变纯色）。
+     用 v-bind 把常量注入 CSS，避免在样式里各写一遍拼接。 */
+  background: #fff7f7 center / cover fixed no-repeat;
+  background-image: url(v-bind('BRAND_BACKDROP'));
 }
 
 .scene-header {

admin-web/src/router/index.ts

@@ -44,7 +44,9 @@ const routes: RouteRecordRaw[] = [
   },
 ]
 
-const router = createRouter({ history: createWebHistory(), routes })
+// history 的 base 必须与 vite 的 base 保持一致（生产构建为 /admin/）。
+// 否则部署在 /admin/ 子路径下时，刷新或直达 /admin/xxx 会因路由匹配基准不符而白屏。
+const router = createRouter({ history: createWebHistory(import.meta.env.BASE_URL), routes })
 
 router.beforeEach((to) => {
   const authStore = useAuthStore()

admin-web/src/views/DashboardView.vue

@@ -157,11 +157,12 @@ import {
 } from '@element-plus/icons-vue'
 import { useAuthStore } from '@/stores/auth'
 import { createEmptyDashboard, loadDashboard } from '@/services/dashboard'
+import { BRAND_ACTIVITY_FALLBACK } from '@/brand'
 import type { DashboardActivity, DashboardModel } from '@/types/dashboard'
 
 const router = useRouter()
 const authStore = useAuthStore()
-const activityFallback = '/brand/activity-default.jpg'
+const activityFallback = BRAND_ACTIVITY_FALLBACK
 const dashboard = ref<DashboardModel>(createEmptyDashboard())
 const loading = ref(true)
 const fatalError = ref('')

admin-web/src/views/LoginView.vue

@@ -1,10 +1,10 @@
 <template>
   <main class="login-shell">
     <section class="brand-panel" aria-label="善缘丹阳公益婚恋服务平台">
-      <img class="brand-scene" src="/brand/login-illustration.jpg" alt="" />
+      <img class="brand-scene" :src="BRAND_LOGIN_SCENE" alt="" />
       <div class="brand-overlay">
         <div class="brand-title">
-          <img src="/brand/logo-mark.png" alt="" />
+          <img :src="BRAND_LOGO" alt="" />
           <div>
             <strong>善缘丹阳</strong>
             <span>公益婚恋服务平台</span>
@@ -62,6 +62,7 @@
 
 <script setup lang="ts">
 import { reactive, ref } from 'vue'
+import { BRAND_LOGIN_SCENE, BRAND_LOGO } from '@/brand'
 import { useRouter } from 'vue-router'
 import { ElMessage } from 'element-plus'
 import type { FormInstance } from 'element-plus'

admin-web/vite.config.ts

@@ -2,8 +2,14 @@ import { defineConfig } from 'vite'
 import vue from '@vitejs/plugin-vue'
 import { resolve } from 'path'
 
-export default defineConfig({
+export default defineConfig(({ command }) => ({
   plugins: [vue()],
+  // 管理端产物部署在 nginx 的 /admin/ 子路径下（见 infrastructure/nginx-production.conf
+  // 与 admin-web/nginx-admin.conf）。构建时必须带 /admin/ 前缀，否则 index.html 引用的
+  // /assets/*.js 会落到站点根路径，被生产 nginx 的其它 location 兜成 404 或错误页面。
+  // 开发服务器保持根路径：http://localhost:13520/ 的既有开发与排查习惯不变
+  // （vite 的 base 对 dev 与 build 各自生效，故此处按 command 分叉）。
+  base: command === 'build' ? '/admin/' : '/',
   resolve: {
     alias: {
       '@': resolve(__dirname, 'src'),
@@ -22,4 +28,4 @@ export default defineConfig({
       },
     },
   },
-})
+}))