hunjing/docs/architecture/bff-and-desktop.md

照壁 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. 请求链路

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. 能力与授权映射

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）完成后的收口阶段（见重写执行计划 M9）。

三、验收要点

项	验收
SSE 端到端	断网重连后从 Last-Event-ID 续流，无丢帧、无重复固化为候答
裁剪安全	白名单外字段不出现在响应；治理/审计字段不被裁剪
镜匣授权	未授契能力调用被拒并留痕；硬急停可中断本地执行
密钥边界	桌面壳与前端零平台密钥；所有请求经照壁