智慧加油站小程序API设计文档

低代码布道师2025-03-16 8:01

智慧加油站系统 - 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：页码，默认1
    • page_size：每页记录数，默认10
    • keyword：搜索关键词
    • role_id：角色ID
    • status：状态
  • 响应结果：分页响应格式
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：页码，默认1
    • page_size：每页记录数，默认10
    • keyword：搜索关键词
    • 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：站点ID
    • status：状态
    • 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：站点ID
    • member_id：会员ID
    • status：订单状态
    • 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：订单ID
    • oil_gun_id：油枪ID
    • status：状态
    • start_date：开始日期
    • end_date：结束日期
  • 响应结果：分页响应格式，加油记录列表

2.8 支付管理接口

2.8.1 获取支付记录列表
  • 接口 ：GET /payments
  • 描述：获取支付记录列表
  • 请求参数 ：
    • order_id：订单ID
    • payment_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：站点ID
    • start_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 有不兼容变更时，将发布新版本，并保持旧版本一段时间的兼容支持。

相关推荐
知码者1 小时前
虚拟健身教练小程序：AI动作识别与个性化训练计划生成
人工智能·微信小程序·小程序·小程序开发
un_fired2 小时前
智能语音对话小程序功能优化day2-语音输入
小程序
大叔_爱编程4 小时前
wx131基于ssm+vue+uniapp的智能停车场管理系统小程序
vue.js·小程序·uni-app·毕业设计·ssm·源码·课程设计
luckyext13 小时前
Postman发送GET请求示例及注意事项
前端·后端·物联网·测试工具·小程序·c#·postman
大大。15 小时前
wepy微信小程序自定义底部弹出框功能,显示与隐藏效果（淡入淡出，滑入滑出）
微信小程序·小程序·notepad++
HAPPY酷1 天前
微信开发者工具内建终端使用不了npm，但是cmd可以
微信小程序·小程序·npm
源码code1 天前
微信小程序校园跑腿的设计与实现【lw+源码+部署+视频+讲解】
小程序
m0_664047021 天前
DeepSeek：为教培小程序赋能，引领行业变革新潮流
java·微信小程序·小程序·小程序开发·心理测评小程序
Good Lucky1 天前
微信小程序-实现锚点跳转，页面加载后自动跳转、点击跳转到指定位置
微信小程序·小程序
热门推荐
01从零安装 LLaMA-Factory 微调 Qwen 大模型成功及所有的坑02如何在WPS和Word/Excel中直接使用DeepSeek功能03DeepSeek各版本说明与优缺点分析04Unity图形学之法线贴图原理05DeepSeek RAGFlow构建本地知识库系统06本地部署DeepSeek教程（Mac版本）07Windows 11 安装 Dify 完整指南 非docker环境08如何本地部署AI智能体平台，带你手搓一个AI Agent09本地化部署AI知识库：基于Ollama+DeepSeek+AnythingLLM保姆级教程10KGG转MP3工具|非KGM文件|解密音频