# 照壁 · 魂镜 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` 本地健康检查。

## 运行

```bash
npm install
npm run dev          # 开发（tsx watch）
BACKEND_URL=http://127.0.0.1:8000 BFF_PORT=3000 npm start

npm test             # vitest
npm run type-check
```

环境变量：`BFF_PORT`（默认 3000）、`BACKEND_URL`（默认 http://127.0.0.1:8000）、`BFF_BODY_LIMIT`、`BFF_LOG_LEVEL`。

## 约束

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

设计依据：[照壁 BFF 与镜匣桌面壳](../docs/architecture/bff-and-desktop.md)。