# 子模块：Integration（FastAPI API + Celery Worker）｜Spec

## 1. 目标描述

将推荐引擎对外暴露为两种调用方式，满足“API 与任务两者都需要”的集成要求：

- **FastAPI**：同步请求/响应式获取推荐结果（客户端直接请求）。
- **Celery**：后台任务式生成推荐（用于 Push/Widget 的定时或批处理）。

两种方式都必须调用同一套 `Reco Engine`，确保行为一致、便于回归测试。

---

## 2. 输入 / 输出定义

### 2.1 API 输入（HTTP Request）

- `scene`: `feed | push | widget`
- `k`（可选；默认按场景）
- `user_profile`（客户端问卷画像，V1.2）
- `already_recommended_ids`（数组）
- `touched_or_viewed_ids`（数组）
- （可选）`now`（用于可测试性；生产可不传，由服务端生成）

### 2.2 API 输出（HTTP Response）

- `items`: 推荐句子列表
- `meta`: RecoMeta（候选规模、回退层级、empty_reason 等）

### 2.3 Celery 任务输入/输出

任务输入与 API 输入等价，但建议仅传必要字段并保持 payload 小（避免 Redis 膨胀）：

- 允许只传 `user_profile` 与历史集合；若历史集合很大，建议传引用 ID（后续演进）。

任务输出：

- 可选择“不存结果”（默认忽略结果）并在任务内部将推荐结果写入下游（如消息队列/推送系统/DB）。
- 或返回 `items/meta`（仅用于开发调试）。

---

## 3. 关键约束

- API 与 Celery **不得复制推荐逻辑**：只能调用 `Reco Engine`。
- 输入合法性：
  - 不因字段缺失而报错（画像允许缺失/跳过）。
  - `already_recommended_ids/touched_or_viewed_ids` 允许为空数组。
- 可测试性：
  - 允许注入 `now`（或在 header/参数中提供），便于确定性测试。

---

## 4. 验收标准（可验证）

- **API 可用**：给定合法请求体可返回推荐结果与 meta。
- **任务可用**：Celery worker 能消费任务并成功调用推荐引擎（至少跑通 ping → reco 的调用链）。
- **一致性**：相同输入下，API 与任务调用返回结果一致（忽略时间戳字段差异时）。

