页面展示
首页
首页
注册
登录
用户端
用户端首页
我的订单
发布订单
个人资料
聊天系统
代取员端
首页
我的接单
实名认证
消息中心
管理员端
数据统计
订单管理
用户管理
代取员管理
消息中心
校园快递代取系统 - 技术规格说明书
1. 系统概述
1.1 项目背景
针对高校校园场景的快递代取服务系统，连接有快递代取需求的用户（学生）和代取员。
1.2 技术选型
-
**后端**: Python Flask + SQLAlchemy + Flask-JWT
-
**前端**: HTML5 + CSS3 + JavaScript (原生)
-
**数据库**: SQLite（开发）/ MySQL（生产）
-
**架构**: REST API + 前后端分离
1.3 用户角色
| 角色 | 描述 |
|-----|-----|
| 用户 | 发起快递代取需求 |
| 代取员 | 接单并完成代取 |
| 管理员 | 系统管理 |
2. 功能模块
2.1 用户端功能
-
x 用户注册/登录
-
x 发布代取需求（填写快递信息、取件码、报酬）
-
x 查看我的订单列表
-
x 订单状态追踪
-
x 评价代取员
2.2 代取员端功能
-
x 代取员注册/认证
-
x 订单大厅（抢单）
-
x 我的接单列表
-
x 完成取件确认
-
x 收入提现
2.3 管理员端功能
-
x 用户管理
-
x 代取员管理
-
x 订单管理
-
x 数据统计看板
3. 数据库设计
3.1 用户表 (users)
| 字段 | 类型 | 说明 |
|-----|-----|-----|
| id | Integer | 主键 |
| username | String(50) | 用户名 |
| password_hash | String(255) | 密码哈希 |
| phone | String(20) | 手机号 |
| role | String(20) | 角色 |
| created_at | DateTime | 创建时间 |
3.2 订单表 (orders)
| 字段 | 类型 | 说明 |
|-----|-----|-----|
| id | Integer | 主键 |
| user_id | Integer | 下单用户ID |
| courier_id | Integer | 代取员ID |
| express_company | String(50) | 快递公司 |
| tracking_no | String(50) | 快递单号 |
| pickup_code | String(20) | 取件码 |
| location | String(100) | 取件地点 |
| reward | Float | 报酬 |
| status | String(20) | 订单状态 |
| created_at | DateTime | 创建时间 |
| completed_at | DateTime | 完成时间 |
3.3 评价表 (reviews)
| 字段 | 类型 | 说明 |
|-----|-----|-----|
| id | Integer | 主键 |
| order_id | Integer | 订单ID |
| user_id | Integer | 评价用户ID |
| courier_id | Integer | 代取员ID |
| rating | Integer | 评分(1-5) |
| comment | String(255) | 评价内容 |
4. API 接口设计
> 所有 `/api/*` 路由均受 CORS 保护。除注册和登录外，所有接口均需要 **JWT Token**（请求头 `Authorization: Bearer <token>`）。
> `/api/admin/*` 下全部端点额外要求 **admin 角色**。
4.0 页面路由
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/` | 首页 |
| GET | `/login` | 登录页 |
| GET | `/register` | 注册页 |
| GET | `/dashboard` | 仪表盘/控制台页 |
| GET | `/admin` | 管理后台页 |
4.1 认证模块 (`/api/auth`)
POST `/api/auth/register`
用户注册，注册成功后返回 JWT Token。
| 字段 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| username | string | 是 | 用户名（唯一） |
| password | string | 是 | 密码 |
| phone | string | 是 | 手机号（唯一） |
| role | string | 是 | 角色：`user`(普通用户) 或 `courier`(代取员) |
| real_name | string | 是 | 真实姓名 |
POST `/api/auth/login`
用户登录，校验通过后返回 JWT Token 和用户信息。
| 字段 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| username | string | 是 | 用户名 |
| password | string | 是 | 密码 |
GET `/api/auth/me`
获取当前登录用户信息（根据 JWT Identity 查询）。**需认证**
4.2 订单模块 (`/api/orders`)
POST `/api/orders`
创建代取快递订单。**需认证**
| 字段 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| express_company | string | 是 | 快递公司名称 |
| tracking_no | string | 是 | 运单号 |
| pickup_code | string | 是 | 取件码 |
| location | string | 是 | 取件地点 |
| reward | float | 是 | 代取报酬（从余额扣除） |
| remark | string | 否 | 备注 |
GET `/api/orders`
查询订单列表，支持过滤和分页。**需认证**
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| status | string | - | `pending`/`accepted`/`completed`/`cancelled` |
| role | string | - | `my`(我的)/`courier`(我接的)/`available`(可抢单)/`all`(全部) |
| page | int | 1 | 页码 |
| per_page | int | 10 | 每页数量 |
GET `/api/orders/<order_id>`
查询单个订单详情。仅下单者、接单者或管理员可查看。**需认证**
PUT `/api/orders/<order_id>`
更新订单信息。下单者可修改 pending 状态订单；管理员可修改状态和原因。**需认证**
POST `/api/orders/<order_id>/grab`
代取员抢单。仅 courier/admin 角色、且订单为 pending 状态时可操作。**需认证**
POST `/api/orders/<order_id>/complete`
确认完成订单。支持上传送达照片，更新代取员统计，扣除下单者余额。**需认证**
| 字段 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| delivery_photo | string | 否 | 送达照片 |
POST `/api/orders/<order_id>/cancel`
取消订单。下单者可取消 pending/accepted 状态订单（已接单退还费用）；管理员也可取消。**需认证**
POST `/api/orders/<order_id>/review`
对已完成订单评价（评分1-5），更新代取员平均评分。同一订单不可重复评价。**需认证**
| 字段 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| rating | int | 是 | 评分（1-5） |
| comment | string | 否 | 评价内容 |
GET `/api/orders/<order_id>/review`
获取指定订单的评价信息。仅下单者、接单者或管理员可查看。**需认证**
GET `/api/users/<user_id>/reviews`
获取指定代取员的评价列表，按时间倒序，支持分页。**需认证**
查询参数：`page`, `per_page`
4.3 用户模块 (`/api/users`)
GET `/api/users/<user_id>` --- 获取用户详情 **需认证**
PUT `/api/users/<user_id>` --- 更新用户信息 **需认证**
可更新字段：`phone`, `real_name`, `password`, `avatar`（只能改自己或管理员改他人）
GET `/api/users/couriers` --- 获取所有代取员列表（按评分降序）**需认证**
POST `/api/users/verify` --- 身份实名认证 **需认证**
| 字段 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| id_card | string | 是 | 身份证号（18位） |
| real_name | string | 是 | 真实姓名 |
GET `/api/users/verify/status` --- 查询身份认证状态及时间 **需认证**
GET `/api/users/wallet` --- 查询钱包（余额/收入/支出）**需认证**
POST `/api/users/wallet/recharge` --- 钱包充值 **需认证**
| 字段 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| amount | float | 是 | 充值金额 |
POST `/api/users/wallet/withdraw` --- 钱包提现（需已实名认证）**需认证**
| 字段 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| amount | float | 是 | 提现金额 |
4.4 管理后台模块 (`/api/admin`) --- 均需 admin 权限
GET `/api/admin/stats` --- 平台总览统计（用户数/订单数/收入/评分等）
GET `/api/admin/stats/users` --- 用户增长趋势（按天，默认7天）
参数：`days`（天数）
GET `/api/admin/stats/orders` --- 订单增长趋势（按天，默认7天）
参数：`days`（天数）
GET `/api/admin/orders` --- 管理员查看所有订单（支持 status/page 分页）
PUT `/api/admin/orders/<order_id>` --- 管理员修改订单（status/status_reason/reward）
DELETE `/api/admin/orders/<order_id>` --- 管理员删除订单
GET `/api/admin/users` --- 管理员查看所有用户（支持 role/is_verified 过滤和分页）
GET `/api/admin/users/<target_user_id>` --- 管理员查看指定用户详情
PUT `/api/admin/users/<target_user_id>` --- 管理员修改用户信息
可更新字段：`phone`, `real_name`, `role`, `balance`, `total_earnings`, `total_spent`, `rating`, `is_verified`, `password`
DELETE `/api/admin/users/<target_user_id>` --- 管理员删除用户（不可删除自己）
GET `/api/admin/couriers` --- 管理员查看所有代取员（按总订单数降序）
GET `/api/admin/reviews` --- 管理员查看所有评价记录（支持 courier_id 过滤和分页）
4.5 聊天消息模块 (`/api/chat`)
GET `/api/chat/conversations` --- 获取会话列表（含最后消息和未读数）**需认证**
GET `/api/chat/messages` --- 获取聊天记录（自动标记已读）**需认证**
参数：`user_id`（必填）、`order_id`（可选）
POST `/api/chat/messages` --- 发送消息（≤500字，非管理员只能发给相关人员）**需认证**
| 字段 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| receiver_id | int | 是 | 接收者 ID |
| content | string | 是 | 消息内容 |
| order_id | int | 否 | 关联订单 ID |
GET `/api/chat/unread` --- 获取未读消息总数 **需认证**
GET `/api/chat/admin/conversations` --- 管理员获取私信会话列表 **需 admin 权限**
4.6 接口汇总
| 模块 | 数量 |
|------|------|
| 页面路由 | 5 |
| 认证 API | 3 |
| 订单 API | 9（含评价查询） |
| 用户 API | 9（含评价列表） |
| 管理 API | 12 |
| 聊天 API | 5 |
| **合计** | **43 个端点** |
HTTP 方法分布：GET(24) / POST(11) / PUT(5) / DELETE(2)
5. 验收标准
-
x 系统可正常启动运行
-
x 用户可完成注册登录
-
x 用户可发布代取订单
-
x 代取员可抢单
-
x 管理员可管理所有数据
-
x 前端界面美观易用
-
x 响应式适配移动端
6. 项目结构
```
campus_express/
├── app.py # Flask应用入口（单文件）
├── requirements.txt # 依赖
├── run.sh # 启动脚本
├── campus_express.db # SQLite数据库
├── static/
│ └── css/
│ └── style.css # 样式文件
│ └── js/
│ ├── main.js # 通用JS
│ ├── auth.js # 认证JS
│ └── dashboard.js # 控制台JS
└── templates/
├── index.html # 首页
├── login.html # 登录页
├── register.html # 注册页
└── dashboard.html # 控制台
```
7. 快速开始
7.1 安装依赖
```bash
cd campus_express
pip install -r requirements.txt
```
7.2 启动系统
```bash
python3 app.py
```
7.3 访问系统
7.4 默认管理员
在注册时设置 `role: admin` 或直接在数据库修改
8. 功能说明
| 功能 | 说明 |
|-----|-----|
| 发布订单 | 用户填写快递信息，发布代取需求 |
| 抢单 | 代取员在订单大厅抢单 |
| 完成取件 | 代取员确认取件完成 |
| 评价 | 用户对代取员进行评价 |
| 管理 | 管理员查看统计数据 |
*最后更新: 2026-04-2
