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

智慧加油站系统 - API接口设计文档

1. API接口规范

1.1 基本信息

• 基础URL：/api/v1
• 认证方式：JWT Token
• 请求头部：
  • Content-Type: application/json
  • Authorization: Bearer {token} (认证接口除外)
• 数据格式：JSON

1.2 通用响应格式

{
    "code": 200,                 // 状态码：200成功，4xx客户端错误，5xx服务器错误
    "message": "success",        // 响应消息
    "data": {}                   // 响应数据
}

1.3 分页响应格式

{
    "code": 200,
    "message": "success",
    "data": {
        "list": [],              // 数据列表
        "pagination": {
            "page": 1,           // 当前页码
            "page_size": 10,     // 每页记录数
            "total": 100,        // 总记录数
            "total_pages": 10    // 总页数
        }
    }
}

1.4 错误响应格式

{
    "code": 400,                 // 错误码
    "message": "参数错误",        // 错误消息
    "errors": {                  // 详细错误信息（可选）
        "field1": ["错误描述1"],
        "field2": ["错误描述2"]
    }
}

2. API接口列表

2.1 认证接口

2.1.1 用户登录

• 接口：POST /auth/login
• 描述：用户登录获取访问令牌
• 请求参数：

{
    "username": "admin",         // 用户名
    "password": "password123",   // 密码
    "remember": true             // 是否记住登录状态
}

• 响应结果：

{
    "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
• 描述：用户登出，注销当前令牌
• 请求参数：无
• 响应结果：

{
    "code": 200,
    "message": "登出成功",
    "data": null
}

2.1.3 刷新令牌

• 接口：POST /auth/refresh
• 描述：刷新访问令牌
• 请求参数：无（通过请求头中的令牌识别）
• 响应结果：

{
    "code": 200,
    "message": "success",
    "data": {
        "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "expires_in": 3600
    }
}

2.2 用户与会员接口

2.2.1 获取用户信息

• 接口：GET /users/current
• 描述：获取当前登录用户信息
• 请求参数：无
• 响应结果：

{
    "code": 200,
    "message": "success",
    "data": {
        "id": 1,
        "username": "admin",
        "real_name": "管理员",
        "mobile": "13800138000",
        "email": "admin@example.com",
        "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
• 描述：添加新用户
• 请求参数：

{
    "username": "cashier001",    // 用户名
    "password": "password123",   // 密码
    "real_name": "张三",         // 真实姓名
    "mobile": "13800138001",     // 手机号
    "email": "zhangsan@example.com", // 邮箱
    "role_id": 2,                // 角色ID
    "status": 1                  // 状态
}

• 响应结果：

{
    "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
• 描述：重置用户密码
• 请求参数：

{
    "password": "newpassword123"
}

• 响应结果：成功响应

2.2.7 获取会员信息

• 接口：GET /members/{id}
• 描述：获取会员详细信息
• 请求参数：无
• 响应结果：

{
    "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
• 描述：会员账户充值
• 请求参数：

{
    "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：状态（可选）
• 响应结果：分页响应格式，数据结构如下：

{
    "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}
• 描述：获取油品详细信息
• 请求参数：无
• 响应结果：

{
    "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
• 描述：添加新油品
• 请求参数：

{
    "name": "95#汽油",
    "code": "95#",
    "type": "汽油",
    "unit": "升",
    "current_price": 8.45,
    "cost_price": 7.85,
    "status": 1
}

• 响应结果：

{
    "code": 200,
    "message": "添加成功",
    "data": {
        "id": 3,
        "name": "95#汽油"
    }
}

2.3.4 更新油品

• 接口：PUT /oils/{id}
• 描述：更新油品信息
• 请求参数：油品信息（同添加）
• 响应结果：成功响应

2.3.5 更新油品价格

• 接口：PUT /oils/{id}/price
• 描述：更新油品价格（同时记录历史）
• 请求参数：

{
    "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
• 描述：添加新油枪
• 请求参数：

{
    "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
• 描述：更新油枪状态
• 请求参数：

{
    "status": 2,
    "remark": "故障维修中"
}

• 响应结果：成功响应

2.6 订单管理接口

2.6.1 创建订单

• 接口：POST /orders
• 描述：创建加油订单
• 请求参数：

{
    "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": "自助加油"
}

• 响应结果：

{
    "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
• 描述：更新订单状态
• 请求参数：

{
    "status": 2,
    "remark": "已完成加油"
}

• 响应结果：成功响应

2.6.5 取消订单

• 接口：POST /orders/{id}/cancel
• 描述：取消订单
• 请求参数：

{
    "reason": "客户取消加油"
}

• 响应结果：成功响应

2.6.6 订单支付

• 接口：POST /orders/{id}/pay
• 描述：订单支付
• 请求参数：

{
    "payment_method": "wechat", 
    "payment_amount": 392.50,
    "transaction_id": "wx202503121535001",
    "cashier_id": 10
}

• 响应结果：成功响应

2.7 加油记录接口

2.7.1 开始加油

• 接口：POST /refuel-records
• 描述：开始加油记录
• 请求参数：

{
    "order_id": 15,
    "oil_gun_id": 3,
    "operator_id": 8
}

• 响应结果：

{
    "code": 200,
    "message": "开始加油",
    "data": {
        "record_id": 25,
        "start_time": "2025-03-12T15:36:05"
    }
}

2.7.2 结束加油

• 接口：PUT /refuel-records/{id}/end
• 描述：结束加油记录
• 请求参数：

{
    "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
• 描述：申请退款
• 请求参数：

{
    "refund_amount": 392.50,
    "reason": "客户投诉，同意退款",
    "operator_id": 1
}

• 响应结果：成功响应

2.9 会员营销接口

2.9.1 创建优惠券

• 接口：POST /coupons
• 描述：创建优惠券
• 请求参数：

{
    "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
• 描述：向用户发放优惠券
• 请求参数：

{
    "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
• 描述：使用优惠券
• 请求参数：

{
    "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：创建订单

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：开始加油

POST /api/v1/refuel-records
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

{
    "order_id": 15,
    "oil_gun_id": 3,
    "operator_id": 8
}

步骤3：结束加油

PUT /api/v1/refuel-records/25/end
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

{
    "actual_amount": 50.0,
    "status": 1
}

步骤4：使用优惠券

POST /api/v1/user-coupons/12/use
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

{
    "order_id": 15
}

步骤5：支付订单

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 有不兼容变更时，将发布新版本，并保持旧版本一段时间的兼容支持。