feat(api): 增加当日烹饪任务列表新接口及相关数据模型支持

- 新增 CookOrderPageRequest、CookOrderMealGroup、CookOrderItem 等数据模型定义
- 在 ApiService 添加 getCookOrderPage 新接口，支持按餐次分组查询烹饪任务
- RemoteRepository 新增对应接口调用封装 getCookOrderPage
- NetViewModel 新增 cookOrderPageState 状态流及接口调用方法
- FoodListFragment 使用新接口替换旧搜索菜品接口，调整数据合并与展示逻辑
- FoodSearchActivity 使用新接口查询烹饪任务，并适配结果展示
- 更新请求拦截器添加 X-DEVICE-TOKEN 请求头支持设备登录Token传递
- 修改 GlobalData 默认基础URL为预发布环境地址
- 修正 ScaleDeviceConfig 中测试设备ID常量值
- SettingActivity 恢复环境切换入口显示，方便环境切换测试
- 补充配比秤-制作菜品新API接口完整文档，详细描述接口请求响应及业务逻辑

app/src/main/java/com/shuwei/dish/match/base/GlobalData.kt

@@ -8,13 +8,13 @@ package com.shuwei.dish.match.base
 enum class DeviceRole { MASTER, SLAVE }
 
 object GlobalData {
-    var appBaseUrl: String = TEST_BASE_URL
+    var appBaseUrl: String = UAT_BASE_URL
 
     /**
      * 具体业务 BaseUrl
      */
-    const val TEST_BASE_URL = "http://192.168.1.201:14801"
+    const val TEST_BASE_URL = "http://192.168.10.101:24801"
-    const val UAT_BASE_URL = "https://dev.yixiong-tech.com:8083"
+    const val UAT_BASE_URL = "https://dev.yixiong-tech.com:8081"
     const val PROD_BASE_URL = "https://api.dm.yixiong-tech.com:8443"
     /**
      * 设备id

app/src/main/java/com/shuwei/dish/match/model/CookOrderModels.kt

@@ -0,0 +1,59 @@
+package com.shuwei.dish.match.model
+
+/**
+ * 当日烹饪任务列表（按餐次分组）请求参数
+ * 对应接口: POST /neglect/ratio-scale/cook-orders/page
+ */
+data class CookOrderPageRequest(
+    /** 计划日期 yyyy-MM-dd，默认当天 */
+    val date: String? = null,
+    /** 餐次筛选: 1=早餐 / 2=午餐 / 3=晚餐 / 4=加餐，不传返回全部 */
+    val mealType: Int? = null,
+    /** 菜品名称模糊搜索 */
+    val keyword: String? = null,
+    /** 保留字段，当前不使用 */
+    val pageNum: Int? = null,
+    /** 保留字段，当前不使用 */
+    val pageSize: Int? = null
+)
+
+/**
+ * 餐次分组，包含该餐次下的烹制单列表
+ */
+data class CookOrderMealGroup(
+    /** 餐次: 1=早餐 / 2=午餐 / 3=晚餐 / 4=加餐 */
+    val mealType: Int = 0,
+    /** 餐次中文名称 */
+    val mealTypeName: String = "",
+    /** 该餐次下的烹制单列表 */
+    val cookOrders: List<CookOrderItem> = emptyList()
+)
+
+/**
+ * 单个烹制单，对应接口响应中 cookOrders 数组的条目
+ * 注意: Long 类型字段服务端序列化为 String
+ */
+data class CookOrderItem(
+    /** 烹制单id（Long → String） */
+    val cookOrderId: String = "",
+    /** 烹制单号 */
+    val cookNo: String = "",
+    /** 菜品名称 */
+    val dishName: String = "",
+    /** 菜品id（关联 nut_food） */
+    val foodId: String = "",
+    /** 餐次: 1=早餐 / 2=午餐 / 3=晚餐 / 4=加餐 */
+    val mealType: Int = 0,
+    /** 餐次中文名称 */
+    val mealTypeName: String = "",
+    /** 烹制状态: 0=待烹制 / 1=烹制中 / 2=已完成 / 3=异常 */
+    val cookStatus: Int = 0,
+    /** 烹制状态中文 */
+    val cookStatusName: String = "",
+    /** 生重(kg)，烹制完成后才有值 */
+    val rawWeight: Double? = null,
+    /** 需求份数 */
+    val needPortions: Int = 0,
+    /** 烹制份数，烹制完成后才有值 */
+    val cookedPortions: Int? = null
+)

app/src/main/java/com/shuwei/dish/match/net/ApiService.kt

@@ -2,6 +2,8 @@ package com.shuwei.dish.match.net
 
 import com.shuwei.dish.match.base.GlobalData
 import com.shuwei.dish.match.model.CookFoodDTO
+import com.shuwei.dish.match.model.CookOrderMealGroup
+import com.shuwei.dish.match.model.CookOrderPageRequest
 import com.shuwei.dish.match.model.FoodRecord
 import com.shuwei.dish.match.model.GoodsItem
 import okhttp3.MultipartBody
@@ -37,7 +39,16 @@ interface ApiService {
     ): ApiResponse<Any?>
 
     /**
-     * 搜索菜品
+     * 查询当日烹饪任务列表（按餐次分组），新配比秤接口
+     */
+    @POST
+    suspend fun getCookOrderPage(
+        @Url url: String = "${GlobalData.appBaseUrl}/nutrition/neglect/ratio-scale/cook-orders/list",
+        @Body request: CookOrderPageRequest
+    ): ApiResponse<List<CookOrderMealGroup>?>
+
+    /**
+     * 搜索菜品（旧接口，采样模式仍在使用）
      */
     @POST
     suspend fun searchFoodList(

app/src/main/java/com/shuwei/dish/match/net/NetViewModel.kt

@@ -4,6 +4,8 @@ import androidx.lifecycle.ViewModel
 import androidx.lifecycle.viewModelScope
 import com.shuwei.dish.match.base.BaseApp
 import com.shuwei.dish.match.model.CookFoodDTO
+import com.shuwei.dish.match.model.CookOrderMealGroup
+import com.shuwei.dish.match.model.CookOrderPageRequest
 import com.shuwei.dish.match.model.FoodRecord
 import com.shuwei.dish.match.model.GoodsItem
 import com.shuwei.dish.match.model.GoodsNameQueryDTO
@@ -104,6 +106,42 @@ class NetViewModel(
         }
     }
 
+    /**
+     * 当日烹饪任务列表的 UI 状态流（新配比秤接口），UI 层通过 collect 监听
+     * 使用 SharedFlow(replay=1) 保证 Fragment 重建后收到最近一次结果
+     */
+    private val _cookOrderPageState = MutableSharedFlow<UiState<List<CookOrderMealGroup>?>>(
+        replay = 1,
+        extraBufferCapacity = 1
+    )
+    val cookOrderPageState: SharedFlow<UiState<List<CookOrderMealGroup>?>> = _cookOrderPageState.asSharedFlow()
+
+    /**
+     * 查询当日烹饪任务列表（新配比秤接口，StateFlow 版本）
+     * 适合 FoodSearchActivity 等通过 collect 监听结果的场景
+     */
+    fun getCookOrderPage(request: CookOrderPageRequest) {
+        viewModelScope.launch {
+            _cookOrderPageState.emit(UiState.Loading)
+            _cookOrderPageState.emit(repository.getCookOrderPage(request))
+        }
+    }
+
+    /**
+     * 查询当日烹饪任务列表（新配比秤接口，回调版本）
+     * 适合 FoodListFragment 下拉刷新、Tab 切换等需要每次都能触发的场景
+     */
+    fun getCookOrderPageWithCallback(
+        request: CookOrderPageRequest,
+        onLoading: () -> Unit = {},
+        onResult: (UiState<List<CookOrderMealGroup>?>) -> Unit
+    ) {
+        viewModelScope.launch {
+            onLoading()
+            onResult(repository.getCookOrderPage(request))
+        }
+    }
+
     /**
      */
     private val _samplingListState = MutableStateFlow<UiState<MutableList<FoodRecord>?>>(UiState.Idle)

app/src/main/java/com/shuwei/dish/match/net/RemoteRepository.kt

@@ -1,6 +1,8 @@
 package com.shuwei.dish.match.net
 
 import com.shuwei.dish.match.model.CookFoodDTO
+import com.shuwei.dish.match.model.CookOrderMealGroup
+import com.shuwei.dish.match.model.CookOrderPageRequest
 import com.shuwei.dish.match.model.FoodRecord
 import com.shuwei.dish.match.model.GoodsItem
 import okhttp3.MultipartBody
@@ -31,6 +33,10 @@ class RemoteRepository {
     suspend fun getFoodDetail(foodId: String): UiState<CookFoodDTO?> =
         safeApiCall { apiService.getFoodDetail(foodId = foodId) }
 
+    /** 查询当日烹饪任务列表（按餐次分组），新配比秤接口 */
+    suspend fun getCookOrderPage(request: CookOrderPageRequest): UiState<List<CookOrderMealGroup>?> =
+        safeApiCall { apiService.getCookOrderPage(request = request) }
+
     /** 搜索菜品列表 */
     suspend fun searchFoodList(param: MutableMap<String, Any>): UiState<MutableList<FoodRecord>?> =
         safeApiCall { apiService.searchFoodList(param = param) }

app/src/main/java/com/shuwei/dish/match/net/RequestInterceptor.kt

@@ -13,6 +13,7 @@ class RequestInterceptor : Interceptor {
         val requestBuilder = originalRequest.newBuilder()
             .header("X-Access-Token", "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjYW50ZWVuSWQiOiJiZTE1NDgzMS0zNDY2LTNiYTItYTJlYS01NzY1MmM5MTlmZWQiLCJ0eXBlIjoiNCIsInVzZXJJZCI6IjAwMDAwMDAwMDAwMDAwMDAwMDEifQ.sN40cOC-O5WQFrF4IDUs8fFlkNdUKLbJt_rHyTsgYYM")
             .header("X-DEVICE-CODE", GlobalData.deviceId)
+            .header("X-DEVICE-TOKEN", GlobalData.deviceId)
             .header("authorization", "57ee87183f2a4fa59683ec9ef41c8f5d")
 
         val newRequest = requestBuilder.build()

app/src/main/java/com/shuwei/dish/match/scale/ScaleDeviceConfig.kt

@@ -6,7 +6,7 @@ package com.shuwei.dish.match.scale
  */
 object ScaleDeviceConfig {
 
-    const val DEVICE_ID_2  = "8fc2ab34-2137-3112-acca-f884ea8736d4"
+    const val DEVICE_ID_2  = "0bd74d78-c221-3182-b5ee-55d86dd79283"//测试0bd74d78-c221-3182-b5ee-55d86dd79283    正式8fc2ab34-2137-3112-acca-f884ea8736d4
     const val DEVICE_ID_22 = "a46fa55c-113c-3511-bb1f-41e5eff77c4b"
     const val DEVICE_ID_18 = "1038da9f-c6eb-326e-a1d9-d6d3af978b22"
     const val DEVICE_ID_1  = "7cc0f6ea-f13d-3013-a867-fc998eb554ac"

app/src/main/java/com/shuwei/dish/match/ui/FoodSearchActivity.kt

@@ -14,6 +14,9 @@ import com.shuwei.dish.match.base.BaseActivity
 import com.shuwei.dish.match.base.BaseApp
 import com.shuwei.dish.match.databinding.ActivityFoodSearchBinding
 import com.shuwei.dish.match.databinding.LayoutEmptyViewBinding
+import com.shuwei.dish.match.model.CookOrderItem
+import com.shuwei.dish.match.model.CookOrderMealGroup
+import com.shuwei.dish.match.model.CookOrderPageRequest
 import com.shuwei.dish.match.model.FoodRecord
 import com.shuwei.dish.match.net.UiState
 import com.shuwei.dish.match.utils.KeyboardUtil
@@ -95,12 +98,12 @@ class FoodSearchActivity : BaseActivity() {
     }
 
     /**
-     * 收集 searchFoodState，统一处理 Loading / Success / Error 状态
+     * 收集 cookOrderPageState，统一处理 Loading / Success / Error 状态
      */
     private fun initObserver() {
         lifecycleScope.launch {
             repeatOnLifecycle(Lifecycle.State.STARTED) {
-                netViewModel.searchFoodState.collect { state ->
+                netViewModel.cookOrderPageState.collect { state ->
                     when (state) {
                         is UiState.Loading -> showLoading()
                         is UiState.Success -> handleSearchResult(state.data)
@@ -109,7 +112,7 @@ class FoodSearchActivity : BaseActivity() {
                             finishRefresh()
                             binding.refreshLayout.setEnableRefresh(true)
                             toast(state.msg)
-                            if (pageNo == 1) loadEmptyView()
+                            loadEmptyView()
                         }
                         is UiState.Idle -> {}
                     }
@@ -173,42 +176,53 @@ class FoodSearchActivity : BaseActivity() {
 
     @SuppressLint("NotifyDataSetChanged")
     private fun queryListInfo(input: String) {
-        val map = mutableMapOf<String, Any>(
+        val request = CookOrderPageRequest(
-            "foodName" to input.trim(),
+            mealType = dinnerType.toIntOrNull(),
-            "pageNum" to pageNo,
+            keyword = input.trim()
-            "pageSize" to pageSize,
-            "placeId" to BaseApp.canteenId,
-            "dinnerType" to getDinnerTypeText()
         )
-        netViewModel.searchFoodList(param = map)
+        netViewModel.getCookOrderPage(request = request)
     }
 
     /**
-     * 处理搜索结果，填充列表或展示空视图
+     * 将 CookOrderItem 映射为 FoodRecord，适配现有 Adapter
+     */
+    private fun CookOrderItem.toFoodRecord(): FoodRecord {
+        return FoodRecord(
+            foodId = foodId,
+            foodName = dishName,
+            totalWeight = ((rawWeight ?: 0.0) * 1000),
+            cookMode = 0,
+            isCooking = cookStatus == 1,
+            dinnerType = mealType.toString(),
+            isOriginalData = true
+        )
+    }
+
+    /**
+     * 处理搜索结果：从分组响应中 flatten 所有 cookOrders，映射为 FoodRecord 后填充列表
      */
     @SuppressLint("NotifyDataSetChanged")
-    private fun handleSearchResult(records: MutableList<FoodRecord>?) {
+    private fun handleSearchResult(groups: List<CookOrderMealGroup>?) {
         delayDismissLoading()
         finishRefresh()
         binding.refreshLayout.setEnableRefresh(true)
+        val records = groups
+            ?.flatMap { it.cookOrders }
+            ?.map { it.toFoodRecord() }
+            ?.toMutableList()
         if (records.isNullOrEmpty()) {
-            if (pageNo == 1) loadEmptyView()
+            loadEmptyView()
             return
         }
-        if (pageNo == 1) list.clear()
+        list.clear()
         list.addAll(records)
         recordAdapter.notifyDataSetChanged()
-        val isLoadMoreEnable = records.size >= pageSize
+        // 新接口暂不分页，禁用加载更多
-        binding.refreshLayout.setEnableLoadMore(isLoadMoreEnable)
+        binding.refreshLayout.setEnableLoadMore(false)
-        if (isLoadMoreEnable) pageNo++
     }
 
     private fun finishRefresh() {
-        if (pageNo == 1) {
         binding.refreshLayout.finishRefresh(1200)
-        } else {
-            binding.refreshLayout.finishLoadMore(1200)
-        }
     }
 
     private var emptyViewBinding: LayoutEmptyViewBinding? = null

app/src/main/java/com/shuwei/dish/match/ui/SettingActivity.kt

@@ -123,7 +123,6 @@ class SettingActivity : BaseActivity() {
         SettingItem(
             type = SettingItem.Type.ENV_SWITCH,
             title = "切换环境",
-            isHidden = true,
             onClick = { EnvSwitchDialog(this).show() }
         ),
         SettingItem(

app/src/main/java/com/shuwei/dish/match/ui/fragment/FoodListFragment.kt

@@ -17,6 +17,9 @@ import com.shuwei.dish.match.databinding.FragmentFoodListBinding
 import com.shuwei.dish.match.databinding.LayoutEmptyViewBinding
 import com.shuwei.dish.match.dialog.CommonDialog
 import com.shuwei.dish.match.db.entity.CookFoodEntity
+import com.shuwei.dish.match.model.CookOrderItem
+import com.shuwei.dish.match.model.CookOrderMealGroup
+import com.shuwei.dish.match.model.CookOrderPageRequest
 import com.shuwei.dish.match.model.FoodRecord
 import com.shuwei.dish.match.net.UiState
 import com.shuwei.dish.match.ui.CookingModeActivity
@@ -64,6 +67,9 @@ class FoodListFragment : BaseFragment<FragmentFoodListBinding>() {
 
     private lateinit var activity: CookingModeActivity
 
+    /** 首次加载标记，首次请求时传 mealType=null 获取全餐次数据，后续切换传具体餐次 */
+    private var isFirstLoad = true
+
     /** 第一页时先查数据库存入此字段，网络结果回来后直接使用，避免时序问题 */
     private var pendingLocalList: MutableList<CookFoodEntity>? = null
 
@@ -212,42 +218,41 @@ class FoodListFragment : BaseFragment<FragmentFoodListBinding>() {
         currentFoodName = foodName
         currentJob?.cancel()
         currentJob = viewLifecycleOwner.lifecycleScope.launch {
-            val param = mutableMapOf<String, Any>(
+            // 首次加载传 mealType=null 获取所有餐次，切换 Tab 时传当前餐次精确请求
-                "pageNum" to pageNo,
+            val mealType = if (isFirstLoad) null else dinnerType.toIntOrNull()
-                "pageSize" to pageSize,
+            val request = CookOrderPageRequest(
-                "placeId" to BaseApp.canteenId,
+                mealType = mealType,
-                "dinnerType" to getDinnerTypeText()
+                keyword = foodName
             )
-            foodName?.let { param["foodName"] = it }
             if (pageNo == 1) {
                 pendingLocalList = activity.dbViewModel.getCookFoodListDirect(
                     cookMode = 0,
                     dinnerType = dinnerType
                 )
             }
-            val localList = if (pageNo == 1) pendingLocalList else null
+            val localList = pendingLocalList
-            netViewModel.searchFoodListWithCallback(
+            netViewModel.getCookOrderPageWithCallback(
-                param = param,
+                request = request,
                 onLoading = { activity.showLoading(timeoutMs = 35_000L) }
             ) { result ->
                 when (result) {
                     is UiState.Success -> {
-                        if (isAdded.not()) return@searchFoodListWithCallback
+                        if (isAdded.not()) return@getCookOrderPageWithCallback
                         Log.d(TAG, "getDishList, UiState.Success")
+                        isFirstLoad = false
                         activity.delayDismissLoading()
                         finishRefresh()
-                        loadAndMergeDishList(result.data, localList)
+                        loadAndMergeCookOrders(result.data, localList)
                     }
                     is UiState.Error -> {
-                        if (isAdded.not()) return@searchFoodListWithCallback
+                        if (isAdded.not()) return@getCookOrderPageWithCallback
                         Log.d(TAG, "getDishList, UiState.Error")
+                        isFirstLoad = false
                         toast(result.msg)
                         finishRefresh()
                         activity.delayDismissLoading()
-                        if (pageNo == 1) {
                         if (localList.isNullOrEmpty()) loadEmptyView()
-                            else loadAndMergeDishList(null, localList)
+                        else loadAndMergeCookOrders(null, localList)
-                        }
                     }
                     else -> {}
                 }
@@ -287,36 +292,56 @@ class FoodListFragment : BaseFragment<FragmentFoodListBinding>() {
     }
 
     private fun finishRefresh() {
-        if (pageNo == 1) {
         binding.refreshLayout.finishRefresh(1200)
-        } else {
-            binding.refreshLayout.finishLoadMore(1200)
-        }
     }
 
     /**
-     * 将网络数据与本地烹饪中数据合并后渲染列表
+     * 将 CookOrderItem 映射为 FoodRecord，适配现有 Adapter
+     * rawWeight 单位 kg → totalWeight 单位 g
+     */
+    private fun CookOrderItem.toFoodRecord(): FoodRecord {
+        return FoodRecord(
+            foodId = foodId,
+            foodName = dishName,
+            totalWeight = ((rawWeight ?: 0.0) * 1000),
+            cookMode = 0,
+            isCooking = cookStatus == 1,
+            dinnerType = mealType.toString(),
+            isOriginalData = true
+        )
+    }
+
+    /**
+     * 将新接口的餐次分组响应与本地烹饪中数据合并后渲染列表
+     * 从分组中按当前 dinnerType 筛选对应餐次的 cookOrders，映射为 FoodRecord 后合并本地数据
      */
     @SuppressLint("NotifyDataSetChanged")
-    private fun loadAndMergeDishList(
+    private fun loadAndMergeCookOrders(
-        records: MutableList<FoodRecord>?,
+        groups: List<CookOrderMealGroup>?,
         localList: MutableList<CookFoodEntity>?
     ) {
         try {
             if (isAdded.not()) return
-            val effectiveLocalList = if (pageNo == 1) localList else null
+            val targetMealType = dinnerType.toIntOrNull() ?: return
-            if (records.isNullOrEmpty() && effectiveLocalList.isNullOrEmpty()) {
+            // 从分组中筛选当前餐次的烹制单列表
-                if (pageNo == 1) loadEmptyView()
+            val cookOrders = groups
+                ?.firstOrNull { it.mealType == targetMealType }
+                ?.cookOrders
+            if (cookOrders.isNullOrEmpty() && localList.isNullOrEmpty()) {
+                loadEmptyView()
                 finishRefresh()
                 binding.refreshLayout.setEnableLoadMore(false)
                 return
             }
-            if (pageNo == 1) list.clear()
+            list.clear()
 
-            val mergedList = records?.toMutableList() ?: mutableListOf()
+            val mergedList = cookOrders?.map { it.toFoodRecord() }?.toMutableList() ?: mutableListOf()
-            mergeCookingItems(mergedList, effectiveLocalList)
+            mergeCookingItems(mergedList, localList)
-            deduplicateForPaging(mergedList, localList)
+
-            renderList(mergedList, records)
+            list.addAll(mergedList)
+            dishAdapter.notifyDataSetChanged()
+            binding.refreshLayout.setEnableRefresh(true)
+            binding.refreshLayout.setEnableLoadMore(false)
         } catch (e: Exception) {
             e.printStackTrace()
         }
@@ -354,29 +379,4 @@ class FoodListFragment : BaseFragment<FragmentFoodListBinding>() {
         }
         mergedList.addAll(0, cookingItems)
     }
-
-    /**
-     * 翻页时从网络结果中剔除第一页已加载的本地烹饪中条目，避免重复出现
-     */
-    private fun deduplicateForPaging(
-        mergedList: MutableList<FoodRecord>,
-        localList: List<CookFoodEntity>?
-    ) {
-        if (pageNo < 2 || localList.isNullOrEmpty()) return
-        val localIds = localList.map { it.foodId }.toHashSet()
-        mergedList.removeAll { it.foodId in localIds }
-    }
-
-    /**
-     * 将合并结果追加到列表并刷新 UI，按网络返回条数决定是否开启加载更多
-     */
-    @SuppressLint("NotifyDataSetChanged")
-    private fun renderList(mergedList: List<FoodRecord>, records: List<FoodRecord>?) {
-        list.addAll(mergedList)
-        dishAdapter.notifyDataSetChanged()
-        val isLoadMoreEnable = (records?.size ?: 0) >= pageSize
-        binding.refreshLayout.setEnableRefresh(true)
-        binding.refreshLayout.setEnableLoadMore(isLoadMoreEnable)
-        if (isLoadMoreEnable) pageNo++
-    }
 }

配比秤-制作菜品-API文档.md

@@ -0,0 +1,446 @@
+# 配比秤（新设备）— 制作菜品 API 文档
+
+> Controller: `NutRatioScaleController`
+> 路径前缀: `/neglect/ratio-scale`（Nacos 白名单 `/nutrition/neglect/**`，无需 Sa-Token）
+> 设备上下文通过请求头 `X-DEVICE-CODE` 解析（`TerminalContextHelper`）
+> 用户上下文通过请求头 `X-DEVICE-TOKEN` 解析（`DeviceAuthContextHelper`，获取登录厨师信息）
+> 日期: 2026-07-29
+>
+> **序列化规则**：Long 类型字段响应中均为字符串（Jackson `ToStringSerializer`），`BigDecimal` 为普通数字
+> **单位约定**：
+> - 食材用量（`actualQty`、`useWeight`）统一为 **克 (g)**
+> - 烹制单生重（`rawWeight`）、熟重（`cookedWeight`）为 **千克 (kg)**
+
+---
+
+## 业务背景
+
+配比秤是一款独立于现有组配秤（`/neglect` 路径）的新硬件设备，部署在食堂后厨。第一期实现"按单烹制"功能：厨师在配比秤终端上查看当日烹饪任务 → 查看菜品食材构成 → 提交食材实际用量并触发组配完成 → 开始烹制 → 烹饪完成后提交熟重和调料用量。
+
+### 核心流程
+
+```
+当日烹饪任务列表 → 查看菜品食材构成 → 去制作（提交主辅材实际用量） → 烹饪完成（提交熟重 + 调料用量）
+```
+
+### 烹制状态枚举
+
+| 状态码 | 状态名 | 说明 |
+|:------:|--------|------|
+| 0 | 待烹制 | 初始状态，可进行"去制作"操作 |
+| 1 | 烹制中 | 已提交制作，可进行"烹饪完成"操作 |
+| 2 | 已完成 | 烹制结束，不可再操作 |
+| 3 | 异常 | 异常状态 |
+
+### 食材分类枚举
+
+| 分类 | 名称 | 说明 |
+|:----:|------|------|
+| 1 | 主材 | 菜品主要食材 |
+| 2 | 辅材 | 菜品辅助食材 |
+| 3 | 调料 | 油盐酱醋等，烹饪完成时提交 |
+
+---
+
+## 接口清单
+
+| 序号 | 接口 | 路径 | 用途 |
+|:----:|------|------|------|
+| 一 | 当日烹饪任务列表（按餐次分组） | `POST /neglect/ratio-scale/cook-orders/page` | 按餐次分组返回今日需烹制的菜品列表 |
+| 二 | 菜品食材构成 | `GET /neglect/ratio-scale/cook-orders/{cookOrderId}/composition` | 查看菜品的主材和辅材清单（含标准用量） |
+| 三 | 去制作 | `POST /neglect/ratio-scale/cook-orders/submit` | 提交主辅材实际用量，完善组配并开始烹制 |
+| 四 | 烹饪完成 | `POST /neglect/ratio-scale/cook-orders/finish` | 提交熟重和调料用量，计算生熟比 |
+
+---
+
+## 一、当日烹饪任务列表（按餐次分组）
+
+```
+POST /neglect/ratio-scale/cook-orders/page
+Content-Type: application/json
+X-DEVICE-CODE: <设备编码>
+X-DEVICE-TOKEN: <设备登录Token>
+```
+
+查询当前食堂当日的烹饪任务，后端按餐次分组返回，每个餐次为一个独立对象，内含该餐次下的烹制单列表。
+
+### 请求体
+
+```json
+{
+  "date": "2026-07-29",           // 选填 — 计划日期 yyyy-MM-dd，默认当天
+  "mealType": 2,                  // 选填 — 餐次筛选: 1=早餐 / 2=午餐 / 3=晚餐 / 4=加餐
+  "keyword": "红烧肉",             // 选填 — 菜品名称模糊搜索
+  "pageNum": 1,                   // 选填 — 保留字段，当前不使用
+  "pageSize": 20                  // 选填 — 保留字段，当前不使用
+}
+```
+
+> 注：`mealType` 不传则返回全部餐次；传了只返回对应餐次的单个分组。
+
+### 响应
+
+```json
+{
+  "code": "200",
+  "msg": "操作成功",
+  "data": [
+    {
+      "mealType": 2,                    // 餐次: 1=早餐 / 2=午餐 / 3=晚餐 / 4=加餐
+      "mealTypeName": "午餐",           // 餐次中文名称
+      "cookOrders": [
+        {
+          "cookOrderId": "10001",       // 烹制单id
+          "cookNo": "CK20260729001",    // 烹制单号
+          "dishName": "红烧肉",          // 菜品名称
+          "foodId": "5001",             // 菜品id（关联 nut_food）
+          "mealType": 2,                // 餐次
+          "mealTypeName": "午餐",       // 餐次中文
+          "cookStatus": 0,              // 烹制状态: 0=待烹制 / 1=烹制中 / 2=已完成 / 3=异常
+          "cookStatusName": "待烹制",    // 烹制状态中文
+          "rawWeight": null,            // 生重(kg) — 烹制完成后才有值
+          "needPortions": 5,            // 需求份数
+          "cookedPortions": null        // 烹制份数 — 烹制完成后才有值
+        },
+        {
+          "cookOrderId": "10002",
+          "cookNo": "CK20260729002",
+          "dishName": "清炒时蔬",
+          "foodId": "5002",
+          "mealType": 2,
+          "mealTypeName": "午餐",
+          "cookStatus": 1,
+          "cookStatusName": "烹制中",
+          "rawWeight": 3.500,
+          "needPortions": 3,
+          "cookedPortions": 3
+        }
+      ]
+    },
+    {
+      "mealType": 3,
+      "mealTypeName": "晚餐",
+      "cookOrders": [
+        {
+          "cookOrderId": "10003",
+          "cookNo": "CK20260729003",
+          "dishName": "清蒸鲈鱼",
+          "foodId": "5003",
+          "mealType": 3,
+          "mealTypeName": "晚餐",
+          "cookStatus": 0,
+          "cookStatusName": "待烹制",
+          "rawWeight": null,
+          "needPortions": 2,
+          "cookedPortions": null
+        }
+      ]
+    }
+  ]
+}
+```
+
+### 逻辑说明
+
+- 数据源：`nut_prod_cook_order` 表
+- 查询条件：`canteen_id` = 终端食堂ID（由 `X-DEVICE-CODE` 解析） + `plan_date` = 指定日期（默认当天）
+- 排序规则：`meal_type ASC, create_time DESC`
+- 后端按 `mealType` 分组，每组为一个 `NutRatioCookMealGroupVO` 对象，内含 `mealType` + `mealTypeName` + `cookOrders` 列表
+- `keyword` 字段对 `dish_name` 做 LIKE 模糊匹配
+- `rawWeight` 在烹制完成后为累计主辅材实际用量之和（kg），烹制中为 null
+
+---
+
+## 二、菜品食材构成（主材+辅材）
+
+```
+GET /neglect/ratio-scale/cook-orders/{cookOrderId}/composition
+X-DEVICE-CODE: <设备编码>
+X-DEVICE-TOKEN: <设备登录Token>
+```
+
+查询烹制单对应菜品的主材和辅材清单（不包含调料，调料在烹饪完成时单独提交）。
+
+### 路径参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|:--:|------|
+| cookOrderId | Long | 是 | 烹制单id |
+
+### 响应
+
+```json
+{
+  "code": "200",
+  "msg": "操作成功",
+  "data": [
+    {
+      "materId": "20001",               // 食材id
+      "ingredientName": "五花肉",        // 食材名称
+      "ingredientClass": 1,             // 食材分类: 1=主材 / 2=辅材
+      "ingredientClassName": "主材",     // 食材分类中文
+      "useWeight": 500.0,               // 标准用量(g)
+      "vegTypeId": "10"                 // 净菜类型id
+    },
+    {
+      "materId": "20002",
+      "ingredientName": "土豆",
+      "ingredientClass": 2,
+      "ingredientClassName": "辅材",
+      "useWeight": 300.0,
+      "vegTypeId": "10"
+    }
+  ]
+}
+```
+
+### 逻辑说明
+
+- 先通过烹制单查询 `food_id`（菜品id），再查 `nut_food_composition` 表
+- 仅返回 `is_main IN (1, 2)` 的食材（主材和辅材），调料（`is_main=3`）不在此接口返回
+- 食材名称通过 `nut_mater_base` 批量查询后回填
+- `vegTypeId` 为净菜类型id，用于前端展示毛菜/净菜标识
+
+---
+
+## 三、去制作：提交食材实际用量并开始烹制
+
+```
+POST /neglect/ratio-scale/cook-orders/submit
+Content-Type: application/json
+X-DEVICE-CODE: <设备编码>
+X-DEVICE-TOKEN: <设备登录Token>
+```
+
+厨师在秤上完成主辅材称重后，提交各食材的实际用量。后端自动完成：组配任务完善 → 组配完成 → 烹制单状态切换为"烹制中" → 烹制食材明细更新。
+
+**该接口为事务性操作（`@Transactional`），所有步骤在同一事务中执行，任意步骤失败则全部回滚。**
+
+### 请求体
+
+```json
+{
+  "cookOrderId": 10001,                 // 必填 — 烹制单id
+  "items": [                            // 必填 — 食材实际用量列表，至少1条
+    {
+      "materId": 20001,                 // 必填 — 食材id
+      "actualQty": 520.5                // 必填 — 实际用量(g)
+    },
+    {
+      "materId": 20002,
+      "actualQty": 310.0
+    }
+  ]
+}
+```
+
+### 响应
+
+```json
+{
+  "code": "200",
+  "msg": "操作成功",
+  "data": null
+}
+```
+
+### 处理流程
+
+```
+1. 校验烹制单状态 = 0（待烹制），否则报错
+2. 通过内供申领单关联餐品净菜包：
+   链路: nut_prod_cook_order.food_id → nut_sup_internal_supply(food_id + canteen_id + clean_type=2)
+        → batch_no → nut_sup_meal_package → nut_sup_meal_pkg_ingredient → trace_code
+3. 解析各食材的溯源码（materId → traceCode 映射）
+4. 完善组配任务明细（按 materCode 匹配 comboTaskItem，更新 actualQty + traceCode）
+5. 完成组配任务（comboStatus=2，记录完成时间）
+6. 计算生重（Σ actualQty / 1000，g→kg，保留3位小数）
+7. 从设备Token获取厨师信息（chef + chefId）
+8. 更新烹制单：
+   - cookStatus → 1（烹制中）
+   - cookStart → 当前时间
+   - rawWeight → 生重(kg)
+   - chef / chefId → 登录厨师
+   - needPortions / cookedPortions → 份数
+9. 更新烹制食材明细（cook_ingredient）：
+   - 已有明细 → 更新 actualQty + traceCode
+   - 无已有明细 → 按 foodComposition 自动创建兜底记录
+```
+
+### 份数计算优先级
+
+```
+内供申领单 quantity > 烹制单 needPortions > 兜底值 1
+```
+
+### 异常场景
+
+| 场景 | 错误信息 |
+|------|---------|
+| 烹制单不存在 | `烹制单不存在` |
+| 当前状态不是"待烹制" | `当前状态不允许此操作，仅待烹制状态可提交制作` |
+| 烹制单未关联组配任务（comboNo 为空） | `烹制单未关联组配任务，无法开始烹制` |
+| 组配任务不存在 | `组配任务不存在，comboNo=xxx` |
+
+### 涉及数据表
+
+| 表名 | 操作 | 说明 |
+|------|:--:|------|
+| `nut_prod_cook_order` | 查询 + 更新 | 校验状态，更新为烹制中 |
+| `nut_sup_internal_supply` | 查询 | 通过 foodId + canteenId + cleanType=2 关联，获取 batchNo 和 quantity |
+| `nut_sup_meal_package` | 查询 | 通过 batchNo 查餐品净菜包 |
+| `nut_sup_meal_pkg_ingredient` | 查询 | 获取各食材的溯源码 |
+| `nut_prod_combo_task` | 查询 + 更新 | 完善组配状态为已完成 |
+| `nut_prod_combo_task_item` | 查询 + 更新 | 更新 actualQty + traceCode |
+| `nut_prod_cook_ingredient` | 查询 + 新增/更新 | 更新实际用量，不存在时兜底创建 |
+| `nut_mater_base` | 查询 | 获取食材编码和名称 |
+| `nut_food_composition` | 查询 | 兜底创建 cook_ingredient 时获取食材分类等信息 |
+
+---
+
+## 四、烹饪完成：提交熟重和调料用量
+
+```
+POST /neglect/ratio-scale/cook-orders/finish
+Content-Type: application/json
+X-DEVICE-CODE: <设备编码>
+X-DEVICE-TOKEN: <设备登录Token>
+```
+
+烹饪结束后，厨师在秤上称量熟重，并提交调料用量。后端自动计算生熟比。
+
+**该接口为事务性操作（`@Transactional`）。**
+
+### 请求体
+
+```json
+{
+  "cookOrderId": 10001,                 // 必填 — 烹制单id
+  "cookedWeight": 3.200,                // 必填 — 熟重(kg)
+  "seasonings": [                       // 选填 — 调料用量列表
+    {
+      "materId": 30001,                 // 必填 — 调料食材id
+      "actualQty": 15.0                 // 必填 — 实际用量(g)
+    },
+    {
+      "materId": 30002,
+      "actualQty": 8.5
+    }
+  ]
+}
+```
+
+### 响应
+
+```json
+{
+  "code": "200",
+  "msg": "操作成功",
+  "data": null
+}
+```
+
+### 处理流程
+
+```
+1. 校验烹制单状态 = 1（烹制中），否则报错
+2. 如有调料：保存到 nut_prod_cook_ingredient
+   - 已在 cook_ingredient 中的调料（ingredientClass=3） → 更新 actualQty
+   - 新调料 → 新增记录（ingredientClass=3 调料）
+3. 计算生熟比 = cookedWeight / rawWeight（保留3位小数，HALF_UP）
+4. 更新烹制单：
+   - cookStatus → 2（已完成）
+   - cookedWeight → 熟重(kg)
+   - rawCookedRatio → 生熟比
+   - cookEnd → 当前时间
+```
+
+### 生熟比计算
+
+```
+生熟比 = 熟重(kg) / 生重(kg)
+精度: 3位小数, HALF_UP
+条件: 生重 > 0 且熟重 != null 时才计算，否则生熟比为 null
+```
+
+### 异常场景
+
+| 场景 | 错误信息 |
+|------|---------|
+| 烹制单不存在 | `烹制单不存在` |
+| 当前状态不是"烹制中" | `当前状态不允许此操作，仅烹制中状态可完成烹制` |
+
+### 涉及数据表
+
+| 表名 | 操作 | 说明 |
+|------|:--:|------|
+| `nut_prod_cook_order` | 查询 + 更新 | 校验状态，更新为已完成，记录熟重和生熟比 |
+| `nut_prod_cook_ingredient` | 查询 + 新增/更新 | 保存调料用量（ingredientClass=3） |
+| `nut_mater_base` | 查询 | 获取调料食材编码和名称 |
+
+---
+
+## 总体数据链路图
+
+```
+nut_prod_cook_order (烹制单)
+    │
+    ├── food_id ──→ nut_food_composition (菜品食材构成: 主材/辅材/调料)
+    │                    │
+    │                    └── mater_id ──→ nut_mater_base (食材库: 编码、名称、分类)
+    │
+    ├── canteen_id + food_id ──→ nut_sup_internal_supply (内供申领单)
+    │                                   │
+    │                                   ├── batch_no ──→ nut_sup_meal_package (餐品净菜包)
+    │                                   │                      │
+    │                                   │                      └── nut_sup_meal_pkg_ingredient (溯源码)
+    │                                   │
+    │                                   └── quantity ──→ 份数
+    │
+    ├── combo_no ──→ nut_prod_combo_task (组配任务)
+    │                      │
+    │                      └── nut_prod_combo_task_item (组配明细: ingredientCode)
+    │
+    └── cook_ingredient: nut_prod_cook_ingredient (烹制食材明细)
+```
+
+---
+
+## 接口调用时序
+
+```
+┌─────────┐          ┌─────────────┐          ┌──────────┐
+│ 配比秤终端 │          │ Controller   │          │ Database  │
+└────┬────┘          └──────┬──────┘          └────┬─────┘
+     │                      │                      │
+     │ 1. POST /cook-orders/page                   │
+     │─────────────────────→│                      │
+     │                      │──→ nut_prod_cook_order (当日+食堂)
+     │  ← 任务列表(按餐次)    │←────────────────────│
+     │                      │                      │
+     │ 2. GET /cook-orders/{id}/composition        │
+     │─────────────────────→│                      │
+     │                      │──→ nut_food_composition (主材+辅材)
+     │                      │──→ nut_mater_base (食材名称)
+     │  ← 食材清单(含标准用量)  │←────────────────────│
+     │                      │                      │
+     │ 3. POST /cook-orders/submit                 │
+     │─────────────────────→│                      │
+     │                      │──→ 校验状态=待烹制     │
+     │                      │──→ 关联internal_supply │
+     │                      │──→ 解析溯源码          │
+     │                      │──→ 完善+完成组配任务    │
+     │                      │──→ 计算生重            │
+     │                      │──→ 更新烹制单=烹制中    │
+     │                      │──→ 更新食材明细        │
+     │  ← 操作成功            │←──── 事务提交 ──────│
+     │                      │                      │
+     │ 4. POST /cook-orders/finish                 │
+     │─────────────────────→│                      │
+     │                      │──→ 校验状态=烹制中     │
+     │                      │──→ 保存调料用量        │
+     │                      │──→ 计算生熟比          │
+     │                      │──→ 更新烹制单=已完成    │
+     │  ← 操作成功            │←──── 事务提交 ──────│
+     │                      │                      │
+```