From 9c26d4b7b266d89f6a664339a18d5b7dec804d90 Mon Sep 17 00:00:00 2001 From: WorkBuddy Date: Fri, 18 Sep 2026 19:36:07 +0800 Subject: [PATCH] =?UTF-8?q?chore(admin-web):=20=E5=BC=80=E5=8F=91=E7=AB=AF?= =?UTF-8?q?=E5=8F=A3=203000=20=E2=86=92=2013520=EF=BC=8C=E5=B9=B6=E7=A6=81?= =?UTF-8?q?=E6=AD=A2=E7=AB=AF=E5=8F=A3=E9=9D=99=E9=BB=98=E6=BC=82=E7=A7=BB?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 本机长期并行运行三个项目（videoos / ai-callcenter / 本项目），3000 属最易被 抢用的端口之一。按用户决定改为 13520。 - admin-web/vite.config.ts：server.port 3000 → 13520 - 同处新增 strictPort: true。vite 默认在端口被占用时静默 +1 退到下一个可用端口， 结果是「文档写 13520、实际跑在 13521」且全程不报错 —— 与本项目反复处理的 「声明与兑现失联」同族。加上后端口被占用会直接失败。 - docs/STATUS.md「当前运行状态」同步为 13520。 - ui-tests/ui-document-baseline-contracts.mjs：新增端口一致性守卫。 端口写在两处（vite.config.ts 是权威，STATUS.md 给人照做），只改一处不会让任何 测试变红，却会让照文档操作的人打不开页面。守卫断言的是「两处一致」而非写死 13520 —— 允许改端口，允许的是「一起改」，不是「只改一处」。 两处解析均用「解析失败即失败」写法，避免正则匹配不到时断言退化成与 undefined 比较而失去意义（本项目踩过的守卫静默失效坑）。 用 assert.equal 而非 assert.match：match 失败会把整份 STATUS.md（3000+ 行） 打进报错，噪声会盖掉真正的不一致信息 —— 负向验证时实测确认。 - .gitignore：忽略 admin-web/vite.config.ts.timestamp-*.mjs。 vite 在 dev server 被强杀（未优雅退出）时遗留该配置临时文件，本机已多次出现。 未改动（有意）： - CORS 不受影响。CorsConfig 默认拒绝所有跨域是刻意设计，且注释已写明「管理端走 Vite 代理（同源）」—— dev 端口变化不产生跨域。 - infrastructure/docker-compose.prod.yml 的 127.0.0.1:3000:80 是生产 admin 容器 的发布端口，与开发服务器无关，未动。 - releases/v1.0.0-RC.* 内的 3000 为历史发布快照，属冻结记录，不改写。 验证 - UI 契约门控 14/14 全绿（含新增守卫）；vue-tsc --noEmit EXIT=0。 - 负向验证：把 STATUS.md 改回 3000 → 守卫变红并精确报出 「管理后台端口不一致：STATUS.md=3000，vite.config.ts=13520」及行号；还原后复绿。 - 真实启停：dev server 实跑 http://localhost:13520/（HTTP 200），旧端口 3000 无监听。 - strictPort 负向验证：端口被占用时第二实例立即以 「Error: Port 13520 is already in use」退出，未漂移到 13521。 - vite build EXIT=0（19.35s）。 注：vite build 直接执行会失败，栈停在 emptyDir(dist) 且全部位于本机 node-safe-delete-shim（批量删除守卫）内，与本次改动无关；改用全新 outDir 复跑即 成功，据此排除「改动导致构建失败」。该现象此前无记录，已写入技能备查。 --- .gitignore | 2 ++ admin-web/vite.config.ts | 6 +++++- docs/STATUS.md | 2 +- ui-tests/ui-document-baseline-contracts.mjs | 18 ++++++++++++++++++ 4 files changed, 26 insertions(+), 2 deletions(-) diff --git a/.gitignore b/.gitignore index 834b506..82c8899 100644 --- a/.gitignore +++ b/.gitignore @@ -15,6 +15,8 @@ backend/target/ admin-web/dist/ miniapp/dist/ miniapp/unpackage/ +# vite 在 dev server 被强杀（未优雅退出）时会遗留配置临时文件 +admin-web/vite.config.ts.timestamp-*.mjs # IDE .idea/ diff --git a/admin-web/vite.config.ts b/admin-web/vite.config.ts index 8c840e8..d6c161d 100644 --- a/admin-web/vite.config.ts +++ b/admin-web/vite.config.ts @@ -10,7 +10,11 @@ export default defineConfig({ }, }, server: { - port: 3000, + // 本机开发端口。避开 3000/8080/8081/8085 等被其他项目占用的常用端口。 + port: 13520, + // 端口被占用时直接失败，而不是静默 +1 退到 13521。 + // 静默漂移会让「文档写 13520、实际跑在别的端口」这种不一致无法被发现。 + strictPort: true, proxy: { '/api': { target: 'http://localhost:8085', diff --git a/docs/STATUS.md b/docs/STATUS.md index 1b77149..de25915 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -467,7 +467,7 @@ ### 当前运行状态 ``` -管理后台: http://localhost:3000/ (凭证由本地环境变量或安全 Seed 提供) +管理后台: http://localhost:13520/ (凭证由本地环境变量或安全 Seed 提供) API 网关: http://localhost:8085/api/v1/ PostgreSQL: localhost:5434 (danyang_match) Redis: localhost:6381 diff --git a/ui-tests/ui-document-baseline-contracts.mjs b/ui-tests/ui-document-baseline-contracts.mjs index 8a5881a..b80d67f 100644 --- a/ui-tests/ui-document-baseline-contracts.mjs +++ b/ui-tests/ui-document-baseline-contracts.mjs @@ -67,4 +67,22 @@ assert.match(matrix, /2026-09-16 验收通过/, '页面矩阵未记录 11 页验 assert.doesNotMatch(matrix, /待重新实现|待开始/, '页面矩阵仍残留未完成状态') assert.doesNotMatch(matrix, /63 个页面.*(全部|全量).*重构/, '页面矩阵仍要求本批全量重构') +// —— 管理端本地开发端口一致性 —— +// 端口在两个地方各写了一份：admin-web/vite.config.ts 是唯一权威， +// docs/STATUS.md 的「当前运行状态」是给人照做的。只改一处不会让任何测试变红， +// 但会让照文档操作的人打不开页面 —— 属于本项目反复出现的「声明与兑现失联」同族问题， +// 因此用门控钉住。注意断言的是「两处一致」而非写死 13520：改端口是允许的， +// 允许的是「一起改」，不是「只改一处」。 +const viteConfig = read('admin-web/vite.config.ts') +const vitePort = viteConfig.match(/^\s*port:\s*(\d+),/m)?.[1] +// 解析失败即失败：正则匹配不到时捕获组为 undefined，断言会退化成"与 undefined 比较" +// 而失去意义 —— 守卫静默失效是本项目踩过的坑。 +assert.ok(vitePort, '未能从 admin-web/vite.config.ts 解析出 server.port（守卫自身失效）') + +// 用 equal 而不是 match：match 失败会把整份文档打进报错里， +// 3000 行的噪声会盖掉真正的不一致信息。 +const docPort = status.match(/管理后台:\s*http:\/\/localhost:(\d+)\//)?.[1] +assert.ok(docPort, 'docs/STATUS.md「当前运行状态」未声明管理后台地址（守卫自身失效）') +assert.equal(docPort, vitePort, `管理后台端口不一致：STATUS.md=${docPort}，vite.config.ts=${vitePort}`) + console.log('UI document baseline contracts passed')