M0：照壁 BFF 骨架（Fastify 透明代理：鉴权/幂等/续传头透传、SSE 直通、HJ-3001 映射）及测试与镜像

bff/README.md

@@ -0,0 +1,32 @@
+# 照壁 · 魂镜 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)。