docs: add ui page testing checklist

2026-02-02 20:15:09 +08:00
parent 3ab1434821
commit bb90bef02e
3 changed files with 105 additions and 120 deletions
--- a/docs/plan.md
+++ b/docs/plan.md
@@ -1,64 +1,63 @@
-# Implementation Plan: Improve Error Logging
+# Implementation Plan: UI Page Testing Checklist

 **Branch**: `main` | **Date**: 2026-01-26 | **Spec**: N/A
-**Input**: 完善应用错误记录，输出更精确的错误定位信息。
+**Input**: 制定页面级自动化测试清单，覆盖 portal/superadmin 核心业务流。

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

 ## Summary

-定位当前错误记录入口与结构，补充关键上下文信息（请求 ID、路径、用户/租户 ID、处理器名称、错误链），并统一输出格式，方便快速定位问题。
+梳理并落地一份可执行的 UI 页面测试清单，涵盖 Portal 与 Superadmin 的关键流（登录、订单、内容、财务、通知等），便于 AI/MCP 按步骤执行与验证。

 ## Technical Context

-**Language/Version**: Go 1.22
-**Primary Dependencies**: Fiber, logrus, errorx
-**Storage**: N/A
-**Testing**: go test / 运行时日志
+**Language/Version**: JS (Vue3 + Vite) + Chrome DevTools MCP
+**Primary Dependencies**: Vite dev servers, seeded data
+**Storage**: PostgreSQL (seed required)
+**Testing**: 页面自动化（MCP）
 **Target Platform**: local/staging
 **Project Type**: Web application
 **Performance Goals**: N/A
-**Constraints**: 不修改生成文件
-**Scale/Scope**: 日志格式与错误处理
+**Constraints**: 仅文档/指令，不改业务代码
+**Scale/Scope**: Portal + Superadmin 核心页面

 ## Constitution Check

 - 遵循 `backend/llm.txt`
- 只改非生成文件
+- 不修改生成文件

 ## Project Structure

 ```text
-backend/app/errorx/
-backend/providers/http/
-backend/app/middlewares/
+docs/
+├── plan.md
+└── seed_verification.md
 ```

 ## Plan Phases

-### Phase 1: 现状定位
- 追踪错误记录入口与结构（errorx + middleware + http provider）。
+### Phase 1: 场景整理
+- 列出 Portal/Superadmin 关键页面与断言点。

-### Phase 2: 日志增强
- 补充 request-id、path、method、tenant/user、handler、error chain。
- 确认错误等级与格式一致。
+### Phase 2: 测试步骤编排
+- 为每个场景编排 MCP 步骤（导航、表单、断言、错误检查）。

-### Phase 3: 验证
- 使用典型 4xx/5xx 请求验证日志输出。
+### Phase 3: 输出清单
+- 将清单写入 `docs/seed_verification.md`。

 ## Tasks

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

 ### Phase 1
- [x] T001 [US0] 定位错误记录入口与字段
+- [ ] T001 [US0] 梳理 Portal 核心页面与断言
+- [ ] T002 [US0] 梳理 Superadmin 核心页面与断言

 ### Phase 2
- [x] T010 [US1] 增强错误日志上下文
- [x] T011 [US1] 统一格式与等级
+- [ ] T010 [US1] 编排 MCP 步骤（导航/登录/断言/错误检查）

 ### Phase 3
- [x] T020 [US2] 验证输出与文档说明
+- [ ] T020 [US2] 输出并归档测试清单

 ## Dependencies

@@ -66,12 +65,12 @@ backend/app/middlewares/

 ## Acceptance Criteria

- 日志可直接定位请求来源与错误链。
- 关键字段完整（request-id、path、tenant/user、handler）。
+- 文档包含 Portal/Superadmin 主要页面与清晰断言点。
+- 每个场景有 MCP 执行步骤（含登录、导航、断言、console error 检查）。

 ## Risks

- 日志字段增加影响性能或泄露敏感信息。
+- 环境/端口变更导致脚本需调整。

 ## Complexity Tracking

--- a/docs/seed_verification.md
+++ b/docs/seed_verification.md
@@ -1,105 +1,58 @@
-# Seed Verification Guide (Staging)
+# Seed Verification & UI Test Guide (Staging)

 ## Service Startup (Local)
-
 - Backend: `go run ./backend/main.go serve` (default `http://localhost:8080`).
- Portal frontend: `npm -C frontend/portal install` then `npm -C frontend/portal run dev` (default `http://localhost:5174`, remote use `http://10.1.1.104:5174`).
- Superadmin frontend: `npm -C frontend/superadmin install` then `npm -C frontend/superadmin run dev` (default `http://localhost:5173`, remote use `http://10.1.1.104:5173`).
- Portal dev server proxies `/v1` to `http://localhost:8080` (`frontend/portal/vite.config.js`).
- Superadmin dev server proxies `/super/v1` and `/v1` to `http://localhost:8080` (`frontend/superadmin/vite.config.mjs`).
+- Portal: `npm -C frontend/portal install && npm -C frontend/portal run dev` (default `http://localhost:5174`, remote `http://10.1.1.104:5174`).
+- Superadmin: `npm -C frontend/superadmin install && npm -C frontend/superadmin run dev` (default `http://localhost:5173`, remote `http://10.1.1.104:5173`).
+- Proxies: portal `/v1` → backend `8080`; superadmin `/super/v1` & `/v1` → backend `8080`.

 ## Chrome DevTools MCP
-
- 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).
+- Remote Chrome 已启动；连接 `http://10.1.1.104:9222`。
+- 仅页面操作，无需 API 直接调用。

 ## AI Auto-Handling Prereqs
+- Seed 检查：`SELECT COUNT(*) FROM tenants;` 为 0 则 `go run ./backend/main.go seed`。
+- tenantCode：`SELECT code FROM tenants ORDER BY id DESC LIMIT 1;` → `/t/:tenantCode`。
+- 清理存储：`localStorage.clear(); sessionStorage.clear();` + 清除 cookies。

- **Seed 检查/执行**
-  - DB 查询（示例）：`SELECT COUNT(*) FROM tenants;`
-  - 若结果为 0，执行 `go run ./backend/main.go seed` 后再继续。
- **tenantCode 获取**
-  - DB 查询：`SELECT code FROM tenants ORDER BY id DESC LIMIT 1;`
-  - 将结果注入到 Portal URL `/t/:tenantCode`。
- **清理浏览器存储**
-  - 在 MCP 中执行脚本：清理 `localStorage` / `sessionStorage`，并清除 cookies。
-  - 示例：`chrome-devtools_evaluate_script` → `() => { localStorage.clear(); sessionStorage.clear(); document.cookie.split(';').forEach(c => document.cookie = c.replace(/^ +/, '').replace(/=.*/, '=;expires=' + new Date().toUTCString() + ';path=/')); }`
+## Portal Test Checklist (tenantCode from DB)
+1) **Login** `/auth/login` → 手机 `13800138000` + OTP `1234`，勾选条款；断言“登录成功”。
+2) **Home** `/t/:tenantCode` → 有内容/导航无报错。
+3) **Content Detail** `/t/:tenantCode/contents/1` → 封面/正文/评论可见。
+4) **Orders** `/t/:tenantCode/me/orders` → 列表非空。
+5) **Library** `/t/:tenantCode/me/library` → 列表非空。
+6) **Favorites** `/t/:tenantCode/me/favorites` → 列表非空，可见“取消收藏”。
+7) **Likes** `/t/:tenantCode/me/likes` → 列表非空，可见“取消点赞”。
+8) **Notifications** `/t/:tenantCode/me/notifications` → 页面无错误。
+9) **Creator entry** `/t/:tenantCode/creator` → 页面可加载。
+- 每页：调用 `chrome-devtools_list_console_messages` 无 `error`。

-### MCP Example Flow (AI Guidance)
-
-1. **Open Portal Home**
-   - `chrome-devtools_new_page` → `http://10.1.1.104: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://10.1.1.104: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`.
- Ensure no panics; capture console output for troubleshooting.
-
-## Data Validation (DB/Logs)
-
- Users: verify `creator`, `test`, `superadmin`, `negative` exist in `users.username`.
- 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.
- Templates: `notification_templates` contains order/audit/interaction types.
-
-## Portal Smoke (Use tenantCode)
-
- Tenant code: query DB (`SELECT code FROM tenants ORDER BY id DESC LIMIT 1;`), then open `http://10.1.1.104: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`.
- Orders & Library: `/t/:tenantCode/me/orders` and `/t/:tenantCode/me/library` show data.
- Likes/Favorites: content detail shows prefilled like/favorite; toggle to confirm.
- Notifications: `/t/:tenantCode/me/notifications` shows unread items.
-
-## Superadmin Smoke
-
- Open `http://localhost:5173/super/auth/login`.
- Login: `superadmin` / `superadmin123`.
- Users: list includes `negative`; balance anomaly list returns result.
- Orders: list includes flagged/reconciled and refund orders.
- Withdrawals: list contains `created`/`paid`/`failed` statuses.
- Finance: ledger list has data; order anomaly list returns missing paid/refund items.
- Content/Reports: content list is populated; report list has pending item.
- Templates: order/audit/interaction templates present.
- System Configs: `site_name` and `support_email` present.
+## Superadmin Test Checklist
+1) **Login** `/super/auth/login` → `superadmin/superadmin123`，成功进入 Dashboard。
+2) **Orders** `/super/superadmin/orders` → 有标记/对账数据。
+3) **Finance** `/super/superadmin/finance` → 提现审核/流水/异常标签有数据。
+4) **Users** `/super/superadmin/users` → 列表可见。
+5) **Tenants** `/super/superadmin/tenants` → 列表可见。
+6) **Notifications** `/super/superadmin/notifications` → 模板列表可见。
+7) **System Configs** `/super/superadmin/system-configs` → `site_name/support_email` 可见。
+8) **Audit Logs** `/super/superadmin/audit-logs` → 列表可见。
+- 每页：检查 console 无 `error`；必要时截图。

 ## Manual-Only Coverage
+- 上传链路（init/part/complete）需真实存储；seed 仅提供素材记录。

- Upload flow (init/part/complete) requires real storage integration; seed only preloads assets.
+## Seed Notes
+- 执行 `go run ./backend/main.go seed` 会 TRUNCATE 全部业务表后重建。
+- 用户：`creator(13800000001)`, `test(13800138000)`, `superadmin(13800009999)`, `negative(13800009998)`。
+- 租户：`meipai_<rand>`（DB 查询获取）。
+- Orders/likes/favorites/notifications 已预置示例数据。
+
+## MCP Steps (Example)
+- `chrome-devtools_new_page http://10.1.1.104:5174/auth/login`
+- 填手机号+勾条款 → 获取验证码 → 填 `1234` → 登录
+- 导航并断言：
+  - `/t/:tenantCode/me/orders` 有行
+  - `/t/:tenantCode/me/library` 有行
+  - `/t/:tenantCode/me/favorites` 有行
+  - `/t/:tenantCode/me/likes` 有行
+- Superadmin：打开登录 → 填账号密码 → 断言 Dashboard → 进入 Orders/Finance/Notifications/System Configs/Audit Logs；每页检查 console `error`。