# 即时配送小程序 - 需求文档（完整版）

> 客户端 + 配送员端 + 管理后台 + 红包系统 + 会员体系 + 实时定位 + 仓储物流
>
> **文档版本**：v5.0 | **更新**：阶段工时费用暂估、多租户站点权限、数据库详情、LLM/RAG

---

## 零、项目阶段划分与报价说明

### 0.1 阶段划分总览

| 阶段 | 名称 | 优先级 | 说明 |
|------|------|--------|------|
| **Phase 1** | 核心跑腿业务 | P0 | 客户端+骑手端+管理后台基础功能 |
| **Phase 2** | 会员与营销 | P1 | 红包/优惠券/积分商城/会员体系 |
| **Phase 3** | 实时定位监控 | P1 | 骑手GPS定位+管理端实时监控 |
| **Phase 4** | 站点与仓储管理 | P2 | 站点管理+入库/出库管理 |
| **Phase 5** | 物流跟踪 | P2 | 运单系统+节点跟踪+车辆定位 |
| **Phase 6** | 司机端APP | 可选 | 独立司机APP（需车辆定位方案） |

---

### 0.2 Phase 1：核心跑腿业务（MVP）

**目标**：完成即时配送基础业务闭环，快速上线验证

**交付物**：
- 📱 用户端小程序（发单/支付/追踪/评价）
- 🏍️ 骑手端小程序（抢单/取送件/钱包）
- 🖥️ 管理后台（订单/调度/骑手/基础统计）

**业务范围**：
- 帮我送、帮我买、帮我办三大服务
- 订单全流程：下单→支付→抢单→取件→配送→签收
- 骑手抢单+指定派单混合模式
- 基础费用计算（距离+时段+保价）
- 微信支付/余额支付

**技术要点**：
- 用户+骑手双端小程序
- 订单状态机（待支付→待接单→已接单→配送中→已完成）
- 简易调度逻辑（基于距离/负载）

**报价参考**：基础工时 60-80%（核心链路）

---

### 0.3 Phase 2：会员与营销（P1）

**目标**：增强用户粘性，提升复购率

**交付物**：
- 会员等级体系（普通/银卡/金卡/钻石）
- 积分系统（获取/消耗/明细）
- 红包系统（满减/随机/新人/节日）
- 优惠券系统
- 积分商城

**业务范围**：
- 成长值计算+等级权益
- 红包创建/发放/兑换
- 积分商城商品管理
- 用户红包/优惠券领取和使用

**报价参考**：工时 15-20%

---

### 0.4 Phase 3：实时定位监控（P1）

**目标**：提供透明化配送体验，提升用户信任

**交付物**：
- 骑手GPS位置上报（30秒间隔）
- 用户端实时骑手位置展示
- 管理端骑手状态分布图
- 历史轨迹查询

**业务范围**：
- 骑手端：GPS获取+位置上报+电量监测
- 用户端：订单详情页地图+骑手实时位置+预计到达
- 管理端：骑手分布地图+实时监控+轨迹回放

**报价参考**：工时 10-15%

---

### 0.5 Phase 4：站点与仓储管理（P2）

**目标**：支持多站点运营，实现货物全流程管理

**交付物**：
- 站点管理（站点新增/编辑/地图展示）
- 入库管理（到货登记/扫描/分拣/上架）
- 出库管理（申请/审核/拣货/打包/装车）
- 库存查询

**业务范围**：
- 站点类型：配送站/中转站/仓储中心/代收点
- 入库流程：供应商发货→到货登记→扫描签收→物品录入→分拣上架
- 出库流程：出库申请→审核→拣货→打包→装车→出库
- 站点库存实时查询

**报价参考**：工时 10-15%

---

### 0.6 Phase 5：物流跟踪（P2/可选方案）

**目标**：实现货物全链路可视化跟踪

**交付物**：
- 运单系统（运单创建/节点跟踪/状态更新）
- 物流节点展示
- 车辆定位（可选）

#### 方案A：纯站点节点跟踪（推荐）

适用于：无自有车辆/依赖第三方物流/航班航运不可控

| 方案 | 追踪粒度 | 数据来源 | 实现成本 |
|------|----------|----------|----------|
| **A.站点节点** | 站点级别 | 人工确认/扫描 | 低 |
| B.车辆GPS | 车辆级别 | GPS设备 | 高 |
| C.物流API | 节点级别 | 第三方API | 中 |

**追踪节点**：
```
[商家发货] → [到达始发站点] → [运输中] → [到达目的站点] → [派送中] → [已签收]
```

#### 方案B：车辆定位（可选扩展）

适用于：自有车辆/对时效要求高/需要竞品分析

**实现方式**：
| 方式 | 设备要求 | 成本 | 精度 |
|------|----------|------|------|
| 手机APP | 司机安装APP | 低 | 中 |
| OBD设备 | 车载OBD | 中 | 高 |
| GPS追踪器 | 外置设备 | 中高 | 高 |
| 物流API | 对接第三方 | 中 | 高 |

**报价参考**：工时 10-15%（不含车辆设备）

---

### 0.7 Phase 6：司机端APP（可选）

**目标**：独立司机端，支持专业运输车队

**触发条件**：
- 自有车辆运营
- Phase 5 选择方案B
- 长途/城际运输需求

**与骑手端区别**：

| 对比项 | 骑手端 | 司机端 |
|--------|--------|--------|
| 服务类型 | 即时配送（30分钟内） | 计划配送（小时/天） |
| 距离 | 0-10km | 10km+ |
| 追踪 | 实时GPS | 站点节点/车辆GPS |
| 支付 | 单单结算 | 批量结算 |
| 设备 | 手机即可 | 建议车载设备 |

**报价参考**：工时 15-20%（独立APP）

---

### 0.8 阶段依赖关系

```
Phase 1（核心）
    ↓
Phase 2（会员营销）← 可并行 →
Phase 3（实时定位）
    ↓
Phase 4（站点仓储）
    ↓
Phase 5（物流跟踪）→ Phase 6（司机APP，可选）
```

---

### 0.9 当前分析范围

> **声明**：本需求文档当前阶段的分析重点为 **Phase 1 核心跑腿业务** 及 **Phase 2 会员营销** 的业务逻辑梳理。
>
> 以下章节（站点/仓储/物流/车辆定位）为本阶段预留的 **扩展功能说明**，具体实现细节需后续专项讨论：
> - 站点管理：站点类型/容量/调度规则
> - 仓储管理：入库流程/库存规则/异常处理
> - 物流跟踪：节点定义/状态同步/第三方对接
> - 车辆定位：设备选型/数据协议/成本核算

---

### 0.10 各阶段工时与费用区间（暂估）

> **友善说明（请您知悉）**  
> 下表中的**人天区间**与**费用区间**是根据当前需求文档所作的**阶段性粗算**，用于内部排期与商务沟通时的**参考锚点**，**并非最终报价**。  
> 最终金额以：**需求说明书定稿**、**变更单**、**团队人天单价**、**交付范围（含第三方接口/地图/短信等）**及**合同条款**为准。  
> 若您的业务模式（多租户站点数、代理层级、仓储规模）与下文假设差异较大，区间可能显著上下浮动——我们建议在 Phase 1 定稿后做一次**固定范围的报价复盘**。

| 阶段 | 参考人天（含联调/基础测试） | 参考费用区间（人民币，含税与否以合同为准） | 备注 |
|------|------------------------------|---------------------------------------------|------|
| Phase 1 核心跑腿 | 45～70 人天 | 约 12～35 万 | 双小程序 + 管理端 MVP，不含复杂定制报表 |
| Phase 2 会员营销 | 18～28 人天 | 约 5～14 万 | 红包/积分/商城规则若频繁变更高位 |
| Phase 3 实时定位 | 12～22 人天 | 约 4～12 万 | 含地图 SDK、轨迹存储策略 |
| Phase 4 站点仓储 | 20～35 人天 | 约 6～18 万 | 与多站点权限、扫描硬件对接相关 |
| Phase 5 物流跟踪 | 15～30 人天 | 约 5～16 万 | 节点型方案偏低；车辆 GPS/第三方 API 另计 |
| Phase 6 司机 APP | 35～55 人天 | 约 12～28 万 | 独立 App 上架、推送、离线弱网 |

**并行说明**：Phase 2 与 Phase 3 在人力允许时可部分并行，**总日历工期**通常短于人天简单相加。

---

### 0.11 多租户、代理节点与站点权限（业务结构影响）

**目标**：同一套系统服务多个租户（品牌/主体），可选支持加盟商（代理节点），仓储与订单数据按**站点**做**独立权限**与列表范围过滤。

| 层级 | 说明 | 数据隔离 |
|------|------|----------|
| 租户 tenant | 平台签约主体/品牌 | 所有业务表带 `tenant_id` |
| 代理 agent | 加盟/区域合作方 | 可选 `agent_id`，报表与分润按代理收敛 |
| 站点 station | 仓/配送节点 | `station_id` + **站点级后台账号**仅看本站 |

**权限模型要点**：

- **平台角色**：总部运营、财务 — `data_scope_type=全部` 或按租户。
- **站点角色**：站长、库管、调度 — `data_scope_type=指定站点`，关联 `ot_admin_user_station`。
- **审计**：关键字段变更写入 `ot_data_change_log`；接口层写 `ot_operation_log`。

**数据库与详情页**：字段级定义、伪删除、创建/编辑人时间见 **`database_schema_detail.md`** 与 **`database_schema.html`**。

---

## 一、项目概述

### 1.1 业务定位
- **即时配送跑腿服务**：帮我送、帮我买、帮我办等多元化服务
- **目标用户**：C端用户（发单方）、配送员（接单方）
- **核心场景**：文件配送、鲜花蛋糕、生鲜外卖、超市代买、代办事务

### 1.2 服务类型

| 服务类型 | 说明 | 典型场景 |
|---------|------|---------|
| 帮我送 | 物品配送 | 文件、鲜花、蛋糕、包裹 |
| 帮我买 | 代购服务 | 超市商品、药品、奶茶 |
| 帮我办 | 代办事务 | 排队、取号、送礼 |

### 1.3 参与角色

| 角色 | 说明 |
|------|------|
| 用户 | C端发单客户 |
| 会员用户 | VIP用户，享受积分/优惠券特权 |
| 配送员/骑手 | 接单配送人员 |
| 调度员 | 订单调度分配 |
| 运营管理员 | 平台运营管理 |
| 客服 | 客户咨询与投诉 |

---

## 二、客户端功能（用户端）

### 2.1 首页

| 功能 | 说明 |
|------|------|
| 发单入口 | 帮我送/帮我买/帮我办三大入口 |
| 分类图标 | 文件、鲜花、蛋糕、生鲜、超市、药品等 |
| 活动 banner | 优惠券、新用户活动、红包 |
| 常用地址 | 快速选择发件/收件地址 |
| 订单入口 | 查看进行中订单 |

### 2.2 发单流程

#### 2.2.1 帮我送

| 步骤 | 字段 | 说明 |
|------|------|------|
| 1 | 发件人信息 | 姓名、电话、地址（定位/手动输入） |
| 2 | 收件人信息 | 姓名、电话、地址 |
| 3 | 物品信息 | 物品类型（小文件/中小件/中件/大事物）、备注 |
| 4 | 保险服务 | 报价/不保价 |
| 5 | **红包抵扣** | 选择可用红包抵扣部分费用 |
| 6 | 优惠券 | 选择可用优惠券 |
| 7 | 费用明细 | 配送费 + 保价费 - 红包 - 优惠 |
| 8 | 立即发单 | 提交订单并支付 |

#### 2.2.2 帮我买

| 步骤 | 字段 | 说明 |
|------|------|------|
| 1 | 购买地址 | 选择要购买的商家/超市 |
| 2 | 收件人信息 | 姓名、电话、送货地址 |
| 3 | 商品清单 | 商品名称、数量、规格要求 |
| 4 | 预期价格 | 买家预期价格（参考） |
| 5 | 垫付费用 | 预付商品费用 |
| 6 | 配送费 | 配送服务费用 |

#### 2.2.3 帮我办

| 步骤 | 字段 | 说明 |
|------|------|------|
| 1 | 收件人信息 | 姓名、电话、地址 |
| 2 | 办理事项 | 事项类型、详细描述 |
| 3 | 办理要求 | 时间要求、注意事项 |
| 4 | 凭证交付 | 是否需要回执 |
| 5 | 垫付费用 | 可能需要的费用 |
| 6 | 配送费 | 服务费用 |

### 2.3 地址管理

| 功能 | 说明 |
|------|------|
| 我的地址 | 地址列表、默认地址设置、编辑/删除 |
| 地址簿 | 常用地址收藏、管理 |
| 地图定位 | GPS自动定位、手动选点 |
| 历史地址 | 最近使用过的地址 |

### 2.4 订单管理

#### 2.4.1 订单列表

| Tab | 说明 |
|-----|------|
| 全部 | 所有订单 |
| 待支付 | 待付款订单 |
| 待取货 | 骑手待取件 |
| 配送中 | 正在配送 |
| 已完成 | 已签收订单 |
| 已取消 | 已取消订单 |

#### 2.4.2 订单详情

| 模块 | 内容 |
|------|------|
| 订单状态 | 状态、时间轴 |
| 骑手信息 | 头像、姓名、电话、**实时位置（地图）** |
| 地图轨迹 | 骑手当前位置、配送路线 |
| 物品信息 | 物品类型、重量、备注 |
| 费用明细 | 配送费、保价费、优惠金额、**红包抵扣**、实付金额 |
| 发件人 | 姓名、电话、地址 |
| 收件人 | 姓名、电话、地址 |
| 操作按钮 | 联系骑手、取消订单、查看面单、催单 |

### 2.5 会员中心

| 功能 | 说明 |
|------|------|
| 会员等级 | 当前等级、升级进度 |
| 积分余额 | 可用积分、积分明细 |
| **积分商城** | 积分兑换优惠券/礼品入口 |
| **我的优惠券** | 红包+优惠券列表 |
| 会员权益 | 等级特权说明 |

### 2.6 积分商城

| 功能 | 说明 |
|------|------|
| 商品列表 | 可用积分兑换的商品/优惠券 |
| 商品详情 | 图片、名称、所需积分、库存 |
| 兑换记录 | 历史兑换记录 |
| 积分明细 | 积分获取/使用明细 |

### 2.7 钱包与优惠券

#### 2.7.1 我的钱包

| 功能 | 说明 |
|------|------|
| 账户余额 | 当前可用余额 |
| **红包** | 张数、立即使用入口 |
| 优惠券 | 张数、立即使用入口 |
| 充值入口 | 余额充值 |
| 消费记录 | 收支明细 |

#### 2.7.2 红包管理

| 功能 | 说明 |
|------|------|
| 我的红包 | 红包列表 |
| 可用红包 | 可使用红包 |
| 已使用 | 已使用红包 |
| 已过期 | 已过期红包 |
| 兑换红包 | 输入兑换码兑换红包 |

#### 2.7.3 优惠券

| Tab | 说明 |
|-----|------|
| 可用 | 可使用的优惠券 |
| 已使用 | 已使用的优惠券 |
| 已过期 | 已过期的优惠券 |
| 积分兑换 | 用积分兑换优惠券 |

### 2.8 帮助与客服

| 功能 | 说明 |
|------|------|
| 常见问题 | FAQ列表 |
| 联系客服 | 在线客服入口 |
| 投诉建议 | 提交投诉反馈 |
| 客服消息 | 客服会话列表 |

---

## 三、配送员端功能（骑手端）

### 3.1 骑手首页

| 模块 | 说明 |
|------|------|
| 今日收入 | 今日收益金额 |
| 订单统计 | 今日完成订单数 |
| 待抢订单 | 可抢订单数量 |
| 我的订单 | 进入订单列表 |
| 我的钱包 | 进入钱包页面 |
| 任务入口 | 待取货/配送中/待确认 |
| **实时位置** | 当前位置展示 |

### 3.2 订单大厅

| 功能 | 说明 |
|------|------|
| 待抢订单列表 | 抢单模式订单 |
| 订单卡片 | 取件地址、送达地址、距离、配送费、时限 |
| 订单详情 | 查看完整信息后抢单 |
| 地图预览 | 取件/送件位置 |

### 3.3 订单详情（骑手视角）

| 模块 | 说明 |
|------|------|
| 取件信息 | 发件人、电话、地址、到店时间 |
| 配送信息 | 收件人、电话、地址 |
| 物品信息 | 物品类型、重量、备注 |
| 费用信息 | 配送费、订单距离 |
| 地图导航 | 一键导航到取件/送件地点 |
| 操作按钮 | 确认取件、联系发件人/收件人 |

### 3.4 骑手任务

| Tab | 说明 |
|-----|------|
| 待取货 | 已接单，待取件 |
| 配送中 | 已取件，配送中 |
| 待确认 | 已送达，待确认 |
| 已完成 | 已完成的订单 |
| 已取消 | 取消的订单 |

### 3.5 骑手钱包

| 模块 | 说明 |
|------|------|
| 累计收益 | 历史总收益 |
| 账户余额 | 可提现金额 |
| 今日收入 | 今日收益 |
| 提现记录 | 体现明细 |
| 体现功能 | 申请提现到银行卡/微信 |

### 3.6 骑手中心

| 功能 | 说明 |
|------|------|
| 任务统计 | 接单数、完成率、好评率 |
| 异常订单 | 异常问题订单 |
| 联系客服 | 在线咨询 |
| 规则协议 | 平台规则、协议 |
| **位置设置** | 定位开关、上报频率设置 |

---

## 四、管理后台功能

### 4.1 调度中心（实时监控）

| 功能 | 说明 |
|------|------|
| **骑手状态分布** | 接单中/配送中/休息中人数统计 |
| **实时位置地图** | 所有在线骑手实时位置展示 |
| **骑手列表** | 头像、姓名、状态、当前位置、联系电话 |
| 待调度 | 新订单、待指派骑手 |
| 已调度 | 已分配骑手订单 |
| 调度操作 | 抢单派单、指定派单 |

### 4.2 订单管理

| 功能 | 说明 |
|------|------|
| 订单列表 | 多条件筛选、搜索 |
| 订单详情 | 完整订单信息、状态变更 |
| 订单导出 | Excel导出 |
| 取消订单 | 用户/骑手取消、后台取消 |

### 4.3 配送员管理

| 功能 | 说明 |
|------|------|
| 骑手列表 | 骑手信息、状态 |
| 骑手详情 | 档案、统计 |
| 骑手统计 | 接单量、好评率、收入 |
| 审核认证 | 骑手入驻审核 |
| **骑手定位** | 查看骑手实时位置 |

### 4.4 用户管理

| 功能 | 说明 |
|------|------|
| 用户列表 | 注册用户、活跃度 |
| 用户详情 | 订单记录、消费记录、**会员等级** |
| **会员管理** | 会员列表、等级设置 |

### 4.5 会员体系管理

#### 4.5.1 会员等级

| 功能 | 说明 |
|------|------|
| 等级列表 | 等级名称、升级门槛、权益说明 |
| 等级规则 | 成长值计算规则 |
| 权益配置 | 每等级特权设置 |

#### 4.5.2 积分规则

| 功能 | 说明 |
|------|------|
| 积分获取规则 | 下单得积分、评价得积分、活动得积分 |
| 积分使用规则 | 抵扣比例、兑换商品 |
| 积分明细 | 用户积分变动记录 |

#### 4.5.3 积分商城

| 功能 | 说明 |
|------|------|
| 商品列表 | 上架/下架商品管理 |
| 商品编辑 | 名称、图片、积分、库存 |
| 兑换记录 | 用户兑换明细 |
| 发货管理 | 实物商品发货 |

### 4.6 红包管理

#### 4.6.1 红包创建

| 字段 | 说明 |
|------|------|
| 红包名称 | 活动名称 |
| 红包类型 | 满减券/随机券/新人券 |
| 面额 | 固定金额/随机金额范围 |
| 使用门槛 | 满X元可用 |
| 发放方式 | 主动发放/用户领取/任务奖励 |
| 发放数量 | 总量/已发/剩余 |
| 有效期 | 开始时间-结束时间 |
| 适用范围 | 全部/指定分类/指定用户 |

#### 4.6.2 红包发放

| 功能 | 说明 |
|------|------|
| 批量发放 | 选择用户批量发放 |
| 定向发放 | 输入手机号发放 |
| 领取码发放 | 生成兑换码 |
| 活动发放 | 绑定活动自动发放 |
| 发放记录 | 发放历史、状态 |

### 4.7 优惠券管理

| 功能 | 说明 |
|------|------|
| 优惠券列表 | 名称、面额、使用条件 |
| **积分兑换配置** | 积分兑换优惠券规则 |
| 发放记录 | 发放用户、状态 |
| 使用统计 | 使用率、核销统计 |

### 4.8 财务管理

| 功能 | 说明 |
|------|------|
| 账单管理 | 用户充值、消费记录 |
| 提现管理 | 骑手提现审核 |
| 佣金结算 | 平台佣金统计 |

### 4.9 客服管理

| 功能 | 说明 |
|------|------|
| 消息中心 | 用户/骑手咨询 |
| 投诉管理 | 投诉工单 |
| 反馈管理 | 建议反馈 |

### 4.10 系统设置

| 功能 | 说明 |
|------|------|
| 基础配置 | 配送费规则、距离计价 |
| 配送区域 | 服务范围设置 |
| 物品类型 | 物品分类与计费 |
| 权限管理 | 角色与权限 |
| 数据字典 | 配置参数 |

---

## 五、会员体系详细设计

### 5.1 会员等级

| 等级 | 名称 | 成长值门槛 | 权益 |
|------|------|-----------|------|
| Lv.1 | 普通会员 | 0 | 1x积分 |
| Lv.2 | 银卡会员 | 500 | 1.2x积分 + 95折 |
| Lv.3 | 金卡会员 | 2000 | 1.5x积分 + 9折 + 专属客服 |
| Lv.4 | 钻石会员 | 5000 | 2x积分 + 85折 + 专属客服 + 优先配送 |

### 5.2 积分获取规则

| 行为 | 积分 | 说明 |
|------|------|------|
| 下单完成 | 订单金额×1 | 每消费1元得1积分 |
| 评价订单 | +50 | 评价完成返积分 |
| 邀请好友 | +200 | 好友首次下单 |
| 签到 | +10 | 每日签到 |
| 充值 | 充值金额×0.5 | 充值返积分 |

### 5.3 积分使用规则

| 用途 | 积分 | 说明 |
|------|------|------|
| 兑换优惠券 | 100积分 | 兑换10元优惠券 |
| 兑换红包 | 200积分 | 兑换20元红包 |
| 积分抵扣 | 100积分 = 1元 | 下单时抵扣 |
| 积分商城 | 按商品定价 | 兑换实物/虚拟商品 |

---

## 六、红包系统详细设计

### 6.1 红包类型

| 类型 | 说明 | 使用条件 |
|------|------|---------|
| 满减红包 | 满X元减Y元 | 满门槛金额 |
| 随机红包 | 随机金额 | 无门槛或满门槛 |
| 新人红包 | 仅新用户 | 首次下单 |
| 节日红包 | 节日活动发放 | 有效期限制 |
| 任务红包 | 完成任务获得 | 完成指定任务 |

### 6.2 红包发放方式

| 方式 | 说明 |
|------|------|
| 主动发放 | 后台选择用户发放 |
| 领取码 | 生成兑换码，用户输入兑换 |
| 用户领取 | 用户主动在活动页领取 |
| 任务奖励 | 完成订单/邀请等任务自动发放 |
| 积分兑换 | 积分商城兑换红包 |

### 6.3 红包抵扣规则

- 红包可抵扣订单部分费用
- 红包不可提现
- 红包过期自动作废
- 一个订单可使用一张红包
- 红包与优惠券可叠加使用

---

## 七、实时定位系统

### 7.1 骑手端定位

| 功能 | 说明 |
|------|------|
| GPS定位 | 获取骑手当前位置 |
| 位置上报 | 每30秒自动上报位置到服务器 |
| 轨迹记录 | 保存骑手配送轨迹 |
| 电量监测 | 低电量时降低上报频率 |

### 7.2 管理端监控

| 功能 | 说明 |
|------|------|
| 骑手状态分布 | 接单中/配送中/休息中人数 |
| 实时地图 | 显示所有在线骑手位置 |
| 骑手列表 | 姓名、电话、状态、位置 |
| 位置追踪 | 点击骑手查看实时位置 |
| 历史轨迹 | 查看骑手历史配送轨迹 |

### 7.3 用户端查看

| 功能 | 说明 |
|------|------|
| 订单详情 | 查看配送骑手实时位置 |
| 地图展示 | 骑手位置、配送路线 |
| 预计到达 | 根据距离计算预计时间 |
| 联系骑手 | 一键拨打电话 |

---

## 八、物流跟踪与仓库管理

### 8.1 站点管理

#### 8.1.1 站点类型

| 类型 | 说明 | 典型场景 |
|------|------|---------|
| 配送站 | 末端配送点，负责周边区域配送 | 社区配送站 |
| 中转站 | 货物中转集散 | 区域分拨中心 |
| 仓储中心 | 大型仓库，存储货物 | 城市仓 |
| 代收点 | 便利店/驿站代收 | 菜鸟驿站 |

#### 8.1.2 站点信息

| 字段 | 说明 |
|------|------|
| 站点编号 | 唯一编码 |
| 站点名称 | 站点名称 |
| 站点类型 | 配送站/中转站/仓储中心/代收点 |
| 所属区域 | 负责区域 |
| 负责人 | 姓名+电话 |
| 地址 | 详细地址 |
| 经纬度 | GPS坐标 |
| 服务范围 | 配送半径/覆盖区域 |
| 容量 | 最大存储件数 |
| 当前库存 | 当前存货数量 |
| 状态 | 营业/休息/歇业 |

#### 8.1.3 站点管理功能

| 功能 | 说明 |
|------|------|
| 站点列表 | 所有站点信息 |
| 站点详情 | 容量/库存/人员 |
| 地图展示 | 站点位置分布 |
| 区域划分 | 服务范围设置 |
| 站点调度 | 跨站点调拨 |

### 8.2 车辆管理

#### 8.2.1 车辆类型

| 类型 | 说明 | 载重 |
|------|------|------|
| 电动三轮车 | 末端配送 | ≤200kg |
| 面包车 | 中短途运输 | ≤1吨 |
| 厢式货车 | 长途运输 | ≤5吨 |
| 大货车 | 跨城运输 | ≥5吨 |

#### 8.2.2 车辆信息

| 字段 | 说明 |
|------|------|
| 车牌号 | 唯一标识 |
| 车辆类型 | 类型 |
| 载重 | 最大载重 |
| 当前位置 | 经纬度 |
| 当前状态 | 空闲/运输中/维修中 |
| 所属站点 | 绑定站点 |
| 司机 | 姓名+电话 |
| 实时位置 | GPS坐标+速度+方向 |

#### 8.2.3 车辆定位

| 功能 | 说明 |
|------|------|
| 实时位置 | 车辆当前位置 |
| 行驶轨迹 | 历史行程记录 |
| 速度监控 | 当前速度 |
| 围栏报警 | 出区域报警 |
| 状态统计 | 在线/离线/运输中 |

### 8.3 入库管理

#### 8.3.1 入库流程

```
供应商发货 → 到达站点 → 扫描签收 → 物品录入 → 分拣上架 → 入库完成
```

#### 8.3.2 入库操作

| 步骤 | 操作 | 说明 |
|------|------|------|
| 1 | 到货登记 | 司机到达，登记到货信息 |
| 2 | 单号扫描 | 扫描运单/包裹号 |
| 3 | 物品录入 | 录入物品信息（数量/重量/体积） |
| 4 | 异常登记 | 破损/少货等异常记录 |
| 5 | 分拣 | 按目的站点分拣 |
| 6 | 上架 | 分配存储位置 |
| 7 | 入库确认 | 确认入库完成 |

#### 8.3.3 入库记录

| 字段 | 说明 |
|------|------|
| 入库单号 | 唯一编码 |
| 来源 | 供应商/站点调拨/退货 |
| 运单号 | 原始运单 |
| 物品数量 | 入库件数 |
| 重量 | 总重量 |
| 体积 | 总体积 |
| 验收人 | 签收人 |
| 入库时间 | 时间 |
| 状态 | 待入库/入库中/已完成 |

### 8.4 出库管理

#### 8.4.1 出库流程

```
出库申请 → 审核 → 拣货 → 打包 → 装车 → 出库 → 配送中
```

#### 8.4.2 出库操作

| 步骤 | 操作 | 说明 |
|------|------|------|
| 1 | 出库申请 | 提交出库需求 |
| 2 | 审核 | 审核出库数量 |
| 3 | 拣货 | 按单拣选取货 |
| 4 | 打包 | 包装处理 |
| 5 | 装车 | 分配车辆装载 |
| 6 | 出库确认 | 确认出库 |
| 7 | 出发 | 开始配送 |

#### 8.4.3 出库记录

| 字段 | 说明 |
|------|------|
| 出库单号 | 唯一编码 |
| 目的站点 | 目标站点 |
| 目的地址 | 收件地址 |
| 物品数量 | 出库件数 |
| 车辆 | 分配车辆 |
| 司机 | 承运人 |
| 出库时间 | 时间 |
| 状态 | 待出库/出库中/已出库 |

### 8.5 物流进度跟踪

#### 8.5.1 物流节点

| 节点 | 说明 | 状态 |
|------|------|------|
| 已发货 | 商家发货 | ✅ |
| 到达网点 | 到达始发站点 | ✅ |
| 运输中 | 干线运输 | 🚚 |
| 到达目的 | 到达目的站点 | ✅ |
| 派送中 | 末端配送 | 🏍️ |
| 已签收 | 客户签收 | ✅ |
| 拒收 | 客户拒收 | ❌ |

#### 8.5.2 轨迹跟踪

| 功能 | 说明 |
|------|------|
| 全程轨迹 | 物流全流程节点 |
| 当前位置 | 实时位置 |
| 预计到达 | ETA时间 |
| 异常记录 | 延误/破损等 |

#### 8.5.3 多站点中转

```
[始发站] → [中转站A] → [中转站B] → [目的站] → [客户]
   ↓           ↓           ↓           ↓
 揽收      分拨       分拨        派送
```

#### 8.5.4 站点调度

| 功能 | 说明 |
|------|------|
| 调拨申请 | 站点间调货 |
| 调拨审批 | 审核调拨 |
| 调拨出库 | 调出站点操作 |
| 调拨入库 | 调入站点操作 |
| 在途跟踪 | 调拨运输跟踪 |

### 8.6 管理后台 - 站点管理

| 功能 | 说明 |
|------|------|
| 站点列表 | 所有站点管理 |
| 站点新增 | 添加新站点 |
| 站点编辑 | 修改站点信息 |
| 库存查看 | 各站点库存 |
| 调度管理 | 跨站调拨 |

### 8.7 管理后台 - 车辆管理

| 功能 | 说明 |
|------|------|
| 车辆列表 | 所有车辆 |
| 车辆新增 | 添加车辆 |
| 实时监控 | 车辆位置 |
| 轨迹回放 | 历史行程 |
| 维护记录 | 维修/保养 |

### 8.8 管理后台 - 仓储管理

| 功能 | 说明 |
|------|------|
| 入库单 | 入库记录查询 |
| 出库单 | 出库记录查询 |
| 库存查询 | 实时库存 |
| 调拨单 | 调拨记录 |
| 盘点 | 库存盘点 |

---

## 九、数据库设计

### 9.1 核心表清单（40+表）

| 分类 | 表名 | 说明 |
|------|------|------|
| 订单 | ot_order | 订单主表 |
| 订单 | ot_order_address | 订单地址 |
| 订单 | ot_order_item | 订单物品 |
| 订单 | ot_order_trace | 订单轨迹 |
| 配送员 | ot_courier | 骑手档案 |
| 配送员 | ot_courier_account | 骑手账户 |
| 配送员 | ot_courier_location | 骑手实时位置 |
| 配送员 | ot_courier_trace | 骑手轨迹 |
| 用户 | ot_user | 用户表 |
| 用户 | ot_user_member | 会员信息 |
| 用户 | ot_member_level | 会员等级 |
| 用户 | ot_point_rule | 积分规则 |
| 用户 | ot_point_log | 积分日志 |
| 商城 | ot_mall_goods | 商城商品 |
| 商城 | ot_mall_order | 商城订单 |
| 红包 | ot_coupon | 优惠券模板 |
| 红包 | ot_user_coupon | 用户红包 |
| 红包 | ot_coupon_grant | 发放记录 |
| 钱包 | ot_wallet | 钱包 |
| 钱包 | ot_wallet_log | 钱包流水 |
| 钱包 | ot_withdraw | 提现记录 |
| 站点 | ot_station | 站点信息 |
| 站点 | ot_station_storage | 站点库存 |
| 车辆 | ot_vehicle | 车辆信息 |
| 车辆 | ot_vehicle_location | 车辆实时位置 |
| 车辆 | ot_vehicle_trace | 车辆轨迹 |
| 仓储 | ot_warehouse_in | 入库记录 |
| 仓储 | ot_warehouse_out | 出库记录 |
| 仓储 | ot_warehouse_stock | 库存记录 |
| 物流 | ot_shipment | 物流运单 |
| 物流 | ot_shipment_trace | 物流节点 |
| 调拨 | ot_transfer | 站点调拨 |
| 配置 | ot_category | 服务分类 |
| 配置 | ot_region | 配送区域 |
| 配置 | ot_fare_rule | 运费规则 |
| 配置 | ot_announcement | 公告 |
| 反馈 | ot_feedback | 用户反馈 |
| 反馈 | ot_complaint | 投诉 |

### 9.2 站点相关表

#### ot_station（站点表）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint PK | |
| code | varchar(32) UK | 站点编码 |
| name | varchar(64) | 站点名称 |
| type | tinyint | 1:配送站 2:中转站 3:仓储中心 4:代收点 |
| province | varchar(32) | 省 |
| city | varchar(32) | 市 |
| district | varchar(32) | 区 |
| address | varchar(256) | 详细地址 |
| lat | decimal(10,6) | 纬度 |
| lng | decimal(10,6) | 经度 |
| manager_name | varchar(32) | 负责人 |
| manager_phone | varchar(20) | 联系电话 |
| service_radius | decimal(8,2) | 服务半径(km) |
| capacity | int | 最大容量 |
| current_stock | int | 当前库存 |
| status | tinyint | 1:营业 2:休息 3:歇业 |

#### ot_station_storage（站点库存）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint PK | |
| station_id | bigint FK | 站点ID |
| order_id | bigint FK | 订单ID |
| status | tinyint | 1:库存中 2:已出库 3:已配送 |
| shelf_no | varchar(32) | 货架号 |
| in_time | datetime | 入库时间 |
| out_time | datetime | 出库时间 |

### 9.3 车辆相关表

#### ot_vehicle（车辆表）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint PK | |
| plate_no | varchar(32) UK | 车牌号 |
| type | tinyint | 1:三轮车 2:面包车 3:厢货 4:大货 |
| load_weight | decimal(8,2) | 载重(kg) |
| station_id | bigint FK | 所属站点 |
| driver_name | varchar(32) | 司机姓名 |
| driver_phone | varchar(20) | 司机电话 |
| status | tinyint | 1:空闲 2:运输中 3:维修中 |

#### ot_vehicle_location（车辆实时位置）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint PK | |
| vehicle_id | bigint FK | |
| lat | decimal(10,6) | 纬度 |
| lng | decimal(10,6) | 经度 |
| address | varchar(256) | 地址 |
| speed | decimal(6,2) | 速度(km/h) |
| direction | int | 方向(0-360) |
| update_time | datetime | |

### 9.4 仓储相关表

#### ot_warehouse_in（入库记录）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint PK | |
| in_no | varchar(32) UK | 入库单号 |
| source_type | tinyint | 1:供应商 2:站点调拨 3:退货 |
| source_no | varchar(64) | 来源单号 |
| station_id | bigint FK | 入库站点 |
| total_count | int | 总件数 |
| total_weight | decimal(8,2) | 总重量 |
| operator_id | bigint FK | 操作人 |
| status | tinyint | 1:待入库 2:入库中 3:已完成 |
| in_time | datetime | 入库时间 |

#### ot_warehouse_out（出库记录）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint PK | |
| out_no | varchar(32) UK | 出库单号 |
| dest_station_id | bigint FK | 目的站点 |
| dest_address | varchar(256) | 目的地址 |
| vehicle_id | bigint FK | 车辆 |
| total_count | int | 总件数 |
| operator_id | bigint FK | 操作人 |
| status | tinyint | 1:待出库 2:出库中 3:已出库 |
| out_time | datetime | |

### 9.5 物流相关表

#### ot_shipment（物流运单）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint PK | |
| shipment_no | varchar(32) UK | 运单号 |
| order_id | bigint FK | 订单ID |
| origin_station_id | bigint FK | 始发站点 |
| dest_station_id | bigint FK | 目的站点 |
| current_station_id | bigint FK | 当前站点 |
| status | tinyint | 1:已发货 2:运输中 3:到达 4:派送中 5:已签收 |
| create_time | datetime | |
| update_time | datetime | |

#### ot_shipment_trace（物流节点）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint PK | |
| shipment_id | bigint FK | |
| station_id | bigint FK | 站点 |
| status | tinyint | 节点状态 |
| description | varchar(256) | 描述 |
| operator | varchar(32) | 操作人 |
| create_time | datetime | |

### 9.6 会员相关表

#### ot_user_member

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint PK | |
| user_id | bigint FK | 用户ID |
| level_id | bigint FK | 等级ID |
| growth_value | int | 成长值 |
| total_points | int | 累计积分 |
| available_points | int | 可用积分 |
| total_consume | decimal(12,2) | 累计消费 |
| join_time | datetime | 加入时间 |
| expire_time | datetime | 等级到期时间 |

#### ot_member_level

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint PK | |
| name | varchar(32) | 等级名称 |
| icon | varchar(128) | 等级图标 |
| growth_min | int | 成长值下限 |
| growth_max | int | 成长值上限 |
| point_rate | decimal(4,2) | 积分倍率 |
| discount | decimal(4,2) | 折扣率 |
| benefits | text | 权益说明 |
| sort | int | 排序 |

#### ot_point_rule

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint PK | |
| type | varchar(32) | 规则类型 |
| name | varchar(64) | 规则名称 |
| points | int | 积分值 |
| rule_config | json | 规则配置 |
| status | tinyint | 状态 |

#### ot_mall_goods

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint PK | |
| name | varchar(64) | 商品名称 |
| type | tinyint | 1:优惠券 2:实物 3:红包 |
| image | varchar(256) | 商品图片 |
| points | int | 所需积分 |
| stock | int | 库存 |
| cost | decimal(8,2) | 成本价 |
| status | tinyint | 上架/下架 |

### 8.3 红包相关表

#### ot_coupon（优惠券/红包模板）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint PK | |
| name | varchar(64) | 名称 |
| type | tinyint | 1:优惠券 2:红包 |
| subtype | tinyint | 满减/随机/新人 |
| amount | decimal(8,2) | 面额 |
| min_amount | decimal(8,2) | 满减门槛 |
| max_deduct | decimal(8,2) | 最高抵扣 |
| total_count | int | 发放总量 |
| remain_count | int | 剩余数量 |
| per_limit | int | 每人限领 |
| start_time | datetime | 开始时间 |
| end_time | datetime | 结束时间 |
| valid_days | int | 领取后有效天数 |
| apply_range | varchar(128) | 适用范围 |
| status | tinyint | 状态 |

#### ot_user_coupon

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint PK | |
| user_id | bigint FK | 用户ID |
| coupon_id | bigint FK | 优惠券ID |
| order_id | bigint FK | 使用订单 |
| type | tinyint | 1:优惠券 2:红包 |
| name | varchar(64) | 名称 |
| amount | decimal(8,2) | 面额 |
| min_amount | decimal(8,2) | 满减门槛 |
| status | tinyint | 未使用/已使用/已过期 |
| receive_time | datetime | 领取时间 |
| use_time | datetime | 使用时间 |
| expire_time | datetime | 过期时间 |

#### ot_coupon_grant

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint PK | |
| coupon_id | bigint FK | 优惠券ID |
| user_id | bigint FK | 用户ID（可为空） |
| grant_type | tinyint | 发放方式 |
| grant_no | varchar(64) | 发放批次号 |
| code | varchar(32) | 兑换码 |
| status | tinyint | 状态 |
| create_time | datetime | 发放时间 |
| use_time | datetime | 使用时间 |

### 8.4 骑手定位表

#### ot_courier_location

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint PK | |
| courier_id | bigint FK | |
| lat | decimal(10,6) | 纬度 |
| lng | decimal(10,6) | 经度 |
| address | varchar(256) | 地址 |
| battery | int | 电量 |
| update_time | datetime | 更新时间 |

#### ot_courier_trace

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint PK | |
| courier_id | bigint FK | |
| order_id | bigint FK | 配送订单 |
| lat | decimal(10,6) | 纬度 |
| lng | decimal(10,6) | 经度 |
| create_time | datetime | 时间 |

---

## 九、API接口设计

### 9.1 用户端 - 会员与积分

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /app/ot/member/info | 会员信息 |
| GET | /app/ot/member/level | 等级权益 |
| GET | /app/ot/point/log | 积分明细 |
| GET | /app/ot/point/balance | 积分余额 |
| POST | /app/ot/point/sign | 每日签到 |

### 9.2 用户端 - 积分商城

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /app/ot/mall/goods | 商品列表 |
| GET | /app/ot/mall/goods/detail | 商品详情 |
| POST | /app/ot/mall/order/create | 兑换订单 |
| GET | /app/ot/mall/order/page | 兑换记录 |

### 9.3 用户端 - 红包与优惠券

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /app/ot/coupon/page | 优惠券列表 |
| GET | /app/ot/coupon/my | 我的红包/优惠券 |
| POST | /app/ot/coupon/claim | 领取优惠券 |
| POST | /app/ot/coupon/exchange | 兑换码兑换 |
| GET | /app/ot/coupon/available | 可用红包 |

### 9.4 骑手端 - 位置

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /app/ot/courier/location/update | 上报位置 |
| GET | /app/ot/courier/location/current | 当前状态 |
| POST | /app/ot/courier/setting | 位置设置 |

### 9.5 管理端 - 会员管理

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /admin/ot/member/page | 会员列表 |
| POST | /admin/ot/member/level/page | 等级列表 |
| POST | /admin/ot/member/level/add | 添加等级 |
| POST | /admin/ot/point/rule/page | 积分规则 |
| POST | /admin/ot/point/rule/add | 添加规则 |

### 9.6 管理端 - 红包管理

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /admin/ot/coupon/page | 红包/优惠券列表 |
| POST | /admin/ot/coupon/add | 创建红包 |
| POST | /admin/ot/coupon/update | 编辑红包 |
| POST | /admin/ot/coupon/grant | 发放红包 |
| POST | /admin/ot/coupon/batch | 批量发放 |
| POST | /admin/ot/coupon/code | 生成兑换码 |

### 9.7 管理端 - 积分商城

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /admin/ot/mall/goods/page | 商品列表 |
| POST | /admin/ot/mall/goods/add | 添加商品 |
| POST | /admin/ot/mall/goods/update | 编辑商品 |
| POST | /admin/ot/mall/order/page | 兑换订单 |
| POST | /admin/ot/mall/order/ship | 实物发货 |

### 9.8 管理端 - 实时监控

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /admin/ot/courier/location/all | 所有骑手位置 |
| GET | /admin/ot/courier/location/one | 单个骑手位置 |
| GET | /admin/ot/courier/trace | 骑手历史轨迹 |
| GET | /admin/ot/courier/status/stats | 骑手状态统计 |

---

## 十、计费规则

### 10.1 配送费计算

```
配送费 = 基础费用 + 距离费用 + 时段费用 + 保价费

基础费用：首公里 ¥3.00
距离费用：(总距离 - 1km) × ¥1.50/km
时段费用：高峰期 ¥2.00
保价费：保价金额 × 0.3%
```

### 10.2 红包/优惠券抵扣

```
实付金额 = 配送费 + 保价费 - 红包抵扣 - 优惠券抵扣
```

### 10.3 积分抵扣

```
积分抵扣金额 = 可用积分 ÷ 100
每个订单最高抵扣 ¥10
```

---

## 十一、技术架构与开发方案

### 11.1 技术栈演进路线

| 阶段 | 后端语言 | 优势 | 适用场景 |
|------|----------|------|----------|
| Phase 1-2 | **Python/FastAPI** | 快速开发/迭代 | MVP/验证业务 |
| Phase 3-4 | **Python + Go微服务** | 高并发/性能 | 中等规模/增长期 |
| Phase 5-6 | **Go + Java** | 集群/高可用/复杂业务 | 大规模/企业级 |

**演进原则**：
- Phase 1-2：追求速度，使用 Python/FastAPI 快速上线验证业务
- Phase 3+：根据负载情况，将性能关键服务（如订单/调度/位置）迁移到 Go
- Phase 5+：引入 Java 生态处理复杂业务（财务/报表/BI）

---

### 11.2 部署架构演进

#### Phase 1：单点部署（MVP）

**架构图**：
```
┌─────────────────────────────────────┐
│            负载均衡 (Nginx)          │
└─────────────────────────────────────┘
                  │
    ┌─────────────┼─────────────┐
    ▼             ▼             ▼
┌────────┐  ┌────────┐  ┌────────┐
│ API S1 │  │ API S2 │  │ API S3 │  ← Python/FastAPI
└────────┘  └────────┘  └────────┘
    │             │             │
    └─────────────┼─────────────┘
                  ▼
    ┌─────────────────────────────┐
    │      MySQL (主从)            │
    │      Redis (缓存/会话)       │
    │      MinIO (文件存储)        │
    └─────────────────────────────┘
```

**配置**：
| 组件 | 规格 | 说明 |
|------|------|------|
| API服务器 | 2核4G × 2 | 最小生产环境 |
| MySQL | 2核4G | 主从部署 |
| Redis | 1核2G | 缓存+会话 |
| 负载均衡 | SLB | 阿里云/腾讯云 |

**适用场景**：
- 日订单量 < 10,000
- 日活用户 < 50,000
- 并发用户 < 500

---

#### Phase 3：集群部署（增长期）

**架构图**：
```
                    ┌──────────────┐
                    │   CDN        │
                    └──────────────┘
                           │
                    ┌──────────────┐
                    │  负载均衡     │
                    │ (Nginx/Lvs)  │
                    └──────────────┘
                           │
        ┌──────────┬───────┴───────┬──────────┐
        ▼          ▼               ▼          ▼
   ┌────────┐ ┌────────┐     ┌────────┐ ┌────────┐
   │Order S │ │User S  │     │Map S   │ │Pay S   │  ← Go 微服务
   └────────┘ └────────┘     └────────┘ └────────┘
        │          │               │          │
        └──────────┴───────┬───────┴──────────┘
                           ▼
              ┌────────────────────────┐
              │     RPC (gRPC)         │
              │  - ETCD (注册中心)     │
              │  - Jaeger (链路追踪)   │
              └────────────────────────┘
                           │
        ┌──────────┬───────┴───────┬──────────┐
        ▼          ▼               ▼          ▼
   ┌────────┐ ┌────────┐     ┌────────┐ ┌────────┐
   │ MySQL  │ │ Redis  │     │Kafka  │ │MongoDB │  ← 分库分表
   │Cluster │ │Cluster │     │       │ │        │
   └────────┘ └────────┘     └────────┘ └────────┘
```

**新增组件**：
| 组件 | 用途 | 说明 |
|------|------|------|
| gRPC | 服务间RPC | 高性能二进制协议 |
| ETCD | 服务发现/注册 | 动态扩缩容 |
| Kafka | 消息队列 | 异步解耦/削峰 |
| Jaeger | 链路追踪 | 分布式追踪 |
| Docker | 容器化 | 快速部署 |

**配置**：
| 组件 | 规格 | 数量 |
|------|------|------|
| API服务器 | 4核8G | 4+ |
| MySQL集群 | 8核16G | 3 |
| Redis集群 | 4核8G | 3 |
| Kafka | 4核8G | 3 |

**适用场景**：
- 日订单量 10,000 - 100,000
- 日活用户 50,000 - 500,000
- 并发用户 500 - 5,000

---

#### Phase 5+：多集群/多地域（企业级）

**架构图**：
```
                    ┌──────────────┐
                    │   全局负载均衡 │
                    │   (DNS/GSLB) │
                    └──────────────┘
                           │
        ┌──────────────────┼──────────────────┐
        ▼                  ▼                  ▼
   ┌─────────┐        ┌─────────┐        ┌─────────┐
   │ 华北区   │        │ 华南区   │        │ 华东区   │
   │ 集群    │        │ 集群    │        │ 集群    │
   └─────────┘        └─────────┘        └─────────┘
        │                  │                  │
        └──────────────────┼──────────────────┘
                           ▼
              ┌────────────────────────┐
              │     统一网关层           │
              │  - Kong/APISIX         │
              │  - OAuth2.0            │
              │  - Rate Limit          │
              └────────────────────────┘
                           │
        ┌──────────┬───────┴───────┬──────────┐
        ▼          ▼               ▼          ▼
   ┌────────┐ ┌────────┐     ┌────────┐ ┌────────┐
   │订单集群│ │用户集群│     │支付集群│ │物流集群│
   └────────┘ └────────┘     └────────┘ └────────┘
        │          │               │          │
        └──────────┴───────┬───────┴──────────┘
                           ▼
              ┌────────────────────────┐
              │     数据总线            │
              │  - Kafka/ RocketMQ   │
              │  - Canal (同步)        │
              └────────────────────────┘
                           │
        ┌──────────┬───────┴───────┬──────────┐
        ▼          ▼               ▼          ▼
   ┌────────┐ ┌────────┐     ┌────────┐ ┌────────┐
   │MySQL  │ │TiDB   │     │ES     │ │HBase  │ ← OLAP/OLTP
   │主库   │ │分布式  │     │搜索   │ │日志   │
   └────────┘ └────────┘     └────────┘ └────────┘
```

**多地域部署策略**：
| 策略 | 说明 | 适用 |
|------|------|------|
| 同城双活 | 主备机房容灾 | 高可用 |
| 两地三中心 | 异地容灾 | 数据安全 |
| 多地域就近接入 | 就近访问 | 用户体验 |

**适用场景**：
- 日订单量 > 100,000
- 日活用户 > 500,000
- 并发用户 > 5,000
- 多地域运营

---

### 11.3 服务拆分与 RPC 设计

#### Phase 1：单体架构（推荐起步）

**服务划分**：单一应用，按模块组织代码

```
app/
├── modules/
│   ├── order/       # 订单模块
│   ├── user/        # 用户模块
│   ├── courier/     # 骑手模块
│   ├── payment/     # 支付模块
│   └── ...
└── core/            # 公共组件
```

**优点**：
- 快速迭代，无需考虑服务间通信
- 调试简单，单点追踪
- 部署简单

**缺点**：
- 扩展性有限
- 技术栈单一

---

#### Phase 3：微服务拆分

**服务列表**：

| 服务名 | 职责 | 关键技术 | 扩展性 |
|--------|------|----------|--------|
| user-service | 用户/会员/积分 | Python/Go | 高 |
| order-service | 订单/调度/轨迹 | Go | 极高 |
| courier-service | 骑手/定位/任务 | Go | 高 |
| payment-service | 支付/钱包/账单 | Java | 中 |
| marketing-service | 红包/优惠券/活动 | Python | 高 |
| map-service | 地图/距离/导航 | 高德/腾讯SDK | 中 |
| notification-service | 推送/短信/消息 | Go | 高 |
| data-service | 统计/报表/BI | Java+ES | 中 |

**RPC 框架选择**：

| 框架 | 语言 | 优势 | 适用场景 |
|------|------|------|----------|
| **gRPC** | 多语言 | 高性能/二进制/双向流 | 服务间通信 |
| **Thrift** | 多语言 | 成熟/广泛 | 跨语言调用 |
| **Dubbo** | Java | 生态完善/Spring | Java技术栈 |

**推荐**：Phase 3 使用 **gRPC + Protobuf**

---

#### RPC 接口设计示例（gRPC）

```protobuf
// order.proto
syntax = "proto3";

package delivery;

service OrderService {
  rpc CreateOrder(CreateOrderRequest) returns (CreateOrderResponse);
  rpc GetOrder(GetOrderRequest) returns (Order);
  rpc CancelOrder(CancelOrderRequest) returns (CancelOrderResponse);
  rpc AssignCourier(AssignCourierRequest) returns (AssignCourierResponse);
}

message CreateOrderRequest {
  int64 user_id = 1;
  string service_type = 2;
  Address sender = 3;
  Address receiver = 4;
  GoodsInfo goods = 5;
}

message Order {
  int64 order_id = 1;
  string order_no = 2;
  int64 user_id = 3;
  int64 courier_id = 4;
  int32 status = 5;
  decimal amount = 6;
}
```

---

### 11.4 数据库设计策略

#### 分库分表策略（Phase 5+）

| 表 | 分片策略 | 分片键 | 说明 |
|----|----------|--------|------|
| ot_order | Hash | user_id | 按用户查询 |
| ot_courier | Hash | courier_id | 按骑手查询 |
| ot_station | Hash | station_id | 按站点查询 |
| ot_wallet | Hash | user_id | 按用户查询 |
| ot_shipment | Range | create_time | 按时间查询 |

#### 数据库选型

| 场景 | 数据库 | 说明 |
|------|--------|------|
| OLTP | MySQL / TiDB | 事务性数据 |
| OLAP | ClickHouse / Doris | 报表分析 |
| 缓存 | Redis / Memcached | 热数据 |
| 搜索 | Elasticsearch | 全文搜索 |
| 文件 | MinIO / OSS | 文件存储 |
| 日志 | MongoDB / HBase | 日志存储 |

---

### 11.5 自动化与 DevOps

#### CI/CD 流程

```
代码提交 → GitLab CI → 构建镜像 → 单元测试
                                    ↓
代码审查 ← 部署预览 ← 集成测试 ← 镜像推送
                                    ↓
                        Kubernetes 自动发布
```

#### 自动化覆盖

| 阶段 | 工具 | 说明 |
|------|------|------|
| 构建 | GitLab CI / Jenkins | 自动构建 |
| 测试 | pytest / JUnit | 单元/集成测试 |
| 镜像 | Docker / BuildKit | 容器化 |
| 编排 | Kubernetes / Docker Swarm | 容器编排 |
| 监控 | Prometheus + Grafana | 监控报警 |
| 日志 | ELK / Loki | 日志收集 |
| 链路 | Jaeger / SkyWalking | 分布式追踪 |

---

### 11.6 阶段性技术债务

| 阶段 | 技术债 | 处理策略 |
|------|--------|----------|
| Phase 1→2 | 单体架构扩展性差 | 预留模块化设计 |
| Phase 2→3 | Python GIL限制 | 关键路径迁移Go |
| Phase 3→5 | 数据库单点 | 引入分库分表 |
| Phase 4→5 | 缺乏监控 | 引入APM |
| Phase 5+ | 技术栈不统一 | 统一gRPC协议 |

---

### 11.7 开发团队配置（参考）

| 阶段 | 后端 | 前端 | 运维 | DBA | 测试 |
|------|------|------|------|-----|------|
| Phase 1 | 2-3人 | 1-2人 | 0.5人 | 0 | 0.5人 |
| Phase 3 | 4-5人 | 2-3人 | 1人 | 0.5人 | 1人 |
| Phase 5+ | 6-8人 | 3-4人 | 2人 | 1人 | 2人 |

---

### 11.8 风险与应对

| 风险 | 等级 | 应对措施 |
|------|------|----------|
| 高并发下单 | 高 | 排队机制/限流/缓存 |
| 支付安全 | 极高 | 第三方支付/对账 |
| 数据一致性 | 高 | 分布式事务/TCC |
| 服务雪崩 | 中 | 熔断/降级/隔离 |
| 数据泄漏 | 高 | 加密/脱敏/审计 |

---

## 十二、LLM / RAG 等 AI 能力拓展（可选）

**独立 HTML（含流程图与 AI-1～AI-5 迭代路线）**：`doc/ai_capabilities.html`  
**文档快捷入口**：`doc/quick_menu.html`

### 12.1 定位说明

在即时配送与仓储物流场景中，大模型与 RAG（检索增强生成）适合作为**辅助能力**：降低客服与运营人力、提升工单与知识处理效率，**不替代**订单支付、调度锁单、库存事务等**强一致核心业务**（仍由传统后端与数据库保证）。

### 12.2 可落地的功能与业务流程（建议优先级）

| 能力模块 | 实现思路 | 用户/运营收益 | 复杂度 |
|----------|----------|----------------|--------|
| **智能客服 / 工单摘要** | 对接微信客服或 Web 聊天；RAG 挂载 FAQ、计费规则、服务范围 | 7×24 常见问题自动答复；会话摘要写入工单 | 中 |
| **订单与物流状态自然语言查询** | NL → 结构化查询（需权限校验 + 仅返回当前用户数据） | 用户用口语查「我的订单到哪了」 | 中高 |
| **运营助手（报表问答）** | RAG + 受控 SQL/指标 API（禁止模型直连写库） | 老板/站长问「本周各站妥投率」 | 高 |
| **入库/出库话术与 SOP 引导** | 库管端步骤提示、异常话术（依赖知识库） | 降低培训成本、减少误操作沟通成本 | 中 |
| **营销文案与活动页草稿** | LLM 生成 + 人工审核发布 | 运营提效 | 低 |
| **评价情感分析与风控提示** | 批量打标差评原因，辅助客服介入 | 体验与舆情预警 | 中 |

**推荐业务流程（客服 RAG 示例）**：

```
用户提问 → 鉴权(会话绑定 user_id) → 向量检索 FAQ/政策片段 → LLM 生成回答
         → 若置信度低 → 转人工 + 附带检索片段
         → 日志落库（不含敏感全文可脱敏）→ 运营定期更新知识库
```

### 12.3 基础方案设计（技术概要）

| 组件 | 方案选项 | 说明 |
|------|----------|------|
| 模型 | 公有云 API（如通义/文心/OpenAI 兼容接口）或私有化部署 | 数据合规决定选型 |
| RAG | 向量库（Milvus / pgvector / ES 向量）+ 文档切分 + 定期同步 | 政策/FAQ/站点手册 |
| 编排 | LangChain / 自研 Pipeline / 低代码 Agent 平台 | 与现有 Java/Python/Go 后端 HTTP 对接 |
| 安全 | 不将完整订单明细喂给模型；查询走后端 API；输出审计 | 防泄漏与幻觉 |

### 12.4 大致成本构成（量级参考，非承诺）

> 与 **0.10** 相同：**以下为粗略量级**，以实际调用量、是否私有化、知识库规模为准。

| 成本项 | 说明 | 量级参考 |
|--------|------|----------|
| 开发集成 | 客服入口 + RAG 管线 + 管理端知识库维护 | 约 15～40 人天（视渠道数与权限复杂度） |
| 模型调用 | Token 计费（问答 + 摘要） | 月均几百～数千元（小流量）；大流量按比例上升 |
| 向量库与存储 | 向量索引、对象存储 | 通常可并入现有云资源，边际较低 |
| 运维 | 知识库更新流程、监控告警 | 可持续占用 0.2～0.5 人力 |

### 12.5 价值总结

- **降本**：减少重复性客服与培训成本。  
- **体验**：用户用自然语言获取状态与规则说明。  
- **风险可控**：通过「后端鉴权 + RAG 边界 + 人工兜底」控制幻觉与数据泄露。  
- **与主系统解耦**：可作为 **Phase 2～3 之后**的独立迭代包，不影响核心交易链路按时上线。

---

**文档版本**：v5.0  
**创建日期**：2026-04-01  
**更新**：数据库详情（多租户/站点权限/审计/软删除）、阶段工时费用暂估说明、LLM/RAG 拓展方案