大屏 Magic-API 接口速查
========================================
分组：/dashboard
前端代理：/api/dashboard/*
源文件：livestock-trading-backend/data/magic-api/api/大屏数据/*.ms
说明：均为只读；复杂逻辑见各 .ms 文件。修改 .ms 后需重启后端。


--------------------------------------------------------------------------------
1. 系统配置
--------------------------------------------------------------------------------
GET /dashboard/system-config
文件：系统配置.ms | 前端：Dashboard.vue、ChinaMap.vue、systemConfig.js

业务：大屏静态配置（标题图、地图枢纽红原、城市坐标、流向等级配色等）。

数据表：无（脚本内硬编码，可在 magic-api 或 .ms 中改）


--------------------------------------------------------------------------------
2. 实时交易统计
--------------------------------------------------------------------------------
GET /dashboard/real-time-stats
文件：实时交易统计.ms | 前端：RealTimeStats.vue

业务：按时间维度统计交易所已完成订单的交易量、订单数、买卖商户数。

参数：dimension（可选）day / week / month / year，不传返回全部

表：yak_sn_order
字段：quantity, seller_id, buyer_id, transaction_time, status, del_flag
条件：del_flag='0'，status='COMPLETED'


--------------------------------------------------------------------------------
3. 交易所牦牛成交数据
--------------------------------------------------------------------------------
GET /dashboard/yak-trading-data
文件：交易所牦牛成交数据.ms | 前端：YakTradingData.vue

业务：近 6 个日/周/月时间桶的牦牛头数与订单数趋势。

参数：period（可选）day / week / month，不传返回全部

表：yak_sn_order
字段：id, quantity, transaction_time, status, del_flag
条件：del_flag='0'，status='COMPLETED'


--------------------------------------------------------------------------------
4. 综合销售统计
--------------------------------------------------------------------------------
GET /dashboard/comprehensive-sales-stats
文件：综合销售统计.ms | 前端：ComprehensiveSalesStats.vue

业务：三个饼图——本月销售、总体销售（按产地乡镇 Top5）、采购地区（Top5）。

参数：type（可选）monthlySales / overallSalesDistribution / purchaseRegionDistribution

表：yak_sn_order；采购地区 LEFT JOIN yak_sn_customer
字段：
  yak_sn_order — quantity, origin_place, destination_place, buyer_id, transaction_time, status, del_flag
  yak_sn_customer — id, region_name, del_flag
条件：del_flag='0'，status='COMPLETED'


--------------------------------------------------------------------------------
5. 活牛/鲜肉价格趋势
--------------------------------------------------------------------------------
GET /dashboard/price-trend
文件：活牛鲜肉价格趋势.ms | 前端：YakPriceTrend.vue

业务：近 8 个月活牛、鲜肉市场采集均价（不做重量折算）。

表：yak_trade_market_price
字段：price_date, price_type（LIVE_YAK / FRESH_MEAT）, price, unit


--------------------------------------------------------------------------------
6. 交易中心实时服务信息
--------------------------------------------------------------------------------
GET /dashboard/exchange-service-info
文件：交易中心实时服务信息.ms | 前端：ExchangeMonitor.vue

业务：交易中心实时概览——供应/待售/已售头数、剩余车位、今日进场车辆、供应商数。

表及字段：
  yak_trade_ear_tag_inventory — status（计总供应/待售/已售）
  yak_car_parking_zone — total_capacity, current_count, status
  yak_car_record — plate_no, entry_time, del_flag
  yak_trade_entry_record — vehicle_no, entered_at
  yak_sn_customer — customer_type='SELLER', del_flag


--------------------------------------------------------------------------------
7. 牦牛销售类型统计
--------------------------------------------------------------------------------
GET /dashboard/yak-sales-type-stats
文件：牦牛销售类型统计.ms | 前端：YakSalesTypeStats.vue

业务：按订单用途归类为屠宰/养殖/其他，统计头数与占比。

表：yak_sn_order
字段：quantity, purpose, status, del_flag
条件：del_flag='0'，status='COMPLETED'


--------------------------------------------------------------------------------
8. 采购商户来源分析
--------------------------------------------------------------------------------
GET /dashboard/buyer-source-analysis
文件：采购商户来源分析.ms | 前端：PurchaserAnalysis.vue

业务：按地区统计采购商户（BUYER）数量 Top9。

表：yak_sn_customer
字段：region_name, customer_type, del_flag
条件：customer_type='BUYER'，del_flag='0'，region_name 非空


--------------------------------------------------------------------------------
9. 牦牛供应实时信息
--------------------------------------------------------------------------------
GET /dashboard/yak-supply-realtime-info
文件：牦牛供应实时信息.ms | 前端：SupplyDemandData.vue

业务：卖方进场登记列表（分页）及汇总（今日进场、总头数、交易中批次）。

参数：pageNo（默认 1）、pageSize（默认 5；勿用 page）

表及字段：
  yak_trade_entry_record — id, name, vehicle_no, phone, party_id, quarantine_certificate_no, entered_at, entry_type
  yak_trade_ear_tag_inventory — seller_entry_record_id, status, ear_tag_no
  yak_trade_entry_record_ear_tag — entry_record_id
  yak_sn_customer — id, region_name, address
条件：entry_type='SELLER'


--------------------------------------------------------------------------------
10. 牦牛供应详情
--------------------------------------------------------------------------------
GET /dashboard/yak-supply-detail
文件：牦牛供应详情.ms | 前端：SupplyDemandData.vue

业务：单条卖方进场详情（基本信息、耳标进度、关联成交订单、进场/检疫/称重图片 URL）。

参数：id（必填，yak_trade_entry_record.id）

表及字段：
  yak_trade_entry_record — id, name, vehicle_no, phone, party_id, quarantine_certificate_no, entry_photo_id, entered_at, entry_type
  yak_trade_ear_tag_inventory — seller_entry_record_id, ear_tag_no, status, locked_order_id
  yak_trade_entry_record_ear_tag — entry_record_id, certificate_image_file_id
  yak_trade_order / yak_trade_order_item — 订单与耳标明细
  yak_trade_weighing_record — weight, photo_id
  yak_trade_quarantine_certificate — certificate_no, image_file_id
  yak_sn_customer — region_name, address（买卖方名称）
  yak_car_record — 关联车辆
  sys_oss — url（图片解析）


--------------------------------------------------------------------------------
11. 市场环境监控
--------------------------------------------------------------------------------
GET /dashboard/market-environment
文件：市场环境监控.ms | 前端：MarketEnvironmentMonitor.vue

业务：环境温湿度 + 气象数据各取最新一条。

表及字段：
  iot_device_env_data — temperature, humidity, collect_time
  iot_device_weather_data — air_pressure, pm25, pm10, uv_index, rainfall, wind_speed, wind_direction, collect_time


--------------------------------------------------------------------------------
12. 市场实时监控
--------------------------------------------------------------------------------
GET /dashboard/market-realtime-monitor
文件：市场实时监控.ms | 前端：MarketRealtimeMonitor.vue

业务：视频监控设备列表及播放/预览地址。

表及字段：
  iot_device_video — id, name, number, location, address, status, play_url, hd_play_url, preview_img_url, channel_number, index, del_flag, is_show
  iot_device_video_data — device_id, stream_url, snapshot_url, online_status, stream_status, fault_code, collect_time
条件：del_flag='0'，is_show=true


--------------------------------------------------------------------------------
13. 市场实时监控播放配置
--------------------------------------------------------------------------------
GET /dashboard/market-realtime-player-config
文件：市场实时监控播放配置.ms | 前端：MarketRealtimeMonitor.vue（liveStreamPlayer.js）

业务：直播流协议识别规则与 hls.js / flv.js 播放器参数（静态配置）。

数据表：无


--------------------------------------------------------------------------------
14. 地图迁徙数据
--------------------------------------------------------------------------------
GET /dashboard/map-trading-network
文件：地图迁徙数据.ms | 前端：ChinaMap.vue

业务：中央地图三种模式流向——销售网络（红原→全国）、源地供应（全国→红原）、红原出栏（乡镇→红原）。

表：yak_sn_order；outflow/inflow LEFT JOIN yak_sn_customer
字段：
  yak_sn_order — quantity, origin_place, destination_place, buyer_id, seller_id, status, del_flag
  yak_sn_customer — id, region_name, del_flag
条件：del_flag='0'，status='COMPLETED'；local 模式另要求 origin_place 含「红原」
关联：系统配置 mapHub.name 与脚本 hubName 需一致（默认「红原县」）


================================================================================
表 → 接口索引
================================================================================
yak_sn_order                  2, 3, 4, 7, 14
yak_sn_customer               4, 6, 8, 9, 10, 14
yak_trade_market_price        5
yak_trade_ear_tag_inventory   6, 9, 10
yak_trade_entry_record        6, 9, 10
yak_trade_entry_record_ear_tag  9, 10
yak_trade_order / _item       10
yak_trade_weighing_record     10
yak_trade_quarantine_certificate  10
yak_car_parking_zone          6
yak_car_record                6, 10
sys_oss                       10
iot_device_env_data           11
iot_device_weather_data       11
iot_device_video              12
iot_device_video_data         12
（无表）                      1, 13
