E2E 测试约定（总纲）

本项目 E2E 体系的初始世界定义与规则手册。场景覆盖地图见 e2e-medilink-场景清单.md；功能行为的 as-is 权威 = prd/fsd-medilink/（FSD）。实现原则：API-first、workers 1、断业务结果不断实现细节、事件链轮询非 sleep。

1. 初始世界定义

1.1 环境矩阵

环境	库	端口	配置	触发
dev	`medilink` @ 192.168.50.139:3308	18031	`configs/config.yaml`	`make start`
e2e	`medilink_e2e` @ 同实例	18032	`configs/config.e2e.yaml`	`bash scripts/dev/e2e.sh`（自管起停）或 `make e2e`
浏览器冒烟	同 e2e（吃十段终态库）	web 5173 / app 8080	`MEDILINK_PROXY_TARGET` 指向 18032	`ci.sh --with-env`（冒烟前置位见 §1.6）

Redis 两世界共用 127.0.0.1:6379，靠键命名空间隔离（限流 rl:<库名>:*、TOTP totp:<库名>:*、RBAC rbac:<库名>:*、翻译缓存 tr:<库名>:*）。MinIO bucket dev=medilink-dev / e2e=medilink-e2e 独立隔离。

1.2 单册策略

单库单册（tech-design §1 裁决）：E2E 世界 = make db-reset 重建独立 e2e 库，无租户克隆、无 ID 重写，隔离问题退化为「独立测试库」。

1.3 账号矩阵（seed 预置，`scripts/dev/seed.sql`）

账号	id	角色	凭据（dev/e2e only）	TOTP
consultant@medilink.local	9001	CONSULTANT	`Consultant#2026`	密文预生成写死（python3 stdlib 现算 code）
doctor@medilink.local	9002	DOCTOR	同策略	secret 独立
admin@medilink.local	9003	ADMIN	同策略	二态重置（见 §1.6）
（注册链创建）	自增	PATIENT	注册表单自设	—

患者账号不由 seed 预置——由 F-REG 段注册事务链真实创建（全链保真）。

1.4 预置种子

4 所医院（3 PUBLISHED + 1 DRAFT——列表 total=3 断言的依据）+ 医院科室 + 专家（PUBLISHED，医生选人消费）+ 3 账号 + 14 权限码字典 + FAILED 邮件样例行（last_error 带 seed: 前缀，幂等清理自造行）。

1.5 确定性规则

TOTP 现算：python3 stdlib 按 seed 密钥现算 6 位码；防重放 SETNX EX 90 → 90s 内重跑必撞重放——失败时睡到下一 30s 边界重算重试恰一次。
限流相位浮动：60/min 固定窗，前段请求消耗随窗口相位浮动 → 限流段永远放最后（[10/10]）；冒烟前置位清 rl:*。
时延断言口径：Send 路径 7 次串行 DB 往返，dev MySQL RTT≈50-70ms → 上界 2.5s（环境如实界）；「原文送达 <500ms」为同机房部署目标（DIF-002 口径），3G 模拟 P95 归人工验收。
翻译轮询：mock 译文前缀 [zh]/[en]；worker 异步 → 轮询等待非固定 sleep。
SSE 捕获：curl --max-time 后台捕获防悬挂；补拉先于实时（after_id=0 拉全量）。

1.6 隔离与清理

ci.sh --with-env 冒烟前置位：ADMIN 二态重置（seed 的 ADMIN totp_status 归 NONE——Playwright 登录无 TOTP 第二段）+ 清 rl:* 限流键（吃十段终态库时限流窗口已耗尽）。

1.7 明令禁止

禁 toISOString()（时区漂移是 E2E 假红第一来源）——时间断言用相对时间。
禁固定 sleep 替代轮询（翻译/邮件等异步链）。
禁断言实现细节（SQL 形态/内部字段序）——断业务结果（状态码/业务字段值/终态）。
禁跳过重建直接跑（十段假设初始世界）。
禁在限流段之前发无谓 /pub 请求（预算：60/min 含 F-HOS+聊天+F-REG 全部匿名请求）。

2. 可测性硬规则

e2e.sh 是一次性长链（非独立用例）：段间有状态依赖（患者=注册创建、工单=注册开出、支付单=方案确认后创建），不支持单段重跑——重跑=整链重跑（make e2e-reset 后 bash scripts/dev/e2e.sh）。
每段头 echo "==> [n/10] ..."；断言失败即 exit 1（expect_status 非零即档位失败——ci.sh –with-env 闸门）。
幂等锚：重复注册 409、重复已读 404/幂等、白名单跳段 409——负路径断言与正路径同等地位。

3. 运行手册

# API 级全链（自管起停，~2min）
make e2e                      # = bash scripts/dev/e2e.sh
make e2e-reset                # 仅重建 e2e 库 + seed

# 浏览器冒烟（需先起 e2e 后端或走 ci.sh 编排）
make e2e-playwright           # 缺省只跑 web project（app project 归 ci.sh --with-env）

# 全档
bash scripts/ci.sh --with-env # 默认档 + e2e 十段 + 冒烟前置位 + Playwright + teardown

4. flaky 处理规则

TOTP 重放（90s 窗）→ 睡到下一 30s 边界重算（已内置）。
限流相位 → 限流段移最后（结构性解决，已内置）。
翻译/邮件异步未达 → 轮询 + 超时上限（禁无条件重跑）。
连续 2 次假红 → 按确定性规则排查（时延口径/种子漂移），修脚本不修断言。