fastadmin_tailored/docs/验货员申请API接口文档.md

验货员申请API接口文档

接口概述

验货员申请功能提供了完整的申请、审核流程，包括用户端申请接口和管理员端审核接口。

用户端API接口

1. 检查申请资格

接口地址： GET /api/inspection/application/checkEligibility

请求参数： 无

响应示例：

{
    "code": 1,
    "msg": "检查成功", 
    "time": "2024-01-01 12:00:00",
    "data": {
        "can_apply": true,
        "status": "no_application",
        "message": "您还未申请验货员，可以提交申请"
    }
}

状态说明：

• no_application: 未申请，可以申请
• pending: 审核中，不可申请
• passed: 审核通过，已是验货员
• rejected: 审核驳回，可以重新申请

2. 提交申请

接口地址： POST /api/inspection/application/create

请求参数：

{
    "name": "彭于晏",
    "phone": "16677778888",
    "province_adcode": "530000",
    "city_adcode": "530100", 
    "district_adcode": "530181",
    "region_full": "云南省丽江市玉龙纳西族自治县",
    "address": "玉龙雪山名胜区",
    "id_card_front": "/uploads/20240101/abc123.jpg",
    "id_card_back": "/uploads/20240101/def456.jpg"
}

响应示例：

{
    "code": 1,
    "msg": "申请提交成功，请耐心等待审核",
    "time": "2024-01-01 12:00:00", 
    "data": {
        "id": 1,
        "audit_status": 1,
        "audit_status_text": "审核中"
    }
}

3. 查看申请详情

接口地址： GET /api/inspection/application/detail

请求参数：

• id: 申请ID (必填)

响应示例：

{
    "code": 1,
    "msg": "获取成功",
    "time": "2024-01-01 12:00:00",
    "data": {
        "id": 1,
        "user_id": 123,
        "name": "彭于晏",
        "phone": "16677778888",
        "province_adcode": "530000",
        "city_adcode": "530100",
        "district_adcode": "530181", 
        "region_full": "云南省丽江市玉龙纳西族自治县",
        "address": "玉龙雪山名胜区",
        "id_card_front": "https://domain.com/uploads/20240101/abc123.jpg",
        "id_card_back": "https://domain.com/uploads/20240101/def456.jpg",
        "apply_time": 1704067200,
        "audit_time": 0,
        "audit_status": 1,
        "reject_reason": "",
        "audit_status_text": "审核中",
        "apply_time_text": "2024-01-01 12:00:00",
        "audit_time_text": ""
    }
}

4. 查看申请列表

接口地址： GET /api/inspection/application/index

请求参数： 无

响应示例：

{
    "code": 1,
    "msg": "获取成功",
    "time": "2024-01-01 12:00:00",
    "data": [
        {
            "id": 1,
            "name": "彭于晏",
            "phone": "16677778888", 
            "region_full": "云南省丽江市玉龙纳西族自治县",
            "audit_status": 1,
            "audit_status_text": "审核中",
            "apply_time": 1704067200,
            "apply_time_text": "2024-01-01 12:00:00",
            "reject_reason": ""
        }
    ]
}

5. 修改申请信息

接口地址： POST /api/inspection/application/update

请求参数：

{
    "id": 1,
    "name": "彭于晏",
    "phone": "16677778888",
    "province_adcode": "530000",
    "city_adcode": "530100",
    "district_adcode": "530181",
    "region_full": "云南省丽江市玉龙纳西族自治县", 
    "address": "玉龙雪山名胜区",
    "id_card_front": "/uploads/20240101/abc123.jpg",
    "id_card_back": "/uploads/20240101/def456.jpg"
}

响应示例：

{
    "code": 1,
    "msg": "修改成功",
    "time": "2024-01-01 12:00:00",
    "data": {
        "id": 1,
        "audit_status": 1,
        "audit_status_text": "审核中"
    }
}

注意事项：

• 只有审核状态为"审核中"的申请才能修改
• 修改后审核状态保持不变，需要重新等待审核

管理员端接口

1. 申请列表（后台）

接口地址： GET /admin/inspection/application/index

功能： 管理员查看所有申请列表，支持搜索和筛选

2. 申请详情（后台）

接口地址： GET /admin/inspection/application/detail/{id}

功能： 查看申请详细信息

3. 审核申请

接口地址： POST /admin/inspection/application/audit/{id}

请求参数：

• audit_status: 审核状态 (2=通过, 3=驳回)
• reject_reason: 驳回原因 (驳回时必填)

4. 批量审核通过

接口地址： POST /admin/inspection/application/batchPass

请求参数：

• ids: 申请ID数组

5. 批量审核驳回

接口地址： POST /admin/inspection/application/batchReject

请求参数：

• ids: 申请ID数组
• reject_reason: 驳回原因

错误码说明

• code: 1 - 成功
• code: 0 - 失败，具体错误信息在 msg 字段中

常见错误信息

• "您已有申请记录，请勿重复申请"
• "该手机号已被其他用户申请"
• "申请记录不存在或无权访问"
• "该申请状态下不允许修改"
• "驳回申请必须填写驳回原因"

数据库设计

审核状态字段值

• 1: 审核中
• 2: 审核通过
• 3: 审核驳回

表结构

CREATE TABLE `inspection_application` (
  `id` int(10) unsigned NOT NULL AUTO_INCREMENT COMMENT '申请ID（主键）',
  `user_id` int(11) NOT NULL DEFAULT '0' COMMENT '用户ID（关联用户表）',
  `name` varchar(50) COLLATE utf8mb4_unicode_ci NOT NULL DEFAULT '' COMMENT '姓名',
  `phone` varchar(20) COLLATE utf8mb4_unicode_ci NOT NULL DEFAULT '' COMMENT '联系电话',
  `province_adcode` varchar(50) COLLATE utf8mb4_unicode_ci NOT NULL DEFAULT '' COMMENT '省级编码',
  `city_adcode` varchar(50) COLLATE utf8mb4_unicode_ci NOT NULL DEFAULT '' COMMENT '市级编码',
  `district_adcode` varchar(50) COLLATE utf8mb4_unicode_ci NOT NULL DEFAULT '' COMMENT '区县编码（关联fa_shop_area）',
  `region_full` varchar(100) COLLATE utf8mb4_unicode_ci NOT NULL DEFAULT '' COMMENT '完整地区名称',
  `address` varchar(255) COLLATE utf8mb4_unicode_ci NOT NULL DEFAULT '' COMMENT '详细地址',
  `id_card_front` varchar(255) COLLATE utf8mb4_unicode_ci NOT NULL DEFAULT '' COMMENT '身份证正面路径',
  `id_card_back` varchar(255) COLLATE utf8mb4_unicode_ci NOT NULL COMMENT '身份证反面路径',
  `apply_time` bigint(20) NOT NULL DEFAULT '0' COMMENT '申请时间',
  `audit_time` bigint(20) NOT NULL DEFAULT '0' COMMENT '审核时间',
  `audit_status` tinyint(4) NOT NULL DEFAULT '1' COMMENT '状态（1:审核中/2:通过/3:驳回）',
  `reject_reason` varchar(255) COLLATE utf8mb4_unicode_ci NOT NULL COMMENT '审核失败原因',
  `status` tinyint(4) NOT NULL DEFAULT '1' COMMENT '状态',
  `createtime` bigint(20) DEFAULT NULL COMMENT '创建时间',
  `updatetime` bigint(20) DEFAULT NULL COMMENT '更新时间',
  `deletetime` bigint(20) DEFAULT NULL COMMENT '删除时间',
  PRIMARY KEY (`id`),
  UNIQUE KEY `unique_phone` (`phone`),
  KEY `idx_name` (`name`),
  KEY `idx_province` (`province_adcode`),
  KEY `idx_city` (`city_adcode`),
  KEY `idx_district` (`district_adcode`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='验货员申请表';