@h-ai/cli 0.1.0-alpha9 → 1.0.0-beta.2

package/templates/skills/hai-app-tests/reference.md

@@ -0,0 +1,462 @@
+# hai-app-tests — 详细用法
+
+从 [SKILL.md](SKILL.md) 选择主题后读取对应小节。代码片段展示 API 用法；省略的业务变量、schema、依赖与 return 上下文需由应用补齐。
+
+新增/改变业务行为或修复缺陷时先用目标用例定义行为，再实现。按 [development.md](../hai-app-create/development.md) 的需求与安全边界选择测试层；纯文案、格式、文档或无行为变化的可逆低影响修改按影响验证，不补只匹配文本/结构的镜像测试。
+
+## 适用场景
+
+- 以 TDD 方式开发新功能（先写测试 → 确认失败 → 再实现 → 确认通过）
+- 为当前架构的公共服务入口编写单元/集成测试
+- 为 API 端点编写 E2E 测试（Playwright）
+- 为页面交互编写 UI E2E 测试（Playwright）
+- 为工具函数、Schema 校验编写单元测试
+- 补齐有具体行为风险的验证缺口；覆盖率是定位线索，不是验收目标
+
+## 行为验证与 TDD 工作流
+
+不要求每个改动同时新增单元与 E2E。先复用现有 fixture 与目标用例，按变化选最小适用层；跨 contract/服务/客户端或 UI 的关键流程仍需相应集成/端到端验证。
+
+### 阶段一：需求分析（Red 前准备）
+
+1. **理解需求**：明确功能的输入、输出、边界条件、错误场景
+2. **拆分测试点**：将需求转化为可验证的测试用例清单
+3. **确定测试类型**：
+   - **单元测试（Vitest）**：服务层、工具函数、Schema 校验、HaiResult 处理
+   - **集成测试**：contract/procedure、事务、持久化、生命周期/失败清理、模块配置的真实组合
+   - **E2E 测试（Playwright）**：API 边界、页面交互、认证流程与跨层用户路径
+
+### 阶段二：Red — 编写失败的测试
+
+1. **编写目标用例**：在适用的单元/集成/E2E 层验证目标变化，不重复创建其它层仅为打勾
+2. 对本次相关的正常、输入边界、越权/跨租户、依赖失败、事务/幂等/清理场景给出可观察断言；纯工具无需添加无关权限路径
+3. **运行测试确认目标用例因预期行为缺失而失败（仍适用的既有回归保持通过）**；明确新需求替代的模板断言同步更新并记录依据，不能为迁就实现改预期：
+   ```bash
+   pnpm --filter <app-name> test        # 目标位于单元/集成时使用
+   pnpm --filter <app-name> test:e2e    # 目标位于 E2E 时使用；脚本以实际 package.json 为准
+   ```
+4. 新增用例若已通过，先确认现有实现是否已满足需求；仅在用例没有覆盖目标行为时修正
+
+### 阶段三：Green — 最小实现
+
+1. 参照 `hai-app-create` 技能编写实现代码
+2. 每实现一个功能点，立即运行对应测试确认通过
+3. 只写让测试通过的最小代码，不做过度设计
+4. 运行受影响测试及必要回归确认通过（按影响选择范围）：
+   ```bash
+   pnpm --filter <app-name> test        # 单元测试 — 应全部 PASS
+   pnpm --filter <app-name> test:e2e    # E2E 测试 — 应全部 PASS
+   ```
+
+### 阶段四：Refactor — 重构优化
+
+1. 参照 `hai-app-review` 技能审查代码规范
+2. 重构后执行受影响测试与必要回归，确认已有行为保持通过
+3. 验证前先分析变更和直接消费者，默认只选相关 test/E2E；全量仅在用户明确要求时执行。多项门禁按 [分轮验证与集中修复](validation.md) 收集一轮结果，汇总后集中修复；先定向确认失败和直接受影响项，再按真实依赖补充受影响流程，不从头重复全量门禁。PowerShell 使用 `pnpm.cmd`
+
+## 测试目录约定
+
+以下是常见组织方式；沿当前应用/workspace 的测试目录、alias 与脚本，不为目录一致性移动已有测试。
+
+```
+tests/                             # 单元测试（Vitest）
+  services/
+    user.test.ts                   # 服务层测试
+    article.test.ts
+  schemas/
+    user-schema.test.ts            # Schema 校验测试
+  utils/
+    helper.test.ts                 # 工具函数测试
+e2e/                               # E2E 测试（Playwright）
+  helpers.ts                       # E2E 共用工具函数
+  health.spec.ts                   # 健康检查 API
+  auth-api.spec.ts                 # 认证 API 测试
+  auth-ui.spec.ts                  # 认证页面 UI 测试
+  users-api.spec.ts                # 用户管理 API 测试
+  users-ui.spec.ts                 # 用户管理页面 UI 测试
+```
+
+## 核心规则
+
+1. **行为测试先行**：新增/改变业务行为和修复缺陷时先定义目标用例；纯文案/格式/文档按影响验证。
+2. **统一入口**：通过框架模块公共 API 测试（`reldb.sql`、`iam.auth`），不直接调用内部实现。
+3. **从实际场景出发**：测试用例验证真实业务行为，不做形式覆盖。
+4. **先审查后修复**：测试不通过时先审查业务逻辑是否有问题，不直接修改测试迎合通过。
+5. **明确隔离层**：单元测试沿真实注入边界 mock 外部依赖；DB/缓存集成用内存 SQLite 或隔离环境/Testcontainers，不能用 mock 证明真实持久化/事务。
+6. **区分证据**：端到端运行完整应用；可用受控外部依赖验证确定性错误路径，但报告替身范围。浏览器通过不等于真实 provider 通过；真实数据库/付费 provider/原生平台各自保留实际执行结果，缺环境说明未验证。
+
+## 覆盖范围
+
+按本次改变的行为选择适用路径；下表是设计依据，不要求每个路径在单元与 E2E 重复一遍。纯函数不必虚构权限场景，受保护资源则不能省掉未登录/缺权限与跨用户/租户验收：
+
+| 路径     | 说明                     | 单元测试示例       | E2E 测试示例            |
+| -------- | ------------------------ | ------------------ | ----------------------- |
+| 正常路径 | 核心功能可用             | 创建用户成功       | POST /api/users → 201   |
+| 边界路径 | 非法输入、空值、格式错误 | 空名称、超长字符串 | 空表单提交 → 校验提示   |
+| 权限路径 | 未认证、无权限           | 未登录调用服务     | 检查真实失败包络/HTTP 状态，kit 页面按实际策略重定向 |
+| 错误路径 | 服务异常、数据库错误     | DB 失败时的 HaiResult | 服务不可用 → 错误提示页 |
+
+## 单元测试（Vitest）
+
+### SQLite 持久化集成示例
+
+```typescript
+import { reldb } from '@h-ai/reldb'
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+
+// 内存 SQLite 隔离数据；应用服务测试同样从服务的公共入口验证结果。
+beforeAll(async () => {
+  const init = await reldb.init({ type: 'sqlite', database: ':memory:' })
+  expect(init.success).toBe(true)
+  const table = await reldb.ddl.createTable('articles', {
+    id: { type: 'TEXT', primaryKey: true },
+    title: { type: 'TEXT', notNull: true },
+  })
+  expect(table.success).toBe(true)
+})
+afterAll(async () => {
+  const closed = await reldb.close()
+  expect(closed.success).toBe(true)
+})
+
+describe('article persistence', () => {
+  it('creates and reads the stored article', async () => {
+    const articles = reldb.crud.table<{ id: string, title: string }>({ table: 'articles', dbType: 'sqlite' })
+    const saved = await articles.create({ id: 'a1', title: 'Test' })
+    expect(saved.success).toBe(true)
+    const found = await articles.findById('a1')
+    expect(found.success).toBe(true)
+    if (found.success) expect(found.data).toEqual({ id: 'a1', title: 'Test' })
+  })
+})
+```
+
+本例验证框架真实持久化，不代替应用服务验收。应用另测相关权限、校验和 DB 失败透传；mock 必须沿真实注入边界或 CRUD 仓库实例配置，create 返回 ExecuteResult，不能伪造为实体。
+
+### Schema 校验测试模板
+
+```typescript
+import { CreateUserSchema } from '$lib/server/schemas/user'
+// tests/schemas/user-schema.test.ts
+import { describe, expect, it } from 'vitest'
+
+describe('CreateUserSchema', () => {
+  it('should accept valid input', () => {
+    const result = CreateUserSchema.safeParse({
+      username: 'testuser',
+      email: 'test@example.com',
+      password: '12345678',
+    })
+    expect(result.success).toBe(true)
+  })
+
+  it('should reject short username', () => {
+    const result = CreateUserSchema.safeParse({
+      username: 'ab',
+      email: 'test@example.com',
+      password: '12345678',
+    })
+    expect(result.success).toBe(false)
+  })
+
+  it('should reject invalid email', () => {
+    const result = CreateUserSchema.safeParse({
+      username: 'testuser',
+      email: 'not-email',
+      password: '12345678',
+    })
+    expect(result.success).toBe(false)
+  })
+})
+```
+
+## E2E 测试（Playwright）
+
+### Playwright 配置
+
+优先复用 CLI 已生成的 `playwright.config.ts`。下列为 SvelteKit preview 示例；API/fullstack/Vite 使用自身已有 webServer/服务组合与 scripts，不照搬 `pnpm preview`：
+
+```typescript
+// playwright.config.ts
+import process from 'node:process'
+import { defineConfig } from '@playwright/test'
+
+const DEFAULT_BASE_URL = 'http://localhost:4173'
+const baseURL = process.env.BASE_URL || DEFAULT_BASE_URL
+const previewHost = resolveHostFromBaseUrl(baseURL, 'localhost')
+const previewPort = resolvePortFromBaseUrl(baseURL, '4173')
+
+function resolveHostFromBaseUrl(urlString: string, fallbackHost: string): string {
+  try {
+    const url = new URL(urlString)
+    return url.hostname || fallbackHost
+  }
+  catch {
+    return fallbackHost
+  }
+}
+
+function resolvePortFromBaseUrl(urlString: string, fallbackPort: string): string {
+  try {
+    const url = new URL(urlString)
+    if (url.port)
+      return url.port
+    return url.protocol === 'https:' ? '443' : '80'
+  }
+  catch {
+    return fallbackPort
+  }
+}
+
+export default defineConfig({
+  testDir: './e2e',
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: 0,
+  workers: 2,
+  reporter: 'list',
+  timeout: 30_000,
+  use: {
+    baseURL,
+    channel: 'chrome',
+    trace: 'retain-on-failure',
+    screenshot: 'only-on-failure',
+  },
+  webServer: {
+    command: `pnpm build && pnpm preview --host ${previewHost} --port ${previewPort} --strictPort`,
+    env: { HAI_E2E: '1', BASE_URL: baseURL },
+    url: baseURL,
+    reuseExistingServer: false,
+    timeout: 180_000,
+  },
+})
+```
+
+### E2E 工具函数模板
+
+以下登录路径、表单字段与 API 仅作 SvelteKit 示例，必须替换为当前应用路由/认证流程；API service/typed client 测试从现有 contract 读取路径，不维护第二份路由常量。
+
+```typescript
+// e2e/helpers.ts
+import type { APIRequestContext, Page } from '@playwright/test'
+
+/** 生成唯一测试用户 */
+export function uniqueUser(prefix = 'e2e') {
+  const safePrefix = (prefix.replace(/\W/g, '') || 'e2e').slice(0, 8)
+  const entropy = `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 6)}`
+  const id = entropy.slice(-10)
+  const username = `${safePrefix}_${id}`.slice(0, 20)
+  return {
+    username,
+    email: `${safePrefix}_${id}@test.local`,
+    password: 'Test1234!@',
+  }
+}
+
+/** 通过 API 注册用户 */
+export async function registerViaApi(
+  request: APIRequestContext,
+  user: ReturnType<typeof uniqueUser>,
+) {
+  return request.post('/api/auth/register', {
+    data: {
+      username: user.username,
+      email: user.email,
+      password: user.password,
+      confirmPassword: user.password,
+    },
+  })
+}
+
+/** 注册并登录，返回已认证的 Page */
+export async function registerAndLogin(
+  page: Page,
+  request: APIRequestContext,
+  prefix = 'e2e',
+) {
+  const user = uniqueUser(prefix)
+  await registerViaApi(request, user)
+  await page.goto('/login')
+  await page.fill('[name="username"]', user.username)
+  await page.fill('[name="password"]', user.password)
+  await page.click('button[type="submit"]')
+  await page.waitForURL('/')
+  return user
+}
+```
+
+### API 端点 E2E 测试模板
+
+下例是返回 kit Response 的 SvelteKit 端点。serv/oRPC 普通 procedure 可能以 HTTP 200 返回失败 HaiResult，需同时检查 `success/error.code`；不能把 `error.httpStatus` 当作 response.status，也不能统一套用下列 401/201 断言。输入校验与传输错误另按实际状态测试。
+
+```typescript
+// e2e/articles-api.spec.ts
+import { expect, test } from '@playwright/test'
+import { registerAndLogin } from './helpers'
+
+test.describe('Articles API', () => {
+  test('GET /api/articles 未认证返回 401', async ({ request }) => {
+    const response = await request.get('/api/articles')
+    expect(response.status()).toBe(401)
+  })
+
+  test('POST /api/articles 创建文章成功', async ({ page, request }) => {
+    await registerAndLogin(page, request, 'article')
+
+    const response = await page.request.post('/api/articles', {
+      data: { title: 'E2E Test Article', content: 'Test content' },
+    })
+    expect(response.status()).toBe(201)
+
+    const body = await response.json()
+    expect(body.success).toBe(true)
+    expect(body.data.title).toBe('E2E Test Article')
+  })
+
+  test('POST /api/articles 空标题返回 400', async ({ page, request }) => {
+    await registerAndLogin(page, request, 'article')
+
+    const response = await page.request.post('/api/articles', {
+      data: { title: '', content: '' },
+    })
+    expect(response.status()).toBe(400)
+  })
+
+  test('GET /api/articles 认证后获取列表', async ({ page, request }) => {
+    await registerAndLogin(page, request, 'article')
+
+    const response = await page.request.get('/api/articles')
+    expect(response.ok()).toBeTruthy()
+
+    const body = await response.json()
+    expect(body.success).toBe(true)
+    expect(Array.isArray(body.data)).toBe(true)
+  })
+})
+```
+
+### 页面 UI E2E 测试模板
+
+```typescript
+// e2e/articles-ui.spec.ts
+import { expect, test } from '@playwright/test'
+import { registerAndLogin } from './helpers'
+
+test.describe('Articles Page', () => {
+  test('未登录跳转登录页', async ({ page }) => {
+    await page.goto('/admin/articles')
+    await expect(page).toHaveURL(/login/)
+  })
+
+  test('已登录显示文章列表', async ({ page, request }) => {
+    await registerAndLogin(page, request, 'artui')
+    await page.goto('/admin/articles')
+
+    await expect(page.locator('h1, h2').first()).toContainText(/文章|article/i)
+  })
+
+  test('创建文章表单提交', async ({ page, request }) => {
+    await registerAndLogin(page, request, 'artui')
+    await page.goto('/admin/articles/new')
+
+    await page.fill('[name="title"]', 'E2E Article')
+    await page.fill('[name="content"]', 'E2E content')
+    await page.click('button[type="submit"]')
+
+    // 验证跳转或成功提示
+    await expect(page.locator('.hai-toast-item[data-variant="success"]')).toBeVisible({ timeout: 5000 })
+  })
+})
+```
+
+## TDD 用例设计策略
+
+以下展示候选验证点，实际按职责和已有用例选择；不要求将同一输入规则在所有层重复实现和测试。
+
+### 从需求到测试用例的转换
+
+```
+需求：用户可以创建文章，标题必填且不超过 100 字符，需要登录后才能操作
+
+↓ 拆分测试点
+
+单元测试（Vitest）：
+  ✅ 创建文章成功返回 ok(data)
+  ✅ 空标题被当前边界 Schema 拒绝
+  ✅ 超长标题（>100 字符）被拒绝
+  ✅ DB 异常时透传错误
+
+Schema 测试（Vitest）：
+  ✅ 合法输入通过校验
+  ✅ 空标题被拒绝
+  ✅ 超长标题被拒绝
+  ✅ 缺少必填字段被拒绝
+
+E2E 测试（Playwright）：
+  ✅ POST /api/articles 未认证 → 401
+  ✅ POST /api/articles 合法数据 → 201
+  ✅ POST /api/articles 空标题 → 400
+  ✅ 页面表单提交成功 → 跳转/提示
+  ✅ 未登录访问创建页 → 重定向登录
+```
+
+## 断言规范
+
+- HaiResult 型 API 校验 `result.success`；其它返回、显式抛错与流式 API 按实际签名验证
+- 失败时校验 `error.code`（不只检查 `success === false`）
+- 使用类型缩窄后访问 data 或 error
+- E2E 断言使用 Playwright 内置 expect 匹配器；同时检查用户可见结果和必要持久化状态，不能只断言 HTTP 200、按钮点击或成功提示
+- 失败验收检查错误码/状态与“没有副作用”；事务中途失败、重复回调/写入、取消/关闭等按需求检查一致性与资源退出
+
+```typescript
+// ✅ 单元测试断言
+const result = await service.create(input)
+expect(result.success).toBe(true)
+if (result.success) {
+  expect(result.data.id).toBeDefined()
+}
+
+// ✅ 单元测试错误断言
+const result = await service.create(invalidInput)
+expect(result.success).toBe(false)
+if (!result.success) {
+  expect(result.error.code).toBe('VALIDATION_FAILED')
+}
+
+// ✅ E2E API 断言
+const response = await request.post('/api/articles', { data: input })
+expect(response.status()).toBe(201)
+const body = await response.json()
+expect(body.success).toBe(true)
+
+// ✅ E2E UI 断言
+await expect(page.locator('.hai-toast-item[data-variant="success"]')).toBeVisible()
+await expect(page).toHaveURL('/admin/articles')
+```
+
+## 质量门禁
+
+从当前 package.json 确认实际脚本和 workspace 名称，按 [分轮验证与集中修复](validation.md) 组织以下适用检查；不要为格式/文档改动运行无关 provider 或新增镜像测试。逐轮记录范围、状态/退出码、日志、mock/真实环境与未验证原因，完整日志按需读取。
+
+```bash
+# 运行单元测试
+pnpm --filter <app-name> test
+
+# 运行 E2E 测试
+pnpm --filter <app-name> test:e2e
+
+# 覆盖率
+pnpm --filter <app-name> test:coverage
+
+# 仅在用户明确要求全量验收时执行
+pnpm typecheck
+pnpm lint
+pnpm build # 构建/配置/跨包变更
+pnpm test
+```
+
+## 相关 Skills
+
+- `hai-app-create`：应用功能创建规范（TDD Green 阶段参照）
+- `hai-app-review`：应用代码审查规范（TDD Refactor 阶段参照）
+- `hai-build`：项目架构总览与 TDD 工作流导航

package/templates/skills/hai-app-tests/validation.md

@@ -0,0 +1,42 @@
+# 分轮验证与集中修复
+
+网站涉及部署目录时，按[网站挂载目录](../hai-build/paths.md)选择带前缀的真实流程，覆盖资源/运行配置、API地址、认证与匿名拒绝、导航/刷新以及部署健康和增量边界。Playwright页面与新增窗口使用同一完整baseURL；查询当前浏览器会话时使用共享该页面Cookie的page.request，独立request上下文用于匿名边界。保留根路径回归，区分前置失败与业务失败。
+
+适用于开发、审查修复、升级后的质量门禁与整体验收。默认执行“变更影响分析 → 选定相关范围 → 收集一轮 → 归并修复 → 定向确认”，只有用户明确要求全量验收时才启动全仓验证。不要遇到一个普通失败就修改代码并从头重跑。新增行为的目标用例仍可做小范围 TDD Red → Green；它不要求提前运行整套门禁。
+
+## 1. 确定本轮检查
+
+- 验证前先由 AI 分析 Git 差异、变更行为、直接调用方和受影响用户流程，再读 `package.json`、任务依赖与环境要求。简述受影响模块/应用、选择哪些 test/E2E 及依据、哪些既有结果可复用，列出命令、工作目录、前置条件和预期证据。
+- 默认只执行变更相关的 test、E2E 及必要静态/构建检查，优先按 workspace、测试文件或用例过滤。跨包变更补充实际受影响的消费者和公开契约检查；影响不明时先补搜索分析，不能据此自动升级全仓验证。只有用户明确要求全量时保留全量范围。纯文案/文档修改只做适用检查，不新增镜像测试。
+- 一轮默认按 typecheck → lint → build（涉及构建/配置/模板/跨包契约）→ test → 相关 E2E 调度；顺序服从真实依赖。同轮收集不等于同时运行：只有输出目录、端口、数据库、容器与 fixture 均隔离的检查才可并行，共用 `dist`、`.svelte-kit` 或预览产物的构建与测试必须串行。
+- 使用现有任务编排或一个临时调度脚本逐项执行、捕获真实退出码并保存日志。不要用跨检查的 `&&`、全局 fail-fast 或 `|| true` 代替结果收集；脚本内部有前置短路时，确认后续检查是否真正执行，必要时分别调度等价子任务，保留原门禁的最终验收。
+
+## 2. 收集全部可执行结果
+
+- 本轮开始后保持被测源码、配置、依赖和运行环境稳定；协作 agent 也不得边测边改，不运行自动修复。普通类型错误、lint 错误、测试断言失败只记录，继续其余具备前置条件的检查。
+- 只有真实前置失败才阻塞依赖它的检查，例如依赖无法安装、执行器无法启动、上游构建未产生必要产物、必需服务不可用。标明阻塞原因，继续独立检查；确实无法继续收集时才提前结束本轮、集中修复阻塞。不得使用旧构建、旧镜像或旧截图让下游假通过。
+- 为每轮使用独立且被 Git 忽略的日志目录，例如 `tmp/validation/round-01/`。逐项记录命令/范围、源码版本及未提交改动、环境、状态（通过/失败/阻塞/未执行）、退出码、耗时和日志路径；未执行与不适用须说明原因，不能写成通过。超时、取消和环境失败单列，不能当作断言失败或忽略。
+- 调度脚本等子进程退出后再记录结果；重定向或管道不能覆盖实际退出码。所有必需项均有有效通过结果，整轮才算通过；收集到任何失败或阻塞时，汇总必须保留非成功状态。
+- 完整输出写日志，AI 先读汇总及每类失败的有限上下文，再按需定位原始日志；不反复载入整份成功日志、密集轮询或启动尚未结束的同一检查。长任务期间定期简述进度。
+
+## 3. 集中分析与修复
+
+- 本轮可执行检查结束后，把问题按根因去重，记录位置、证据、影响、修复项及关联门禁。上游故障造成的连锁失败合并处理；区分本次引入、原有问题和环境问题。
+- 在已有授权范围内集中修复本次范围的问题，保留仍有效的断言与回归。不能靠删断言、跳过用例、放宽超时或关闭规则换绿灯。环境故障先保存证据、确认恢复条件，再定向重试；不反复重跑到偶然通过。
+- 下载超时先区分 registry、DNS、代理等网络前提与实际编译/业务错误。复用包管理器的有界重试、可信镜像和缓存，保留总时限与每次结果；只对可安全重复的瞬时网络操作重试，不重试断言或掩盖业务失败。超时/取消后确认本轮进程树及已登记资源回收，再重试或启动冲突任务。
+- 新发现的独立问题加入同一清单；修复期间的小范围诊断不触发从头全量重跑，也不能替代下一轮必要验收。
+
+## 4. 先定向回归，再扩大验收
+
+- 集中修复后，先用最小适用范围验证原失败、已解除的阻塞及直接受影响的消费者；保留必要构建/服务前置。定向回归仍失败时继续归并和修复，只重跑失败及受新改动影响的项，暂不启动较完整门禁。
+- 相关问题均已验证解决后，仅按实际依赖扩大到受影响工作区或完整用户流程，不自动扩大到全仓。用户先前要求的全量已完成后，后续局部修复也只使相关结果失效；补测相关项，除非用户再次要求全量。扩大验收发现新问题时，仍先收集、集中修复和定向确认，不从头重复整套流程。
+- 只有源码、依赖、配置、工具、环境及所用产物等输入均未改变的已通过项才可复用，并注明来源轮次或缓存；输入变化使相关结果失效。最终所有必需检查必须对最终代码仍有效，缺项不能称为完成。真实部署、Provider、浏览器或原生验收不能只引用静态检查/构建缓存。
+- 保留原有 CI/发布门禁的失败阻断；问题收集时继续运行不代表允许失败提交发布或忽略 required checks。
+- 每轮都在 finally/teardown 停止本轮进程、清理本轮临时工程/容器/镜像/数据；确认退出和资源释放后再运行冲突任务。日志、截图与报告保留到问题分析和交付结束，再按项目约定清理，不覆盖失败证据、不提交验收产物、不删除用户资源。
+- 部署夹具先检查固定公开基础镜像，仅确认缺失才拉取；成功 create 先登记完整 ID，再在私有 PID namespace 内异步准备 APT/pip/sshd。所有准备 exec 转交同一取消信号，等待本地客户端 close 后按该 ID 停止全树并核验消失。总准备 deadline 早于 hook 并预留回收预算；公共缓存不删，私有 tag 回收前复核内容 ID/owner。未取得可信 create 回执或测试进程被强制终止时记录未知，不能按名称或 label 认领资源。
+- 浏览器执行器默认将每轮、每组的证据分别放入忽略的 `test-results/run-*/group-*`；只清理本轮临时数据库/上传数据。显式 `HAI_AUTH_EVIDENCE_DIR`、`--output` 和 Playwright HTML 输出目录会保留，取消也不删除已有报告。不要复制私有环境、密钥或业务数据库到证据目录。
+- 经托管 `test:e2e` 入口为服务子进程提供绝对 `HAI_E2E_DATA_ROOT` 和显式测试后端，隔离继承的 `HAI_*` / `PUBLIC_*` / `VITE_*` 与用户 `.env.local`。仅本轮测试启用 `HAI_E2E=1`；普通开发与生产的 dotenv 加载、共享后端守卫不放宽。启用 transport 的验收使用本轮可信 ring 和 registry，不能关闭加密掩盖客户端契约问题。
+- Fullstack验收已部署服务时，通过 `E2E_ADMIN_PASSWORD`、`E2E_AUDIT_ADMIN_PASSWORD`、`E2E_CONFIG_ADMIN_PASSWORD`、`E2E_BUSINESS_OPERATOR_PASSWORD` 分别提供同环境的初始管理员、审计管理员、配置管理员、业务操作员密码；对应 `HAI_ADMIN_DEFAULT_PASSWORD`、`HAI_AUDIT_ADMIN_PASSWORD`、`HAI_CONFIG_ADMIN_PASSWORD`、`HAI_BUSINESS_OPERATOR_PASSWORD`。测试配置、登录和再次验证共用这些值；固定回退只用于托管测试账号，不能替代随机部署凭据。只核对来源与变量名，不把值写入日志、截图或报告；保留同密码拒绝、初始凭据和再次验证断言。
+- 最终报告各项门禁状态、执行/复用范围、修复结果和未验证原因；mock、容器、真实服务及原生结果分别说明。只陈述实际证据，不以“脚本执行完了”代表验证通过。
+
+公开 API 变更需验证 package.exports 实际入口与配套声明，核对根/子路径真实导入和浏览器打包；不使用 src/dist 深层导入绕过缺失公开产物。Svelte 默认组件、明确 selective/type-only 导出与 client/server 分隔按实际契约验收，不把内部 Provider/Deps 扩成公共 API。