NianToB/docs/PILOT_QA.md

YINIAN Desktop Pilot QA

Updated: 2026-04-26
Scope: M1/M2 pilot demo package for B-end business desktop flow

1. Pilot Scope

This pilot validates the desktop product loop that is already implemented:

• Login-first YINIAN entry.
• Session restore and logout cleanup.
• Single workspace/service context in the sidebar.
• Customer-facing sidebar focused on the service Dashboard card, 快速使用, 对话, and 设置.
• Knowledge Base v0 upload/list/search surface.
• Service-managed model/Agent/channel/schedule configuration notice in Settings.
• Config sync in mock or HTTP mode.
• Today operations cockpit.
• Workspace-scoped local skill registry.
• Skills Manager sync/status flow.
• Gateway start after authenticated workspace context.
• Legacy ClawX/OpenClaw compatibility in E2E mode.

Out of scope for this pilot:

• Real skill bundle download.
• Signature verification and unpacking.
• Real OTA/PMS task execution.
• Real payment, provisioning, or account administration.
• Customer-specific branding beyond current YINIAN visual system pass.

2. Environment Modes

Mock Mode

Default mode. Do not set YINIAN_API_BASE_URL.

Use this for product walkthroughs, local QA, and stakeholder demos before the NIANXX server is ready.

HTTP Mode

Set YINIAN_API_BASE_URL to enable server-backed control plane calls:

YINIAN_API_BASE_URL=https://api.example.com pnpm run dev

HTTP mode expects the contract documented in docs/SERVER_CONTRACT_V0.md.

E2E Compatibility Mode

Playwright uses CLAWX_E2E=1 through test fixtures. In this mode, legacy ClawX setup/main flows stay available so inherited regression tests remain meaningful.

3. Demo Script

Use mock mode unless the server is explicitly being validated.

1. Start the app:

   pnpm run dev
   

2. Confirm first screen is YINIAN login.

3. Login with mock SMS credentials:

   • Phone: 13800000000
   • Code: 123456

4. Confirm the app lands on /today.

5. Review Today cockpit:

   • Service name and login user are visible.
   • Clicking the sidebar service card returns to Today/Dashboard.
   • Application readiness cards render.
   • Status queue explains app sync/update/failed states.
   • Application status board merges server entitlements and local registry.

6. Open /skills.

7. Confirm Skills Manager:

   • Entitlement count is visible.
   • Local registry count is visible.
   • Empty registry warning appears before sync when relevant.
   • Each skill explains its current state.

8. Click 同步 Skills.

9. Confirm:

   • Sync completes without leaving the page.
   • Skill cards update to installed/skipped/updated states.
   • Today page reflects local registry status after returning.

10. Open 知识库.

11. Confirm:

• Upload entry is visible.
• Empty state is readable before upload.
• Search and document list area are present.

12. Hover 历史会话.

13. Confirm:

• History popover opens.
• Clicking 历史会话 opens the latest session when history exists, otherwise opens Chat.

14. Open Settings.

15. Confirm:

• 账号与组织 shows the current service and user.
• 同步组织配置 refreshes config for the current service.
• Model, Agent, channel, and scheduling-policy configuration are shown as server-managed capabilities.
• Today and Skills stay scoped to the same workspace context.

16. Click Settings 退出登录.

17. Confirm:

• App returns to /login.
• Current workspace config and local registry context are cleaned for the logged-out session.

4. QA Checklist

Auth And Session

• Login succeeds in mock mode.
• App restores a valid mock session after relaunch.
• Logout returns to /login.
• Logout clears current workspace config and current business skill registry context.
• HTTP mode restore calls /auth/refresh when a persisted refresh token exists.
• HTTP mode does not persist access tokens.

Workspace Context

• Sidebar service context appears only after authentication.
• No workspace switcher is visible in the product shell.
• Settings sync refreshes config for the current service.
• Today and Skills stay scoped to the current workspace registry.

Sidebar And Settings IA

• Production sidebar service card opens Today/Dashboard.
• Production sidebar quick-use area shows Skills, 定时任务, and 知识库.
• Chat area shows 新对话 and 历史会话.
• Hovering 历史会话 reveals the history popover.
• Models, Agents, Channels, and Dev Console are not visible in normal customer navigation.
• Account logout lives in Settings, not as a primary sidebar action.
• Settings explains that model/provider strategy, Agent orchestration, channels, and scheduling policy are managed by the service side.

Knowledge Base

• Knowledge page opens from the sidebar.
• Upload button opens the system file picker.
• Uploaded files appear in the local document list.
• Search filters the visible document list.
• Empty state distinguishes "no files yet" from "no search matches".

Gateway Boundary

• Gateway does not start before login in production mode.
• Gateway starts once after authenticated workspace context exists.
• CLAWX_LEGACY_AUTOSTART=1 restores the old ClawX startup behavior for debugging.
• E2E compatibility mode keeps legacy setup and Chat defaults available.

Today

• Today renders without config errors after login.
• Empty states are visible when there are no pending items, skills, or actions.
• Skill status labels are clear:
  • 已开通未同步
  • 已安装
  • 已更新
  • 已是最新
  • 有更新
  • 已禁用
  • 同步失败
• Refresh button updates config without triggering duplicate gateway starts.

Skills Manager

• Empty entitlement state appears when an organization has no opened skills.
• Empty local registry state is distinct from no entitlements.
• Sync first install marks skills as installed/updated.
• Syncing the same manifest again marks same-version skills as skipped.
• Failed sync surfaces an error and retry affordance.
• Disabled entitlements cannot run.
• Version drift is shown as 有更新.

Visual System

• Login, Today, Skills, and sidebar feel like one product.
• Primary actions use the YINIAN navy treatment.
• Status colors are restrained and readable.
• Panels use 8px radius or less.
• Text does not overflow buttons, cards, or status badges at common desktop widths.
• No marketing-style hero page appears after authentication.
• Visual smoke screenshots are refreshed for Login, Today, Skills, Knowledge, and Settings.

5. Verification Commands

Run this full gate before a guided demo:

pnpm run typecheck
pnpm run test
pnpm run build:vite
pnpm run test:e2e

Last known green verification:

• Typecheck: passed.
• Unit tests: 89 files, 572 tests passed.
• Vite build: passed.
• E2E: 26 passed, 1 skipped.
• Visual smoke: Login, Today, Skills, Knowledge, and Settings passed.

Known non-blocking warnings:

• Vitest MaxListenersExceededWarning.
• Vite dynamic/static import chunk warnings.
• Vite large chunk warning.
• Playwright/Electron NO_COLOR ignored because FORCE_COLOR is set.

6. Packaging Notes

For local macOS pilot packaging, prefer:

pnpm run package:mac:local

This skips preinstalled skills and is more suitable for a fast local artifact. Full release packaging should use the platform-specific package:* scripts after dependency and signing decisions are settled.

Do not treat the current pilot build as production-ready until:

• Real server auth is validated end to end.
• Real bundle download and signature verification are implemented.
• The installer signing/notarization path is finalized.
• Customer-specific privacy and logging requirements are reviewed.

7. Known Issues And Product Gaps

• Today uses config and local registry as its data source; real PMS/OTA/task data is not connected yet.
• Skills sync consumes manifest metadata only; it does not download, verify, or execute real bundles.
• Knowledge Base v0 is local UI state only; persistence, indexing, permissions, and service sync are not connected yet.
• HTTP control plane contract is still draft v0.
• Device identity is still a placeholder and should become a stable installation id.
• Legacy ClawX configuration pages remain available for compatibility/E2E routes, but should stay hidden from production customer navigation until an admin/developer mode is explicitly designed.
• Bundle size warnings remain from the inherited app structure.