test: 测试框架五层金字塔 + 四道闸(L0-L4, CI 首跑验证) #1

Closed

wangjia wants to merge 0 commits from feature/stats-overhaul into main

pull from: feature/stats-overhaul

merge into: wangjia:main

wangjia:main

wangjia:feat/pay-v2-integration

wangjia:worktree-fix-sysext-appgroup

wangjia:worktree-macos-killswitch

Conversation 1 Commits - Files Changed -

wangjia commented 2026-06-25 08:00:50 +00:00

Owner

Copy Link

Copy Source

本会话搭的测试体系: L0 契约快照/codegen漂移/可移植SQL扫描、L1 数值单测、L2 登陆&连接 flow、L3 golden(components+auth)、L4 进程级 e2e(gRPC全链路)、四道闸(脚手架/pre-commit/CI硬闸/PR模板)。开此 PR 触发 nas runner 首跑 9 个 CI job、按真实日志迭代修。stats-overhaul 业务 WIP 不在本 PR。

本会话搭的测试体系: L0 契约快照/codegen漂移/可移植SQL扫描、L1 数值单测、L2 登陆&连接 flow、L3 golden(components+auth)、L4 进程级 e2e(gRPC全链路)、四道闸(脚手架/pre-commit/CI硬闸/PR模板)。开此 PR 触发 nas runner 首跑 9 个 CI job、按真实日志迭代修。stats-overhaul 业务 WIP 不在本 PR。

wangjia added 19 commits 2026-06-25 08:00:50 +00:00

docs(test): 测试框架架构 + 开发规范五支柱文档 ... 29ddd5b453

- docs/test-architecture.html：分层测试金字塔(L0契约→L4 E2E) + 契约接缝
  数据流 + 四类诉求映射 + CI 流水线 + E2E 拓扑，5 张内联 SVG/表格图
- docs/dev-conventions.html：可测试性五支柱(接缝即接口/契约单源/纯逻辑分离/
  错误是值/可观测) + 支柱↔测试层咬合矩阵 + 反例对照表 + 执行机制四道闸
- docs/index.html：登记两份文档到知识库/调研，双向互链

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

test(ci): 第1刀 可移植 SQL 扫描硬闸 + 五支柱 PR 自检模板 ... 2bf6701def

执行机制四道闸 → 闸4(CI 硬闸) + 评审兜底落地：
- ci/scan-portable-sql.sh：扫 server Go 运行时查询禁用 MySQL 专属构造
  (UTC_TIMESTAMP/UTC_DATE/NOW()/FIELD(/ON DUPLICATE KEY/IFNULL)，
  豁免方言层 dialect*.go / _test.go / 注释行；当前 152 文件 0 违规
- ci.yml：新增 portable-sql-scan job；push 触发路径补 server/**
- .gitea/PULL_REQUEST_TEMPLATE.md：可测试性五支柱 + 测试 + 红线自检清单
- 守支柱 3(纯逻辑/IO 分离·双库可移植)，见 docs/dev-conventions.html

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

test(ci): 第2刀a codegen 漂移检查(token 单源不漂移) ... c34d8d8fb5

支柱 2(契约单源)守门:
- ci/check-codegen-drift.sh：重生成 pangolin_tokens.gen.dart,与已提交版本
  不一致即失败(改了 CSS 真相源没重生成,或手改了生成物 *.gen.dart)
- ci.yml：新增 codegen-drift job(node:20 镜像,含 git/bash)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

test(contract): 第2刀b Dart 契约快照(stats + /v1 API 字段面冻结) ... 149aa90cfa

支柱 2(契约单源)守门 — 堵 mac-stats-0 一类跨进程契约悄悄分叉:
- test/contract/stats_contract_test.dart：冻结 pangolin/vpn/stats payload
  字段面 + status 四值,改契约即测试红、逼同步原生产出端 + 文档
- test/contract/api_contract_test.dart：冻结 /v1/me、/v1/usage、
  /v1/usage/devices 的 snake_case 字段面
- ci.yml：flutter job 测试纳入 test/contract;本地 15 用例全过

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

test(contract): 第2刀c Go 契约快照(/v1/me·usage·UsageEntry)+ Go CI job ... 747ceb06f0

支柱 2(契约单源)后端守门 + 两端对账:
- httpapi/contract_test.go：冻结 /v1/me 字段面(12 key,与 Dart _frozenMeKeys 对账,
  注明后端多发 uuid/dp_uuid + expire_at 别名)
- usage/contract_test.go：冻结 /v1/usage(UsagePoint)、/v1/usage/devices
  (DeviceUsagePoint + envelope)字段面
- pb/agentv1/contract_test.go：冻结 agent↔控制面 UsageEntry 字段面
- ci.yml：新增 go-server job(golang:1.25 build+test)——此前 server 测试未进 CI
- 本地:5 契约用例 + 全量 go test ./...(25 包)绿

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

test(ci): 第4刀a pre-commit hook(闸3 提交前本地把关) ... 6df453f057

复用 CI 同款检查的快子集,提交前本地拦截:
- .githooks/pre-commit：红线词 + 可移植SQL + codegen 漂移(成功静默/失败打详情)
- ci/install-hooks.sh：一键启用(core.hooksPath=.githooks)
- 不放 flutter/go test(慢,留 CI 闸4);可 --no-verify 临时跳过

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

test(e2e): 第5刀a L4 进程级冒烟编排 + HTTP 段 ... b3cbeef7cf

真起 server 二进制(sqlite + Redis)跑 HTTP 用户旅程,验证 in-process 测试给不了的
信心(二进制起/迁移/路由/鉴权/DB 端到端):
- scripts/e2e-smoke.sh：起栈编排(Redis 三选一:已有 addr / docker / 内嵌 miniredis
  兜底)+ 随机端口 + trap 清理;调 Go driver
- server/test/e2e/smoke_test.go (tag e2e)：造用户(复用 argon2 HashPassword)
  → 登录 → /v1/me(dp_uuid/plan/email) → /v1/usage 鉴权 + 无 token 401
- server/test/e2e/miniredis (tag e2e)：无 docker 时 Redis 兜底 launcher
- 本地绿;go build/test ./...(无 tag)仍 25 包绿,tag e2e 文件被静默跳过

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

test(e2e): 第5刀b L4 gRPC 全链路(enroll→ReportUsage→统计真入库真读出) ... fd82d82fe3

在 HTTP 段基础上接 gRPC mTLS 全链路,真验证「统计准不准」:
- 脚本:生成 Node CA + gRPC server 证书(镜像 deploy.sh)、起 server 带 gRPC、
  nodectl 签 bootstrap token,传 E2E_GRPC_ADDR/CA/token/node 给 driver
- driver:复用 agentd.EnsureEnrolled 真 TCP enroll → enroll 到的 client cert
  建 mTLS → ReportUsage 注入 1GiB/100MiB(dp_uuid=用户) → 轮询 /v1/usage
  断言 bytes_up=1GiB·bytes_down=100MiB 真入库真读回
- 本地全链路绿;go build ./... 不受影响(tag e2e)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

test(ci): 第5刀c e2e-smoke CI job + 文档 L4 状态更新 ... 6bd5c04cba

- ci.yml 新增 e2e-smoke job(golang:1.25 + apt openssl/curl/python3);容器内无
  docker daemon → 脚本走内嵌 miniredis 兜底,无需 docker-in-docker——CI 走的
  正是本机已验证绿的同款路径
- docs/test-architecture.html:L4 从「完全缺·最大缺口」更新为已落地
  scripts/e2e-smoke.sh + server/test/e2e/
- 注:本机无 docker,e2e job 未在真 nas runner 实跑;逻辑等同本机已绿的
  miniredis 路径,首次 CI 运行需观察 apt 包/go module 下载

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

fix(ci): 修 flutter analyze 闸长期 exit 1(形同虚设) ... dbd183ee00

发现:CI flutter analyze 退出码 1(1204 个 info,0 error/warning),其中 1191 来自
第三方 vendored 包 lucide_icons_patched —— 这道闸一直红/无效。
- analysis_options.yaml:exclude packages/lucide_icons_patched/**(去 1191 噪音)
- ci.yml:flutter analyze --no-fatal-infos(info 是建议级不该硬挡 merge;
  error/warning 仍致命)→ analyze EXIT 0、闸真正可用
- 顺手清 11 个 clean 文件 info:auth_api 删 >>>AUTHLOG 调试 print 残留(+unused sw)、
  account_page/plan_card withOpacity→withValues、vpn_bridge where(is Map)→whereType、
  测试文件删多余 import + final→const
- 剩 2 个 info 在 stats-overhaul dirty 文件(stats_page/device_stat_row),留其合并清
- 验证:flutter analyze --no-fatal-infos EXIT 0(1204→2)、flutter test 48 全过

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

refactor(api): /v1/me 收敛 expire_at → 只发 expires_at(无 web 用户中心) ... 64f96fe018

之前后端同时发 expire_at + expires_at(分别给 app + web 用户中心)。现已无 web 端,
双发是纯冗余,统一只用 expires_at:
- account.go:meResponse 删 ExpireAt 字段 + GetMe handler 不再赋值
- client me.dart:fromJson 删 (expires_at ?? expire_at) 别名回退
- 两端契约快照同步:Go meResponse 冻结集去 expire_at(12→11 key)、删 Dart 别名测试
- 验证:go test httpapi 绿、flutter test contract(14)绿、analyze EXIT 0、e2e 全链路绿

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

test(client): L1 数值格式化纯函数单测 + 从 widget 抽出(支柱3) ... cb6fc25bc9

- lib/util/format.dart:抽出 formatSpeed/formatDuration(原私有于 connect_page
  _speed / connect_button _fmt,混在 widget 里没法单测)
- connect_page/connect_button 改用公共纯函数(渲染输出不变)
- test/unit/format_test.dart:10 用例覆盖速率 B/s→GB/s 各单位边界 +
  时长 HH:MM:SS 补零/小时不封顶/取模 60
- 验证:format 10 + widget 8 全过、analyze 无 error/warning

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

test(client): L2 登陆/重启续登/登出 流程(真 AuthNotifier) ... 95fad37989

驱动真实 AuthNotifier(非桩),仅在可注入接缝 TokenStore 处换内存实现,覆盖最初诉求:
- 登陆:saveTokens → isLoggedIn + 令牌持久化
- 重启续登:新 AuthNotifier 从同一 store 恢复登录态(无需重输密码)
- 登出:logout → 未登录 + store 清空,再重启仍未登录
- 3 用例全过

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

test(client): L2 点连接能连上 流程 + ConnectApi 注入(支柱1) ... 76dbdcfa83

- connection_provider:加 connectApiFactoryProvider(原内部 new ConnectApi 改成
  可注入工厂,支柱1 接缝即接口)——默认行为不变
- test/unit/flow_connect_test.dart:真 toggle → fetchConfig(注入 MockClient 回占位
  config)→ bridge.start → statusStream 确认 → on → 再 toggle → off;
  验证「非乐观翻转」红线(on 必由 bridge 确认)
- 全量 unit/widget 47 全过(重构不破坏)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

test(ci): L3 golden 权威环境脚本(进 CI 前置准备) ... c5223af4a1

golden 真进 CI 卡两个硬约束:Linux/mac 渲染不一致(mac 基线在 CI 全红)+ 基线绑定
stats-overhaul dirty 工作区。本提交备好权威环境,不裹挟 dirty、不破坏:
- scripts/update-goldens.sh:在 CI 同款镜像 cirruslabs/flutter 重生成 Linux 权威基线
  (开发者改 UI 后用它刷新,而非裸 mac --update-goldens,保持与 CI 一致)
- docs/test-architecture.html:L3 现状更新 + 列明启 CI 硬闸的两个前置条件
- 真启闸需:有 docker 的机器生成并提交 Linux 基线 + dirty 工作区合并(本机无 docker)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

test(ci): 闸1 接缝脚手架 new-seam.sh(支柱1:让对的写法成默认) ... 63bb31066f

预防式闸:一条命令生成「接口 + Impl + Fake + Riverpod provider + flow-test 桩」,
外部依赖从一开始就藏接口后、可注入、自带 Fake、可测——把支柱1 变成阻力最小路径。
- scripts/new-seam.sh <PascalName> [lib子目录]
- 验证:生成样例 SampleProbe → flutter analyze 无 issue + test 过 → 清理

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

test(ci): L3 golden 进 CI(components+auth 子集,Linux 权威基线) ... bb2688cede

L3 视觉回归真进 CI(此前卡 docker daemon 未起 + dirty 纠缠;现启 Docker 落地干净子集):
- 在 ghcr.io/cirruslabs/flutter 容器重生成 components+auth 的 14 张 Linux 权威基线
  (auth_login/connect 三态/quota/smart_card;mac 渲染与 CI Linux 不一致,故钉死 Linux),
  容器内 --update-goldens 后无 flag 复跑幂等通过
- ci.yml 新增 golden job(第9个):flutter test components_golden_test + auth_redesign_golden_test
- 解耦干净:这俩只 import clean widget;stats-overhaul 的 l10n 改动纯新增(现有键未动)
  → 渲染不受影响、不裹挟 dirty;tablet/desktop-stats golden 仍耦合 stats-overhaul,待合并后并入
- docs/test-architecture.html:L3 状态更新为「已进 CI(子集)」

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

test(ci): 闸2 Dart 支柱4 lint 升 error 级(真守门) ... 945c2e2f8d

analyze 闸修好后(exit 0),把支柱4 两条规则提升为 error 级:
- only_throw_errors / avoid_catching_errors → analyzer.errors: error
- 即使 CI --no-fatal-infos,这俩违规仍致命(挡 merge);当前零违规
- 将来 throw 字符串 / catch Error → CI 红(支柱4:错误是有类型的值)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

test(ci): 闸2 Go go vet 进 CI(支柱-adjacent;golangci-lint 暂受 go1.25 阻) ... 58e06708f4

go-server job 加 go vet ./...(项目工具链,零版本摩擦):
- golangci-lint(errcheck/depguard)暂用不了:其 go1.23 构建 < 项目 go1.25.10,
  报版本错;待 golangci-lint 跟上 go1.25 再上 errcheck(支柱4)+ depguard(import 方向)
- go vet 当前零违规,接进 go build+vet+test 链

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

wangjia added 1 commit 2026-06-25 10:01:20 +00:00

fix(ci): 去掉误提交的 .claude/worktrees gitlink ... 9a2d14adbe

.claude/worktrees/iridescent-sleeping-lampson 是个 git worktree 目录,被误提交成
gitlink(mode 160000)。.gitignore 已有 .claude/worktrees/ 但它在那之前就提交了。
git rm --cached 去跟踪(不删磁盘 worktree)。修 actions/checkout 的 submodule 警告
(No url found for submodule path)+ 清理仓库。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

wangjia added 1 commit 2026-06-25 10:13:29 +00:00

fix(test): 契约测试解耦 stats-overhaul WIP(CI 抓到的真问题) ... eb1bd11439

CI 暴露:我的契约测试引用了未提交的 stats-overhaul 文件,本地能过(文件在工作区)、
CI checkout 已提交代码就崩:
- api_contract_test.dart import device_usage.dart(?? 未提交)→ flutter analyze 报
  'Target of URI doesn't exist'
- usage/contract_test.go 引用 DeviceUsagePoint/deviceUsageResponse(HEAD service.go/
  handler.go 均无)→ go-server 编译失败
摘掉 /v1/usage/devices(DeviceUsage)契约,保留 /v1/me + /v1/usage(已提交)。
待 stats-overhaul 合并后再补 DeviceUsage 契约。
验证:flutter analyze test/contract 'No issues';go vet usage 无错。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

wangjia added 1 commit 2026-06-25 10:21:33 +00:00

ci(debug): shellcheck 改挂整个 repo + 加 checkout 诊断 ... dc22328eb4

shellcheck 在 mac runner 上 $PWD/deploy 挂载为空(openapi 的 design/server 子路径却
能挂),怀疑 act host checkout 没拉 deploy。改挂 $PWD:/repo(codegen 已证整 repo 挂载
可用)+ 加 ls 诊断,定位 deploy 是否在 checkout 里。整 repo 挂载在 Linux 也对。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

wangjia added 1 commit 2026-06-25 10:25:24 +00:00

fix(ci): shellcheck 去掉多余的 shellcheck 命令(预存 bug) ... 62a86c5c0e

koalaman/shellcheck 镜像 ENTRYPOINT 已是 shellcheck;ci.yml 命令又写了一遍,
变成 'shellcheck shellcheck -S warning …',把字面 'shellcheck' 当文件检查→
'openBinaryFile: does not exist' 报错。去掉多余的 shellcheck 即可。
这是 CI 从没跑过、谁都没发现的预存 bug,首次真跑暴露。本地验证去掉后 exit 0。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

wangjia added 1 commit 2026-06-25 10:38:17 +00:00

fix(test): e2e 去掉 /v1/usage/devices 断言(stats-overhaul WIP) ... 65bd7c381b

CI 暴露:e2e smoke 断言 /v1/usage/devices 返 200,但该路由(deviceUsageHandler)是
未提交的 stats-overhaul WIP,committed server 没注册它 → 404 → assertStatus200
(t.Errorf 非致命)记错 → TestE2ESmoke FAIL(尽管 HTTP/enroll/ReportUsage 全 ✓)。
本地复现不了(工作区有 WIP、路由在)。去掉该断言,/v1/usage 保留。
这是第 4 个'测试依赖未提交 WIP'实例,与契约测试同源。待 stats-overhaul 合并后补。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

wangjia added 1 commit 2026-06-25 10:52:57 +00:00

docs(ci): runner 设置记录(决定用 1 个 mac-pangolin-2 + 清理/持久化) ... 034a585e3b

记录 pangolin CI 的 self-hosted runner:决定保留 1 个(mac-pangolin-2,项目级、
mac host 模式、label nas、复用 jiu 的 relay 13000),含 config、为何 host+mac、
relay 原因、已删 orphan(mac-pangolin id5)的清理命令、持久化(launchd)TODO。
登记进 docs/index.html。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

wangjia added 1 commit 2026-06-25 12:06:25 +00:00

ci: pangolin runner launchd 持久化(start script + plist) ... 97b2ac02f1

mac-pangolin-2 从临时后台进程改成开机自启的 launchd 服务,仿 jiu 的 com.jiu.act-runner:
- deploy/runner/act_runner_pangolin_start.sh:等 jiu relay(13000)就绪 → 起 daemon →
  退出自重启;PATH 含 docker/node/go(host 模式 job 要用)
- deploy/runner/com.pangolin.act-runner.plist:RunAtLoad + KeepAlive
- docs/ci-runner.md:持久化章节改为实际部署步骤(cp + launchctl load)
复用 jiu 的 relay 13000(端口已占,不另起)。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

wangjia referenced this issue from a commit 2026-07-08 01:16:17 +00:00

feat(web): 修语言下拉漂移(class 化)+ 主页登录态用户中心按钮 + 用户中心返回主页

wangjia commented 2026-07-08 02:51:09 +00:00

Author

Owner

Copy Link

Copy Source

其分支 feature/stats-overhaul 已全部包含在 main 中(随 worktree-macos-killswitch 一并落地),领先 main 0 提交、0 文件改动,已无可合并内容 → 关闭。

其分支 feature/stats-overhaul 已全部包含在 main 中(随 worktree-macos-killswitch 一并落地),领先 main 0 提交、0 文件改动,已无可合并内容 → 关闭。

wangjia closed this pull request 2026-07-08 02:51:14 +00:00

wangjia referenced this issue from a commit 2026-07-11 08:45:12 +00:00

fix(server): pay webhook 兜底补行不再漏停用用户(修静默丢钱)+ 未知事件日志 + PAY_BIZ_SECRET 启动守卫

Some checks are pending

Hide all checks

ci-pangolin / Lint — shellcheck (pull_request) Successful in 8s

Details

ci-pangolin / OpenAPI Sync Check (pull_request) Successful in 17s

Details

ci-pangolin / Redline Scan — 脱敏 (UI 文案) (pull_request) Successful in 5s

Details

ci-pangolin / Flutter — analyze + test (pull_request) Successful in 22s

Details

ci-pangolin / Portable SQL — 可移植性 (mysql/sqlite) (pull_request) Successful in 5s

Details

ci-pangolin / Codegen Drift — token 生成物未漂移 (pull_request) Successful in 4s

Details

ci-pangolin / Go — build + test (pull_request) Successful in 9s

Details

ci-pangolin / E2E Smoke — L4 进程级端到端 (pull_request) Successful in 14s

Details

ci-pangolin / Go — integration (mysql/redis testcontainers) (pull_request) Successful in 4m17s

Details

ci-pangolin / Golden — 视觉回归 (components + auth) (pull_request) Successful in 13s

Details

Pull request closed

Please reopen this pull request to perform a merge.

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

No items

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

wangjia

No Assignees

1 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: wangjia/pangolin#1