云驰智运 YunChi
官网 · 文档中心 · 完整功能说明书 v1.1

完整功能说明书 v1.1

25 章覆盖 90+ 模块的业务定义 · 云驰智运 YunChi · Smart Logistics Cloud

云驰智运 · 完整功能说明书（v1.1 / Sprint 25 截稿）

项目代号：YunChi 云驰智运 一句话定位：面向中大型物流企业的双运力 + 多分站 + 全链路智能 SaaS 一体化平台。

0. 目录

  1. 业务定位与角色矩阵
  2. C 端 / 货主 App 功能
  3. B 端 / 个人车主 App 功能
  4. 物流公司 / 配货站后台
  5. 平台总后台 + 管理台
  6. 财务结算与多渠道支付
  7. 调度与运力优化（含 AI / 强化学习预留）
  8. 运单 / 货物 / 轨迹 / 单据打印
  9. IoT 车联网 + 时序数据
  10. 跨境 / 海关 / CBAM
  11. AIGC（OCR / 智能客服 / 营销文案）
  12. 区块链存证 + NFT 签收
  13. 数字孪生 + MEC 边缘计算
  14. AR 验收 / 司机园区导航
  15. AI 异常检测 + LLM 告警摘要
  16. 多端登录 / SSO / 数据脱敏
  17. 可观测体系（Logs / Metrics / Traces / Profiling / eBPF）
  18. 安全合规（PQC / TEE / CoCo / SLSA / Kyverno）
  19. DevOps / GitOps / 多云调度
  20. 数据治理（湖仓 / 血缘 / 搜索）
  21. OpenAPI / DevPortal / SDK
  22. 灾备 / 多集群联邦
  23. 信创全栈适配
  24. 业务规则热更新（WASM）
  25. 增长引擎（YC 积分 + B2B 渠道）

1. 业务定位与角色矩阵

1.1 5 大角色 + 3 级 RBAC

角色 主要场景 入口
货主（C 端） 下单、追踪、签收、对账 uni-app H5 / 小程序 / iOS / Android
个人车主（B 端） 抢单、运输打卡、收款 uni-app App
物流公司 自有车队管理、订单分配 admin-pc Web
配货站 货车撮合、抽佣 admin-pc Web
平台管理员 全局调度、风控、财务、运营 admin-pc Web

权限模型：Tenant → Role → Permission（资源 + 操作粒度），多租户行级隔离 tenant_id。

1.2 双运力 + 多分站

  • 同一订单可路由到「自有车队」或「平台撮合的个人车主」
  • 总公司 - 分站二级体系；分站独立结算、跨站协同（订单跨分站交接、佣金分润）

2. C 端 / 货主 App

  • 下单：常规 / 整车 / 零担 / 大件 / 冷链 / 跨境
  • 询价：实时计费（基于 WASM 规则引擎，运营可热更）
  • 追踪：高德 / 百度地图 + 车辆实时轨迹（VictoriaMetrics 时序）
  • 签收：电子签字 + AR 验收 + NFT 上链
  • 对账：账单导出 PDF / Excel
  • 客服：AIGC 智能客服 + 转人工

3. B 端 / 个人车主 App

  • 实名认证 + 人脸核身 + 驾驶证 OCR（百度/通义 OCR）
  • 接单大厅：基于地理位置 + 车型 + 运力评分
  • 行程：起点/终点导航 + 园区 AR 月台导航
  • 收款：T+1 自动结算到银行卡 / 微信
  • 信用：完成单数、好评率、违约扣分

4. 物流公司 / 配货站后台

  • 车辆 / 司机管理 + 车辆保养 / 年检提醒
  • 订单池 + 智能分单（强化学习 PPO 预留）
  • 撮合大厅（配货站）+ 抽佣比例配置
  • 多分站协同 + 跨分站交接单
  • 单据打印（PC Lodop / 移动 ESC/POS） — 15 类单据

5. 平台总后台

  • 租户管理（B 端开通 / 套餐 / 配额）
  • 全局风控（限流 / 黑名单 / 异常订单）
  • 实时大屏（Superset / Grafana）
  • 财务总账 + 分润对账
  • 运营活动（优惠券 / 推荐返佣）

6. 财务结算

渠道 状态
微信 V3 / 支付宝 v3 适配层 PayProvider 已就位（生产替换 Mock）
银联无卡支付 同上
跨境多币种 USD/EUR/HKD 实时汇率，T+2 跨境结算
分账 平台 - 公司 - 分站 - 司机 四方分账
发票 增值税电子发票 API（票麦/航信）

7. 调度与运力优化

  • 启发式分单：距离 + 车型 + 信用 + 价格 4 维加权
  • AI 强化学习（PPO）预留接口（Sprint 25 候选）
  • 司机推荐：协同过滤 + 实时画像

8. 运单 / 单据

  • 15 类单据（运单 / 提货单 / 送货单 / 回单 / 装箱单 / 报关单...）
  • PC 端 Lodop 套打；移动端蓝牙 ESC/POS（佳博/芝柯/汉印）
  • 模板可视化设计器（admin-pc 内嵌）

9. IoT 车联网

  • 车载终端 MQTT 上报：位置 / 油耗 / 速度 / 温湿度（冷链）
  • 时序存储：VictoriaMetrics（5000 车 17 亿点/天 ≈ 3GB）
  • 异常检测：Z-Score + IQR 双方法（油耗骤降、围栏越界）
  • 数字孪生：3D 园区 + 车辆实时姿态

10. 跨境 / 海关

  • 多币种 + 汇率快照
  • 报关单生成（China Single Window 适配层）
  • CBAM 碳关税计算（欧盟出口）

11. AIGC

  • 智能客服（FAQ + 大模型问答）
  • OCR：身份证 / 驾驶证 / 行驶证 / 报关单
  • 营销文案 / 推送话术生成

12. 区块链

  • NFT 签收存证（ERC-721 简化实现）
  • 跨链消息（Polygon ↔ BSC 桥接占位）

13. 数字孪生 + MEC

  • 园区 3D 模型 + 车辆姿态联动
  • MEC 边缘节点：低延迟视频推理（车辆牌照 / 闯岗）

14. AR

  • 司机园区 AR 导航（WebXR）
  • 客户 AR 验收（WebXR hit-test + NFT 存证）

15. 智能 Ops

  • AI 异常检测：业务时序（订单量 / GMV / P99）
  • LLM 告警摘要：Alertmanager → 一句话故障简报（Ollama 本地化部署）

16. 多端登录 / SSO

  • OIDC：企业微信 / 钉钉 / Google
  • SAML 2.0：客户内网 AD / Okta
  • 数据脱敏：手机 / 邮箱 / 身份证 / 银行卡 / 姓名 / 地址（@Sensitive 注解 + Jackson）

17. 可观测

维度 工具
Metrics Prometheus / VictoriaMetrics + Grafana
Logs Loki + Grafana / 备 ELK
Traces Tempo + OpenTelemetry SDK + W3C 传播
Profiling Pyroscope（JFR 模式 < 1% CPU）
内核 / 协议 Pixie eBPF / Cilium Hubble
安全事件 Falco modern-bpf

18. 安全合规

  • PQC：CRYSTALS-Kyber + Dilithium 签名（量子安全过渡）
  • TEE：SGX Enclave SDK（小数据高敏感）
  • CoCo：Kata + TDX（容器级全程加密内存）
  • 供应链：SLSA L3（cosign keyless + provenance + SBOM CycloneDX）
  • 准入：Kyverno ClusterPolicy 仅放行已签名镜像

19. DevOps

  • CI：GitHub Actions（构建 / 测试 / 安全扫描 / 镜像签名）
  • CD：Argo CD GitOps + Helm
  • ARM64 信创：buildx 多架构 amd64+arm64 镜像
  • Serverless：Knative + KEDA（突发型 worker：缩略 / PDF / 批量短信）
  • 多集群联邦：Istio Multi-Primary（沪/穗/海外）

20. 数据治理

  • 湖仓：Iceberg + Flink + Trino（实时 + 离线统一）
  • 数据血缘：OpenLineage + Marquez / DataHub
  • 搜索：Lucene 9 全文检索 + ES 审计索引

21. OpenAPI / DevPortal

  • OpenAPI 3.1 自动导出
  • SDK：Java / Node / Python / Go（openapi-generator）
  • 沙箱网关：sandbox-api.* 每日重置
  • Webhook：HMAC-SHA256 签名 + 重试 5 次

22. 灾备

  • DRaaS：跨区域热备 + RPO 5min / RTO 30min
  • 多集群联邦：任一集群故障不影响其他

23. 信创全栈

  • CPU：鲲鹏 / 飞腾 / 龙芯
  • OS：麒麟 V10 / UOS V20 / openEuler / Loongnix
  • 数据库：达梦 DM8 适配（init-dm.sql）
  • 中间件：东方通 / TongRDS

24. WASM 业务规则热更新

  • 运费阶梯 / 路由策略 / 风控阈值 → Rust/AS 编译 wasm 上传
  • 影子模式灰度 → 阶梯放量 → 一键回滚

25. 增长引擎（logistics-growth）

25.1 双轨设计

轨道 子包 受众 货币 资金性质
B2B 商务渠道 partner/ 渠道伙伴 / SI 集成商 人民币现金 财务返佣（按客户回款释放）
C/B 端推广 point/ 货主 / 司机 / 配货站 YC 积分（虚拟币，不可提现） 平台运营成本

两套完全隔离，开关独立 growth.point.enabled / growth.partner.enabled，可按区域 / 阶段分别启停。

25.2 YC 积分引擎（C/B 端）

  • 一级邀请严格制：A 推 B → A 得奖；B 再推 C 与 A 无关（合规防层级计酬）
  • 三阶段奖励：实名 500 / 首单 1500 / 90 天交易 ¥5000+ 奖 2000；新人礼包 300
  • 业务必消耗：发布货源 30 YC、车源 10 YC、查看联系方式 5 YC、置顶 200-500 YC、群发匹配 100 YC、抵扣订单费 100 YC = ¥1（最多抵 30%）
  • FIFO 12 月过期：每条 EARN 流水带 remaining + expire_at，SPEND 按时间正序扣批次；每日 0:05 ExpireJob 清理过期
  • CAS 防超扣：UPDATE yc_account SET balance=balance+:delta WHERE balance+:delta >= 0
  • 反作弊四维去重：设备指纹 + 身份证 hash + 手机 + 银行卡；月度封顶 30000 / 年度 200000
  • 关停闸门：growth.point.enabled=false → 所有 earn/spend 静默返回 0，业务侧无需改代码

25.3 B2B 渠道引擎（partner）

  • 4 级伙伴：Referral / Reseller / Premium / SI；首年 / 续约返佣比例独立
  • 线索 4 维去重报备：USCC + 邮箱 + 手机 + 客户名（任一命中即 DUPLICATE）
  • 锁单 N 天（默认 30）：锁单期间其他伙伴报相同客户自动判重
  • 提成按客户回款释放：commissionAmount = paidAmount × commissionRate，分阶段 PENDING → APPROVED → PAID

25.4 业务侧接入示例

// 货源发布业务里只加一行
pointService.spend(uid, 30L, "PUBLISH", cargoId, "发布货源");

// 查看司机联系方式
pointService.spend(uid, 5L, "VIEW_CONTACT", driverId, "查看联系方式");

业务模块不感知积分逻辑细节；关停积分时只需改配置不需改代码。

25.5 经济模型

按 1 万 MAU 推算：发放 1100 万 YC / 月 - 消耗 860 万 YC / 月 = 净沉淀 240 万 YC，靠 12 个月过期机制兜底。详见 docs/44-推广积分体系v2.md。

25.6 反作弊钩子

反作弊阈值通过 §24 WASM 规则引擎 上传，运营毫秒级热改：薅羊毛模式（短时大量低价订单）/ 设备聚集（同 IP 段 N 个新号）/ 日内消耗暴涨 等。

25.7 接口速览

GET  /point/my?uid=                       # 我的余额
GET  /point/my/transactions?uid=&page=    # 流水分页
POST /point/consume?uid=&cost=&bizType=   # 业务侧扣分（统一入口）
GET  /point/invitation/code?uid=          # 我的邀请码
POST /point/invitation/bind?uid=&code=    # 首次启动绑定

POST /partner/lead/report                  # 渠道报备线索
POST /partner/deal/win                     # 平台登记成交
POST /partner/commission/pay               # 客户回款释放提成

附录 A：85+ 模块速查

详见 versions.txt + 本目录下 00-40 各章节。

附录 B：API 接口清单（动态生成）

cd server && ./mvnw -pl logistics-app spring-boot:run
# 浏览 http://localhost:8080/swagger-ui/index.html
# 或 OpenAPI JSON: http://localhost:8080/v3/api-docs

附录 C：与同类产品对比

维度 云驰智运 传统 TMS（某邀自研） 通用 SaaS（货 XX 企业版）
双运力支持 ✅ 原生 ❌ 仅自有车队 ✅
多分站 ✅ 三级 RBAC ⚠️ 部分 ❌
信创适配 ✅ 全栈 ⚠️ ❌
AI / LLM ✅ 异常检测 + 告警摘要 ❌ ⚠️ 客服
区块链 / NFT 签收 ✅ ❌ ❌
跨境 + CBAM ✅ ⚠️ ❌
数据血缘 ✅ OpenLineage ❌ ❌
私有化部署 ✅ Docker / K8s ✅ ❌ 仅 SaaS