# fancy-xz

**Repository Path**: springllc/fancy-xz

## Basic Information

- **Project Name**: fancy-xz
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-21
- **Last Updated**: 2026-06-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# fanxiaozhu（泛小助）

HIS 医生端异常响应与反馈闭环助手。**独立仓库**，消费 `lcy-lit-monitor` 的监控数据（只读，不改动它）。

> 项目背景、产品需求、全部已拍板决策见**伞形根目录**的 [`../AGENTS.md`](../AGENTS.md) 与 [`../泛小助-PRD.md`](../泛小助-PRD.md)。动手前务必先读。

## 结构

```
packages/contracts/   共享类型：assistant_event / feedback + lit-monitor 事件契约副本(D9)
packages/sdk/         FanXiaoZhu 客户端 SDK（框架无关，Shadow DOM；tsup 打包）
apps/server/          NestJS 后端（接入鉴权 / 事件接入 / 规则引擎 / 下发 / 反馈工单 / 动作审计 / 模型增强）
apps/admin/           React 控制台（后续，尚未创建）
```

## 起步

```bash
pnpm install
pnpm build              # 全量构建
pnpm dev:server         # 启动后端，GET http://localhost:3100/api/health
pnpm dev:sdk            # SDK watch 构建
```

## 医生端 SDK 嵌入

```ts
import { FanXiaoZhu } from '@fanxiaozhu/sdk'

FanXiaoZhu.init({
  doctorId: currentDoctor.id,
  hospitalId: currentHospital.id,
  page: 'inpatient-orders',
})

FanXiaoZhu.registerActions({
  reload: () => orderTable.reload(),
  openFeedbackPanel: ({ eventId }) => feedbackPanel.open(eventId),
})

FanXiaoZhu.connect({
  mode: 'poll',
  url: '/api/assistant/events/pending',
  intervalMs: 3000,
  getAccessToken: () => hisSession.getFanXiaoZhuToken(),
})
```

`init()` 会将蓝白机器人挂载到 Shadow DOM，不污染 HIS 页面样式。SDK 会由 pending URL 推导同级的 `/feedback` 接口，用于一键建单和工单状态轮询；非标准路由可通过 `feedbackUrl` 显式传入。SDK 构建后，可打开 `packages/sdk/demo/index.html` 验证四级事件和拖拽交互。

### 真实数据体验版

`packages/sdk/demo/live.html` 不直接伪造事件。页面调用受 JWT 保护的真实演示接口，由 SDK 自动采集 fetch/XHR，再经过规则引擎、数据库、SSE 和反馈工单回到机器人。当 server 配置 Kafka 时，同一时间线也会展示 `lit-monitor` 真实消费事件。

```bash
pnpm build

# 终端 1：无外部依赖的本地体验服务
DB_DRIVER=sqlite JWT_SECRET=experience-secret PORT=3100 \
  node apps/server/dist/main.js

# 终端 2：在仓库根目录启动静态服务
python3 -m http.server 4173 --bind 127.0.0.1
```

打开 `http://127.0.0.1:4173/packages/sdk/demo/live.html`。可依次执行“慢速加载”、“保存医嘱”、“校验摘要”，再在机器人气泡中一键反馈，最后从右侧推进真实工单状态。

机器人使用内联的透明 WebP 3D 形象 + CSS 分层表情/动效，不使用 WebGL/Three.js，不依赖外部图片服务。七种视觉状态由事件和工单流程自动驱动，联调时也可手动切换：

```ts
FanXiaoZhu.setVisualState('recording')
// idle | alert | care | recording | accepted | done | critical
```

动效遵循 `prefers-reduced-motion`，用户系统关闭动画时自动降级为静态形象。

## 铁律（摘自 AGENTS.md）

- **不改动 lit-monitor**（D3）；不直接 import 其内部代码，类型靠 `packages/contracts` 复制契约（D9）。
- 泛小助崩溃绝不能拖垮 HIS 业务主流程（低侵入、Shadow DOM、try/catch、熔断）。
- 安全动作白名单 + 写动作幂等键（D7）；高风险医疗动作一律禁止。
- 鉴权以登录态 token 为准，前端不传 doctorId（D6/D8）。