0 Fork 0

Files

T

chenxin 2483a25f63 M9：桌面壳与收口——镜匣最小壳、器谱登记、发布证据落位、重写计划功成身退

- 镜匣 desktop/（Tauri v2 最小壳）：WebView 承载琉璃镜（frontend/out 或 devUrl）；能力桥最小命令（通知）；乾坤通道 HMAC 短期凭证构造（与 sandbox/src/auth.rs 验签同算法，密钥仅经 SANDBOX_AUTH_SECRET 环境注入——二进制零平台密钥，静态审计钉死）；hard_stop/resume 本地硬急停原子断路（全部通道命令过 ensure_not_halted，本地最高优先级不经云端）；tantivy 依赖与 capabilities/ 目录预留；updater 插件位预留；cargo check 通过
- 器谱域 domains/tianzai（迁移 010）：devices/device_grants——一次配对（密钥指纹登记）、逐项授契（可授面显式枚举，未知能力键拒）、撤回立即生效、设备撤销连带全部授契失效且不可再授；/devices 器谱 API 组
- 发布收口：release-evidence.md 落位重写期 RW-* 证据包（M0–M9 十里程碑验收自动化套件与结果物）；能力矩阵 M9 行收官；rewrite-plan.md 按计划删除（M0–M9 全部完成，能力矩阵与证据台账接棒），全库引用清理
- 验收（test_m9_jingxia 四用例）：器谱未授契 403 留痕/撤回即效/设备撤销连带；镜匣零平台密钥（rg 审计源码与配置为空）；硬急停语义钉死（通道命令全检查+resume 唯一恢复+HMAC 无密钥不出凭证）
- 五套件终检全绿：后端 349、前端 203、BFF 4、神识 5 包、镜匣 cargo check（2 个预存环境失败历次 HEAD 复验与本周期无关）；Compose nginx profile 配置校验通过

2026-08-28 09:35:27 +08:00

4.4 KiB

Raw Permalink Blame History

照壁 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 只交付最小桌面壳：

WebView 承载琉璃镜：加载本地打包的前端或指向自托管部署地址；登录与全部功能即 Web 功能；
本地能力桥：文件对话框、系统通知、托盘常驻、开机自启（可选）；
乾坤本地执行通道：桌面端可连接本地/局域乾坤沙箱，作为该镜域器谱中的一台设备（须在器谱登记并经人物授契后才可用）；
tantivy 本地检索（预留）：为本地文件索引预留接口与能力声明，1.0 不实现索引构建；
自动更新：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` 续流，无丢帧、无重复固化为候答
裁剪安全	白名单外字段不出现在响应；治理/审计字段不被裁剪
镜匣授权	未授契能力调用被拒并留痕；硬急停可中断本地执行
密钥边界	桌面壳与前端零平台密钥；所有请求经照壁

4.4 KiB Raw Permalink Blame History Unescape Escape