fix:更新算法

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

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