---
doc_id: DES-202606-001
feature_id: FEAT-202606-001-unified-entry-client
type: design
title: Unified Entry Terminal Web Demo Design
status: approved
owner: 医梦研发团队
created_at: 2026-06-02
updated_at: 2026-06-02
reviewers: []
related_docs:
  - PRD-202606-001
  - DDS-202606-003
related_modules:
  - emoon-terminal-client
tags:
  - 统一入口客户端
  - Web Demo
  - UI设计
---

# Unified Entry Terminal Web Demo Design

## 1. Objective

Build a single-application Web demo for the unified entry terminal client. The demo should feel like an intelligent hospital service entrance rather than a traditional menu system, and it must support one complete outpatient registration flow for next-week customer demonstration.

The first version prioritizes desktop Web demonstration at `1440x900` and `1920x1080`. It does not target vertical self-service kiosk screens yet.

## 2. Product Positioning

The Web demo represents a hospital-facing AI service entrance similar in spirit to a friendly healthcare assistant. The patient should express intent through natural language. The system then recognizes intent, routes to the right backend task, and presents deterministic business cards only when the flow requires selection or confirmation.

The UI must not look like a traditional feature menu. It should not make registration, triage, doctor lookup, and route guidance appear as a growing left navigation tree of agents. The visible UI can explain what the assistant can handle, but the primary entry point is conversation.

## 3. Scope

### In Scope

- Single Vue 3 + TypeScript + Vite Web application.
- A+B layout direction:
  - A: friendly AI assistant entry feel.
  - B: task workspace once registration begins.
- Complete registration flow:
  - user message or typed intent
  - department recommendation card
  - doctor selection card
  - time slot selection card
  - appointment confirmation card
  - mock payment card
  - appointment success card
- SSE conversation handling for `message_delta`, `message_completed`, `task_updated`, `card_created`, `error`, and `completed`.
- Card action handling with `idempotencyKey`.
- Static cartoon doctor assistant image in the right context panel when no card is active.
- Mock result labeling whenever backend returns `mock:true`.
- Desktop visual QA for `1440x900` and `1920x1080`.

### Out Of Scope

- Real HIS integration.
- Real payment,医保,退号退费.
- Full robot, kiosk, guide-screen multi-app monorepo.
- TTS/STT implementation.
- Dynamic avatar animation, lip sync, listening animation, or voice state transitions.
- Medical diagnosis text generated by frontend.
- Direct Dify, HIS, MCP Tool, tongue diagnosis, or metering calls from frontend.

## 4. Brand Color System

Company theme colors:

| Token | Value | Usage |
| --- | --- | --- |
| `brandPrimary` | `#2b1f99` | Main action, selected task, user message, active progress |
| `brandAccent` | `#3ad4d8` | Accent border, secondary action, progress highlight, assistant glow |
| `pageBg` | `#f7fbff` | App background |
| `surface` | `#ffffff` | Panels and cards |
| `softTint` | `#f4fdff` | Selected card background and assistant hint background |
| `border` | `#dfe7f7` | Panel borders |
| `textPrimary` | `#16133a` | Main text |
| `textSecondary` | `#69708a` | Secondary text |
| `warningBg` | `#fff8e8` | Mock/payment warning surface |
| `warningText` | `#735b14` | Mock/payment warning text |

The palette should feel clean and medical-tech oriented. It should not drift into a generic blue dashboard or use heavy gradients across the whole page. Gradients are allowed only on the assistant identity mark and doctor image environment.

## 5. Layout

Use a three-column desktop layout:

```text
Header
├── Left Assistant Context Panel
├── Center Conversation Panel
└── Right Context Panel
```

### Header

The header contains:

- product name: `医梦门诊助手`
- small environment label: `Web Demo · 门诊大厅 · 联调演示`
- optional device identifier when available

### Left Assistant Context Panel

The left panel is not a functional menu. It contains:

- assistant identity block
- short explanation: `说出需求，我来判断下一步`
- examples the patient can say:
  - `我头疼三天，想挂号`
  - `明天上午有神经内科的号吗`
  - `我想找李明医生`
- current capability tags, rendered as informational chips:
  - `挂号`
  - `导诊`
  - `医生查询`
- mock/demo warning note

It must not render large clickable buttons for each agent or workflow.

### Center Conversation Panel

The center panel is the only input area in the first version.

It contains:

- conversation title and brief instruction
- streamed assistant messages
- user messages
- input field
- voice button
- send button

The voice button is visible for future STT affordance but does not implement real STT in this version. It can show a disabled/demo behavior or a short toast depending on implementation readiness.

### Right Context Panel

The right panel is a stateful context panel.

State `idle`:

- shows static cartoon doctor assistant image only
- shows short supporting text:
  - `医生助手`
  - `当前仅作为静态形象展示。语音与发送操作仍在中间输入区完成。`
- no voice button
- no send button
- no `可听` / `可说` interaction chips

State `task`:

- shows registration progress
- shows current business card
- card actions are rendered from backend `actions`

State `error`:

- shows error card with user-readable message
- includes `traceId` when available
- offers a retry or restart action if the backend response supports it

State `completed`:

- shows appointment success card
- includes `mock:true` label when present
- user can click `完成` to return right panel to `idle`

## 6. Doctor Assistant Asset

Do not draw the doctor assistant with CSS primitives.

Use a real static image asset. A generated candidate already exists at:

```text
/Users/destiny/.codex/generated_images/019e8719-cee0-7723-83a4-ac1a9e0a3bd4/ig_037570e350a4f508016a1e882c0c188191b10d3dbe9b5f776a.png
```

Implementation should copy this image into the frontend project as:

```text
src/assets/doctor-assistant.png
```

The original generated image must remain in place unless explicitly deleted by the user.

Asset requirements:

- polished 2D cartoon doctor assistant
- white coat and friendly expression
- uses `#2b1f99` and `#3ad4d8` as accents
- no text in image
- no third-party logo
- fits the right panel without cropping at `1440x900`

## 7. Interaction Flow

### Startup

```text
load app config
→ register device or use demo device
→ heartbeat every 30 seconds
→ load scene profile
→ render idle layout
```

For Web demo, a demo signer or dev-only bearer/HMAC helper may be used, but signing secrets must not be placed in browser-exposed `VITE_*` variables for real deployment.

### Registration Start

User can type:

```text
我头疼三天，还有点恶心，想挂号
```

Frontend calls:

```text
POST /api/v1/agent/chat/stream
```

Frontend must not pass `agentId`.

SSE handling:

```text
task_updated -> set active task and right panel task state
message_delta -> append assistant text
message_completed -> finalize assistant message
card_created -> fetch card instance and render right panel card
completed -> store conversationId and traceId
error -> show error state
```

### Card Flow

Card flow:

```text
department-selection
→ doctor-selection
→ time-slot-selection
→ confirm-appointment
→ payment-qrcode
→ appointment-success
```

Every card action posts:

```text
POST /api/v1/cards/{cardInstanceId}/actions/{actionName}
```

The request must include:

```json
{
  "idempotencyKey": "stable-key-for-this-logical-action",
  "confirm": true,
  "payload": {}
}
```

### Mock Payment

The payment card must clearly label:

```text
联调演示 / Mock 支付
```

The mock payment action can be rendered as a visible demo button only in Web demo mode. It must not use WeChat, Alipay,医保, or any real payment brand.

## 8. Components

Core components:

| Component | Responsibility |
| --- | --- |
| `AppShell` | Header and three-column layout |
| `AssistantContextPanel` | Left assistant identity, examples, capability chips |
| `ConversationPanel` | Message stream, input, voice button, send button |
| `ContextPanel` | Right panel state switch: idle/task/error/completed |
| `DoctorAssistantFigure` | Static doctor image display |
| `RegistrationProgress` | Step progress for registration |
| `CardRenderer` | Switches cardKey to card component |
| `DepartmentSelectionCard` | Renders departments and select action |
| `DoctorSelectionCard` | Renders doctors and select action |
| `TimeSlotSelectionCard` | Renders slots and select action |
| `ConfirmAppointmentCard` | Summary and second confirmation |
| `PaymentQrCard` | Mock payment QR/content and mock paid action |
| `AppointmentSuccessCard` | Appointment result and mock label |
| `ErrorCard` | Error message, traceId, retry/restart action |

## 9. State Model

Use a small frontend store with these slices:

```text
device:
  deviceId
  deviceType
  sceneProfile
  heartbeatStatus

conversation:
  conversationId
  messages[]
  streaming
  currentTraceId

task:
  taskId
  taskType
  currentStep
  status

contextPanel:
  mode: idle | task | error | completed
  activeCardInstanceId
  activeCard

ui:
  inputText
  pendingActionKey
  demoMode
```

The right panel mode is derived primarily from task/card state:

```text
no active task and no active card -> idle
active card -> task
error event -> error
appointment-success card -> completed
```

## 10. Error Handling

Required behavior:

- Auth error: show startup blocking message.
- Device pending/rejected: show startup blocking state, not the main UI.
- SSE disconnect: keep existing messages and offer retry.
- Invalid card: show error card with `traceId`.
- Expired card: show card disabled state and ask user to restart current step.
- Duplicate submit: keep first returned result, do not visually create a second card.
- Mock HIS timeout: show error card, do not pretend success.

## 11. Testing And QA

Use Playwright for visual and interaction QA.

Viewports:

```text
1440x900
1920x1080
```

Minimum checks:

- Header and three columns fit without horizontal scroll.
- Left panel has no large workflow buttons.
- Center panel owns voice and send buttons.
- Right idle panel shows the static doctor image only.
- Starting registration switches right panel from idle to task.
- All card actions use idempotency keys.
- Mock payment and appointment success show `联调演示` or `Mock`.
- Text does not overflow buttons/cards at desktop viewport.

## 12. Open Decisions

None for the first implementation plan.

The first implementation plan should build the Web demo as a single application. Later work can split it into `packages/api-client`, `packages/medical-cards`, and multi-terminal apps when the first Web demo is accepted.

## 13. Approval Summary

Approved direction:

- A+B mixed layout.
- Web browser demo first.
- Registration loop first.
- Brand colors `#3ad4d8` and `#2b1f99`.
- Dialogue-first design, no left workflow menu.
- Right panel is context panel.
- Idle right panel shows a static cartoon doctor only.
- Voice and send controls stay in center conversation input.