86 lines
4.4 KiB
Markdown
86 lines
4.4 KiB
Markdown
# 照壁 BFF 与镜匣桌面壳
|
||
|
||
> 状态：重写目标态（rewrite/1.0 基线）
|
||
> 两项均为新增工程：照壁（Fastify BFF）进入 Compose 应用层；镜匣（Tauri 最小桌面壳）为桌面构建产物。
|
||
|
||
## 一、照壁（BFF，Node.js 22 + Fastify）
|
||
|
||
### 1. 定位
|
||
|
||
照壁是琉璃镜/镜匣与灵台之间的唯一通道：鉴权透传、SSE/WebSocket 代理、响应裁剪、类型桥接。**无状态、无业务规则、无权威数据**——"能否看到"的语义一律来自灵台，照壁只做传输与形状处理。
|
||
|
||
### 2. 职责清单
|
||
|
||
| 职责 | 说明 |
|
||
| --- | --- |
|
||
| 鉴权透传 | JWT Cookie（httpOnly）原样转发灵台；刷新流程代理；不做本地权限判断 |
|
||
| SSE 代理 | 透传灵台 SSE：禁缓冲（`X-Accel-Buffering: no`）、透传 `Last-Event-ID` 断线续传、心跳保活、客户端断开即向上游取消 |
|
||
| WebSocket 代理 | 双向协同场景（预留，P0 不启用） |
|
||
| 响应裁剪 | 按端点白名单裁剪字段（移动端轻量视图）；不裁剪治理与审计字段 |
|
||
| 轻量聚合 | 跨灵台端点的合并请求（如镜树页一次取树+入口+待确认）；只合并不改写语义 |
|
||
| 类型桥接 | 灵台 OpenAPI 3.1 生成 TypeScript 类型，openapi-fetch 类型安全调用；BFF 自身入参用 Zod 校验 |
|
||
| 日志 | pino 结构化日志：request_id、用户 ID、耗时、上游状态；不含请求体敏感原文 |
|
||
|
||
### 3. 请求链路
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
A[琉璃镜 / 镜匣] -->|HTTPS + JWT Cookie| B[天门 Nginx]
|
||
B --> C[照壁 Fastify]
|
||
C -->|鉴权透传 + Idempotency-Key| D[灵台]
|
||
D -->|SSE / JSON| C
|
||
C -->|裁剪 + 保活| A
|
||
```
|
||
|
||
### 4. 工程约定
|
||
|
||
- 目录 `bff/`（Node 22 LTS、TypeScript、Fastify、Zod、openapi-fetch、pino）；
|
||
- 测试：Vitest + supertest（代理行为、断线续传、裁剪白名单）；
|
||
- 部署：`docker/bff/Dockerfile`，容器 `hunjing-bff`，挂 `hunjing-net`；天门将 `/api/*` 指向照壁；
|
||
- 性能红线：SSE 代理链路不引入整帧缓冲；代理自身超时大于灵台同类超时，避免 BFF 先于后端掐断流。
|
||
|
||
## 二、镜匣（桌面壳，Rust + Tauri v2）
|
||
|
||
### 1. 定位与范围（最小壳）
|
||
|
||
镜匣在 1.0 只交付最小桌面壳：
|
||
|
||
1. **WebView 承载琉璃镜**：加载本地打包的前端或指向自托管部署地址；登录与全部功能即 Web 功能；
|
||
2. **本地能力桥**：文件对话框、系统通知、托盘常驻、开机自启（可选）；
|
||
3. **乾坤本地执行通道**：桌面端可连接本地/局域乾坤沙箱，作为该镜域器谱中的一台设备（须在器谱登记并经人物授契后才可用）；
|
||
4. **tantivy 本地检索（预留）**：为本地文件索引预留接口与能力声明，1.0 不实现索引构建；
|
||
5. **自动更新**：tauri-plugin-updater；本地配置 tauri-plugin-store。
|
||
|
||
**不做**：本地人物副本、离线人格运行、绕过照壁直连灵台、本地保存平台密钥。设备失联只做安全自治与输入暂存。
|
||
|
||
### 2. 能力与授权映射
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
T[Tauri capabilities<br/>壳内声明] --> M[器谱登记<br/>镜域设备]
|
||
M --> G[人物授契<br/>逐项授权]
|
||
G --> S[司命裁决<br/>云端]
|
||
S --> Q[乾坤本地执行<br/>双裁决]
|
||
Q --> H[本地硬急停<br/>最高优先]
|
||
```
|
||
|
||
- Tauri capability（窗口、文件、通知等）映射为器谱设备能力项；未经人物授契的能力，Web 层不可调用；
|
||
- 实体动作执行走"云端司命 + 设备本地安全控制"双裁决；本地硬急停优先级最高；
|
||
- 镜匣身份：安装时生成设备密钥并登记器谱，可撤销证书。
|
||
|
||
### 3. 工程约定
|
||
|
||
- 目录 `desktop/`（cargo + Tauri v2 + specta 类型导出）；
|
||
- 与前端共享：加载同一份琉璃镜构建产物，不维护第二套 UI；
|
||
- 分发：签名安装包 + updater 清单；开发档允许 `devUrl` 指向本地 `next dev`；
|
||
- 交付时点：主链路（M0–M5）完成后的收口阶段（见[重写执行计划](../operations/rewrite-plan.md) M9）。
|
||
|
||
## 三、验收要点
|
||
|
||
| 项 | 验收 |
|
||
| --- | --- |
|
||
| SSE 端到端 | 断网重连后从 `Last-Event-ID` 续流，无丢帧、无重复固化为候答 |
|
||
| 裁剪安全 | 白名单外字段不出现在响应；治理/审计字段不被裁剪 |
|
||
| 镜匣授权 | 未授契能力调用被拒并留痕；硬急停可中断本地执行 |
|
||
| 密钥边界 | 桌面壳与前端零平台密钥；所有请求经照壁 |
|