hunjing/bff

照壁 · 魂镜 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 与镜匣桌面壳。