From 8b44767f110ff3da3fa09a7f6a563dbade9cd6f5 Mon Sep 17 00:00:00 2001
From: Rogee <rogee@ipao.vip>
Date: Mon, 26 Jan 2026 11:49:32 +0800
Subject: [PATCH] docs: refine ai ui testing guidance

---
 AGENTS.md                 | 12 ++++++++
 docs/plan.md              | 64 ++++++++++++++++++++++-----------------
 docs/seed_verification.md | 47 +++++++++++++++++++++++++---
 3 files changed, 91 insertions(+), 32 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 1262407..aecd9e2 100644
--- 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.
diff --git a/docs/plan.md b/docs/plan.md
index 47decf2..b211496 100644
--- 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
 
diff --git a/docs/seed_verification.md b/docs/seed_verification.md
index 659b7a3..ae53068 100644
--- 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`.