diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 628116a..34327e2 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -148,8 +148,12 @@ jobs: runs-on: ubuntu-latest # Phase 23 遗留（收尾计划 批 1 Task 1.1）：UI 契约门禁此前**只在本地手工执行**， # 没有 CI 把关 —— 即「改动破坏了源码结构契约也不会被发现」。 - # 2026-09-19：14 → 15 个守卫，新增 WXML 结构守卫（此前 14 绿时小程序仍有两个页面 - # 编译失败:service-history / service-program 各多一个 ）。 + # 2026-09-19：14 → 15 → 18 个守卫。 + # 第 15 项 WXML 结构守卫（此前 14 绿时小程序仍有两个页面编译失败: + # service-history / service-program 各多一个 ）； + # 第 16/17 项：`this._x()` 无定义（运行期 TypeError，曾致所有请求 Promise 永不 settle） + # 与组件 WXSS 违规选择器（标签/ID/属性选择器）； + # 第 18 项：api.js 请求层**行为**契约（桩 wx.request 真跑，非源码断言）。 # 守卫是纯 node 内建模块、零 npm 依赖，故无需装依赖；统一执行器负责逐个跑 + 汇总 + 非零退出， # 并校验守卫数量下限（防止守卫被删除/改名后仍然报绿）。 steps: diff --git a/AGENTS.md b/AGENTS.md index e22ccf6..2d36070 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 契约门禁 **15/15** 全绿（2026-09-16 时为 13 项，此后新增端口与 `/admin/` 子路径一致性门禁；2026-09-19 新增第 15 项 **WXML 结构守卫** —— 此前 14 项全绿时小程序实际有两个页面 `service-history` / `service-program` 因多一个 `` **编译失败**，说明既有门禁全是源码内容断言、没有一条会解析 WXML）。管理端桌面端目视复验仍待用户执行。 +当前 UI 重设计唯一总计划：`docs/superpowers/plans/2026-09-13-reference-driven-dual-client-ui-redesign.md`。首批范围（小程序 11 个核心页面 + 管理端框架/工作台）已于 **2026-09-16 通过用户验收（结论：基本达标）**，此前"视觉否决 / REOPENED"的判定随之关闭，UI 契约门禁 **18/18** 全绿（2026-09-16 时为 13 项，此后新增端口与 `/admin/` 子路径一致性门禁；2026-09-19 连补 4 项 —— 第 15 项 **WXML 结构守卫**：此前全绿时小程序实际有两个页面 `service-history` / `service-program` 因多一个 `` **编译失败**；第 16 项 **私有方法调用守卫**：`this._x()` 无定义会抛 TypeError，且该调用位于 `resolve` 之前时会让**所有请求**的 Promise 永不 settle；第 17 项 **组件 WXSS 选择器守卫**；第 18 项 **api.js 请求层行为契约**（桩掉 `wx.request` 真跑）。前三项说明既有门禁全是源码内容断言、没有一条会解析 WXML/WXSS 或符号）。管理端桌面端目视复验仍待用户执行。 --- diff --git a/docs/STATUS.md b/docs/STATUS.md index 7ffbe94..aa6e3b4 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -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 契约门禁为 **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）启动需用户确认。** +> 阶段 0（在途收口）、阶段 1（小程序 C 组 + discover 筛选重设计）、阶段 2（管理端 Vue 新框架适配）、阶段 3（CapabilityService 独立化）、阶段 4（双端总验收）全部完成。三端构建通过、**13/13 契约全绿**（阶段 4 验收时点值；当前 UI 契约门禁为 **18/18**）、核心 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 契约门禁 18/18 全绿（第 15~18 项为 2026-09-19 新增）。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 契约测试 | **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` 两页各多一个 ``，**微信开发者工具实际编译失败** | +| UI 契约测试 | **18/18 通过**（2026-09-19） | 统一执行器 `scripts/run-ui-contracts.mjs`，**已接入 CI**（job `ui-contracts`）；历史：2026-09-16 为 13 项，此后新增端口一致性与 `/admin/` 子路径守卫（14 项）；2026-09-19 连补 4 项（15~18）—— WXML 结构（两页多 `` 实际编译失败）、私有方法调用（`this._x()` 无定义致所有请求 Promise 永不 settle）、组件 WXSS 违规选择器、api.js 请求层行为契约 | | 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 契约门禁 **15/15**；管理端入口收敛至 `/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 契约门禁 **18/18**；管理端入口收敛至 `/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 串联，**需基础设施决策**）/ @@ -59,6 +59,7 @@ | 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 个页面**各多一个 ``（`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.0-rc.18 | 2026-09-19 | **小程序两处运行期/编译期缺陷 + 再补 3 项门禁（15 → 18）**。① **P0 运行期崩溃**：`utils/api.js` 成功回调把 `releaseIdempotencyKey` 误写成 `this._releaseIdempotencyKey`（多一个下划线），且调用位于 `resolve()` **之前** → 抛错使 **每一个成功请求的 Promise 永不 settle** → 所有页面永远停在 loading + `App.onError` 刷屏。修复方式不仅是改名：改为**先 `resolve` 再释放**且释放自身 try/catch 兜底 —— 收尾动作不允许挡在响应路径上。② 组件 `recommend-card/index.wxss` 使用标签选择器 `.compact-like image`（组件 wxss 只允许类选择器）→ 改为 `.compact-like__icon` 并同步 WXML 类名。③ 新增门禁：`wxml-structure-contracts`（第 15）、`miniapp-self-method-contracts`（第 16，判据先自证假阳性 —— 首版正则漏认 `this._x = 值` 形式误报 3 个页面）、`wxss-component-selector-contracts`（第 17）、`miniapp-api-client-behavior`（第 18，**桩掉 `wx.request` 真跑 api.js** 的成功/失败/幂等键释放/收尾容错 4 组行为断言）。负向验证：注入「未定义私有方法」「标签选择器」「多余闭合标签」均精准变红且合法样例不被误报；`UI_GUARDS_MIN=99` 拒绝报绿。基线 **PASS 18/18**。**未验证**：微信开发者工具真实编译与真机渲染（本机无该环境） | --- diff --git a/miniapp/components/recommend-card/index.wxml b/miniapp/components/recommend-card/index.wxml index 966610f..c836231 100644 --- a/miniapp/components/recommend-card/index.wxml +++ b/miniapp/components/recommend-card/index.wxml @@ -7,7 +7,7 @@ {{item}} - + 暂不考虑 diff --git a/miniapp/components/recommend-card/index.wxss b/miniapp/components/recommend-card/index.wxss index 0d71b01..182ecda 100644 --- a/miniapp/components/recommend-card/index.wxss +++ b/miniapp/components/recommend-card/index.wxss @@ -1 +1 @@ -.ui-rec{display:flex;align-items:center;gap:16rpx;min-height:132rpx;padding:14rpx 16rpx;background:#fff;border-bottom:1rpx solid #F0F1F6}.ui-rec:last-child{border-bottom:0}.ui-rec__info{flex:1;min-width:0}.ui-rec__name-row{display:flex;align-items:center;gap:10rpx}.ui-rec__name{font-size:26rpx;font-weight:700;color:#222746}.ui-rec__age{font-size:21rpx;color:#545B76}.ui-rec__online{margin-left:auto;font-size:18rpx;color:#39A987}.ui-rec__online::before{content:'·';margin-right:4rpx}.ui-rec__meta{margin-top:5rpx;font-size:20rpx;color:#767C94;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}.ui-rec__reasons{display:flex;gap:7rpx;margin-top:8rpx;overflow:hidden}.ui-rec__reason{flex:none;padding:4rpx 9rpx;border-radius:12rpx;background:#F3EEFF;color:#7860AE;font-size:17rpx;white-space:nowrap}.ui-rec__actions{width:82rpx;display:flex;flex-direction:column;align-items:center;gap:7rpx}.compact-like{width:64rpx;height:64rpx;display:flex;align-items:center;justify-content:center;border-radius:32rpx;background:#FFF0F5;box-shadow:0 7rpx 18rpx rgba(255,79,145,.18)}.compact-like image{width:44rpx;height:44rpx}.compact-pass{font-size:17rpx;color:#A0A4B4;white-space:nowrap} +.ui-rec{display:flex;align-items:center;gap:16rpx;min-height:132rpx;padding:14rpx 16rpx;background:#fff;border-bottom:1rpx solid #F0F1F6}.ui-rec:last-child{border-bottom:0}.ui-rec__info{flex:1;min-width:0}.ui-rec__name-row{display:flex;align-items:center;gap:10rpx}.ui-rec__name{font-size:26rpx;font-weight:700;color:#222746}.ui-rec__age{font-size:21rpx;color:#545B76}.ui-rec__online{margin-left:auto;font-size:18rpx;color:#39A987}.ui-rec__online::before{content:'·';margin-right:4rpx}.ui-rec__meta{margin-top:5rpx;font-size:20rpx;color:#767C94;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}.ui-rec__reasons{display:flex;gap:7rpx;margin-top:8rpx;overflow:hidden}.ui-rec__reason{flex:none;padding:4rpx 9rpx;border-radius:12rpx;background:#F3EEFF;color:#7860AE;font-size:17rpx;white-space:nowrap}.ui-rec__actions{width:82rpx;display:flex;flex-direction:column;align-items:center;gap:7rpx}.compact-like{width:64rpx;height:64rpx;display:flex;align-items:center;justify-content:center;border-radius:32rpx;background:#FFF0F5;box-shadow:0 7rpx 18rpx rgba(255,79,145,.18)}.compact-like__icon{width:44rpx;height:44rpx}.compact-pass{font-size:17rpx;color:#A0A4B4;white-space:nowrap} diff --git a/miniapp/utils/api.js b/miniapp/utils/api.js index ae63711..21ff573 100644 --- a/miniapp/utils/api.js +++ b/miniapp/utils/api.js @@ -152,11 +152,25 @@ class ApiClient { if (res.statusCode === 200) { const body = res.data || {}; if (body.success) { - // 操作已成功落地：释放幂等键，下一次同域操作是新的一次。 - // 失败时刻意**不释放** —— 用户重试时复用同一把键， - // 后端才能识别出这是重复投递而不是第二次操作。 - this._releaseIdempotencyKey(idempotencyKey); + /** + * 顺序很关键：**先 resolve，再做收尾动作**。 + * 收尾逻辑（释放幂等键）绝不能挡在响应路径上 —— 2026-09-19 实测过代价： + * 此处曾把方法名误写成 `_releaseIdempotencyKey`（多一个下划线），抛错发生在 + * `resolve()` **之前**，于是**每一个成功请求**的 Promise 都永不 settle， + * 表现为「所有页面永远停在 loading + App.onError 刷屏」。 + * 一个字符的笔误被放大成全局不可用，就是因为收尾动作写在了响应路径上。 + * + * 语义（勿改）：操作已成功落地 → 释放幂等键，下一次同域操作是新的一次； + * 失败时刻意**不释放** —— 用户重试时复用同一把键，后端才能识别出这是重复投递 + * 而不是第二次操作。 + */ resolve(body.data); + try { + this.releaseIdempotencyKey(idempotencyKey); + } catch (error) { + // 释放失败最多是"下次操作没拿到新键"，绝不能升级为业务失败。 + console.warn('[api] 释放幂等键失败，已忽略', error); + } } else { reject({ code: body.code || REQUEST_ERROR.BUSINESS_ERROR, diff --git a/scripts/check-wxss-component-selectors.mjs b/scripts/check-wxss-component-selectors.mjs new file mode 100644 index 0000000..e1e7075 --- /dev/null +++ b/scripts/check-wxss-component-selectors.mjs @@ -0,0 +1,56 @@ +#!/usr/bin/env node +// 组件 WXSS 选择器检查 CLI +// +// node scripts/check-wxss-component-selectors.mjs miniapp/components +// node scripts/check-wxss-component-selectors.mjs <某个.wxss> +// +// ⚠️ 只对**自定义组件**目录有意义（page 的 wxss 允许标签选择器）。 +// +// 由来：2026-09-19 开发者工具警告 +// Some selectors are not allowed in component wxss ... (components/recommend-card/index.wxss:1:1092) +// 实测违规 1 处：`.compact-like image`（标签选择器）。 +// +// 退出码：0 = 通过；1 = 存在违规；2 = 用法/路径错误。 + +import { relative } from 'node:path'; +import { statSync } from 'node:fs'; +import { checkWxss, readFileSync, walkWxss } from './lib/wxss-selectors.mjs'; + +const roots = process.argv.slice(2); +if (roots.length === 0) { + console.error('用法：node scripts/check-wxss-component-selectors.mjs <组件目录或文件> [...]'); + process.exit(2); +} + +const files = []; +for (const r of roots) { + let isFile = false; + try { + isFile = statSync(r).isFile(); + } catch { + isFile = false; + } + if (isFile) { + files.push(r); + continue; + } + const found = walkWxss(r); + if (found.length === 0) { + console.error(`未找到 .wxss（路径不存在或目录为空）：${r}`); + process.exit(2); + } + files.push(...found); +} + +let failed = 0; +for (const f of files) { + const problems = checkWxss(readFileSync(f, 'utf8')); + if (problems.length) { + failed++; + console.log(`✗ ${relative(process.cwd(), f)}`); + for (const p of problems) console.log(` 第 ${p.line} 行：${p.message}`); + } +} + +console.log(`\n检查 ${files.length} 个组件 WXSS 文件，含违规选择器 ${failed} 个`); +process.exit(failed ? 1 : 0); diff --git a/scripts/lib/wxss-selectors.mjs b/scripts/lib/wxss-selectors.mjs new file mode 100644 index 0000000..78ea80d --- /dev/null +++ b/scripts/lib/wxss-selectors.mjs @@ -0,0 +1,113 @@ +// 组件 WXSS 选择器检查（lib）：供 CLI 与 UI 契约门禁共用。 +// +// 规则来源：微信小程序**自定义组件**的 wxss 只允许类选择器。使用标签选择器（`image`/`view`…）、 +// ID 选择器（`#id`）、属性选择器（`[attr]`）时开发者工具警告： +// [pages/index/index] Some selectors are not allowed in component wxss, +// including tag name selectors, ID selectors, and attribute selectors. +// (./components/recommend-card/index.wxss:1:1092) +// +// ⚠️ 作用域：**page 的 wxss 不受此限制**（页面不是组件）。 +// 对 `miniapp/pages/` 套用本规则会产生误报，故只管 `miniapp/components/`。 + +import { readFileSync, readdirSync } from 'node:fs'; +import { join } from 'node:path'; + +/** 去掉注释，并用等长空白占位以保持原始字符偏移（报错行号才准） */ +export function stripComments(src) { + return src.replace(/\/\*[\s\S]*?\*\//g, (m) => ' '.repeat(m.length)); +} + +/** 切出所有「选择器前置文本」（`{` 之前），跳过 at-rule 与声明块内部 */ +export function extractSelectorPreludes(src) { + const preludes = []; + let depth = 0; + let buf = ''; + let bufStart = 0; + for (let i = 0; i < src.length; i++) { + const c = src[i]; + if (c === '{') { + if (depth === 0) preludes.push({ text: buf, index: bufStart }); + depth++; + buf = ''; + continue; + } + if (c === '}') { + depth = Math.max(0, depth - 1); + buf = ''; + continue; + } + if (depth === 0) { + if (buf === '') bufStart = i; + buf += c; + } + } + return preludes; +} + +/** + * 检查一段选择器前置文本是否含违规成分。 + * @returns {string[]} 违规描述（去重） + */ +export function findViolations(selector) { + const bad = []; + const s = selector.trim(); + if (!s) return bad; + if (s.startsWith('@')) return bad; // @media / @keyframes / @import 不是选择器 + + // 去掉伪类/伪元素及其函数括号内容，避免把 `:nth-child(2)` 里的标识符当标签 + const cleaned = s.replace(/:{1,2}[a-zA-Z-]+(\([^)]*\))?/g, '').replace(/\([^)]*\)/g, ''); + + for (const part of cleaned.split(',')) { + const token = part.trim(); + if (!token) continue; + + const idMatch = token.match(/#[A-Za-z_][\w-]*/); + if (idMatch) bad.push(`ID 选择器 \`${idMatch[0]}\``); + + const attrMatch = token.match(/\[[^\]]*\]/); + if (attrMatch) bad.push(`属性选择器 \`${attrMatch[0]}\``); + + // 标签选择器：`>`/空格/`+`/`~` 之后紧跟的裸元素名 + const tagMatch = token.match(/(^|[\s>+~])([a-zA-Z][\w-]*)/); + if (tagMatch) bad.push(`标签选择器 \`${tagMatch[2]}\``); + } + return [...new Set(bad)]; +} + +/** + * 检查单个 wxss 文件内容。 + * @returns {{line:number, message:string}[]} + */ +export function checkWxss(src) { + const clean = stripComments(src); + const out = []; + for (const { text, index } of extractSelectorPreludes(clean)) { + for (const v of findViolations(text)) { + out.push({ + line: clean.slice(0, index).split('\n').length, + message: `${v}（选择器原文 \`${text.trim().slice(0, 60)}\`）`, + }); + } + } + return out; +} + +export function walkWxss(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 (!['node_modules', 'miniprogram_npm'].includes(e.name)) walkWxss(p, out); + } else if (e.name.endsWith('.wxss')) { + out.push(p); + } + } + return out; +} + +export { readFileSync }; diff --git a/scripts/run-ui-contracts.mjs b/scripts/run-ui-contracts.mjs index ed9198a..d51db15 100644 --- a/scripts/run-ui-contracts.mjs +++ b/scripts/run-ui-contracts.mjs @@ -1,7 +1,7 @@ #!/usr/bin/env node // UI 契约门禁统一执行器（本地 + CI 共用入口） // -// 背景：ui-tests/*.mjs 是一组「源码结构断言」守卫（纯 node 内建模块、零 npm 依赖）， +// 背景：ui-tests/*.mjs 是一组「源码结构与关键行为断言」守卫（纯 node 内建模块、零 npm 依赖）， // 2026-09-18 之前**只在本地手工逐个执行** —— 没有 CI 把关，改坏了没人知道。 // 本脚本把「逐个跑 + 汇总 + 非零退出」固化下来： // @@ -23,12 +23,18 @@ import { fileURLToPath } from 'node:url' const root = resolve(dirname(fileURLToPath(import.meta.url)), '..') const UI_TESTS_DIR = resolve(root, 'ui-tests') -// 2026-09-19 基线：ui-tests/ 下 15 个守卫（14 → 15：新增 wxml-structure-contracts， -// 补「WXML 能否编译」这一层 —— 此前 14 绿时小程序仍有两个页面编译失败）。 +// 2026-09-19 基线：ui-tests/ 下 18 个守卫 +// 14 → 15：新增 wxml-structure-contracts（补「WXML 能否编译」这一层 —— +// 此前 14 绿时小程序仍有两个页面编译失败）； +// 15 → 17：新增 miniapp-self-method-contracts（`this._x()` 无定义 → 运行期 TypeError， +// 且该调用位于 resolve 之前时会让所有请求的 Promise 永不 settle）、 +// wxss-component-selector-contracts（组件 wxss 用了标签/ID/属性选择器）； +// 17 → 18：新增 miniapp-api-client-behavior（**唯一一组行为断言**：桩掉 wx.request， +// 真跑 api.js，验证成功/失败/幂等键释放/收尾容错 4 组行为）。 // 新增/删减守卫时同步修改本默认值。 // 可用环境变量 UI_GUARDS_MIN 覆盖 —— 唯一目的是让「数量下限」这条分支本身可被自检 // （`UI_GUARDS_MIN=99 node scripts/run-ui-contracts.mjs` 必须拒绝报绿）。 -const MIN_GUARDS = Number(process.env.UI_GUARDS_MIN ?? 15) +const MIN_GUARDS = Number(process.env.UI_GUARDS_MIN ?? 18) const cliArgs = process.argv.slice(2) const explicit = cliArgs.length > 0 @@ -53,7 +59,7 @@ if (!explicit && guards.length < MIN_GUARDS) { process.exit(1) } -console.log(`UI 契约门禁（源码结构断言）— ${guards.length} 个守卫\n`) +console.log(`UI 契约门禁（源码结构与关键行为断言）— ${guards.length} 个守卫\n`) const pad = String(guards.length).length const failures = [] diff --git a/ui-tests/miniapp-api-client-behavior.mjs b/ui-tests/miniapp-api-client-behavior.mjs new file mode 100644 index 0000000..b4b684f --- /dev/null +++ b/ui-tests/miniapp-api-client-behavior.mjs @@ -0,0 +1,130 @@ +// 契约：小程序 API 请求层的**响应路径行为**（不是源码结构断言，是真跑） +// +// 由来（2026-09-19）：`miniapp/utils/api.js` 的成功回调把 `releaseIdempotencyKey` +// 误写成 `this._releaseIdempotencyKey`（多一个下划线），且该调用位于 `resolve()` **之前**： +// TypeError → resolve 永不执行 → **每一个成功请求**的 Promise 永不 settle +// → 所有页面永远停在 loading（App.onError 刷屏）。 +// +// 静态断言（grep / 类型检查）抓不到这类问题有两个原因： +// ① `utils/api.js` 是 .js，`tsc` 不管；② 判据只比对"源码里写了什么"。 +// 故此处直接 **require 真实模块 + 桩掉 wx.request**，断言响应路径的真实行为。 +// +// 能这么做的前提：`api.js` 只依赖 `../constants` 与 `../env`（纯数据模块）， +// `wx` 只在调用期使用 —— 所以可以在 node 里给它一个 `wx` 桩。若将来 api.js +// 在加载期就调用 wx 或引入其他运行时依赖，本契约会立刻报错（这是好事，不是噪音）。 + +import assert from 'node:assert/strict' +import { createRequire } from 'node:module' +import { resolve } from 'node:path' + +const require = createRequire(import.meta.url) +const root = resolve(import.meta.dirname, '..') + +// ── wx 桩 ──────────────────────────────────────────────────────── +const storage = new Map() +let pendingRequest = null +let lastRequestOptions = null + +globalThis.wx = { + getStorageSync: (k) => (storage.has(k) ? storage.get(k) : ''), + setStorageSync: (k, v) => storage.set(k, v), + removeStorageSync: (k) => storage.delete(k), + request: (options) => { + pendingRequest = options + lastRequestOptions = options + }, +} + +const api = require(resolve(root, 'miniapp/utils/api.js')) + +function respond(statusCode, data) { + assert.ok(pendingRequest, '没有待响应的请求 —— 被测代码没走到 wx.request') + const opt = pendingRequest + pendingRequest = null + opt.success({ statusCode, data }) +} + +/** 断言 Promise 在限定时间内 settle，否则视为「永不 settle」缺陷 */ +function withinSettle(promise, ms = 1000) { + return Promise.race([ + promise, + new Promise((_, reject) => + setTimeout( + () => reject(new Error(`Promise 在 ${ms}ms 内未 settle —— 收尾逻辑又跑到了 resolve 之前`)), + ms, + ), + ), + ]) +} + +// ── 1. 成功路径必须 resolve（回归：曾在此处抛 TypeError 导致永久 pending）── +{ + const key = api.idempotencyKey('like', 'u1') + const p = api.post('/likes', { targetUserId: 'u1' }, undefined, key) + respond(200, { success: true, data: { liked: true } }) + const data = await withinSettle(p) + assert.deepEqual(data, { liked: true }, '成功响应应把 body.data 交给调用方') + assert.equal( + lastRequestOptions.header['Idempotency-Key'], + key, + '幂等键必须真的写进请求头（否则后端无法识别重复投递）', + ) +} + +// ── 2. 成功之后必须释放幂等键：同域下一次操作应拿到**新**键 ── +{ + const before = api.idempotencyKey('like', 'u1') + const p = api.post('/likes', { targetUserId: 'u1' }, undefined, before) + respond(200, { success: true, data: { liked: true } }) + await withinSettle(p) + const after = api.idempotencyKey('like', 'u1') + assert.notEqual( + after, + before, + '成功落地后未释放幂等键 —— 用户的第二次操作会被后端当成重复投递而被幂等丢掉', + ) +} + +// ── 3. 失败时**刻意不释放**：重试必须复用同一把键 ── +{ + const before = api.idempotencyKey('pass', 'u9') + const p = api.post('/passes', { targetUserId: 'u9' }, undefined, before) + respond(200, { success: false, code: 'RATE_LIMITED', message: '太频繁' }) + // 注意：本层 reject 的是**普通对象** `{code, message, requestId}` 而非 Error， + // 所以不能用 /正则/ 直接匹配（那只对 Error.message 生效），要传校验函数。 + // 代价是丢掉堆栈 —— 属既有契约，此处不改，仅记录。 + await assert.rejects( + withinSettle(p), + (err) => { + assert.equal(err.code, 'RATE_LIMITED') + assert.equal(err.message, '太频繁') + return true + }, + '业务失败应 reject 并带服务端原文', + ) + const after = api.idempotencyKey('pass', 'u9') + assert.equal(after, before, '失败后不应释放幂等键 —— 重试需复用同键，后端才能识别重复投递') +} + +// ── 4. 收尾动作自身抛错，绝不能破坏响应路径（本轮结构性教训的固化）── +{ + const original = api.releaseIdempotencyKey + const warns = [] + const originalWarn = console.warn + console.warn = (...args) => warns.push(args.join(' ')) + api.releaseIdempotencyKey = () => { + throw new Error('模拟收尾动作崩溃') + } + try { + const p = api.post('/likes', { targetUserId: 'u2' }, undefined, api.idempotencyKey('like', 'u2')) + respond(200, { success: true, data: { liked: true } }) + const data = await withinSettle(p) + assert.deepEqual(data, { liked: true }, '收尾动作抛错不应影响调用方拿到数据') + assert.ok(warns.length > 0, '收尾动作抛错必须留下告警，不能静默吞掉') + } finally { + api.releaseIdempotencyKey = original + console.warn = originalWarn + } +} + +console.log('Miniapp API client behavior contracts passed（成功/失败/释放/收尾容错 4 组）') diff --git a/ui-tests/miniapp-self-method-contracts.mjs b/ui-tests/miniapp-self-method-contracts.mjs new file mode 100644 index 0000000..4fc9b29 --- /dev/null +++ b/ui-tests/miniapp-self-method-contracts.mjs @@ -0,0 +1,150 @@ +// 契约：小程序内 `this._私有方法(...)` 调用必须在同文件有定义 +// +// 由来（2026-09-19）：运行期崩溃 +// TypeError: _this._releaseIdempotencyKey is not a function +// 定位：miniapp/utils/api.js 里定义了 `releaseIdempotencyKey()`， +// 但成功回调写成了 `this._releaseIdempotencyKey(...)`（**多一个下划线**）。 +// +// 为什么危害远大于「一个方法名写错」： +// 该调用位于 `wx.request` 的 success 回调内、**在 `resolve()` 之前**。 +// 抛错 → `resolve` 永不执行 → 该 Promise **永不 settle** → 页面永远停在 loading。 +// 即：一个字符的笔误，把「所有成功请求」变成「所有页面卡死」。 +// +// 为什么既有门禁全都抓不到： +// - `miniapp tsc --noEmit` 只检查 .ts；`utils/api.js` 是 **.js**，不在类型检查范围内； +// - UI 契约门禁是「源码内容断言」（grep 关键字 / 数条目），不做符号解析。 +// 又是一处**覆盖盲区**（与 WXML 结构、`pass` 空壳同族）。 +// +// 判据范围（**刻意收窄，宁少不误**）： +// 只检查**下划线前缀**的私有方法调用 `this._x(` / `self._x(` / `that._x(` / `_this._x(`， +// 要求同文件内存在其定义（方法简写 `_x(`、类字段 `_x =`、对象属性 `_x:`、prototype 赋值）。 +// 不做通用「方法是否存在」检查 —— 那会把 `this.setData` / `this.selectComponent` +// 这类运行时注入的宿主方法全部误报，守卫一旦有假阳性就会被绕过（本项目已有先例）。 + +import assert from 'node:assert/strict' +import { readFileSync, readdirSync } from 'node:fs' +import { extname, join, relative, resolve } from 'node:path' + +const root = resolve(import.meta.dirname, '..') +// SCAN_ROOT 仅用于负向注入自证（指向临时目录），默认 miniapp/ +const scanRoot = resolve(root, process.env.MINIAPP_SCAN_ROOT ?? 'miniapp') + +const SKIP_DIRS = new Set(['node_modules', 'miniprogram_npm', 'dist', 'build', '.git']) + +function walk(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)) walk(p, out) + } else if (['.js', '.ts'].includes(extname(e.name)) && !e.name.endsWith('.d.ts')) { + out.push(p) + } + } + return out +} + +const RECEIVERS = ['this', 'self', 'that', '_this'] + +/** + * 收集同文件内定义的私有成员名。 + * + * 定义形态（必须都覆盖，否则产生假阳性）： + * 1. 方法简写 / 函数声明：`_x() {}`、`function _x()` + * 2. 类字段 / 对象属性：`_x: ...`、`_x = ...` + * 3. 实例属性赋值：`this._x = ...`（**首版漏了这条** —— `_unsub` 就属于这种， + * 它由 `this._unsub = matchStore.bindToPage(...)` 定义、在 `onUnload` 里调用， + * 首版判据把它误报成「未定义」。注意正则前缀必须允许 `this.` 这种带点的形式） + * 4. prototype 赋值：`.prototype._x =` + * + * 例外：赋值为 `undefined` / `null` 不算定义（后面调用照样会抛）。 + */ +function collectDefinitions(src, names) { + const defined = new Set() + for (const n of names) { + const esc = n.replace(/[$]/g, '\\$') + const patterns = [ + new RegExp(`(^|[^\\w$.])${esc}\\s*\\(`, 'm'), // 方法简写 _x( + // 注意 lookahead 里必须再吃一次 `\s*`：写成 `=\s*(?!undefined|null)` + // 会因 `\s*` 回溯到零宽而在「= null」上误判成功（实测踩到）。 + new RegExp(`(^|[^\\w$.])${esc}\\s*[:=]\\s*(?!\\s*(?:undefined|null)\\b)`, 'm'), + new RegExp(`\\b(?:this|self|that|_this)\\.${esc}\\s*=\\s*(?!\\s*(?:undefined|null)\\b)`, 'm'), + new RegExp(`\\.prototype\\.${esc}\\s*=`, 'm'), // prototype 赋值 + ] + if (patterns.some((re) => re.test(src))) defined.add(n) + } + return defined +} + +const files = walk(scanRoot) +assert.ok(files.length > 0, `未在 ${scanRoot} 下找到任何 .js/.ts —— 扫描清单可能失配，拒绝报绿`) + +const violations = [] + +for (const file of files) { + const src = readFileSync(file, 'utf8') + + // 1) 找出所有 `接收者._私有名(` 调用 + const callRe = new RegExp(`\\b(${RECEIVERS.join('|')})\\.(_[A-Za-z_$][\\w$]*)\\s*\\(`, 'g') + const calls = new Map() // name -> firstLine + let m + while ((m = callRe.exec(src))) { + const name = m[2] + if (!calls.has(name)) calls.set(name, src.slice(0, m.index).split('\n').length) + } + if (calls.size === 0) continue + + // 2) 同文件内必须能找到定义 + const defined = collectDefinitions(src, [...calls.keys()]) + for (const [name, line] of calls) { + if (!defined.has(name)) { + violations.push( + `${relative(root, file).replace(/\\/g, '/')}:${line} 调用了 ${RECEIVERS[0]}.${name}() 但同文件无该定义`, + ) + } + } +} + +// 3) 负向自检：确认判据本身有牙（一个「只调用、无定义」的样例必须被判红） +{ + const sample = 'class T {\n go() {\n return this._missingHelper(1)\n }\n}\n' + const callRe = new RegExp(`\\b(${RECEIVERS.join('|')})\\.(_[A-Za-z_$][\\w$]*)\\s*\\(`, 'g') + const found = [...sample.matchAll(callRe)].map((x) => x[2]) + assert.ok(found.includes('_missingHelper'), '自检失败：判据未能识别 this._x( 调用') + assert.deepEqual( + [...collectDefinitions(sample, ['_missingHelper'])], + [], + '自检失败：判据把未定义的方法误判为已定义', + ) +} + +// 4) 反向自检：**假阳性**防线。 +// `this._unsub = expr` 这种「运行时赋值定义」必须被认成有定义， +// 否则守卫会把合法代码报成缺陷（首版即如此，误报 3 个页面）。 +{ + const assignDefined = 'Page({\n onLoad() {\n this._unsub = store.bind(this)\n },\n onUnload() {\n if (this._unsub) this._unsub()\n },\n})\n' + assert.deepEqual( + [...collectDefinitions(assignDefined, ['_unsub'])], + ['_unsub'], + '自检失败：`this._x = 值` 形式未被认成定义（会导致假阳性）', + ) + const assignNull = 'Page({\n onLoad() {\n this._late = null\n },\n go() {\n this._late()\n },\n})\n' + assert.deepEqual( + [...collectDefinitions(assignNull, ['_late'])], + [], + '自检失败：赋值为 null/undefined 不应被认成可用定义', + ) +} + +assert.deepEqual( + violations, + [], + `以下私有方法调用在同文件内找不到定义（会抛 TypeError；若位于 resolve 之前将导致 Promise 永不 settle）：\n${violations.join('\n')}`, +) + +console.log(`Miniapp self-method contracts passed（扫描 ${files.length} 个文件）`) diff --git a/ui-tests/wxss-component-selector-contracts.mjs b/ui-tests/wxss-component-selector-contracts.mjs new file mode 100644 index 0000000..2c2ba0a --- /dev/null +++ b/ui-tests/wxss-component-selector-contracts.mjs @@ -0,0 +1,70 @@ +// 契约：自定义组件的 WXSS 不得使用标签 / ID / 属性选择器 +// +// 由来（2026-09-19）开发者工具警告： +// [pages/index/index] Some selectors are not allowed in component wxss, +// including tag name selectors, ID selectors, and attribute selectors. +// (./components/recommend-card/index.wxss:1:1092) +// 实测违规 1 处：`.compact-like image`。 +// +// ⚠️ 作用域刻意限定 `miniapp/components/`：**page 的 wxss 允许标签选择器**， +// 把本规则套到 pages 上会立刻产生误报 —— 守卫一旦有假阳性就会被绕过。 +// +// 自检：内置正向样例（合法类选择器 + 伪类 + `>` 子选择器）与反向样例 +// （标签 / ID / 属性各一），确保判据既不全哑、也不误伤。 + +import assert from 'node:assert/strict' +import { readFileSync } from 'node:fs' +import { relative, resolve } from 'node:path' +import { checkWxss, walkWxss } from '../scripts/lib/wxss-selectors.mjs' + +const root = resolve(import.meta.dirname, '..') +// WXSS_SCAN_ROOT 仅用于负向注入自证（指向临时目录），默认 miniapp/components +const scanRoot = resolve(root, process.env.WXSS_SCAN_ROOT ?? 'miniapp/components') + +// ── 1. 判据自检 ────────────────────────────────────────────────── +const selfCheckCases = [ + { + name: '正向：纯类选择器 / 伪类 / 子选择器 均合法', + src: [ + '.a { color: red }', + '.a .b { color: red }', + '.a > .b { color: red }', + '.a:active, .b::after { color: red }', + '.a:nth-child(2) { color: red }', + '@media (min-width: 600px) { .a { color: red } }', + '/* .commented-out image { color: red } */', + ].join('\n'), + expect: 0, + }, + { name: '反向：标签选择器', src: '.a image { width: 1px }', expect: 1 }, + { name: '反向：ID 选择器', src: '#main { width: 1px }', expect: 1 }, + { name: '反向：属性选择器', src: '.a[data-x="1"] { width: 1px }', expect: 1 }, +] + +for (const c of selfCheckCases) { + const got = checkWxss(c.src) + assert.equal( + got.length, + c.expect, + `判据自检失败 —— ${c.name}\n期望 ${c.expect} 条，实得 ${got.length} 条：\n${got.map((x) => x.message).join('\n')}`, + ) +} + +// ── 2. 全量扫描组件 WXSS ──────────────────────────────────────── +const files = walkWxss(scanRoot) +assert.ok(files.length > 0, `未在 ${scanRoot} 下找到任何 .wxss —— 扫描清单可能失配，拒绝报绿`) + +const broken = [] +for (const file of files) { + for (const p of checkWxss(readFileSync(file, 'utf8'))) { + broken.push(`${relative(root, file).replace(/\\/g, '/')}:${p.line} ${p.message}`) + } +} + +assert.deepEqual( + broken, + [], + `以下组件 WXSS 使用了不允许的选择器（开发者工具会警告，样式不生效）：\n${broken.join('\n')}`, +) + +console.log(`WXSS component selector contracts passed（${files.length} 个组件样式文件）`)