智慧加油站系统 - API接口设计文档
1. API接口规范
1.1 基本信息
- 基础URL :
/api/v1
- 认证方式:JWT Token
- 请求头部 :
Content-Type: application/json
Authorization: Bearer {token}
(认证接口除外)
- 数据格式:JSON
1.2 通用响应格式
json
{
"code": 200, // 状态码:200成功,4xx客户端错误,5xx服务器错误
"message": "success", // 响应消息
"data": {} // 响应数据
}
1.3 分页响应格式
json
{
"code": 200,
"message": "success",
"data": {
"list": [], // 数据列表
"pagination": {
"page": 1, // 当前页码
"page_size": 10, // 每页记录数
"total": 100, // 总记录数
"total_pages": 10 // 总页数
}
}
}
1.4 错误响应格式
json
{
"code": 400, // 错误码
"message": "参数错误", // 错误消息
"errors": { // 详细错误信息(可选)
"field1": ["错误描述1"],
"field2": ["错误描述2"]
}
}
2. API接口列表
2.1 认证接口
2.1.1 用户登录
- 接口 :
POST /auth/login
- 描述:用户登录获取访问令牌
- 请求参数:
json
{
"username": "admin", // 用户名
"password": "password123", // 密码
"remember": true // 是否记住登录状态
}
- 响应结果:
json
{
"code": 200,
"message": "success",
"data": {
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expires_in": 3600,
"user_info": {
"id": 1,
"username": "admin",
"role": {
"id": 1,
"name": "管理员",
"code": "admin"
}
}
}
}
2.1.2 用户登出
- 接口 :
POST /auth/logout
- 描述:用户登出,注销当前令牌
- 请求参数:无
- 响应结果:
json
{
"code": 200,
"message": "登出成功",
"data": null
}
2.1.3 刷新令牌
- 接口 :
POST /auth/refresh
- 描述:刷新访问令牌
- 请求参数:无(通过请求头中的令牌识别)
- 响应结果:
json
{
"code": 200,
"message": "success",
"data": {
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expires_in": 3600
}
}
2.2 用户与会员接口
2.2.1 获取用户信息
- 接口 :
GET /users/current
- 描述:获取当前登录用户信息
- 请求参数:无
- 响应结果:
json
{
"code": 200,
"message": "success",
"data": {
"id": 1,
"username": "admin",
"real_name": "管理员",
"mobile": "13800138000",
"email": "[email protected]",
"role": {
"id": 1,
"name": "管理员",
"code": "admin"
},
"avatar": "https://example.com/avatar.jpg",
"last_login_time": "2025-03-12T10:30:45"
}
}
2.2.2 用户列表
- 接口 :
GET /users
- 描述:获取用户列表
- 请求参数 :
page
:页码,默认1page_size
:每页记录数,默认10keyword
:搜索关键词role_id
:角色IDstatus
:状态
- 响应结果:分页响应格式
2.2.3 添加用户
- 接口 :
POST /users
- 描述:添加新用户
- 请求参数:
json
{
"username": "cashier001", // 用户名
"password": "password123", // 密码
"real_name": "张三", // 真实姓名
"mobile": "13800138001", // 手机号
"email": "[email protected]", // 邮箱
"role_id": 2, // 角色ID
"status": 1 // 状态
}
- 响应结果:
json
{
"code": 200,
"message": "添加成功",
"data": {
"id": 10,
"username": "cashier001"
}
}
2.2.4 更新用户
- 接口 :
PUT /users/{id}
- 描述:更新用户信息
- 请求参数:用户信息(不包含密码)
- 响应结果:成功响应
2.2.5 删除用户
- 接口 :
DELETE /users/{id}
- 描述:删除用户
- 请求参数:无
- 响应结果:成功响应
2.2.6 重置密码
- 接口 :
POST /users/{id}/reset-password
- 描述:重置用户密码
- 请求参数:
json
{
"password": "newpassword123"
}
- 响应结果:成功响应
2.2.7 获取会员信息
- 接口 :
GET /members/{id}
- 描述:获取会员详细信息
- 请求参数:无
- 响应结果:
json
{
"code": 200,
"message": "success",
"data": {
"id": 1,
"user_id": 5,
"member_no": "M2025031200001",
"level": 2,
"level_name": "银卡会员",
"balance": 1250.50,
"points": 3600,
"join_time": "2024-12-15T09:30:00",
"expire_time": "2025-12-15T09:30:00",
"status": 1,
"user_info": {
"username": "user001",
"real_name": "李四",
"mobile": "13900139000"
}
}
}
2.2.8 会员充值
- 接口 :
POST /members/{id}/recharge
- 描述:会员账户充值
- 请求参数:
json
{
"amount": 500.00, // 充值金额
"payment_method": "wechat", // 支付方式
"transaction_id": "wx123456789", // 支付流水号
"operator_id": 3 // 操作员ID
}
- 响应结果:成功响应
2.3 油品管理接口
2.3.1 获取油品列表
- 接口 :
GET /oils
- 描述:获取油品列表
- 请求参数 :
page
:页码,默认1page_size
:每页记录数,默认10keyword
:搜索关键词status
:状态(可选)
- 响应结果:分页响应格式,数据结构如下:
json
{
"code": 200,
"message": "success",
"data": {
"list": [
{
"id": 1,
"name": "92#汽油",
"code": "92#",
"type": "汽油",
"unit": "升",
"current_price": 7.85,
"status": 1,
"status_text": "正常"
},
// ...其他油品
],
"pagination": {
"page": 1,
"page_size": 10,
"total": 8,
"total_pages": 1
}
}
}
2.3.2 获取油品详情
- 接口 :
GET /oils/{id}
- 描述:获取油品详细信息
- 请求参数:无
- 响应结果:
json
{
"code": 200,
"message": "success",
"data": {
"id": 1,
"name": "92#汽油",
"code": "92#",
"type": "汽油",
"unit": "升",
"current_price": 7.85,
"cost_price": 7.25,
"status": 1,
"status_text": "正常",
"created_at": "2024-12-01T08:00:00",
"updated_at": "2025-03-01T10:15:30"
}
}
2.3.3 添加油品
- 接口 :
POST /oils
- 描述:添加新油品
- 请求参数:
json
{
"name": "95#汽油",
"code": "95#",
"type": "汽油",
"unit": "升",
"current_price": 8.45,
"cost_price": 7.85,
"status": 1
}
- 响应结果:
json
{
"code": 200,
"message": "添加成功",
"data": {
"id": 3,
"name": "95#汽油"
}
}
2.3.4 更新油品
- 接口 :
PUT /oils/{id}
- 描述:更新油品信息
- 请求参数:油品信息(同添加)
- 响应结果:成功响应
2.3.5 更新油品价格
- 接口 :
PUT /oils/{id}/price
- 描述:更新油品价格(同时记录历史)
- 请求参数:
json
{
"price": 8.05,
"effective_time": "2025-03-15T00:00:00",
"remark": "调价通知[2025]第12号"
}
- 响应结果:成功响应
2.3.6 获取油品价格历史
- 接口 :
GET /oils/{id}/price-history
- 描述:获取油品价格调整历史
- 请求参数 :
start_date
:开始日期end_date
:结束日期page
:页码page_size
:每页记录数
- 响应结果:分页响应格式,历史价格列表
2.4 站点管理接口
2.4.1 获取站点列表
- 接口 :
GET /stations
- 描述:获取加油站点列表
- 请求参数 :
page
:页码page_size
:每页记录数keyword
:搜索关键词city
:城市status
:状态
- 响应结果:分页响应格式,站点列表
2.4.2 获取站点详情
- 接口 :
GET /stations/{id}
- 描述:获取站点详细信息
- 请求参数:无
- 响应结果:站点详细信息
2.4.3 添加站点
- 接口 :
POST /stations
- 描述:添加新站点
- 请求参数:站点信息
- 响应结果:成功响应
2.4.4 更新站点
- 接口 :
PUT /stations/{id}
- 描述:更新站点信息
- 请求参数:站点信息
- 响应结果:成功响应
2.4.5 获取站点油品列表
- 接口 :
GET /stations/{id}/oils
- 描述:获取站点销售的油品列表
- 请求参数:无
- 响应结果:油品列表
2.4.6 获取站点油枪列表
- 接口 :
GET /stations/{id}/oil-guns
- 描述:获取站点的油枪列表
- 请求参数:无
- 响应结果:油枪列表及状态
2.5 油枪管理接口
2.5.1 获取油枪列表
- 接口 :
GET /oil-guns
- 描述:获取油枪列表
- 请求参数 :
station_id
:站点IDstatus
:状态oil_id
:油品ID
- 响应结果:分页响应格式,油枪列表
2.5.2 获取油枪详情
- 接口 :
GET /oil-guns/{id}
- 描述:获取油枪详细信息
- 请求参数:无
- 响应结果:油枪详细信息
2.5.3 添加油枪
- 接口 :
POST /oil-guns
- 描述:添加新油枪
- 请求参数:
json
{
"gun_no": "A1",
"station_id": 1,
"oil_id": 2,
"status": 1,
"remark": "新安装油枪"
}
- 响应结果:成功响应
2.5.4 更新油枪
- 接口 :
PUT /oil-guns/{id}
- 描述:更新油枪信息
- 请求参数:油枪信息
- 响应结果:成功响应
2.5.5 更新油枪状态
- 接口 :
PUT /oil-guns/{id}/status
- 描述:更新油枪状态
- 请求参数:
json
{
"status": 2,
"remark": "故障维修中"
}
- 响应结果:成功响应
2.6 订单管理接口
2.6.1 创建订单
- 接口 :
POST /orders
- 描述:创建加油订单
- 请求参数:
json
{
"station_id": 1,
"member_id": 5,
"oil_id": 2,
"oil_gun_id": 3,
"service_type": 1,
"amount": 50,
"vehicle_no": "粤B12345",
"attendant_id": 8,
"remark": "自助加油"
}
- 响应结果:
json
{
"code": 200,
"message": "订单创建成功",
"data": {
"order_id": 15,
"order_no": "GS202503121530001"
}
}
2.6.2 获取订单列表
- 接口 :
GET /orders
- 描述:获取订单列表
- 请求参数 :
page
:页码page_size
:每页记录数station_id
:站点IDmember_id
:会员IDstatus
:订单状态start_date
:开始日期end_date
:结束日期
- 响应结果:分页响应格式,订单列表
2.6.3 获取订单详情
- 接口 :
GET /orders/{id}
- 描述:获取订单详细信息
- 请求参数:无
- 响应结果:订单详细信息,包含加油记录、支付记录
2.6.4 更新订单状态
- 接口 :
PUT /orders/{id}/status
- 描述:更新订单状态
- 请求参数:
json
{
"status": 2,
"remark": "已完成加油"
}
- 响应结果:成功响应
2.6.5 取消订单
- 接口 :
POST /orders/{id}/cancel
- 描述:取消订单
- 请求参数:
json
{
"reason": "客户取消加油"
}
- 响应结果:成功响应
2.6.6 订单支付
- 接口 :
POST /orders/{id}/pay
- 描述:订单支付
- 请求参数:
json
{
"payment_method": "wechat",
"payment_amount": 392.50,
"transaction_id": "wx202503121535001",
"cashier_id": 10
}
- 响应结果:成功响应
2.7 加油记录接口
2.7.1 开始加油
- 接口 :
POST /refuel-records
- 描述:开始加油记录
- 请求参数:
json
{
"order_id": 15,
"oil_gun_id": 3,
"operator_id": 8
}
- 响应结果:
json
{
"code": 200,
"message": "开始加油",
"data": {
"record_id": 25,
"start_time": "2025-03-12T15:36:05"
}
}
2.7.2 结束加油
- 接口 :
PUT /refuel-records/{id}/end
- 描述:结束加油记录
- 请求参数:
json
{
"actual_amount": 50.0,
"status": 1
}
- 响应结果:成功响应
2.7.3 获取加油记录列表
- 接口 :
GET /refuel-records
- 描述:获取加油记录列表
- 请求参数 :
order_id
:订单IDoil_gun_id
:油枪IDstatus
:状态start_date
:开始日期end_date
:结束日期
- 响应结果:分页响应格式,加油记录列表
2.8 支付管理接口
2.8.1 获取支付记录列表
- 接口 :
GET /payments
- 描述:获取支付记录列表
- 请求参数 :
order_id
:订单IDpayment_method
:支付方式status
:状态start_date
:开始日期end_date
:结束日期
- 响应结果:分页响应格式,支付记录列表
2.8.2 获取支付记录详情
- 接口 :
GET /payments/{id}
- 描述:获取支付记录详情
- 请求参数:无
- 响应结果:支付记录详情
2.8.3 退款
- 接口 :
POST /payments/{id}/refund
- 描述:申请退款
- 请求参数:
json
{
"refund_amount": 392.50,
"reason": "客户投诉,同意退款",
"operator_id": 1
}
- 响应结果:成功响应
2.9 会员营销接口
2.9.1 创建优惠券
- 接口 :
POST /coupons
- 描述:创建优惠券
- 请求参数:
json
{
"name": "满100减10元优惠券",
"type": 1,
"discount_value": 10.00,
"min_amount": 100.00,
"total_quantity": 1000,
"start_time": "2025-03-15T00:00:00",
"end_time": "2025-04-15T23:59:59",
"applicable_oil_ids": "1,2,3",
"status": 1
}
- 响应结果:成功响应
2.9.2 获取优惠券列表
- 接口 :
GET /coupons
- 描述:获取优惠券列表
- 请求参数 :
status
:状态type
:类型keyword
:关键词搜索
- 响应结果:分页响应格式,优惠券列表
2.9.3 发放优惠券
- 接口 :
POST /coupons/{id}/distribute
- 描述:向用户发放优惠券
- 请求参数:
json
{
"user_ids": [1, 5, 8, 10],
"remark": "新用户注册活动"
}
- 响应结果:成功响应
2.9.4 获取用户优惠券
- 接口 :
GET /users/{id}/coupons
- 描述:获取用户的优惠券列表
- 请求参数 :
status
:状态(1-未使用,2-已使用,3-已过期)
- 响应结果:优惠券列表
2.9.5 使用优惠券
- 接口 :
POST /user-coupons/{id}/use
- 描述:使用优惠券
- 请求参数:
json
{
"order_id": 15
}
- 响应结果:成功响应
2.10 统计分析接口
2.10.1 销售统计
- 接口 :
GET /statistics/sales
- 描述:销售数据统计
- 请求参数 :
station_id
:站点IDstart_date
:开始日期end_date
:结束日期group_by
:分组方式(day/week/month/oil)
- 响应结果:统计数据
2.10.2 会员统计
- 接口 :
GET /statistics/members
- 描述:会员数据统计
- 请求参数 :
start_date
:开始日期end_date
:结束日期level
:会员等级
- 响应结果:会员统计数据
2.10.3 站点对比分析
- 接口 :
GET /statistics/stations/compare
- 描述:多站点数据对比
- 请求参数 :
station_ids
:站点ID列表start_date
:开始日期end_date
:结束日期indicator
:指标(sales/orders/members)
- 响应结果:对比数据
3. API 使用示例
3.1 完整加油流程 API 调用示例
步骤1:创建订单
http
POST /api/v1/orders
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
{
"station_id": 1,
"member_id": 5,
"oil_id": 2,
"oil_gun_id": 3,
"service_type": 1,
"amount": 50,
"vehicle_no": "粤B12345",
"attendant_id": 8
}
步骤2:开始加油
http
POST /api/v1/refuel-records
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
{
"order_id": 15,
"oil_gun_id": 3,
"operator_id": 8
}
步骤3:结束加油
http
PUT /api/v1/refuel-records/25/end
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
{
"actual_amount": 50.0,
"status": 1
}
步骤4:使用优惠券
http
POST /api/v1/user-coupons/12/use
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
{
"order_id": 15
}
步骤5:支付订单
http
POST /api/v1/orders/15/pay
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
{
"payment_method": "wechat",
"payment_amount": 392.50,
"transaction_id": "wx202503121535001",
"cashier_id": 10
}
4. API 安全设计
4.1 认证与授权
- JWT 令牌认证
- 令牌过期时间控制
- 令牌刷新机制
- 基于角色的权限控制(RBAC)
4.2 数据安全
- 敏感数据加密传输(HTTPS)
- 密码加密存储(使用 bcrypt 等算法)
- 敏感信息脱敏(例如手机号显示为 138****8000)
4.3 防护措施
- 频率限制(Rate Limiting)
- CSRF 防护
- 输入验证与过滤
- SQL 注入防护
- XSS 防护
5. 版本控制
API 版本控制采用 URL 路径方式,示例:
- 当前版本:
/api/v1/
- 未来版本:
/api/v2/
当 API 有不兼容变更时,将发布新版本,并保持旧版本一段时间的兼容支持。