mindfulness/spec_kit/Personalized Reco/modules/integration-api-worker/spec.md

子模块：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 与任务调用返回结果一致（忽略时间戳字段差异时）。