lingxi/e2e/README.md

e2e（Playwright）

现有用例

文件	说明	默认是否执行
smoke.spec.ts	A0 冒烟：登录、模块切换、403 / 404	是
a1-identity.spec.ts	A1-QA-01 账号生命周期（①–⑥）	否，需 A1_E2E=1
a2-roles.spec.ts	A2-QA-01 角色管理 / 权限三态 / SoD / 即时生效	否，需 A2_E2E=1
a3-client.spec.ts	A3-QA-01 客户与行业六页可访问 / 数据加载	否，需 A3_E2E=1
a4-dicts-settings.spec.ts	A4-QA-01 数据字典 / 三层合并 / 编码只读 / 系统配置 / 阈值确认 / 变更记录	否，需 A4_E2E=1
a5-audit-logs.spec.ts	A5-QA-01 操作日志列表 / 筛选 / 详情 diff / 导出闭环 / 权限三态 / 运行日志	否，需 A5_E2E=1

A1 账号生命周期用例

覆盖 6 类：首登强改 → 重登 → /users；刷新页面单飞刷新；登出后 refresh 失效；停用后旧会话与再登录被拒；角色变更下一次请求生效；无 user:view 访问 /users 显示 403。

前置

1. API：pnpm --filter @lingxi/api dev（http://127.0.0.1:3000/api/v1，真实 PG + Redis，已 pnpm db:init；不要执行 db:reset，会清空本地账号密码）。
2. Web：pnpm --filter @lingxi/web dev（http://127.0.0.1:5173，需 VITE_PUBLIC_DEMO_SESSION=false，否则登录走演示会话）。
3. 管理员 actor：默认用种子超管 jiang.lan（首登会把初始密码 lingxi2026 改成 QaE2eAdmin2026，之后复用）。 若本地已改密或想换账号，覆盖：A1_E2E_ACTOR_ACCOUNT / A1_E2E_ACTOR_PASSWORD。 ⚠️ 不要用 admin：本地 admin 密码可能已被人工修改或触发登录锁定。 ⚠️ e2e 会把 actor 密码改成 QaE2eAdmin2026（之后复用），请用专用测试账号/测试库，不要指向日常在用的账号。

运行

A1_E2E=1 pnpm exec playwright test e2e/a1-identity.spec.ts --reporter=list

• 可选覆盖：A1_E2E_BASE_URL（缺省 http://127.0.0.1:5173）、A1_E2E_API_BASE_URL（缺省 http://127.0.0.1:3000/api/v1）。
• 截图：design/a1-ui-v1/shots/impl/e2e/（01-* … 06-*）。
• 数据自建自清：用管理员 token 通过 API 创建 qa.first.* / qa.main.* / qa.noperm.* / qa.disable.* 四个用户，结束后统一停用（不删除，便于审计回看）；不改 admin 密码。

说明

• 门控未开启（无 A1_E2E=1）时整文件 test.skip，pnpm test:e2e 与 CI 行为不变。
• 若在 vite preview（4173）上执行，需把 API 的 WEB_ORIGIN 同时包含 http://127.0.0.1:4173，否则跨域请求被拦；本用例默认打 5173 dev，避免改动 API 配置。

A2 角色管理用例（A2-QA-01）

覆盖一条完整旅程（真实 API + 真实 PG/Redis + 真实浏览器）：

1. 管理员登录 → /system/roles → 新建角色（名称、2 个普通权限、数据范围「本部门」）→ 保存进入编辑器。
2. 编辑器改权限点；授予特殊权限（delivery:export 开关）触发二次确认，保存前再确认一次（特殊权限双确认）。
3. SoD 冲突：同时勾选 script:write × script:review → 顶部「命中职责互斥」拦截 + 底部「存在职责互斥，保存不可用」且保存按钮禁用；解除后恢复可保存。
4. 用 API 断言权限即时生效：绑定用户同一 access token 的 /me 在下一次请求即包含 user:view 与 delivery:export，GET /users 由 403 → 200；GET /roles/{id} 的普通权限与特殊权限分桶正确。
5. 权限三态（UI 侧）：该用户有 user:view 但无 role:view，访问 /system/roles 显示 403 页。
6. 停用确认（勾选知晓 + 停用原因）→ 编辑器状态变「停用」；API 断言 /me 权限清空、GET /users 返回 403 40301；列表「停用」筛选下可见该角色且行内标记「停用」。
7. 数据自建自清：beforeAll 按前缀清理上次异常中断的遗留角色/用户；afterAll 解绑并停用 qa2.roles.* 用户、删除 A2E2E-角色-* 角色（不停用 admin、不改 admin 密码）。

前置与运行

前置与 A1 相同（API http://127.0.0.1:3000/api/v1、Web http://127.0.0.1:5173 非 demo 会话、已 pnpm db:init）：

A2_E2E=1 pnpm exec playwright test e2e/a2-roles.spec.ts --reporter=list

• 门控未开启（无 A2_E2E=1）时整文件 test.skip，pnpm test:e2e / CI 行为不变。
• 可选覆盖：A2_E2E_BASE_URL（缺省 http://127.0.0.1:5173）、A2_E2E_API_BASE_URL（缺省 http://127.0.0.1:3000/api/v1）、A2_E2E_ACTOR_ACCOUNT / A2_E2E_ACTOR_PASSWORD（缺省 jiang.lan / QaE2eAdmin2026，首跑用种子口令 lingxi2026 自动完成首登改密）。
• 截图：design/a2-ui-v1/shots/impl/e2e/（01-roles-list … 11-roles-list-disabled，共 11 张 1440×900）。
• 说明：用户按 A1 口径只停用不删除（用户不可删）；角色在解绑后删除，可重复运行。

A3 客户与行业用例（A3-QA-01）

覆盖：登录注入 → 行业管理 / 客户列表 / 新建客户 / 客户组 / 字段审批五页标题 → 客户列表有数据 → 点击行进入客户详情深链。

前置与运行

1. API 3000 + Web 5173（pnpm dev，真实 PG；已执行 pnpm db:init）。
2. 用例自建临时超管 qa3.e2e（Prisma 写入，结束后删除），不依赖本地账号密码。

A3_E2E=1 pnpm exec playwright test e2e/a3-client.spec.ts --reporter=list

• 可选覆盖：A3_E2E_BASE_URL（缺省 http://127.0.0.1:5173）、A3_E2E_API_BASE_URL（缺省 http://127.0.0.1:3000/api/v1）。
• 截图：design/a3-ui-v1/impl/（实施报告引用）。

A4 数据字典与系统配置用例（A4-QA-01）

覆盖 7 条：

1. /system/dicts 主从页：h1、左侧「字典类型」、右栏 script_direction 类型头、三层 chips（通用 5 + 父行业 2 + 本行业 1 = 生效 7）、默认行业「电商 / 服饰鞋包」、种草短视频（已覆盖）/ 直播切片 / 穿搭教程；树 ↔ 词表切换（?view=tree|list）；行业作用域切全平台（生效 5）再切回。
2. 条目：新增 SideSheet → 列表出现 → 编辑态编码 disabled 且值锁定 → Modal.confirm 停用 / 启用 → 行状态变化。
3. 类型：新建（a4e2e_ 唯一 code + 名称 + 分组 + 形态树）→ 左侧类型列表可见 → 编辑类型编码 / 形态只读。
4. /system/settings：6 组导航、6 个占位符 chips、实时预览「电商-花间集-口播-20261104-01」、模板行内编辑与放弃恢复。
5. 阈值：客户基础字段上限改 12 → 保存全部更改 → 二次确认 → toast / Prisma 断言版本 +1 / 变更记录抽屉含前后值与原因。
6. 只读态：无 dict:manage / system:configure 账号访问两页 → /403。
7. 未登录访问 /system/dicts → 重定向登录页。

前置与运行

1. API 3000 + Web 5173（pnpm dev，真实 PG；已执行 pnpm db:init）。
2. 用例自建临时超管 qa4.dicts.e2e 与只读账号 qa4.dicts.ro（Prisma 写入，结束后删除）；字典类型 / 条目按 a4e2e_ 前缀清理；系统配置保存后恢复原值并删除本次 history。

A4_E2E=1 pnpm exec playwright test e2e/a4-dicts-settings.spec.ts --reporter=list

• 可选覆盖：A4_E2E_BASE_URL（缺省 http://127.0.0.1:5173）、A4_E2E_API_BASE_URL（缺省 http://127.0.0.1:3000/api/v1）。
• 结果：7 passed（约 1.1m）。
• 截图：不生成常驻截图；失败时 Playwright 默认 only-on-failure 落 test-results/。

选择器校准（Semi）

• Semi Select 选项可访问名含图标 aria-label（tick），精确匹配不到，使用 .semi-select-option 文本点击。
• Modal.confirm 的确认 / 取消按钮 aria-label 固定为 confirm / cancel，不要按 okText 文本定位。
• RadioGroup 隐藏 input 被 addon 拦截，点可见文本或 .semi-radio-addon-buttonRadio。

A5 审计与日志用例（A5-QA-01）

覆盖 5 条：

1. /system/audit-logs 列表可见：h1「操作日志」、副标题、查看留痕提示条（audit.log.view）、表格有数据、导出按钮（超管）。
2. 筛选：动作分类「权限与角色」→ URL ?category=permission 且结果变化；「重置」恢复默认。
3. 详情：点击「修改角色权限」行 → /system/audit-logs/{id}；变更对比含「权限点」；元信息含 trace_id / IP / 请求 / 耗时；切换「原始 JSON」可看到完整记录（occurred_at / actor / action / target / before / after）；只读说明存在。
4. 导出闭环：打开 560 抽屉 → 创建导出任务 → 轮询到「导出完成」→ 导出历史出现「已完成」任务 → API 断言 download_token 存在且签名下载返回 200 CSV → 关闭抽屉并重置筛选后，列表出现 audit.export 记录（导出自身留痕）。
5. 权限三态：无 audit:read 账号访问 /system/audit-logs → /403；仅有 audit:read（自定义角色，无 audit:export）→ 页面显示「只读 · 无 audit:export 权限」且不渲染导出按钮。
6. 运行日志：audit.logs_platform_url 置空 → 空态 + 「前往系统配置」；写入示例地址后刷新 → 外链与平台入口卡存在；结束后还原配置。

前置与运行

1. API 3000 + Web 5173（pnpm dev，真实 PG；已执行 pnpm db:init）。
2. 用例自建临时账号 qa5.audit.e2e（超管）、qa5.audit.viewer（仅 audit:read）、qa5.audit.ro（素材运营，无 audit:read）与自定义角色 a5e2e_audit_viewer；结束后删除账号 / 角色并还原 audit.logs_platform_url。
3. ⚠️ 审计表 append-only：用例产生的登录 / 查看 / 导出 / 下载审计记录不删除，属预期留痕。

A5_E2E=1 pnpm exec playwright test e2e/a5-audit-logs.spec.ts --reporter=list

• 可选覆盖：A5_E2E_BASE_URL（缺省 http://127.0.0.1:5173）、A5_E2E_API_BASE_URL（缺省 http://127.0.0.1:3000/api/v1）。
• 用例不点击外网链接；运行日志只断言外链 href 存在。