33 lines
1.5 KiB
Markdown
33 lines
1.5 KiB
Markdown
# 照壁 · 魂镜 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：
|
||
|
||
```bash
|
||
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 与镜匣桌面壳](../docs/architecture/bff-and-desktop.md)。
|