Files

照壁 · 魂镜 BFF(hunjing-bff)

文化命名「照壁」(契约词典 §2.1):入门第一重——鉴权透传、SSE/WebSocket 代理、响应透传与类型桥接。照壁无状态、无业务规则、无权威数据;"能否看到"的语义一律来自灵台(service-boundaries.md §3)。

职责(rewrite/1.0 M0 骨架)

  • ALL /api/* → 灵台透明代理:透传 Authorization / Idempotency-Key / Last-Event-ID / X-Trace-Id;
  • SSE 流式直通:检测 text/event-stream 后 hijack 连接,逐块转发并设置 X-Accel-Buffering: no;
  • 请求体按原始字节透传(任意 Content-Type,含 multipart);
  • 上游不可达映射 HJ-3001(API 契约 §5 错误结构);
  • GET /healthz 本地健康检查。

运行

统一经根目录 Makefile:

make dev-bff          # 开发(tsx watch,:3000)
make test-bff         # vitest
make typecheck-bff    # tsc --noEmit
# 首次进入 bff/ 需 npm install;环境变量默认值见 src/config.ts

环境变量:BFF_PORT(默认 3000)、BACKEND_URL(默认 http://127.0.0.1:8000)、BFF_BODY_LIMIT、BFF_LOG_LEVEL。

约束

  • 代理超时须大于灵台同类超时,避免照壁先掐断 SSE 流;
  • 不得在此层添加权限判断或业务裁剪逻辑(响应字段白名单按 rewrite-plan M2+ 需要再引入);
  • 日志不落请求体敏感原文。

设计依据:照壁 BFF 与镜匣桌面壳。