生鲜食材配送与团餐管理系统 — 需求文档

1. 项目概述

构建一套面向生鲜食材配送企业和团餐服务商的 B2B/B2C 一体化管理平台，覆盖采购、仓储、分拣、配送、团餐订制、财务结算全链路。

1.1 核心目标

• 实现生鲜食材从供应商 → 中央仓 → 分拣 → 配送 → 客户的全流程数字化
• 支持团餐（学校、企事业单位、医院等）批量订餐与周期配送
• 降低损耗率、提升配送准时率、优化库存周转

1.2 用户角色

2. 功能模块

2.1 商品管理

• 商品库：SPU/SKU 管理，支持规格（斤/箱/份）、批次、产地、质检信息
• 品类树：蔬菜、水果、肉禽蛋奶、冻品、粮油调味、日配等
• 价格管理：阶梯价、客户等级价、促销价、季节调价
• 质检管理：进货质检、巡检记录、不合格品处理

2.2 采购管理

• 供应商管理（资质、评级、合同）
• 智能采购建议（基于库存预警 + 历史销量）
• 采购单生成、审批、发货、入库
• 采购退货与索赔流程

2.3 仓储管理

• 入库管理（采购入库、退货入库、盘盈入库）
• 出库管理（分拣出库、报损出库）
• 库存盘点（支持 PDA/手机扫码）
• 库存预警（保质期预警、安全库存预警）
• 库位管理（分区/货架/托盘级）

2.4 分拣管理

• 波次分拣（按线路/客户聚合）
• 分拣任务分配（PDA 推送）
• 称重录入（支持蓝牙电子秤）
• 差异处理（缺货替换、数量调整）
• 分拣标签打印（商品名、客户名、重量、条形码）

2.5 配送管理

• 线路规划：固定线路 + 智能排线（按地址/时间窗）
• 配送任务：装车清单、配送顺序、预计到达时间
• 温度监控：冷链车温度记录（IoT 接入）
• 签收确认：客户签字 / 拍照 / 电子签收
• 回单管理：纸质回单拍照上传、电子回单

2.6 团餐管理

• 菜单管理：周菜单、月菜单、自定义套餐
• 团餐订单：按周期（日/周/月）批量下单
• 用餐人数预报：客户提交次日/下周预估人数
• 营养分析：菜品营养成分统计报表
• 食堂管理：多食堂/多窗口配送分货

2.7 订单管理

• 客户自主下单（PC / 微信小程序 / H5）
• 客服代下单
• 订单审核、拆分、合并
• 售后流程（拒收、少件、品质问题）
• 订单状态全链路追踪

2.8 财务结算

• 客户账单（按账期 / 按订单）
• 供应商结算单
• 配送费结算
• 应收账款 / 应付账款管理
• 发票管理

2.9 数据报表

• 销售日报/月报/年报
• 商品销售排行
• 客户复购率 / 流失分析
• 损耗分析报表
• 配送准时率统计
• 团餐用餐统计

2.10 系统管理

• 组织架构与员工管理
• 角色权限（RBAC）
• 操作日志审计
• 消息通知（短信 / 微信 / App 推送）
• 系统配置（配送时间窗、结算周期等）

3. 非功能需求

4. 业务流程简图

供应商 → 采购入库 → 中央冷库 → 分拣打包 → 装车配送 → 客户签收
               ↓                      ↑
          库存预警 ←—— 销售订单 —— 团餐预订

5. 验收标准

• 所有核心模块 CRUD 正常
• 角色权限正确隔离
• 订单流程跑通（下单→审核→分拣→配送→签收）
• 团餐周期下单与配送逻辑正确
• 报表数据与业务数据一致
• 压力测试达标

生鲜食材配送与团餐管理系统 — 开发文档

1. 技术架构

1.1 整体架构图

1.2 技术选型

1.3 数据库设计原则

• 每张表必须包含 id, created_at, updated_at, deleted_at（逻辑删除）
• 核心业务表使用分布式 ID（Snowflake）
• 订单号规则：yyMMdd + 业务线 + 6位自增
• 分表策略：订单表按 order_date 水平分表
• 所有金额字段使用 DECIMAL(12,2)，单位统一为元

2. 核心数据模型

2.1 商品 (product)

CREATE TABLE `product` (
  `id`          BIGINT       NOT NULL PRIMARY KEY,
  `spu_code`    VARCHAR(32)  NOT NULL COMMENT 'SPU编码',
  `sku_code`    VARCHAR(32)  NOT NULL COMMENT 'SKU编码',
  `name`        VARCHAR(128) NOT NULL COMMENT '商品名称',
  `category_id` BIGINT       NOT NULL COMMENT '品类ID',
  `unit`        VARCHAR(10)  NOT NULL COMMENT '单位: 斤/箱/份',
  `spec`        VARCHAR(64)  DEFAULT '' COMMENT '规格描述',
  `price`       DECIMAL(12,2) NOT NULL COMMENT '零售价',
  `cost_price`  DECIMAL(12,2) NOT NULL COMMENT '成本价',
  `barcode`     VARCHAR(32)  DEFAULT '' COMMENT '条形码',
  `status`      TINYINT      NOT NULL DEFAULT 1 COMMENT '1上架 0下架',
  `images`      JSON         COMMENT '商品图片',
  `created_at`  DATETIME     NOT NULL,
  `updated_at`  DATETIME     NOT NULL,
  `deleted_at`  DATETIME     DEFAULT NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

2.2 订单 (order)

CREATE TABLE `order` (
  `id`            BIGINT       NOT NULL PRIMARY KEY,
  `order_no`      VARCHAR(32)  NOT NULL UNIQUE COMMENT '订单号',
  `customer_id`   BIGINT       NOT NULL COMMENT '客户ID',
  `order_type`    TINYINT      NOT NULL COMMENT '1普通 2团餐',
  `total_amount`  DECIMAL(12,2) NOT NULL COMMENT '订单总额',
  `discount`      DECIMAL(12,2) DEFAULT 0 COMMENT '优惠金额',
  `pay_amount`    DECIMAL(12,2) NOT NULL COMMENT '实付金额',
  `status`        TINYINT      NOT NULL COMMENT '0待审核 1已审核 2分拣中 3配送中 4已签收 5已取消',
  `delivery_date` DATE         NOT NULL COMMENT '配送日期',
  `delivery_time_slot` VARCHAR(32) COMMENT '配送时段',
  `remark`        VARCHAR(255) DEFAULT '' COMMENT '备注',
  `created_at`    DATETIME     NOT NULL,
  `updated_at`    DATETIME     NOT NULL,
  `deleted_at`    DATETIME     DEFAULT NULL,
  INDEX `idx_customer` (`customer_id`),
  INDEX `idx_date` (`delivery_date`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

2.3 配送任务 (delivery_task)

CREATE TABLE `delivery_task` (
  `id`            BIGINT       NOT NULL PRIMARY KEY,
  `task_no`       VARCHAR(32)  NOT NULL UNIQUE COMMENT '任务编号',
  `driver_id`     BIGINT       NOT NULL COMMENT '配送员ID',
  `vehicle_id`    VARCHAR(32)  COMMENT '车辆编号',
  `route_id`      BIGINT       COMMENT '线路ID',
  `order_ids`     JSON         NOT NULL COMMENT '关联订单ID列表',
  `total_stops`   INT          NOT NULL DEFAULT 0 COMMENT '配送点数',
  `status`        TINYINT      NOT NULL COMMENT '0待装车 1配送中 2已完成',
  `depart_time`   DATETIME     COMMENT '发车时间',
  `finish_time`   DATETIME     COMMENT '完成时间',
  `created_at`    DATETIME     NOT NULL,
  `updated_at`    DATETIME     NOT NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

2.4 团餐菜单 (group_menu)

CREATE TABLE `group_menu` (
  `id`            BIGINT       NOT NULL PRIMARY KEY,
  `customer_id`   BIGINT       NOT NULL COMMENT '客户（食堂）ID',
  `menu_name`     VARCHAR(64)  NOT NULL COMMENT '菜单名称',
  `menu_date`     DATE         NOT NULL COMMENT '菜单日期',
  `menu_type`     TINYINT      NOT NULL COMMENT '1早餐 2午餐 3晚餐',
  `items`         JSON         NOT NULL COMMENT '菜品列表 [{dish_id, dish_name, quantity, unit_price}]',
  `total_calories` INT         DEFAULT 0 COMMENT '总卡路里',
  `status`        TINYINT      DEFAULT 0 COMMENT '0草稿 1已发布',
  `created_at`    DATETIME     NOT NULL,
  `updated_at`    DATETIME     NOT NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

3. API 设计规范

3.1 命名规则

GET    /api/v1/products          — 商品列表（分页）
POST   /api/v1/products          — 新增商品
GET    /api/v1/products/{id}     — 商品详情
PUT    /api/v1/products/{id}     — 更新商品
DELETE /api/v1/products/{id}     — 删除商品

GET    /api/v1/orders?status=1&date=2026-06-02  — 订单列表
POST   /api/v1/orders            — 创建订单
GET    /api/v1/orders/{orderNo}  — 订单详情
PUT    /api/v1/orders/{orderNo}/status  — 更新订单状态

3.2 统一响应格式

{
  "code": 0,
  "message": "success",
  "data": {},
  "trace_id": "xxx"
}

3.3 分页请求/响应

// 请求
{ "page": 1, "page_size": 20 }

// 响应
{
  "code": 0,
  "data": {
    "list": [],
    "total": 100,
    "page": 1,
    "page_size": 20
  }
}

4. 关键业务流程代码示例

4.1 订单状态机

var OrderStateMachine = map[OrderStatus][]OrderStatus{
    StatusPending:    {StatusApproved, StatusCancelled},
    StatusApproved:   {StatusPicking, StatusCancelled},
    StatusPicking:    {StatusDelivering, StatusCancelled},
    StatusDelivering: {StatusSigned, StatusRejected},
    StatusSigned:     {},
    StatusCancelled:  {},
    StatusRejected:   {},
}

4.2 分拣波次算法（伪代码）

1. 查询当天待分拣订单，按 delivery_route_id 分组
2. 同线路订单聚合为波次
3. 按商品 SKU 汇总数量，生成分拣总单
4. 分拣员扫码分拣 → 称重 → 贴标 → 按客户分筐
5. 装车前扫码核单确认

5. 部署架构

# docker-compose 示意
services:
  gateway:
    image: kong:3.5
  user-svc:
    image: registry.example.com/user-svc:latest
  product-svc:
    image: registry.example.com/product-svc:latest
  order-svc:
    image: registry.example.com/order-svc:latest
  delivery-svc:
    image: registry.example.com/delivery-svc:latest
  group-meal-svc:
    image: registry.example.com/group-meal-svc:latest
  mysql:
    image: mysql:8.0
  redis:
    image: redis:7-alpine
  rabbitmq:
    image: rabbitmq:3-management

生产环境 K8s：每个微服务 2-4 副本，配置 HPA（CPU > 70% 自动扩容）。

6. 开发规范

7. 环境规划

8. 开发里程碑