智谷天厨食材与菜品同步方案

版本：V1.2
日期：2026-09-03
目标系统：康比特智慧营养健康餐厅
最新范围：只拉取食材目录和菜品配方，不对接设备控制

1. 结论

当前对接不需要管理或控制炒菜机器人，只把智谷天厨作为外部菜品与配方数据源：

厂家食材目录 → 康比特食物成分匹配
厂家菜品及原料重量 → 康比特菜品和配方
康比特食物成分营养值 → 重新计算菜品营养

必接3个只读接口：

GET /openapi/v1/materials/custom；
GET /openapi/v1/dishes；
GET /openapi/v1/dishes/details/{dishId}。

首次初始化可选使用GET /openapi/v1/dishes/details批量拉取完整明细，但不作为常规定时接口。

2. 厂家数据能力判断

厂家食材接口只返回食材ID、编号、名称、描述、图片、单位和公有/私有标识，不包含任何营养素数值。因此厂家数据只能帮助建立“菜品用了什么食材、用了多少克”，不能替代康比特食物成分库。

营养数据继续以ydy_foods_composition为真源。厂家食材未唯一匹配时，对应菜品保持阻断状态，不生成营养值全0或错误匹配的菜品。

3. 系统落点

store PC管理端
  食材匹配、菜品同步状态、失败处理
              ↓
ai_api 智谷天厨只读适配层
  签名、分页、字段解析、幂等和同步日志
              ↓
智谷天厨OpenAPI
  食材列表、菜品列表、菜品明细

前端不持有AccessKey或SecretKey。所有厂家访问由服务端完成。

4. 数据表对应

4.1 复用现有表

表	用途
`ydy_foods_composition`	康比特食物成分与营养数据，只读匹配
`ydy_dishes`	康比特菜品主表，通过现有菜品服务新增/更新
`ydy_dish`	菜品食材、重量和比例，通过现有菜品服务维护
`yoshop_dishes`及关联表	继续由现有菜品服务同步，不由适配器直接写

不写ydy_material和库存流水，因为厂家食材目录不是采购库存实物。

4.2 新增表

表	用途
`ydy_tchef_config`	厂家环境、调用身份、加密密钥引用和同步配置
`ydy_tchef_material_map`	厂家食材与`ydy_foods_composition`匹配关系
`ydy_tchef_dish_map`	厂家菜品与`ydy_dishes`关系、基础/明细快照和状态
`ydy_tchef_sync_log`	同步批次、数量、游标和失败原因

完整字段和唯一键见tchef-interface-scope.md和tchef-interface-business-table-map.csv。

5. 同步业务规则

5.1 食材

厂家食材按external_material_id唯一；
已确认映射优先复用；
可用稳定materialNo或标准化后的精确名称寻找候选；
0个候选标记pending，多个候选标记ambiguous；
不做模糊名称自动绑定；
不用全0营养素自动新增食物成分。

5.2 菜品

厂家菜品按external_dish_id唯一；
基础列表发现新增、变化、停用和删除；
新增或变化时查询单条完整明细；
所有必需食材唯一匹配后，调用现有菜品服务写入ydy_dishes + ydy_dish；
由现有逻辑同步AI营养师侧菜品，不直接写yoshop_dishes；
同名本地菜品不自动合并；
厂家停用或删除先停用映射，不自动物理删除本地菜品。

5.3 配方和营养

原料重量统一换算为克；
ydy_dish.foods_weight保存食材重量；
食材比例根据菜品总重量计算；
菜品营养由ydy_foods_composition重新汇总到ydy_dishes；
厂家菜品总重量和原料合计不一致时阻断或告警，不自动篡改。

6. 同步流程

同步食材目录并建立匹配
→ 同步菜品基础列表
→ 找出新增或变化菜品
→ 获取单条菜品明细
→ 解析原料、重量和单位
→ 校验所有食材映射
→ 调用现有菜品服务新增/更新菜品与配方
→ 写同步日志

一个菜品使用一个数据库事务；单个菜品失败不影响其他菜品，但必须保留错误原因。

7. 康比特内部接口

接口	用途
`POST /api/tchef/config/test`	验证签名和只读访问
`POST /api/tchef/sync/materials`	同步厂家食材
`GET /api/tchef/materials`	查询食材匹配状态
`POST /api/tchef/materials/match`	人工确认食材映射
`POST /api/tchef/sync/dishes`	同步菜品与配方
`GET /api/tchef/dishes`	查询同步状态和错误
`POST /api/tchef/dishes/bind`	决定复用已有菜品或新增
`GET /api/tchef/sync/logs`	查询同步批次

8. 明确不做

不查询或控制炒菜机器人；
不下发烹饪、暂停、出菜、洗锅等指令；
不接烹饪日志Webhook；
不同步厂家组织、门店、设备、用户和权限；
不向厂家新增或修改菜谱、食材和调料；
不根据厂家数据自动扣库存；
不使用厂家食材描述冒充营养成分。

9. 待确认问题

“食物成分”是指厂家食材及菜品配方，还是必须取得营养素数值；当前厂家接口不提供营养素。
顶层materialList和programList[].materialList哪一份是最终配方真源，是否重复。
materialNo是否稳定且唯一。
菜品列表是否支持按更新时间增量拉取。
厂家停用/删除后，本地菜品采用停用还是只解除映射。
厂家分类、味型、烹饪方式与康比特字段映射规则。
签名app_key/app-key和时间戳秒/毫秒仍需厂家Golden Test。

10. 验收标准

食材和菜品分页完整、重复同步幂等；
未匹配食材不会生成错误营养菜品；
原料重量、比例和菜品营养计算正确；
菜品新增、更新、停用状态可追溯；
单条失败可重试且不影响整批；
现有菜品管理、营养计算、菜单和AI营养师同步回归通过；
密钥不进入前端、日志和Git。