fix(miniapp): 修复 2 个页面 WXML 结构缺陷，并补第 15 项门禁（WXML 结构守卫）

现象：微信开发者工具报 [ WXML 文件编译错误] ./pages/service-history/service-history.wxml get tag end without start, near `</` 真实缺陷（实测 2 处，非 1 处）： - pages/service-history/service-history.wxml 多 1 个 </view> - pages/service-program/service-program.wxml 多 1 个 </view> （均为单行压缩写法，随更早提交入库；全仓另外 84 个 WXML 结构自洽）根因不是这两个文件写错，而是**门禁覆盖盲区**：既有 14 项 UI 契约全是「源码内容 / 清单断言」，没有任何一条会解析 WXML，所以「14/14 全绿」与「小程序能不能编译」之间没有因果关系。修复： 1. 删掉两处多余闭合标签 → 86 个 WXML 结构全部自洽。 2. 新增 scripts/lib/wxml-structure.mjs：按**引号状态机**逐字符扫描标签。不能用懒惰正则 —— 属性值里可以合法出现 `>`（`subtitle="{{unreadTotal > 0 ? ...}}"`），正则会在引号内的 `>` 处提前收尾，把自闭合标签的 `/` 读掉，报出假阳性。（首版实现即踩此坑，曾把合法的 messages.wxml 误判为坏文件；已复核排除。） 3. 新增 scripts/check-wxml-structure.mjs（CLI，退出码 0/1/2）。 4. 新增 ui-tests/wxml-structure-contracts.mjs：全量扫描 + **3 组内置自检样例** （正向样例故意在属性值内放 `>`，把「假阳性」这个坑钉进门禁）。 5. scripts/run-ui-contracts.mjs：MIN_GUARDS 14 → 15（守卫被删/改名仍会拒绝报绿）。 6. 文档口径同步：AGENTS.md、STATUS.md（4 处当前口径 + 新增 rc.17 版本行）； ci.yml ui-contracts job 注释 14 → 15。历史时点行保留原值。负向验证（三项，全部通过）： - 注入「多余闭合 / 未闭合」→ 退出 1，且只报坏文件、合法的 `>` 属性文件未被误报； - UI_GUARDS_MIN=99 → 拒绝报绿（数量下限分支可自检）； - CLI 直扫坏目录 → 退出 1。验证：node scripts/run-ui-contracts.mjs → PASS 15 / 15，0 失败，退出码 0。未跑：微信开发者工具真实编译（本机无该环境），结论仅由结构判据支撑。
2026-09-19 11:25:05 +08:00
parent 5715987049
commit d036c9b986
9 changed files with 298 additions and 9 deletions
@@ -146,8 +146,10 @@ jobs:
  ui-contracts:
    name: UI Contracts (source-structure gates)
    runs-on: ubuntu-latest
-    # Phase 23 遗留（收尾计划 批 1 Task 1.1）：14 个 UI 契约门禁此前**只在本地手工执行**，
+    # Phase 23 遗留（收尾计划 批 1 Task 1.1）：UI 契约门禁此前**只在本地手工执行**，
    # 没有 CI 把关 —— 即「改动破坏了源码结构契约也不会被发现」。
+    # 2026-09-19：14 → 15 个守卫，新增 WXML 结构守卫（此前 14 绿时小程序仍有两个页面
+    # 编译失败:service-history / service-program 各多一个 </view>）。
    # 守卫是纯 node 内建模块、零 npm 依赖，故无需装依赖；统一执行器负责逐个跑 + 汇总 + 非零退出，
    # 并校验守卫数量下限（防止守卫被删除/改名后仍然报绿）。
    steps:
@@ -22,7 +22,7 @@ V1.1 是 V1.0 的增量升级。正确的 V1.0 核心按 KEEP 处理，不得因

 业务 Phase 唯一执行计划：`docs/善缘丹阳 V1.1 客户需求基线增量开发与修复计划.md`。

-当前 UI 重设计唯一总计划：`docs/superpowers/plans/2026-09-13-reference-driven-dual-client-ui-redesign.md`。首批范围（小程序 11 个核心页面 + 管理端框架/工作台）已于 **2026-09-16 通过用户验收（结论：基本达标）**，此前"视觉否决 / REOPENED"的判定随之关闭，UI 契约门禁 **14/14** 全绿（2026-09-16 时为 13 项，此后新增端口与 `/admin/` 子路径一致性门禁）。管理端桌面端目视复验仍待用户执行。
+当前 UI 重设计唯一总计划：`docs/superpowers/plans/2026-09-13-reference-driven-dual-client-ui-redesign.md`。首批范围（小程序 11 个核心页面 + 管理端框架/工作台）已于 **2026-09-16 通过用户验收（结论：基本达标）**，此前"视觉否决 / REOPENED"的判定随之关闭，UI 契约门禁 **15/15** 全绿（2026-09-16 时为 13 项，此后新增端口与 `/admin/` 子路径一致性门禁；2026-09-19 新增第 15 项 **WXML 结构守卫** —— 此前 14 项全绿时小程序实际有两个页面 `service-history` / `service-program` 因多一个 `</view>` **编译失败**，说明既有门禁全是源码内容断言、没有一条会解析 WXML）。管理端桌面端目视复验仍待用户执行。

 ---

@@ -2,7 +2,7 @@

 > **2026-09-18 当前有效结论：`V1.1 RECOVERY PHASE 01~22 CLOSED / PHASE 23 PARTIALLY CLOSED / HORIZONTAL HARDENING DONE (HTTP SEMANTICS + IDEMPOTENCY + PORT/ENTRY GUARDS) / UI REDESIGN ACCEPTED BY USER / 669 TESTS GREEN / STOPPED BEFORE PHASE 24 (UAT) — AWAITING USER GO`。**
 >
-> 阶段 0（在途收口）、阶段 1（小程序 C 组 + discover 筛选重设计）、阶段 2（管理端 Vue 新框架适配）、阶段 3（CapabilityService 独立化）、阶段 4（双端总验收）全部完成。三端构建通过、**13/13 契约全绿**（阶段 4 验收时点值；当前 UI 契约门禁为 **14/14**）、核心 11 页面**全部 TS-only（11/11）**。**UI 重设计首批 11 页已于 2026-09-16 通过用户验收（结论：基本达标）**；`/me/*` 前后端契约同轮收敛，17 个 404 调用已恢复。**Phase 08（Like / Match / Block）、Phase 09（Text Chat）、Phase 10（Image & Chat Safety）、Phase 11（Notification）、Phase 12（Relationship Progress）、Phase 13（公益红娘转介）、Phase 13A（婚恋咨询与婚前辅导）、Phase 14（多类型公益活动）、Phase 15（活动报名、审核与签到）、Phase 16（活动互选与双方开启沟通确认）、Phase 17（举报与风控）、Phase 18（申诉）、Phase 19（统一运营后台 + 用户端公益服务页面）、Phase 20（Analytics 数据统计与管理驾驶舱）复验已关闭**，十四轮共修复 130+ 处真实缺陷（含 3 处隐藏编译缺陷），并各自补齐测试保真度与守卫。**Phase 21、22 复验已关闭（2026-09-18）**；**Phase 23 为「部分关闭」（2026-09-18）** —— 已清除 44 个 `pass` 空壳与 14 个只断言常量的假不变量测试，新增 4 个经负向注入验证的真实行为守卫与空壳阻断闸门，后端回归 655 全绿；但 **E2E 进入 CI 因需「活栈供给方式」基础设施决策而列为遗留，故不宣布「失败为零可进入 UAT」**。**Phase 23B（E2E 测试基建重建，33→49 passed）、HTTP 语义检修（失败响应携带真实状态码）、幂等键检修（`Idempotency-Key` 30 端点落地，V045/V046）均已于 2026-09-18 完成**，后端全量回归 **669 / 0 failures / 0 errors / 3 skipped**。**管理端入口已收敛到 `/admin/` 子路径（vite base + router base + 三处 nginx 接线），staging 端口 13521；UI 契约门禁 14/14 全绿。Phase 24（UAT）启动需用户确认。**
+> 阶段 0（在途收口）、阶段 1（小程序 C 组 + discover 筛选重设计）、阶段 2（管理端 Vue 新框架适配）、阶段 3（CapabilityService 独立化）、阶段 4（双端总验收）全部完成。三端构建通过、**13/13 契约全绿**（阶段 4 验收时点值；当前 UI 契约门禁为 **15/15**）、核心 11 页面**全部 TS-only（11/11）**。**UI 重设计首批 11 页已于 2026-09-16 通过用户验收（结论：基本达标）**；`/me/*` 前后端契约同轮收敛，17 个 404 调用已恢复。**Phase 08（Like / Match / Block）、Phase 09（Text Chat）、Phase 10（Image & Chat Safety）、Phase 11（Notification）、Phase 12（Relationship Progress）、Phase 13（公益红娘转介）、Phase 13A（婚恋咨询与婚前辅导）、Phase 14（多类型公益活动）、Phase 15（活动报名、审核与签到）、Phase 16（活动互选与双方开启沟通确认）、Phase 17（举报与风控）、Phase 18（申诉）、Phase 19（统一运营后台 + 用户端公益服务页面）、Phase 20（Analytics 数据统计与管理驾驶舱）复验已关闭**，十四轮共修复 130+ 处真实缺陷（含 3 处隐藏编译缺陷），并各自补齐测试保真度与守卫。**Phase 21、22 复验已关闭（2026-09-18）**；**Phase 23 为「部分关闭」（2026-09-18）** —— 已清除 44 个 `pass` 空壳与 14 个只断言常量的假不变量测试，新增 4 个经负向注入验证的真实行为守卫与空壳阻断闸门，后端回归 655 全绿；但 **E2E 进入 CI 因需「活栈供给方式」基础设施决策而列为遗留，故不宣布「失败为零可进入 UAT」**。**Phase 23B（E2E 测试基建重建，33→49 passed）、HTTP 语义检修（失败响应携带真实状态码）、幂等键检修（`Idempotency-Key` 30 端点落地，V045/V046）均已于 2026-09-18 完成**，后端全量回归 **669 / 0 failures / 0 errors / 3 skipped**。**管理端入口已收敛到 `/admin/` 子路径（vite base + router base + 三处 nginx 接线），staging 端口 13521；UI 契约门禁 15/15 全绿（第 15 项为 2026-09-19 新增的 WXML 结构守卫）。Phase 24（UAT）启动需用户确认。**

 最后更新: 2026-09-18 — 分支 `main`（`feat-ui-v11` 保留为冗余锚点）

@@ -27,10 +27,10 @@
 | `/me/*` 路径族 | **已完成**（2026-09-16） | 小程序按 REST 规范（§16 / §22-§40 / §80 / §83-§84）调用 `/me/*`，后端此前**无 `/me` 基路径**致 17 个调用 404。新增 `MeController` 委托既有 service 暴露规范路径，旧路径全部保留，小程序三条历史写法（`/me/privacy-settings`、`/me/photos/{id}/main`、`/me/appeals`）一并兼容；由 `MeRouteContractTest` 锁定 |
 | Admin Web | **验证通过** | 2026-09-14 阶段 4：vue-tsc ✅、vite build ✅ 11.68s；18 modules 齐全；壳层+工作台通过参考图 QA |
 | Miniapp | **验证通过** | 2026-09-16：tsc ✅；**11 核心页全部 TS-only（11/11）**；首批 11 页于 2026-09-16 通过用户验收；discover 筛选重设计已通过 DevTools 验证 |
-| UI 契约测试 | **14/14 通过**（2026-09-18） | 统一执行器 `scripts/run-ui-contracts.mjs`，**已接入 CI**（job `ui-contracts`）；历史：2026-09-16 为 13 项，此后新增端口一致性与 `/admin/` 子路径守卫 |
+| UI 契约测试 | **15/15 通过**（2026-09-19） | 统一执行器 `scripts/run-ui-contracts.mjs`，**已接入 CI**（job `ui-contracts`）；历史：2026-09-16 为 13 项，此后新增端口一致性与 `/admin/` 子路径守卫（14 项）；2026-09-19 新增 `wxml-structure-contracts.mjs`（第 15 项）—— 此前 14 项全绿时小程序 `service-history` / `service-program` 两页各多一个 `</view>`，**微信开发者工具实际编译失败** |
 | Git 工作区 | **已清零** | 阶段 0~4 共 24+ commit 可追溯；`git status --porcelain` 0 行 |
 | 核心待清债务 | 0 项 | 已全部清偿：3 页 JS→TS 迁移、backend 全量回归（420 tests）、DevTools 真机截图留档（2026-09-14）、`/me/*` 路径族收敛（2026-09-16）、实体↔生产迁移漂移修复（V037/V038/V039，2026-09-16/17） |
-| UAT / RC / Production | **Phase 01~22 复验关闭；Phase 23 部分关闭；停在 Phase 24（UAT）门前** | 后端 **669 / 0 failures / 0 errors / 3 skipped**；UI 契约门禁 **14/14**；管理端入口收敛至 `/admin/` 子路径（staging 13521）；HTTP 语义 + 身份收敛 + 幂等键三轮横向加固完成。**Phase 24 启动需用户确认** |
+| UAT / RC / Production | **Phase 01~22 复验关闭；Phase 23 部分关闭；停在 Phase 24（UAT）门前** | 后端 **669 / 0 failures / 0 errors / 3 skipped**；UI 契约门禁 **15/15**；管理端入口收敛至 `/admin/` 子路径（staging 13521）；HTTP 语义 + 身份收敛 + 幂等键三轮横向加固完成。**Phase 24 启动需用户确认** |

 > **下一阶段计划（唯一）**：`docs/superpowers/plans/2026-09-18-phase23-closeout-and-uat-readiness.md`
 > —— 批 1 快速收尾（ui-tests 接入 CI）/ 批 2 Phase 23 剩余（E2E 实现 + CI 串联，**需基础设施决策**）/
@@ -58,6 +58,7 @@
 | 1.1.0-rc.14 | 2026-09-18 | Phase 23 **部分关闭**（44 个 `pass` 空壳清除、4 个真实 INV 行为守卫、空壳阻断闸门）；Phase 23B E2E 基建重建（conftest + seed + CI e2e job，本机活栈 33 passed）；全量回归 **655 tests** 全绿 |
 | 1.1.0-rc.15 | 2026-09-18 | HTTP 语义检修（105 处错误响应携带真实状态码，回归 664）→ 身份收敛（运营身份禁入用户端 + PathPattern 守卫）→ 幂等键检修（`Idempotency-Key` 30 端点落地，V045/V046，前端 25 处调用点修正，E2E 49 passed）；admin 端口收敛 13520（vite / 文档 / 生产 compose 三处一致）；全量回归 **669 / 0 / 0 / 3** 全绿 |
 | 1.1.0-rc.16 | 2026-09-18 | 管理端入口收敛（承接 rc.15 的端口收敛）：staging admin 端口 3001 → **13521**（保持「生产 + 1」，同步 `run-uat.sh` 默认入口）；管理端产物改为 **`/admin/` 子路径部署**（vite 构建 base + router history base + 三处 nginx 接线统一为「不剥离前缀」转发）；**修复生产 nginx `/admin/` 的假成功**——原 `alias` 指向 `nginx:alpine` 自带默认页目录，访问返回 200 + nginx 欢迎页（比 404 更难发现），已改为 `upstream admin_web` + `proxy_pass` 并以真实两跳容器实测；补修 `run-uat.sh` 被截断的尾部（原文件语法不完整、无法运行）并把 `ADMIN_URL` 接到管理端可达性实测；品牌资源引用统一走 `src/brand.ts` 的 `BASE_URL` 拼接（原 5 处写死根路径，子路径下会裂图），favicon 由不存在的 `/favicon.svg` 改为存在的品牌标；UI 门控 **14/14 绿**，新增端口/入口断言 6 条（全部经负向注入验证） |
+| 1.1.0-rc.17 | 2026-09-19 | **小程序 WXML 结构缺陷修复 + 补第 15 项门禁**：微信开发者工具报 `service-history.wxml` `get tag end without start`，实测 **2 个页面**各多一个 `</view>`（`service-history` / `service-program`，单行压缩写法，已随更早提交入库）→ 修复后 86 个 WXML 结构全部自洽。**根因是门禁覆盖盲区**：既有 14 项全是「源码内容/清单断言」，没有一条会解析 WXML，故 14 绿与「小程序能不能编译」无关。新增 `scripts/lib/wxml-structure.mjs`（引号状态机扫描器）+ `scripts/check-wxml-structure.mjs`（CLI）+ `ui-tests/wxml-structure-contracts.mjs`（守卫，含 3 组内置自检样例，其中正向样例**故意在属性值内放 `>`** —— 早期用懒惰正则实现时此处是假阳性来源）。`MIN_GUARDS` 14 → 15。负向验证三项：注入「多余闭合 / 未闭合」→ **退出 1 且只报坏文件**；`UI_GUARDS_MIN=99` → 正确拒绝报绿；CLI 直扫坏目录 → 退出 1。基线 **PASS 15/15**。**未跑**：微信开发者工具真实编译（本机无该环境），仅以结构判据断言 |

 ---

@@ -1 +1 @@
-<view class="service-page"><view class="hero"><text class="eyebrow">U64 公益服务记录</text><text class="hero-title">每一次服务，都清楚可查</text><text class="hero-desc">这里只展示与你有关的公益服务事实，不展示咨询正文。</text></view><view class="content"><view wx:if="{{loading}}" class="card empty-panel"><view class="empty-symbol">…</view><text class="empty-title">正在加载</text></view><view wx:elif="{{error}}" class="card empty-panel"><view class="empty-symbol">!</view><text class="empty-title">{{error}}</text></view><view wx:elif="{{records.length}}" class="block"><view class="card"><view wx:for="{{records}}" wx:key="key" class="record-row"><view class="feature-icon">{{item.icon}}</view><view class="feature-copy"><text class="feature-title">{{item.title}}</text><text class="feature-desc">{{item.date}}</text></view><text class="tag">{{item.status}}</text></view></view></view><view wx:else class="card empty-panel"><view class="empty-symbol">记</view><text class="empty-title">还没有公益服务记录</text><text class="meta">预约到站服务或申请公益咨询后，会在这里留下时间线。</text></view></view><view class="notice">咨询与公益红娘记录彼此分离；工作人员只能查看职责范围内的信息。</view></view></view>
+<view class="service-page"><view class="hero"><text class="eyebrow">U64 公益服务记录</text><text class="hero-title">每一次服务，都清楚可查</text><text class="hero-desc">这里只展示与你有关的公益服务事实，不展示咨询正文。</text></view><view class="content"><view wx:if="{{loading}}" class="card empty-panel"><view class="empty-symbol">…</view><text class="empty-title">正在加载</text></view><view wx:elif="{{error}}" class="card empty-panel"><view class="empty-symbol">!</view><text class="empty-title">{{error}}</text></view><view wx:elif="{{records.length}}" class="block"><view class="card"><view wx:for="{{records}}" wx:key="key" class="record-row"><view class="feature-icon">{{item.icon}}</view><view class="feature-copy"><text class="feature-title">{{item.title}}</text><text class="feature-desc">{{item.date}}</text></view><text class="tag">{{item.status}}</text></view></view></view><view wx:else class="card empty-panel"><view class="empty-symbol">记</view><text class="empty-title">还没有公益服务记录</text><text class="meta">预约到站服务或申请公益咨询后，会在这里留下时间线。</text></view></view><view class="notice">咨询与公益红娘记录彼此分离；工作人员只能查看职责范围内的信息。</view></view>
@@ -1 +1 @@
-<view class="service-page"><view class="hero"><text class="eyebrow">专项公益服务</text><text class="hero-title">让需要帮助的人被认真看见</text><text class="hero-desc">针对特定群体提供阶段性公益支持，项目条件与服务边界公开透明。</text></view><view class="content"><view wx:if="{{loading}}" class="card empty-panel"><view class="empty-symbol">…</view><text class="empty-title">正在加载</text></view><view wx:elif="{{error}}" class="card empty-panel"><view class="empty-symbol">!</view><text class="empty-title">{{error}}</text></view><view wx:elif="{{programs.length}}" class="block"><view wx:for="{{programs}}" wx:key="id" class="card"><view style="display:flex;justify-content:space-between"><text class="feature-title">{{item.name}}</text><text class="tag">{{item.status}}</text></view><text class="feature-desc" style="margin-top:16rpx">{{item.description}}</text><view><text class="tag">公益免费</text><text class="tag">自愿申请</text><text class="tag">隐私保护</text></view><view wx:if="{{item.applicable}}" class="primary-btn" style="margin-top:24rpx" data-id="{{item.id}}" bindtap="apply">申请加入</view></view></view><view wx:else class="card empty-panel"><view class="empty-symbol">项</view><text class="empty-title">暂无可申请的专项服务</text><text class="meta">新项目上线后会在这里公布。</text></view></view><view class="notice">项目主办或协作关系不会自动获得用户资料访问权限。</view></view></view>
+<view class="service-page"><view class="hero"><text class="eyebrow">专项公益服务</text><text class="hero-title">让需要帮助的人被认真看见</text><text class="hero-desc">针对特定群体提供阶段性公益支持，项目条件与服务边界公开透明。</text></view><view class="content"><view wx:if="{{loading}}" class="card empty-panel"><view class="empty-symbol">…</view><text class="empty-title">正在加载</text></view><view wx:elif="{{error}}" class="card empty-panel"><view class="empty-symbol">!</view><text class="empty-title">{{error}}</text></view><view wx:elif="{{programs.length}}" class="block"><view wx:for="{{programs}}" wx:key="id" class="card"><view style="display:flex;justify-content:space-between"><text class="feature-title">{{item.name}}</text><text class="tag">{{item.status}}</text></view><text class="feature-desc" style="margin-top:16rpx">{{item.description}}</text><view><text class="tag">公益免费</text><text class="tag">自愿申请</text><text class="tag">隐私保护</text></view><view wx:if="{{item.applicable}}" class="primary-btn" style="margin-top:24rpx" data-id="{{item.id}}" bindtap="apply">申请加入</view></view></view><view wx:else class="card empty-panel"><view class="empty-symbol">项</view><text class="empty-title">暂无可申请的专项服务</text><text class="meta">新项目上线后会在这里公布。</text></view></view><view class="notice">项目主办或协作关系不会自动获得用户资料访问权限。</view></view>
@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+// WXML 结构检查 CLI
+//
+//   node scripts/check-wxml-structure.mjs miniapp
+//   node scripts/check-wxml-structure.mjs <某个.wxml> [...]
+//
+// 退出码：0 = 全部通过；1 = 存在结构错误；2 = 用法/路径错误。
+//
+// 由来：2026-09-19 微信开发者工具报
+//   `[ WXML 文件编译错误] ./pages/service-history/service-history.wxml get tag end without start`
+// 而当时 UI 契约门禁 14/14 全绿 —— 说明门禁覆盖不到「WXML 是否可编译」这一层。
+// 本脚本 + ui-tests/wxml-structure-contracts.mjs 补上该层。
+//
+// 扫描逻辑见 scripts/lib/wxml-structure.mjs（共用实现，含「为什么不能用正则」的说明）。
+
+import { relative } from 'node:path';
+import { checkWxml, isFile, readFileSync, walkWxml } from './lib/wxml-structure.mjs';
+
+const roots = process.argv.slice(2);
+if (roots.length === 0) {
+  console.error('用法：node scripts/check-wxml-structure.mjs <目录或文件> [...]');
+  process.exit(2);
+}
+
+const files = [];
+for (const r of roots) {
+  if (isFile(r)) {
+    files.push(r);
+    continue;
+  }
+  const found = walkWxml(r);
+  if (found.length === 0) {
+    console.error(`未找到 .wxml（路径不存在或目录为空）：${r}`);
+    process.exit(2);
+  }
+  files.push(...found);
+}
+
+let failed = 0;
+for (const f of files) {
+  const errors = checkWxml(readFileSync(f, 'utf8'));
+  if (errors.length) {
+    failed++;
+    console.log(`✗ ${relative(process.cwd(), f)}`);
+    for (const e of errors) console.log(`    ${e}`);
+  }
+}
+
+console.log(`\n检查 ${files.length} 个 WXML 文件，结构异常 ${failed} 个`);
+process.exit(failed ? 1 : 0);
@@ -0,0 +1,160 @@
+// WXML 结构扫描器（lib）：供 CLI 与 UI 契约门禁共用，避免两份实现漂移。
+//
+// 关键设计：**不能**用「一条懒惰正则」判断标签配对。
+//   属性值里可以合法出现 `>`：`subtitle="{{unreadTotal > 0 ? unreadTotal + ' 条未读' : '全部已读'}}"`
+//   若用 `<(\/?)([a-zA-Z][\w-]*)([^>]*?)(\/?)>`，`[^>]*?` 会在**引号内的 `>`** 处提前收尾，
+//   于是 `<ui-section-header ... />` 的自闭合斜杠被读掉 → 报出「未闭合/错配」的**假阳性**。
+//   2026-09-19 首次实现即踩此坑（把 messages.wxml 误判为坏文件），故改为按引号状态机逐字符扫描。
+//
+// 本模块只做**结构**判断：标签名与嵌套关系。它不解析属性语义、不校验组件是否存在。
+
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const SKIP_DIRS = new Set(['node_modules', '.git', 'miniprogram_npm', 'dist', 'build']);
+
+/** 递归收集目录下的 .wxml（跳过 SKIP_DIRS） */
+export function walkWxml(dir, out = []) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const e of entries) {
+    const p = join(dir, e.name);
+    if (e.isDirectory()) {
+      if (!SKIP_DIRS.has(e.name)) walkWxml(p, out);
+    } else if (e.name.endsWith('.wxml')) {
+      out.push(p);
+    }
+  }
+  return out;
+}
+
+/**
+ * 按引号状态机扫描出全部标签。
+ * @returns {{tag:string, close:boolean, selfClose:boolean, index:number, line:number}[]}
+ */
+export function scanTags(src) {
+  const tags = [];
+  let i = 0;
+  let line = 1;
+
+  while (i < src.length) {
+    const ch = src[i];
+
+    if (ch === '\n') {
+      line++;
+      i++;
+      continue;
+    }
+
+    // 注释 <!-- ... --> 整体跳过（其中的 < > 不参与配对）
+    if (src.startsWith('<!--', i)) {
+      const end = src.indexOf('-->', i + 4);
+      const stop = end === -1 ? src.length : end + 3;
+      for (let k = i; k < stop; k++) if (src[k] === '\n') line++;
+      i = stop;
+      continue;
+    }
+
+    if (ch !== '<') {
+      i++;
+      continue;
+    }
+
+    const startLine = line;
+    const startIdx = i;
+    i++; // 吃掉 '<'
+
+    let close = false;
+    if (src[i] === '/') {
+      close = true;
+      i++;
+    }
+    // 非标签起始（裸文本里的 "<"）→ 当作普通字符跳过
+    if (!/[a-zA-Z]/.test(src[i] || '')) continue;
+
+    let name = '';
+    while (i < src.length && /[\w:.-]/.test(src[i])) name += src[i++];
+
+    // 属性区：引号内的一切（含 '>'）都不算标签结束
+    let quote = null;
+    let selfClose = false;
+    while (i < src.length) {
+      const c = src[i];
+      if (c === '\n') line++;
+      if (quote) {
+        if (c === quote) quote = null;
+        i++;
+        continue;
+      }
+      if (c === '"' || c === "'") {
+        quote = c;
+        i++;
+        continue;
+      }
+      if (c === '/' && src[i + 1] === '>') {
+        selfClose = true;
+        i += 2;
+        break;
+      }
+      if (c === '>') {
+        i++;
+        break;
+      }
+      i++;
+    }
+
+    tags.push({ tag: name, close, selfClose, index: startIdx, line: startLine });
+  }
+
+  return tags;
+}
+
+/**
+ * 校验 WXML 结构。
+ * @returns {string[]} 错误描述（空数组 = 结构合法）
+ */
+export function checkWxml(src) {
+  const stack = [];
+  const errors = [];
+
+  for (const t of scanTags(src)) {
+    if (t.selfClose) continue;
+    if (t.close) {
+      const top = stack.pop();
+      if (!top) {
+        errors.push(`第 ${t.line} 行：多余的闭合标签 </${t.tag}>（此时没有任何未闭合的标签）`);
+        break;
+      }
+      if (top.tag !== t.tag) {
+        errors.push(
+          `第 ${t.line} 行：闭合标签 </${t.tag}> 与栈顶 <${top.tag}>（第 ${top.line} 行）不匹配`,
+        );
+      }
+    } else {
+      stack.push(t);
+    }
+  }
+
+  if (stack.length) {
+    errors.push(
+      `文件结束时仍有 ${stack.length} 个标签未闭合：` +
+        stack.map((s) => `<${s.tag}>@第${s.line}行`).join('、'),
+    );
+  }
+
+  return errors;
+}
+
+export function isFile(p) {
+  try {
+    return statSync(p).isFile();
+  } catch {
+    return false;
+  }
+}
+
+export { readFileSync };
@@ -23,10 +23,12 @@ import { fileURLToPath } from 'node:url'
 const root = resolve(dirname(fileURLToPath(import.meta.url)), '..')
 const UI_TESTS_DIR = resolve(root, 'ui-tests')

-// 2026-09-18 基线：ui-tests/ 下 14 个守卫。新增/删减守卫时同步修改本默认值。
+// 2026-09-19 基线：ui-tests/ 下 15 个守卫（14 → 15：新增 wxml-structure-contracts，
+// 补「WXML 能否编译」这一层 —— 此前 14 绿时小程序仍有两个页面编译失败）。
+// 新增/删减守卫时同步修改本默认值。
 // 可用环境变量 UI_GUARDS_MIN 覆盖 —— 唯一目的是让「数量下限」这条分支本身可被自检
 // （`UI_GUARDS_MIN=99 node scripts/run-ui-contracts.mjs` 必须拒绝报绿）。
-const MIN_GUARDS = Number(process.env.UI_GUARDS_MIN ?? 14)
+const MIN_GUARDS = Number(process.env.UI_GUARDS_MIN ?? 15)

 const cliArgs = process.argv.slice(2)
 const explicit = cliArgs.length > 0
@@ -0,0 +1,74 @@
+// 契约：小程序 WXML 必须结构自洽（可被编译）
+//
+// 由来（2026-09-19）：微信开发者工具报
+//   [ WXML 文件编译错误] ./pages/service-history/service-history.wxml
+//   get tag end without start, near `</`
+// 而当时 UI 契约门禁 14/14 全绿 —— 说明既有门禁全是「源码结构/内容断言」，
+// **没有一条会真的去编译或解析 WXML**。两个页面（service-history、service-program）
+// 因此各带一个多余 `</view>` 进入仓库且长期无人发现。
+//
+// 本守卫补上这一层：按引号状态机解析标签配对，任何多余闭合/错配/未闭合直接判红。
+//
+// 自检（防止守卫自己变哑）：内置 3 组样例，正向 1 组 + 反向 2 组。
+//   正向样例**故意在属性值里放了 `>`**（`"{{a > 0}}"`）—— 早期用懒惰正则实现时，
+//   这里会被误判为结构错误（假阳性），把 messages.wxml 这种合法文件报成坏文件。
+//   把该样例固化进守卫，等于把「假阳性」这个坑钉在门禁里。
+
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { relative, resolve } from 'node:path'
+import { checkWxml, walkWxml } from '../scripts/lib/wxml-structure.mjs'
+
+const root = resolve(import.meta.dirname, '..')
+
+// ── 1. 扫描器自检 ────────────────────────────────────────────────
+const selfCheckCases = [
+  {
+    name: '正向：属性值内含 `>` 比较运算符（早期正则实现的假阳性来源）',
+    src: '<view class="a"><ui-section-header title="x" subtitle="{{unreadTotal > 0 ? 1 : 0}}" /><text>{{n >= 3}}</text></view>',
+    expectErrors: 0,
+  },
+  {
+    name: '反向：多余的闭合标签',
+    src: '<view class="a"><text>x</text></view></view>',
+    expectErrors: 1,
+  },
+  {
+    name: '反向：标签未闭合',
+    src: '<view class="a"><text>x</text>',
+    expectErrors: 1,
+  },
+]
+
+for (const c of selfCheckCases) {
+  const errors = checkWxml(c.src)
+  assert.equal(
+    errors.length,
+    c.expectErrors,
+    `扫描器自检失败 —— ${c.name}\n期望 ${c.expectErrors} 条错误，实得 ${errors.length} 条：\n${errors.join('\n')}`,
+  )
+}
+
+// ── 2. 全量扫描小程序页面 ────────────────────────────────────────
+// WXML_SCAN_ROOT 仅用于「负向注入自证」：把扫错文件的门禁指向一个临时目录，
+// 确认它真的会变红。默认扫仓库内 miniapp/。
+const scanRoot = resolve(root, process.env.WXML_SCAN_ROOT ?? 'miniapp')
+const files = walkWxml(scanRoot)
+
+assert.ok(files.length > 0, `未在 ${scanRoot} 下找到任何 .wxml —— 扫描清单可能失配，拒绝报绿`)
+
+const broken = []
+for (const file of files) {
+  const errors = checkWxml(readFileSync(file, 'utf8'))
+  if (errors.length) {
+    broken.push(`${relative(root, file).replace(/\\/g, '/')}\n    ${errors.join('\n    ')}`)
+  }
+}
+
+assert.deepEqual(
+  broken,
+  [],
+  `以下 WXML 结构不自洽，微信开发者工具会编译失败：\n${broken.join('\n')}`,
+)
+
+console.log(`WXML structure contracts passed（${files.length} 个文件）`)