每次放学时间一到校门口就堵满了车和人家长一边看手机一边四处张望。要是家里同时有两个孩子在不同校区或者今天临时加班、出差接送立刻变成一场灾难。我做了一个叫“逐光”的小学生接送帮共享平台核心思路很简单把孩子“放学后谁去接”这件事做成一个可发布、可委托、可共享的线上协作流程。技术选型上用 Python 做后端、Vue3 做前端不搞花架子把接送任务、委托关系、状态提醒这些环节拆开做实。这篇内容适合正在做类似共享协作类项目的开发者也适合想用 Python Vue3 快速搭一套完整前后端系统的同学参考。我会把需求分析、数据库设计、核心接口、前端交互、以及实际开发中踩过的坑都讲清楚尽量做到能直接照着落地。1. 需求分析与整体方案设计1.1 接送场景的痛点与共享逻辑小学生接送和普通打车、快递配送最大的区别在于“信任门槛”极高。你不能随便把一个一年级孩子交给陌生人也不能像快递柜那样把小孩放进去寄存。这个平台的核心矛盾不是“有没有人愿意顺路接”而是“家长凭什么信任这个人”。所以整个需求设计不能只做发布和接单还得把关系链、信用记录、实时确认机制全部做进去否则就是一个空壳。我在设计逐光平台时把用户行为拆成了四个阶段发起、匹配、接送、确认。发起阶段家长填写孩子姓名、学校、年级、放学校区、到家地址、预计离校时间等信息。匹配阶段系统按“同学校、同小区、同时间段”三个维度和历史信用分进行推荐。接送阶段通过实时状态流转展示任务进度包括“待出发、已到达、已接到、已送达”几个状态。确认阶段双方对过程进行评分和留言这笔信用数据又会反向影响后续匹配。共享逻辑的关键是“可委托的熟人关系”。如果直接开放给全平台陌生人安全风险太大了。所以我设置了“关系链”字段家长可以手动添加同班家长、邻居、亲友作为可信任联系人系统优先在这些关系链内做匹配只有关系链内无人响应时才扩大到同学校同小区的“扩展圈”。这个设计其实参考了拼车平台的顺路算法但多了社交信任维度更符合接送场景。1.2 技术选型为什么是 Python 加 Vue3后端选 Python不单是因为生态成熟更因为这类业务有大量围绕时间、地点、用户关系的逻辑要快速迭代。Python 的 FastAPI 框架天然支持异步配合 Pydantic 做参数校验和接口文档生成在开发效率上比 Java 那套低配置成本高很多。当然如果你用 Flask 也一样能做只是我更喜欢 FastAPI 的自动交互文档联调的时候能让前端同学少问很多问题。前端选 Vue3核心原因是组合式 API 更适合做这种“状态多、页面多、权限区分明显”的管理类应用。Composition API 可以把某个业务模块的所有状态和逻辑集中在一起比如接送任务的状态流我可以用一个 useTaskStore 模块统一管理组件里只负责渲染。这和 Vue2 的 Options API 比起来代码复用和模块组织都舒服很多。整个系统采用前后端分离部署后端是 Python FastAPI 提供 RESTful 接口前端是 Vue3 Vite 开发单页应用数据库用 MySQL缓存和实时推送用 Redis。开发环境里前端通过 Vite 代理解决跨域生产环境用 Nginx 统一转发这样开发调试和上线部署的路径都很顺。1.3 功能模块梳理平台功能我划分为六个模块用户中心、关系链管理、接送任务、匹配推荐、实时状态、信用评分。用户中心包含注册、登录、家庭成员管理和孩子档案。孩子档案要预留字段记录学校名称、班级、放学时间、校区地址、接送偏好这些信息是后续匹配的核心素材。关系链管理用来维护“我信任谁”。可以从通讯录导入也可以扫描二维码添加还可以通过共同群组成员推荐。关系链里的关系类型分为“家人”“邻居”“同班家长”“好友”不同的关系类型在信用加权时有不同权重。接送任务是业务核心包括发布、修改、取消、延期、完成等操作。每个任务除了基本信息还要有有效时间范围比如“今天下午16:30-16:50可以接”超过这个时间任务自动进入异常待处理状态。匹配推荐不是简单的 SQL 查询而是综合多个条件的打分排序引擎。打分项包括地理位置距离、时间重合度、信用分、历史完成单数、关系亲密度最后生成一个总分分数高的人排在前面。实时状态通过 WebSocket 推送给相关人家长在手机端可以直接看到受托人当前走到哪了是否已经到校门口孩子是否被接到。这些都是节点状态不是 GPS 持续追踪尊重隐私又足够透明。信用评分是保证共享生态能持续运行的关键。每次任务完成后双方可以互相评价标签包括“守时”“细心”“沟通顺畅”等。被投诉多的人会被限制接单差评记录会进入关系链推荐的黑名单。2. 核心细节与数据库设计2.1 用户角色与权限设计这个系统里角色划分不搞复杂的 RBAC我简单分成了四类普通家长、受托人、学校管理员、平台管理员。普通家长可以发任务、接受别人委托、评价对方。受托人是实际去接孩子的用户可能是家长本人也可能是被委托的邻居或亲友权限上必须能看到孩子的基本信息和接送任务详情。学校管理员是可选角色主要是学校门口放学引导的辅助人员可以有限查看某个时间段内的待接任务数量方便安排老师或保安引导秩序。但学校管理员不能看到家长联系方式也不能参与接单防止信息泄露。平台管理员负责处理投诉、审查异常行为、管理信用分。后台前端也用的是 Vue3但独立成一套管理页面。权限校验在后端用依赖注入实现。FastAPI 的 Depends 非常方便我可以写一个 get_current_user 函数从请求头取出 JWT解析出用户信息再配合角色检查装饰器控制接口访问范围。前端则根据登录用户角色动态渲染菜单和按钮。2.2 数据模型设计数据库表我精心设计过字段不需要太多但要支撑所有的查询和统计需求。用户表 users 主要字段id、phone、password_hash、nickname、avatar_url、role、school_id、community_id、credit_score、created_at。这里 school_id 和 community_id 是为了索引用户所在的学校和小区加速匹配查询。孩子表 students 主要字段id、user_id、name、grade、class_name、school_id、campus_address、pickup_time_default、home_address。一个家长可能绑多个孩子每个孩子独立记录接送偏好。关系链表 relations 主要字段id、user_id、related_user_id、relation_type、status、created_at。关系是双向的所以我会做两行记录或者查询时用 OR 条件但更推荐直接保存两条方便单向信任的情况。接送任务表 pickup_tasks 主要字段id、publisher_id、student_id、pickup_date、start_time、end_time、from_address、to_address、status、assignee_id、timeout_flag、remark。status 按顺序为 pending、matched、in_progress、completed、cancelled、abnormal。状态记录表 pickup_status_logs 字段id、task_id、status、operator_id、location_desc、created_at。每次状态变化必须写日志方便异常回溯。通知表 notifications 字段id、recipient_id、task_id、type、content、is_read、created_at。信用评分表 credit_records 字段id、user_id、change_value、reason、related_task_id、created_at。其实这些表结构已经很完整了但我要强调一点所有时间字段统一用字符串存储格式为 UTC 时间加时区偏移。因为接送任务和用户实际所在地区相关如果不做时区处理很容易出现“孩子放学了但推送还没发”的尴尬局面。2.3 接口设计要点接口设计遵循 RESTful 风格主要接口有POST /api/auth/register 注册POST /api/auth/login 登录GET /api/users/me 获取当前用户信息GET /api/students 获取我的孩子列表POST /api/students 添加孩子GET /api/relations 获取我的关系链POST /api/relations 添加关系POST /api/tasks 发布接送任务GET /api/tasks 获取任务列表分页筛选GET /api/tasks/{id} 获取任务详情POST /api/tasks/{id}/accept 接受任务POST /api/tasks/{id}/status 更新任务状态POST /api/tasks/{id}/cancel 取消任务GET /api/tasks/{id}/logs 获取任务状态日志POST /api/tasks/{id}/rate 评价任务这里有个很重要的细节所有列表接口都要支持游标分页而不是传统的页码分页。因为任务列表是高频数据用户在手机上不断下拉刷新如果中间有新数据插入页码分页会导致重复或漏数据游标分页用任务 ID 和时间作为游标稳定得多。JWT 有效期要设置成短时间加刷新机制。因为接送任务涉及孩子安全如果前端 Token 泄露后果很严重所以 access token 我设置为 30 分钟过期refresh token 7 天过期前端在 Axios 拦截器里统一处理刷新逻辑。3. 前后端实操过程与关键实现3.1 开发环境准备Python 安装与 Vue3 项目创建如果你还没有 Python 环境先到官网下载对应系统版本Windows 用户记得在安装界面勾选“Add Python to PATH”否则后面跑命令会连 python 都找不到。Linux 和 macOS 系统一般自带 Python3但版本可能比较老建议装一个 pyenv 来管理多版本。后端项目我习惯用虚拟环境避免项目依赖互相污染python -m venv venv source venv/bin/activate # Windows 下是 venv\Scripts\activate pip install fastapi uvicorn sqlalchemy pymysql redis aiohttp pydantic我选 FastAPI但很多人会问为什么不选 Django。原因是这个项目重点是接口快速迭代和与前端的高效协作Django 自带 Admin 和 ORM 虽然省事但太重了而且异步支持没有 FastAPI 丝滑。如果你熟悉 Flask项目结构改成 Flask 也完全可以核心逻辑是相通的。前端用 Vite 创建 Vue3 项目是现在最舒服的姿势npm create vitelatest pickup-frontend -- --template vue cd pickup-frontend npm install npm install vue-router pinia axios element-plus注意 npm 源如果太慢可以临时用淘宝镜像npm config set registry https://registry.npmmirror.com创建完项目后我会先搭好目录结构src/api 放所有接口封装src/stores 放 Pinia 状态src/router 放路由配置src/views 放页面组件src/components 放公共组件。这样后续写业务代码的时候思路非常清晰。3.2 后端核心业务实现我先讲后端最核心的接送任务发布和接单逻辑。发布任务时前端提交过来的数据结构包含孩子 ID、日期、时间段、起终点地址后端收到后先校验孩子是否属于当前用户再检查该时间段内是否已有冲突任务如果没有就创建新任务并设置状态为 pending。这里我用了一个很小的技巧日期和时间段合并成一个开始时间和结束时间存储为 datetime 格式后续所有匹配、冲突检测都用这两个字段。很多新手容易把日期和时间段分开存导致写 SQL 的时候拼来拼去不仅效率低还容易出错。接单接口是平台的关键我加了一个乐观锁机制防止两个人同时点“接受”按钮导致同一个任务被抢走。具体做法是在任务表加一个 version 字段更新时带上版本号如果数据库更新成功行数为 0说明已经被别人改了需要重新加载提示。# 伪代码示例 updated db.execute( UPDATE pickup_tasks SET assignee_id:uid, statusmatched, versionversion1 WHERE id:task_id AND version:version AND statuspending, {uid: uid, task_id: task_id, version: version} ) if updated.rowcount 0: raise HTTPException(status_code409, detail任务已被抢接或状态已变化)状态流转我封装了一个状态机函数允许的转换关系为pending 可以被接受为 matched也可以被发布者取消为 cancelledmatched 可以由受托人开始为 in_progress也可以由发布者取消in_progress 可以标记某节点完成最后变成 completed超过约定结束时间未完成自动变成 abnormal系统推送通知这个状态机的校验保证了业务流程不会出现“已完成的任务又被接受”“已取消的任务还能操作”这种逻辑漏洞。3.3 前端核心页面与交互实现前端我用 Vue3 组合式 API 写了几个核心页面。发布任务页是最复杂的因为它涉及日期时间选择、孩子选择、地址选择、备注信息。我把这些表单逻辑封装在一个 usePublishTask 函数里返回响应式表单对象、提交方法、校验规则。在组件里只需要引入并 return 到模板即可代码非常清爽。任务列表页我采用了无限滚动方案。前端滚动到底部时携带当前游标 ID 请求下一页数据。列表项展示孩子名字、接送时间、任务状态、对方头像和昵称。状态用不同颜色标签渲染比如待接单是橙色已完成是绿色异常是红色。状态实时更新用了 WebSocket。后端在任务状态变化后向 Redis 频道发送消息前端 WebSocket 服务收到消息后在 Pinia store 里更新对应任务的状态。这里我遇到过一个坑WebSocket 连接在移动端网络切换时会断开所以我在前端加了心跳机制每 30 秒发送一个 ping如果连续几次没有收到 pong自动重连。委托分享页也是一个亮点。发布者可以把任务生成一个带 token 的短连接发送到微信群接收人点开后能看到任务详情点击“我来接”就能直接登录并执行接单。这个 token 是临时签发的7 天有效只能绑定到一个任务防止被人拿到后恶意获取其他数据。3.4 共享匹配逻辑的实现匹配推荐是整个系统最有技术含量的部分。我不会直接 SQL 查出来一堆人给用户看而是综合打分。基础条件是同学校 ID 相同且用户所在小区距离任务中提到的 from_address 在 3 公里以内。时间条件要求对方当天在这个时间段没有已经接受的任务或者说时间冲突检测不能只检查“完全重叠”还要考虑前后缓冲我设置了前后各 15 分钟缓冲防止连续接两单导致迟到。打分细节如下关系链亲密度权重 40 分家人 40邻居 35同班家长 30好友 25信用分权重 20 分把用户的 credit_score 线性映射到 0-20 分满分不低于 4.5星历史完成单数权重 15 分完成 50 单以上拿满分低于 5 单只能拿 5 分时间重合度权重 15 分任务时间窗口与对方空闲时间窗口的重合比例越高分越高距离权重 10 分距离越近分越高超过 3 公里直接过滤最终总成绩超过 70 分才会出现在推荐列表且按分数降序排列。这个逻辑我单独写成一个 recommend.py 模块和数据库访问层分开方便后面替换成更复杂的算法。匹配逻辑要支持异步重算。当用户发布任务后后台用一个异步任务去扫描候选池计算分数生成推荐列表写入缓存前端再通过一个 GET /api/tasks/{id}/candidates 接口读取避免了发布时长时间等待。4. 常见问题与排查技巧实录4.1 跨域与请求问题开发阶段最容易遇到的就是跨域。Vue3 前端跑在 5173 端口后端跑在 8000 端口直接请求肯定会被浏览器拦截。我有两种解决方案但推荐用 Vite 代理server: { proxy: { /api: { target: http://localhost:8000, changeOrigin: true } } }这样前端所有请求都写 /api/... 相对路径开发环境自动代理到后端生产环境 Nginx 再做同样配置前端代码里不需要写死任何域名。有一个场景我要特别提醒如果你使用 Axios而某个页面还没有登录就去请求接口后端会返回 401。我一开始只是在页面里单独判断 code后来发现非常繁琐不如直接在 Axios 响应拦截器里统一处理遇到 401 就清空本地登录状态并跳转到登录页这样每个接口都不需要重复写鉴权逻辑。4.2 实时通知与时间精度问题WebSocket 推送也好短信通知也好时间都是关键环节。有一次我在测试时发现任务在 16:35 开始系统却在 16:32 就推送了“已出发”给委托人。排查后发现问题出在前后端时区不一致后端在 Docker 容器里默认是 UTC 时间而前端浏览器用的是东八区。解决方案是后端在生成数据时统一使用带有 UTC Offset 的 datetime 字符串返回比如 2024-05-20T16:30:0008:00前端解析时直接用 Day.js 处理转成本地时间。数据库存储仍然使用 UTC 时间只在接口层做转换。另外调度提醒功能不要依赖简单的 cron 轮询数据库因为任务量大起来很浪费性能。我使用 Redis 的 keyspace notifications 或者直接做一个延时队列把要触发的提醒任务放进 Redis ZSet分数设为提醒时间戳后台起一个循环每 10 秒取一次当前时间之前的元素再执行推送逻辑。这个方案简单可靠不用引入额外的消息队列中间件。4.3 安全与隐私保护涉及孩子信息隐私保护一定不能松懈。我做了几件事接口统一走 HTTPS这是前提。所有返回给前端的用户手机号做脱敏处理比如 138****1234只有双方确认建立关系后才允许查看完整号码。拼接临时链接的 token 使用 HMAC 签名并绑定任务 ID防止被篡改后访问别人任务。关键操作接单、取消、评价都要在校验 JWT 的同时校验操作者是否与任务有合法关系。比如一个无关用户尝试调 accept 接口必须阻止。我还写了一个简单的访问频率限制中间件基于 Redis 对每个用户每秒钟的请求次数做计数超过阈值直接返回 429。别小看这个公开项目上线后非常容易被爬虫或者恶意脚本刷接口有这一层能省很多麻烦。4.4 性能与部署小技巧开发环境跑得通不代表线上能扛住。我这里介绍几个生产化配置要点。数据库查询要避免多表 JOIN 太多。我的任务列表页默认只查 pickup_tasks 表用户昵称和头像单独用内存缓存而不是每次 SELECT 时 JOIN users 表。这样在高频查询场景下能明显降低数据库压力。静态资源用 Nginx 服务前端打包后 dist 目录直接指向根路径。后端用 Gunicorn 启动 Uvicorn Workergunicorn main:app -k uvicorn.workers.UvicornWorker -w 4 -b 0.0.0.0:80004 个 Worker 对于大多数学校规模的用户量已经够用如果并发更高再横向加机器做负载均衡。整机部署我用 Docker Compose 一键编排包含 MySQL、Redis、后端、前端 Nginx 四个容器。前端 Nginx 配置里同时处理静态文件反向代理和后端 /api 反向代理非常简单。日志统一输出到 Docker Volume方便排查问题。最后还想分享一个细节不要把业务全部压在一个服务里如果后面要扩展把匹配计算抽成独立 Worker 进程通过 Redis 队列消费任务前端不会因为后台计算量变大而卡死。我的项目目前就是这么做的实测稳定。这个平台后续还有很多可以扩展的方向比如接入地图轨迹共享、增加语音提醒、对接学校门禁系统甚至给老师提供免费的批量签到工具。根据我实际开发下来的体会最核心的并不是技术有多深、框架有多新而是把信任闭环和数据模型设计清楚。只要你把“谁可以在什么条件下看到什么信息、执行什么操作”这件基础事情想明白了Python 后端和 Vue3 前端都只是实现你想法的工具。做这类共享平台别急着堆功能先把一个“发布、匹配、确认、评价”的闭环打磨到极致再往外扩。这是我在逐光项目里最有价值的收获。
Python + Vue3 构建小学生接送共享平台：需求、设计与实践
每次放学时间一到校门口就堵满了车和人家长一边看手机一边四处张望。要是家里同时有两个孩子在不同校区或者今天临时加班、出差接送立刻变成一场灾难。我做了一个叫“逐光”的小学生接送帮共享平台核心思路很简单把孩子“放学后谁去接”这件事做成一个可发布、可委托、可共享的线上协作流程。技术选型上用 Python 做后端、Vue3 做前端不搞花架子把接送任务、委托关系、状态提醒这些环节拆开做实。这篇内容适合正在做类似共享协作类项目的开发者也适合想用 Python Vue3 快速搭一套完整前后端系统的同学参考。我会把需求分析、数据库设计、核心接口、前端交互、以及实际开发中踩过的坑都讲清楚尽量做到能直接照着落地。1. 需求分析与整体方案设计1.1 接送场景的痛点与共享逻辑小学生接送和普通打车、快递配送最大的区别在于“信任门槛”极高。你不能随便把一个一年级孩子交给陌生人也不能像快递柜那样把小孩放进去寄存。这个平台的核心矛盾不是“有没有人愿意顺路接”而是“家长凭什么信任这个人”。所以整个需求设计不能只做发布和接单还得把关系链、信用记录、实时确认机制全部做进去否则就是一个空壳。我在设计逐光平台时把用户行为拆成了四个阶段发起、匹配、接送、确认。发起阶段家长填写孩子姓名、学校、年级、放学校区、到家地址、预计离校时间等信息。匹配阶段系统按“同学校、同小区、同时间段”三个维度和历史信用分进行推荐。接送阶段通过实时状态流转展示任务进度包括“待出发、已到达、已接到、已送达”几个状态。确认阶段双方对过程进行评分和留言这笔信用数据又会反向影响后续匹配。共享逻辑的关键是“可委托的熟人关系”。如果直接开放给全平台陌生人安全风险太大了。所以我设置了“关系链”字段家长可以手动添加同班家长、邻居、亲友作为可信任联系人系统优先在这些关系链内做匹配只有关系链内无人响应时才扩大到同学校同小区的“扩展圈”。这个设计其实参考了拼车平台的顺路算法但多了社交信任维度更符合接送场景。1.2 技术选型为什么是 Python 加 Vue3后端选 Python不单是因为生态成熟更因为这类业务有大量围绕时间、地点、用户关系的逻辑要快速迭代。Python 的 FastAPI 框架天然支持异步配合 Pydantic 做参数校验和接口文档生成在开发效率上比 Java 那套低配置成本高很多。当然如果你用 Flask 也一样能做只是我更喜欢 FastAPI 的自动交互文档联调的时候能让前端同学少问很多问题。前端选 Vue3核心原因是组合式 API 更适合做这种“状态多、页面多、权限区分明显”的管理类应用。Composition API 可以把某个业务模块的所有状态和逻辑集中在一起比如接送任务的状态流我可以用一个 useTaskStore 模块统一管理组件里只负责渲染。这和 Vue2 的 Options API 比起来代码复用和模块组织都舒服很多。整个系统采用前后端分离部署后端是 Python FastAPI 提供 RESTful 接口前端是 Vue3 Vite 开发单页应用数据库用 MySQL缓存和实时推送用 Redis。开发环境里前端通过 Vite 代理解决跨域生产环境用 Nginx 统一转发这样开发调试和上线部署的路径都很顺。1.3 功能模块梳理平台功能我划分为六个模块用户中心、关系链管理、接送任务、匹配推荐、实时状态、信用评分。用户中心包含注册、登录、家庭成员管理和孩子档案。孩子档案要预留字段记录学校名称、班级、放学时间、校区地址、接送偏好这些信息是后续匹配的核心素材。关系链管理用来维护“我信任谁”。可以从通讯录导入也可以扫描二维码添加还可以通过共同群组成员推荐。关系链里的关系类型分为“家人”“邻居”“同班家长”“好友”不同的关系类型在信用加权时有不同权重。接送任务是业务核心包括发布、修改、取消、延期、完成等操作。每个任务除了基本信息还要有有效时间范围比如“今天下午16:30-16:50可以接”超过这个时间任务自动进入异常待处理状态。匹配推荐不是简单的 SQL 查询而是综合多个条件的打分排序引擎。打分项包括地理位置距离、时间重合度、信用分、历史完成单数、关系亲密度最后生成一个总分分数高的人排在前面。实时状态通过 WebSocket 推送给相关人家长在手机端可以直接看到受托人当前走到哪了是否已经到校门口孩子是否被接到。这些都是节点状态不是 GPS 持续追踪尊重隐私又足够透明。信用评分是保证共享生态能持续运行的关键。每次任务完成后双方可以互相评价标签包括“守时”“细心”“沟通顺畅”等。被投诉多的人会被限制接单差评记录会进入关系链推荐的黑名单。2. 核心细节与数据库设计2.1 用户角色与权限设计这个系统里角色划分不搞复杂的 RBAC我简单分成了四类普通家长、受托人、学校管理员、平台管理员。普通家长可以发任务、接受别人委托、评价对方。受托人是实际去接孩子的用户可能是家长本人也可能是被委托的邻居或亲友权限上必须能看到孩子的基本信息和接送任务详情。学校管理员是可选角色主要是学校门口放学引导的辅助人员可以有限查看某个时间段内的待接任务数量方便安排老师或保安引导秩序。但学校管理员不能看到家长联系方式也不能参与接单防止信息泄露。平台管理员负责处理投诉、审查异常行为、管理信用分。后台前端也用的是 Vue3但独立成一套管理页面。权限校验在后端用依赖注入实现。FastAPI 的 Depends 非常方便我可以写一个 get_current_user 函数从请求头取出 JWT解析出用户信息再配合角色检查装饰器控制接口访问范围。前端则根据登录用户角色动态渲染菜单和按钮。2.2 数据模型设计数据库表我精心设计过字段不需要太多但要支撑所有的查询和统计需求。用户表 users 主要字段id、phone、password_hash、nickname、avatar_url、role、school_id、community_id、credit_score、created_at。这里 school_id 和 community_id 是为了索引用户所在的学校和小区加速匹配查询。孩子表 students 主要字段id、user_id、name、grade、class_name、school_id、campus_address、pickup_time_default、home_address。一个家长可能绑多个孩子每个孩子独立记录接送偏好。关系链表 relations 主要字段id、user_id、related_user_id、relation_type、status、created_at。关系是双向的所以我会做两行记录或者查询时用 OR 条件但更推荐直接保存两条方便单向信任的情况。接送任务表 pickup_tasks 主要字段id、publisher_id、student_id、pickup_date、start_time、end_time、from_address、to_address、status、assignee_id、timeout_flag、remark。status 按顺序为 pending、matched、in_progress、completed、cancelled、abnormal。状态记录表 pickup_status_logs 字段id、task_id、status、operator_id、location_desc、created_at。每次状态变化必须写日志方便异常回溯。通知表 notifications 字段id、recipient_id、task_id、type、content、is_read、created_at。信用评分表 credit_records 字段id、user_id、change_value、reason、related_task_id、created_at。其实这些表结构已经很完整了但我要强调一点所有时间字段统一用字符串存储格式为 UTC 时间加时区偏移。因为接送任务和用户实际所在地区相关如果不做时区处理很容易出现“孩子放学了但推送还没发”的尴尬局面。2.3 接口设计要点接口设计遵循 RESTful 风格主要接口有POST /api/auth/register 注册POST /api/auth/login 登录GET /api/users/me 获取当前用户信息GET /api/students 获取我的孩子列表POST /api/students 添加孩子GET /api/relations 获取我的关系链POST /api/relations 添加关系POST /api/tasks 发布接送任务GET /api/tasks 获取任务列表分页筛选GET /api/tasks/{id} 获取任务详情POST /api/tasks/{id}/accept 接受任务POST /api/tasks/{id}/status 更新任务状态POST /api/tasks/{id}/cancel 取消任务GET /api/tasks/{id}/logs 获取任务状态日志POST /api/tasks/{id}/rate 评价任务这里有个很重要的细节所有列表接口都要支持游标分页而不是传统的页码分页。因为任务列表是高频数据用户在手机上不断下拉刷新如果中间有新数据插入页码分页会导致重复或漏数据游标分页用任务 ID 和时间作为游标稳定得多。JWT 有效期要设置成短时间加刷新机制。因为接送任务涉及孩子安全如果前端 Token 泄露后果很严重所以 access token 我设置为 30 分钟过期refresh token 7 天过期前端在 Axios 拦截器里统一处理刷新逻辑。3. 前后端实操过程与关键实现3.1 开发环境准备Python 安装与 Vue3 项目创建如果你还没有 Python 环境先到官网下载对应系统版本Windows 用户记得在安装界面勾选“Add Python to PATH”否则后面跑命令会连 python 都找不到。Linux 和 macOS 系统一般自带 Python3但版本可能比较老建议装一个 pyenv 来管理多版本。后端项目我习惯用虚拟环境避免项目依赖互相污染python -m venv venv source venv/bin/activate # Windows 下是 venv\Scripts\activate pip install fastapi uvicorn sqlalchemy pymysql redis aiohttp pydantic我选 FastAPI但很多人会问为什么不选 Django。原因是这个项目重点是接口快速迭代和与前端的高效协作Django 自带 Admin 和 ORM 虽然省事但太重了而且异步支持没有 FastAPI 丝滑。如果你熟悉 Flask项目结构改成 Flask 也完全可以核心逻辑是相通的。前端用 Vite 创建 Vue3 项目是现在最舒服的姿势npm create vitelatest pickup-frontend -- --template vue cd pickup-frontend npm install npm install vue-router pinia axios element-plus注意 npm 源如果太慢可以临时用淘宝镜像npm config set registry https://registry.npmmirror.com创建完项目后我会先搭好目录结构src/api 放所有接口封装src/stores 放 Pinia 状态src/router 放路由配置src/views 放页面组件src/components 放公共组件。这样后续写业务代码的时候思路非常清晰。3.2 后端核心业务实现我先讲后端最核心的接送任务发布和接单逻辑。发布任务时前端提交过来的数据结构包含孩子 ID、日期、时间段、起终点地址后端收到后先校验孩子是否属于当前用户再检查该时间段内是否已有冲突任务如果没有就创建新任务并设置状态为 pending。这里我用了一个很小的技巧日期和时间段合并成一个开始时间和结束时间存储为 datetime 格式后续所有匹配、冲突检测都用这两个字段。很多新手容易把日期和时间段分开存导致写 SQL 的时候拼来拼去不仅效率低还容易出错。接单接口是平台的关键我加了一个乐观锁机制防止两个人同时点“接受”按钮导致同一个任务被抢走。具体做法是在任务表加一个 version 字段更新时带上版本号如果数据库更新成功行数为 0说明已经被别人改了需要重新加载提示。# 伪代码示例 updated db.execute( UPDATE pickup_tasks SET assignee_id:uid, statusmatched, versionversion1 WHERE id:task_id AND version:version AND statuspending, {uid: uid, task_id: task_id, version: version} ) if updated.rowcount 0: raise HTTPException(status_code409, detail任务已被抢接或状态已变化)状态流转我封装了一个状态机函数允许的转换关系为pending 可以被接受为 matched也可以被发布者取消为 cancelledmatched 可以由受托人开始为 in_progress也可以由发布者取消in_progress 可以标记某节点完成最后变成 completed超过约定结束时间未完成自动变成 abnormal系统推送通知这个状态机的校验保证了业务流程不会出现“已完成的任务又被接受”“已取消的任务还能操作”这种逻辑漏洞。3.3 前端核心页面与交互实现前端我用 Vue3 组合式 API 写了几个核心页面。发布任务页是最复杂的因为它涉及日期时间选择、孩子选择、地址选择、备注信息。我把这些表单逻辑封装在一个 usePublishTask 函数里返回响应式表单对象、提交方法、校验规则。在组件里只需要引入并 return 到模板即可代码非常清爽。任务列表页我采用了无限滚动方案。前端滚动到底部时携带当前游标 ID 请求下一页数据。列表项展示孩子名字、接送时间、任务状态、对方头像和昵称。状态用不同颜色标签渲染比如待接单是橙色已完成是绿色异常是红色。状态实时更新用了 WebSocket。后端在任务状态变化后向 Redis 频道发送消息前端 WebSocket 服务收到消息后在 Pinia store 里更新对应任务的状态。这里我遇到过一个坑WebSocket 连接在移动端网络切换时会断开所以我在前端加了心跳机制每 30 秒发送一个 ping如果连续几次没有收到 pong自动重连。委托分享页也是一个亮点。发布者可以把任务生成一个带 token 的短连接发送到微信群接收人点开后能看到任务详情点击“我来接”就能直接登录并执行接单。这个 token 是临时签发的7 天有效只能绑定到一个任务防止被人拿到后恶意获取其他数据。3.4 共享匹配逻辑的实现匹配推荐是整个系统最有技术含量的部分。我不会直接 SQL 查出来一堆人给用户看而是综合打分。基础条件是同学校 ID 相同且用户所在小区距离任务中提到的 from_address 在 3 公里以内。时间条件要求对方当天在这个时间段没有已经接受的任务或者说时间冲突检测不能只检查“完全重叠”还要考虑前后缓冲我设置了前后各 15 分钟缓冲防止连续接两单导致迟到。打分细节如下关系链亲密度权重 40 分家人 40邻居 35同班家长 30好友 25信用分权重 20 分把用户的 credit_score 线性映射到 0-20 分满分不低于 4.5星历史完成单数权重 15 分完成 50 单以上拿满分低于 5 单只能拿 5 分时间重合度权重 15 分任务时间窗口与对方空闲时间窗口的重合比例越高分越高距离权重 10 分距离越近分越高超过 3 公里直接过滤最终总成绩超过 70 分才会出现在推荐列表且按分数降序排列。这个逻辑我单独写成一个 recommend.py 模块和数据库访问层分开方便后面替换成更复杂的算法。匹配逻辑要支持异步重算。当用户发布任务后后台用一个异步任务去扫描候选池计算分数生成推荐列表写入缓存前端再通过一个 GET /api/tasks/{id}/candidates 接口读取避免了发布时长时间等待。4. 常见问题与排查技巧实录4.1 跨域与请求问题开发阶段最容易遇到的就是跨域。Vue3 前端跑在 5173 端口后端跑在 8000 端口直接请求肯定会被浏览器拦截。我有两种解决方案但推荐用 Vite 代理server: { proxy: { /api: { target: http://localhost:8000, changeOrigin: true } } }这样前端所有请求都写 /api/... 相对路径开发环境自动代理到后端生产环境 Nginx 再做同样配置前端代码里不需要写死任何域名。有一个场景我要特别提醒如果你使用 Axios而某个页面还没有登录就去请求接口后端会返回 401。我一开始只是在页面里单独判断 code后来发现非常繁琐不如直接在 Axios 响应拦截器里统一处理遇到 401 就清空本地登录状态并跳转到登录页这样每个接口都不需要重复写鉴权逻辑。4.2 实时通知与时间精度问题WebSocket 推送也好短信通知也好时间都是关键环节。有一次我在测试时发现任务在 16:35 开始系统却在 16:32 就推送了“已出发”给委托人。排查后发现问题出在前后端时区不一致后端在 Docker 容器里默认是 UTC 时间而前端浏览器用的是东八区。解决方案是后端在生成数据时统一使用带有 UTC Offset 的 datetime 字符串返回比如 2024-05-20T16:30:0008:00前端解析时直接用 Day.js 处理转成本地时间。数据库存储仍然使用 UTC 时间只在接口层做转换。另外调度提醒功能不要依赖简单的 cron 轮询数据库因为任务量大起来很浪费性能。我使用 Redis 的 keyspace notifications 或者直接做一个延时队列把要触发的提醒任务放进 Redis ZSet分数设为提醒时间戳后台起一个循环每 10 秒取一次当前时间之前的元素再执行推送逻辑。这个方案简单可靠不用引入额外的消息队列中间件。4.3 安全与隐私保护涉及孩子信息隐私保护一定不能松懈。我做了几件事接口统一走 HTTPS这是前提。所有返回给前端的用户手机号做脱敏处理比如 138****1234只有双方确认建立关系后才允许查看完整号码。拼接临时链接的 token 使用 HMAC 签名并绑定任务 ID防止被篡改后访问别人任务。关键操作接单、取消、评价都要在校验 JWT 的同时校验操作者是否与任务有合法关系。比如一个无关用户尝试调 accept 接口必须阻止。我还写了一个简单的访问频率限制中间件基于 Redis 对每个用户每秒钟的请求次数做计数超过阈值直接返回 429。别小看这个公开项目上线后非常容易被爬虫或者恶意脚本刷接口有这一层能省很多麻烦。4.4 性能与部署小技巧开发环境跑得通不代表线上能扛住。我这里介绍几个生产化配置要点。数据库查询要避免多表 JOIN 太多。我的任务列表页默认只查 pickup_tasks 表用户昵称和头像单独用内存缓存而不是每次 SELECT 时 JOIN users 表。这样在高频查询场景下能明显降低数据库压力。静态资源用 Nginx 服务前端打包后 dist 目录直接指向根路径。后端用 Gunicorn 启动 Uvicorn Workergunicorn main:app -k uvicorn.workers.UvicornWorker -w 4 -b 0.0.0.0:80004 个 Worker 对于大多数学校规模的用户量已经够用如果并发更高再横向加机器做负载均衡。整机部署我用 Docker Compose 一键编排包含 MySQL、Redis、后端、前端 Nginx 四个容器。前端 Nginx 配置里同时处理静态文件反向代理和后端 /api 反向代理非常简单。日志统一输出到 Docker Volume方便排查问题。最后还想分享一个细节不要把业务全部压在一个服务里如果后面要扩展把匹配计算抽成独立 Worker 进程通过 Redis 队列消费任务前端不会因为后台计算量变大而卡死。我的项目目前就是这么做的实测稳定。这个平台后续还有很多可以扩展的方向比如接入地图轨迹共享、增加语音提醒、对接学校门禁系统甚至给老师提供免费的批量签到工具。根据我实际开发下来的体会最核心的并不是技术有多深、框架有多新而是把信任闭环和数据模型设计清楚。只要你把“谁可以在什么条件下看到什么信息、执行什么操作”这件基础事情想明白了Python 后端和 Vue3 前端都只是实现你想法的工具。做这类共享平台别急着堆功能先把一个“发布、匹配、确认、评价”的闭环打磨到极致再往外扩。这是我在逐光项目里最有价值的收获。