docs: refine ai ui testing guidance

2026-01-26 11:49:32 +08:00
parent 6086b982f8
commit 8b44767f11
3 changed files with 91 additions and 32 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -25,6 +25,18 @@
 - Go tests: `go test ./...` (some service tests exist under `backend/app/services/*_test.go`).
 - Frontend: build + lint are the main checks (`npm -C frontend/superadmin run build && npm -C frontend/superadmin run lint`).

+## AI UI Testing References
+
+When driving browser tests via Chrome DevTools MCP, consult:
+
+- `docs/seed_verification.md` (full UI flow + MCP steps)
+- `frontend/portal/vite.config.js` (proxy + port)
+- `frontend/superadmin/vite.config.mjs` (proxy + port)
+- `frontend/portal/src/router/index.js` (portal routes)
+- `frontend/superadmin/src/router/index.js` (superadmin routes)
+- `backend/app/services/user.go` (OTP rule: `1234`)
+- `backend/app/commands/seed/seed.go` (seed users/passwords)
+
 ## Planning Requirements

 - Before any non-trivial development work, first produce a complete plan document (tasks, sequence, dependencies, and acceptance criteria) and get confirmation to proceed.
--- a/docs/plan.md
+++ b/docs/plan.md
@@ -1,30 +1,30 @@
-# Implementation Plan: Page Automation Verification
+# Implementation Plan: AI UI Test Readiness

 **Branch**: `main` | **Date**: 2026-01-26 | **Spec**: `docs/seed_verification.md`
-**Input**: 将验证流程转为纯页面自动化测试（Playwright）。
+**Input**: 验证 AI 浏览器自动化遗漏点并修复，更新 `AGENTS.md` 指引。

 **Note**: 本计划遵循 `docs/templates/plan-template.md`。

 ## Summary

-新增一份“纯页面自动化验证”文档，包含服务启动步骤（backend/portal/superadmin）和 Playwright 操作清单，确保 AI 能在无 API 调用前提下完成冒烟验证。
+逐项验证 AI 浏览器自动化的遗漏点（代理、登录、tenantCode、断言、错误检测），补齐相关配置或文档，并在 `AGENTS.md` 中列出 AI 测试应参考的关键文件。

 ## Technical Context

-**Language/Version**: JS (Playwright) + Go 1.22 + Vite
-**Primary Dependencies**: Playwright, Vite dev server
-**Storage**: PostgreSQL (seed 数据)
-**Testing**: 页面自动化 (browser-driven)
-**Target Platform**: Local + staging
+**Language/Version**: Go 1.22 + Vite + Chrome DevTools MCP
+**Primary Dependencies**: Vite proxy, seeded data
+**Storage**: PostgreSQL
+**Testing**: 页面自动化 (MCP)
+**Target Platform**: local/staging
 **Project Type**: Web application
 **Performance Goals**: N/A
-**Constraints**: 仅写文档，不修改业务代码
-**Scale/Scope**: 覆盖 portal + superadmin 冒烟场景
+**Constraints**: 不修改生成文件
+**Scale/Scope**: 文档与种子数据/配置修复

 ## Constitution Check

- 不修改生成文件
- 仅新增/更新文档
+- 遵循 `backend/llm.txt`
+- 只改非生成文件

 ## Project Structure

@@ -33,33 +33,43 @@
 ```text
 docs/
 ├── plan.md
-└── seed_verification.md
+├── seed_verification.md
+└── plans/
+```
+
+### Source Code (repository root)
+
+```text
+backend/app/commands/seed/seed.go
+AGENTS.md
 ```

 ## Plan Phases

-### Phase 1: 启动流程梳理
- 明确 backend/portal/superadmin 本地启动方式与代理关系。
+### Phase 1: 缺口验证
+- 逐项验证代理、登录、tenantCode、断言、错误检测。

-### Phase 2: 自动化场景清单
- 按 portal/superadmin 视图输出可自动化步骤与断言。
+### Phase 2: 修复与补充
+- 通过 seed/文档补齐缺口，更新 `AGENTS.md`。

-### Phase 3: 输出验证文档
- 更新 `docs/seed_verification.md` 为“纯页面自动化”版本。
+### Phase 3: 复核与归档
+- 复核覆盖面，完成 plan 归档。

 ## Tasks

 **Format**: `[ID] [P?] [Story] Description`

 ### Phase 1
- [x] T001 [US0] 梳理服务启动命令与端口
+- [ ] T001 [US0] 校验代理/端口与登录细节
+- [ ] T002 [US0] 校验 tenantCode 获取方式与断言点
+- [ ] T003 [US0] 校验错误检测与 console 监控指引

 ### Phase 2
- [x] T010 [US1] Portal 页面自动化步骤
- [x] T011 [US1] Superadmin 页面自动化步骤
+- [ ] T010 [US1] 修复 seed/配置/文档缺口
+- [ ] T011 [US1] 更新 `AGENTS.md` AI 测试参考文件

 ### Phase 3
- [x] T020 [US2] 更新验证文档（含 DevTools MCP 指引）
+- [ ] T020 [US2] 复核并归档计划

 ## Dependencies

@@ -67,13 +77,13 @@ docs/

 ## Acceptance Criteria

- 文档包含完整启动流程与端口说明。
- 文档包含可直接执行的页面自动化步骤。
- 不涉及 API 级验证说明。
+- 文档包含完整 AI 自动化前置与断言说明。
+- `AGENTS.md` 指明 AI 测试参考文件。
+- 计划已归档并清空 `docs/plan.md`。

 ## Risks

- 登录依赖 OTP/浏览器控制台获取。
+- Staging 环境不可访问导致验证不足。

 ## Complexity Tracking

--- a/docs/seed_verification.md
+++ b/docs/seed_verification.md
@@ -10,10 +10,48 @@

 ## Chrome DevTools MCP

- Start Chrome with remote debugging: `google-chrome --remote-debugging-port=9222`.
- Use MCP to connect at `http://127.0.0.1:9222`.
+- Chrome remote debugging已由远程机器启动，无需本机手动启动浏览器。
+- Use MCP to connect at `http://10.1.1.104:9222` (SSH forwarded DevTools port).
 - Open target URLs via MCP and run page-level assertions (no API-level calls required).

+### MCP Example Flow (AI Guidance)
+
+1. **Open Portal Home**
+   - `chrome-devtools_new_page` → `http://localhost:5174/t/:tenantCode`
+   - `chrome-devtools_wait_for` text: `探索戏曲` or page title
+
+2. **Portal Login**
+   - Navigate to `/t/:tenantCode/auth/login`
+   - Tick checkbox `#terms` (required)
+   - `chrome-devtools_fill` phone input with `13800138000`
+   - Click `获取验证码`, wait for OTP step
+   - `chrome-devtools_fill` OTP input with `1234`
+   - Click `登录 / 注册`
+   - `chrome-devtools_wait_for` text: `个人中心` or user nickname
+
+3. **Verify Orders & Library**
+   - Navigate to `/t/:tenantCode/me/orders` and assert at least 1 row
+   - Navigate to `/t/:tenantCode/me/library` and assert at least 1 item
+
+4. **Open Content Detail**
+   - From home list, click the first content card
+   - Assert detail page loads and cover/media is visible
+
+5. **Superadmin Login**
+   - `chrome-devtools_new_page` → `http://localhost:5173/super/auth/login`
+   - Fill `#username` with `superadmin` and `#password1` with `superadmin123`
+   - Click `Sign In`
+   - Wait for dashboard cards or `Dashboard` text
+
+6. **Superadmin Lists**
+   - `/super/superadmin/orders` → verify flagged order badge
+   - `/super/superadmin/finance` → verify ledger table row
+   - `/super/superadmin/notifications` → verify template rows
+
+7. **Console/Error Checks**
+   - After each page, call `chrome-devtools_list_console_messages` and fail on `error` entries.
+   - Use `chrome-devtools_take_snapshot` to locate table rows by text.
+
 ## Run Seed

 - Execute `go run ./backend/main.go seed`.
@@ -22,7 +60,7 @@
 ## Data Validation (DB/Logs)

 - Users: verify `creator`, `test`, `superadmin`, `negative` exist in `users.username`.
- Tenant: read `tenants.code` to obtain `tenantCode` (DB query or admin UI).
+- Tenant: read `tenants.code` to obtain `tenantCode` (example: `SELECT code FROM tenants ORDER BY id DESC LIMIT 1;`).
 - Memberships: `tenant_users` includes `creator` as `tenant_admin`, `test` as `member`.
 - Orders: `orders` has `content_purchase` + `withdrawal`, plus flagged/reconciled records.
 - Ledger: `tenant_ledgers` has at least one row.
@@ -30,8 +68,7 @@

 ## Portal Smoke (Use tenantCode)

- Tenant code: query DB, then open `http://localhost:5174/t/:tenantCode`.
- Login: OTP is fixed to `1234` (see `backend/app/services/user.go`).
+- Tenant code: query DB (`SELECT code FROM tenants ORDER BY id DESC LIMIT 1;`), then open `http://localhost:5174/t/:tenantCode`.- Login: OTP is fixed to `1234` (see `backend/app/services/user.go`).
 - Home: `/t/:tenantCode` lists content.
 - Detail: open any content detail; cover and main asset render.
 - Login: sign in as `test` (phone `13800138000`, OTP `1234`) and open `/t/:tenantCode/me`.