Sam Hardy物流管理系统产品系统

甲方是美国本土一家中型卡车运输车队，主营州际整车运输，车队规模约十余台车、几十名司机，业务覆盖订舱、派车、在途跟踪、回单签收、开票回款全链路。

行业背景：美国卡车运输是典型的重资产强合规行业。一次运输要同时满足 DOT/FMCSA 合规要求（CDL 驾照与到期、体检卡、药检与 Clearinghouse、车辆注册/保险/年检、IFTA/IRP/UCR 及 2290 税费），每趟还要跑通纸质单据链条：运价确认单、提单、签收回单、发票。这些单据分散在司机手机、邮箱、白板和文件柜里。

立项痛点很具体：一是靠 Excel 台账加邮件沟通调度，无法实时知道哪台车在哪、哪票货卡在哪个环节；二是车辆证件与司机资质到期日靠人记台账，漏检一次就是罚款加停运，直接侵蚀利润；三是纸质回单靠即时通讯软件传照片，单据真伪、金额和归属车次对不上；四是月底财务要人工拼表核算单票毛利，周期长且滞后，老板拿不到实时经营视图；五是司机、调度、老板三方各看各的表格，信息不同步。

所以立项目标明确：把一票货从订舱到签收、开票、回款的完整链路搬到线上，同时把合规到期、每票毛利、实时经营看板三件事做出来，让管理从追着人问变成看系统就知道哪里卡住、哪里有风险。

项目含 24 个业务模块、112 个后端接口，覆盖车队运营全链路。
1. 账号权限：老板/员工/司机/Li 四角色，支持密码登录与微信小程序绑定，令牌 24 小时有效；按角色与任务指派范围控制可见范围。
2. 车队司机：车辆台账含车号、VIN、车型、里程、ELD、保养间隔及注册/保险/年检/IFTA/IRP/UCR/2290 到期日，状态分在营、维修中、停用、已售；司机档案含 CDL 与体检卡。
3. 运单货单：运单含寄收双方、指派司机、状态流转、电子签名与版本号乐观锁；货单含客户、装卸地址、货物、费率、里程、TONU 等并绑定司机车辆，走订舱到关单 9 段流转。
4. 维修加油：司机报修含故障类型、位置、影响面与三级严重度，走报价多版本与审批流，发票上传自动校验金额异常；加油登记车辆、里程与收据多图。
5. 财务账单：账单同记收入与燃油、司机、路桥成本并自动估算毛利，收款状态分待开票、待付款、已付、逾期，可标记已付与关单。
6. 任务审批：任务分 7 种类型、7 种状态、红黄绿三级优先级，支持指派、转交、退回、批量更新与逾期判定；统一审批覆盖合同、付款、事故、纪律四类。
7. 合规提醒：合规事项按对象、到期日登记，到期提醒可按周期或里程触发，并提供日历聚合视图。
8. 沟通通知：沟通记录区分电话、邮件、短信、面谈，登记摘要，标记等待回复或需老板决策；站内通知分提醒、指派、审批、告警、系统五类。
9. 文件中心：支持运价确认单、提单、签收回单、发票、CDL 等 18 类文档，上传对象存储并记录 SHA256，下载链接带时效令牌。
10. 看板与保障：今日概览含总单量、待提、在途、已送达、异常数，另有待办逾期任务、待开票待付款逾期账款与保养告警；健康检查含存活、就绪与 Prometheus 指标；审计日志记录操作人、动作与前后值；定时任务去重与抢占锁；备份归档同步远程存储。

我独立完成了从后端到前端的全部开发与上线运维。
具体任务：设计实现后端全部数据模型与 112 个 REST 接口；开发 Vue 3 管理后台全部业务页面；开发 uni-app 微信小程序司机端；完成服务器部署、证书配置、反向代理与 HTTPS 跳转；配置对象存储与备份策略；持续处理线上故障。
技术栈：后端 Python + FastAPI（131 个 Pydantic 模型，全量入参校验），鉴权 JWT（HS256、24 小时有效）加四角色 RBAC；前端 Vue 3 + Element Plus + Pinia + Axios；小程序 uni-app；数据层 SQLAlchemy ORM 加关系型数据库（UUID 主键，金额列 NUMERIC(12,2) 精确小数）；单据存腾讯云 COS；部署 Ubuntu + Nginx + Let's Encrypt + HSTS，子域分离；可观测性用 Prometheus 指标、健康检查、审计日志与请求 ID 贯穿。
架构亮点：一是契约先行，OpenAPI 自动出文档、统一分页信封，Pydantic v2 严格校验金额、日期、UUID 与编码正则，非法数据入口即挡；二是状态机驱动，货单 9 态、任务 7 态、维修 5 态、收款 4 态全枚举化，流转接口返回允许的下一状态白名单，杜绝非法跳转；三是权限三层收敛为统一权限点列表，司机端只需少量接口、老板端要全局视图，靠权限点裁剪接口集；四是合规引擎把证件到期日统一收口，按天或按里程触发提醒并判逾期。
难点与解决：跨时区跨端协同（国内开发、美国本土运营、司机途中回传），统一 UTC 存储按本地时区展示；签收回单由司机手机端签名拍照回传，签名图与业务对象关联、链接带时效令牌；金额一律走 Decimal，杜绝浮点误差；一人兼顾后端前端小程序与运维，靠统一权限模型与自动化备份降低维护成本。