智谷天厨食材与菜品只读同步接口范围
- 版本：V2.0
- 日期：2026-09-03
- 最新业务范围：只从智谷天厨拉取食材和菜品，不控制炒菜机器人
1. 结论
按最新确认，康比特只需要同步厂家食材目录、菜品基础信息和菜品配方明细。接口范围收敛为：
| 类型 | 数量 | 说明 |
|---|---|---|
| 必接 | 3 | 食材列表、菜品列表、单条菜品明细 |
| 可选 | 1 | 首次初始化时批量查询菜品明细 |
| 不接 | 其余接口 | 组织、门店、设备、控制指令、Webhook、日志、统计、写接口 |
厂家食材目录
→ 匹配康比特食物成分库
→ 厂家菜品及原料重量
→ 生成/更新康比特菜品和配方
→ 使用康比特营养成分重新计算菜品营养
2. 必须先纠正一个概念
厂家GET /openapi/v1/materials/custom返回的是“食材目录”，字段包括食材ID、编号、名称、描述、图片、单位和公有/私有标识。
该接口不返回：能量、蛋白质、脂肪、碳水化合物、膳食纤维、维生素、矿物质等营养数据。因此：
- 厂家食材不能直接新增成完整的
ydy_foods_composition记录； - 厂家食材要先匹配康比特已有食物成分；
- 菜品营养值由康比特根据食物成分和原料重量计算；
- 未匹配食材不能用全0营养值自动创建，否则会污染营养分析。
如果业务所说“拉取食物成分”是指拉取营养素数值，厂家当前文档没有提供对应接口；需要厂家另行提供营养成分接口或数据文件。
3. 需要对接的厂家接口
3.1 食材列表
GET /openapi/v1/materials/custom
用途：同步厂家公共食材和公司自定义食材。主要字段为id/materialNo/materialName/materialDesc/picBig/picSmall/unit/isPrivate。分页拉取全部数据，按厂家食材ID幂等更新。
3.2 菜品基础列表
GET /openapi/v1/dishes
用途：分页同步厂家菜品目录，识别新增、修改、停用和删除状态。主要字段为id/dishCode/dishName/dishNameEnglish/dishDesc/weight/unit/picBig/picSmall/dishStatus/isDel/deviceModelId/updateTime。
只同步基础信息，不直接生成配方。按external_dish_id判断同一厂家菜品，不能只按菜名判断。
3.3 单条菜品明细
GET /openapi/v1/dishes/details/{dishId}
用途：对新增或变化的菜品拉取完整明细。
materialList：备菜原料、重量、单位和处理形态；programList[].materialList：每个烹饪步骤中的原料及重量；techList：工艺说明，只保留为外部快照；dishLabels/category/taste/deviceModel：外部分类与机型信息，只用于追溯和映射。
原料可能同时出现在顶层materialList和programList[].materialList。正式开发前必须确定哪一层是配方重量真源，不能简单相加造成重复。
3.4 首次初始化可选接口
GET /openapi/v1/dishes/details
该接口分页返回完整菜品明细，但厂家明确提示耗时较长。首次数据量较小且厂家确认性能可接受时可以使用；常规定时同步使用菜品基础列表，对新增或updateTime变化的数据逐条查询明细。
4. 接口、业务和数据表对应
| 厂家接口 | 康比特业务 | 读取现有表 | 写入现有表 | 新增表 | 关键规则 |
|---|---|---|---|---|---|
GET /materials/custom |
厂家食材匹配康比特食物成分 | ydy_foods_composition |
无 | ydy_tchef_material_map |
厂家ID唯一；匹配成功后关联foods_composition_id |
GET /dishes |
同步厂家菜品目录和状态 | ydy_dishes |
匹配确认后通过现有菜品服务写ydy_dishes |
ydy_tchef_dish_map |
store_id + external_dish_id唯一 |
GET /dishes/details/{dishId} |
生成菜品食材配方和营养 | ydy_foods_composition、ydy_dishes、ydy_dish |
通过现有菜品服务写ydy_dishes + ydy_dish |
两张映射表保存外部快照 | 所有食材匹配后才发布菜品 |
GET /dishes/details |
首次全量导入 | 同上 | 同上 | 同上 | 低频分页，可选 |
所有路径实际带/openapi/v1前缀，表中为便于阅读省略。
5. 现有表职责
| 表 | 用途 | 同步规则 |
|---|---|---|
ydy_foods_composition |
康比特食物成分和营养数据真源 | 只匹配、只读；厂家没有营养值时不自动新增 |
ydy_dishes |
康比特菜品主表 | 通过现有菜品服务新增或更新 |
ydy_dish |
菜品与食物成分关系、食材重量和比例 | 菜品明细完整匹配后随菜品事务更新 |
yoshop_dishes及关联表 |
AI营养师侧菜品 | 继续由现有菜品服务同步，不由智谷适配器直接写 |
不写入ydy_material和库存流水。ydy_material属于采购库存物料，厂家食材目录和机器人配方不能自动视为库存实物。
6. 建议新增4张表
6.1 ydy_tchef_config
保存store_id、测试/正式环境、co_id、调用mobile、加密密钥引用、同步开关和同步时间。密钥不能明文入库。
6.2 ydy_tchef_material_map
保存厂家食材ID/编号/名称、公私属性、匹配的foods_composition_id、匹配状态和原始快照。match_status使用pending/matched/ambiguous/rejected，唯一键为store_id + external_material_id。
6.3 ydy_tchef_dish_map
保存厂家菜品ID/编码/名称/状态、关联的dishes_id/dishes_uuid、重量、机型、同步状态、基础和明细快照。唯一键为store_id + external_dish_id。
6.4 ydy_tchef_sync_log
保存每次同步类型、开始/结束时间、分页数、新增/更新/跳过/失败数量、错误摘要和游标，用于排查定时同步和失败重试。
7. 数据匹配和写入规则
7.1 食材匹配
- 已有
external_material_id映射，直接复用； - 厂家
materialNo存在稳定映射时使用编号； - 标准化名称后在
ydy_foods_composition中精确匹配； - 0个候选标记
pending，多个候选标记ambiguous； - 未唯一匹配前不写菜品配方。
不得做模糊匹配后自动落库，也不得创建营养值全0的新食物成分。
7.2 菜品新增与更新
- 使用
external_dish_id识别厂家同一菜品； - 第一次同步时，如果未绑定本地菜品，先进入
pending； - 所有必需食材唯一匹配、重量和单位有效后，调用现有菜品服务新增
ydy_dishes和ydy_dish； - 已有关联时按厂家
updateTime/payload_hash判断是否更新； - 同名本地菜品不能自动合并；
- 厂家停用或删除时先禁用映射，不自动物理删除康比特菜品。
7.3 重量和营养计算
- 厂家重量统一转换为克；
ydy_dish.foods_weight保存各食材克数；- 比例根据菜品总重量重新计算；
- 菜品能量和营养素由
ydy_foods_composition计算并写入ydy_dishes； - 厂家菜品总重量与食材重量合计不一致时标记异常，不自动修正。
8. 同步流程
定时/人工触发
→ 拉取厂家食材列表并更新映射
→ 拉取菜品基础列表
→ 找出新增或变化的菜品
→ 拉取单条菜品明细
→ 校验原料、重量、单位和食材映射
→ 全部匹配：调用现有菜品服务写入菜品和配方并计算营养
→ 未全部匹配：保持blocked，不产生不完整菜品
→ 写同步日志
单个菜品在一个数据库事务内更新ydy_dishes和ydy_dish；一个菜品失败不影响其他菜品继续同步，但必须记录失败原因。
9. 康比特内部接口建议
| 接口 | 用途 |
|---|---|
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 |
查看同步批次和失败记录 |
这些接口仅供PC管理端授权角色使用。前端不持有厂家密钥，也不直接请求厂家接口。
10. 不再对接
- 组织、门店、用户和角色接口；
- 机型、设备及设备转移接口；
POST /devices/commands及全部控制指令；- 烹饪日志Webhook和日志统计接口；
- 菜谱新增、修改、删除、复制、恢复和门店分配接口；
- 调料、食材写接口和文件上传接口。
11. 开发前待确认
- “食物成分”是否确定指厂家食材/配方，而不是要求厂家提供营养素数值。
- 顶层
materialList和programList[].materialList哪一份是配方重量真源，二者是否可能重复。 - 厂家食材
materialNo是否稳定且全局唯一。 - 菜品基础列表是否保证返回
updateTime，是否支持增量更新时间筛选。 - 厂家停用/删除菜品后，康比特应停用同步菜品还是只解除映射。
- 厂家分类、味型、烹饪方式与康比特字段如何映射；未配置时菜品保持待处理。
- 当前签名中的
app_key/app-key和秒/毫秒问题仍需Golden Test确认。
12. 验收标准
- 食材分页无遗漏，重复同步不产生重复映射；
- 同名不同ID、同ID改名、公有/私有食材均正确处理；
- 未匹配或多候选食材不会生成营养值错误的菜品；
- 菜品新增、更新、停用和删除状态可追溯；
- 配方重量、单位和营养计算正确；
- 同一厂家菜品重复同步只更新同一个本地菜品；
- 单菜品失败不影响其他菜品，同步日志可定位原因；
- 现有菜品新增/编辑、营养计算、菜单和AI营养师同步回归通过。
13. 证据边界
- 厂家食材接口不提供营养素字段是当前文档已确认事实。
ydy_foods_composition/ydy_dishes/ydy_dish职责来自当前系统表结构和菜品服务代码。- 4张
tchef表是方案建议，当前数据库尚未创建。 - 本方案是只读数据同步范围，不代表签名接口已经联调成功。