13 KiB

Raw Blame History

Authorization Service API 文档

概述

Authorization Service 提供 RESTful API 用于管理用户授权和月度考核。

Base URL: /api/v1
Content-Type: application/json
认证方式: JWT Bearer Token

认证

所有接口都需要 JWT 认证，除非特别说明。

请求头

Authorization: Bearer <jwt_token>

Token 结构

{
  "sub": "user-id",
  "roles": ["USER", "ADMIN"],
  "iat": 1700000000,
  "exp": 1700086400
}

通用响应格式

成功响应

{
  "success": true,
  "data": { ... },
  "message": "操作成功"
}

错误响应

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "错误描述"
  }
}

用户授权接口

1. 获取我的授权列表

获取当前用户的所有授权角色。

请求

GET /api/v1/authorizations/my

响应

{
  "success": true,
  "data": [
    {
      "id": "auth-123",
      "roleType": "AUTH_PROVINCE_COMPANY",
      "status": "ACTIVE",
      "provinceCode": "430000",
      "provinceName": "湖南省",
      "cityCode": null,
      "cityName": null,
      "communityName": null,
      "authorizedAt": "2024-01-15T10:30:00Z",
      "createdAt": "2024-01-01T08:00:00Z"
    }
  ]
}

2. 申请省代公司授权

用户申请成为省代公司。

请求

POST /api/v1/authorizations/province
Content-Type: application/json

{
  "provinceCode": "430000",
  "provinceName": "湖南省"
}

参数说明

参数	类型	必填	说明
provinceCode	string	是	省份代码（6位数字）
provinceName	string	是	省份名称

响应

{
  "success": true,
  "data": {
    "id": "auth-456",
    "roleType": "AUTH_PROVINCE_COMPANY",
    "status": "PENDING",
    "provinceCode": "430000",
    "provinceName": "湖南省",
    "createdAt": "2024-01-20T09:00:00Z"
  },
  "message": "授权申请已提交，等待审核"
}

错误场景

错误码	说明
ALREADY_HAS_AUTHORIZATION	用户已有省代或市代授权
TEAM_CONFLICT	本团队已有人申请该区域授权
INVALID_PROVINCE_CODE	省份代码格式无效

3. 申请市代公司授权

用户申请成为市代公司。

请求

POST /api/v1/authorizations/city
Content-Type: application/json

{
  "provinceCode": "430000",
  "provinceName": "湖南省",
  "cityCode": "430100",
  "cityName": "长沙市"
}

参数说明

参数	类型	必填	说明
provinceCode	string	是	省份代码
provinceName	string	是	省份名称
cityCode	string	是	城市代码（6位数字）
cityName	string	是	城市名称

响应

{
  "success": true,
  "data": {
    "id": "auth-789",
    "roleType": "AUTH_CITY_COMPANY",
    "status": "PENDING",
    "provinceCode": "430000",
    "provinceName": "湖南省",
    "cityCode": "430100",
    "cityName": "长沙市",
    "createdAt": "2024-01-20T09:00:00Z"
  },
  "message": "授权申请已提交，等待审核"
}

4. 申请社区授权

用户申请成为社区管理员。

请求

POST /api/v1/authorizations/community
Content-Type: application/json

{
  "communityName": "阳光社区"
}

参数说明

参数	类型	必填	说明
communityName	string	是	社区名称

响应

{
  "success": true,
  "data": {
    "id": "auth-abc",
    "roleType": "COMMUNITY",
    "status": "PENDING",
    "communityName": "阳光社区",
    "createdAt": "2024-01-20T09:00:00Z"
  },
  "message": "授权申请已提交，等待审核"
}

5. 获取授权详情

获取指定授权的详细信息。

请求

GET /api/v1/authorizations/:id

响应

{
  "success": true,
  "data": {
    "id": "auth-123",
    "userId": "user-001",
    "roleType": "AUTH_PROVINCE_COMPANY",
    "status": "ACTIVE",
    "provinceCode": "430000",
    "provinceName": "湖南省",
    "cityCode": null,
    "cityName": null,
    "communityName": null,
    "authorizedBy": "admin-001",
    "authorizedAt": "2024-01-15T10:30:00Z",
    "activatedAt": "2024-02-01T00:00:00Z",
    "createdAt": "2024-01-01T08:00:00Z",
    "updatedAt": "2024-02-01T00:00:00Z"
  }
}

管理员授权接口

需要 ADMIN 角色

1. 创建省代公司授权（直接）

管理员直接为用户创建省代公司授权。

请求

POST /api/v1/admin/authorizations/province-company
Content-Type: application/json

{
  "userId": "user-001",
  "provinceCode": "430000",
  "provinceName": "湖南省"
}

参数说明

参数	类型	必填	说明
userId	string	是	目标用户ID
provinceCode	string	是	省份代码
provinceName	string	是	省份名称

响应

{
  "success": true,
  "data": {
    "id": "auth-123",
    "userId": "user-001",
    "roleType": "AUTH_PROVINCE_COMPANY",
    "status": "APPROVED",
    "provinceCode": "430000",
    "provinceName": "湖南省",
    "authorizedBy": "admin-001",
    "authorizedAt": "2024-01-20T10:00:00Z"
  },
  "message": "省代公司授权创建成功"
}

2. 创建市代公司授权（直接）

管理员直接为用户创建市代公司授权。

请求

POST /api/v1/admin/authorizations/city-company
Content-Type: application/json

{
  "userId": "user-002",
  "provinceCode": "430000",
  "provinceName": "湖南省",
  "cityCode": "430100",
  "cityName": "长沙市"
}

3. 审核授权申请

审核用户提交的授权申请。

请求

POST /api/v1/admin/authorizations/:id/review
Content-Type: application/json

{
  "approved": true,
  "reason": "审核通过"
}

参数说明

参数	类型	必填	说明
approved	boolean	是	是否通过
reason	string	否	审核原因/备注

响应

{
  "success": true,
  "data": {
    "id": "auth-123",
    "status": "APPROVED",
    "reviewedBy": "admin-001",
    "reviewedAt": "2024-01-20T11:00:00Z",
    "reviewReason": "审核通过"
  },
  "message": "授权审核完成"
}

4. 撤销授权

撤销用户的授权角色。

请求

POST /api/v1/admin/authorizations/:id/revoke
Content-Type: application/json

{
  "reason": "违规操作"
}

响应

{
  "success": true,
  "data": {
    "id": "auth-123",
    "status": "REVOKED",
    "revokedBy": "admin-001",
    "revokedAt": "2024-03-01T14:00:00Z",
    "revokeReason": "违规操作"
  },
  "message": "授权已撤销"
}

5. 查询待审核列表

获取所有待审核的授权申请。

请求

GET /api/v1/admin/authorizations/pending?page=1&limit=20

查询参数

参数	类型	必填	默认值	说明
page	number	否	1	页码
limit	number	否	20	每页数量
roleType	string	否	-	筛选角色类型

响应

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "auth-456",
        "userId": "user-003",
        "userName": "张三",
        "roleType": "AUTH_PROVINCE_COMPANY",
        "status": "PENDING",
        "provinceCode": "440000",
        "provinceName": "广东省",
        "createdAt": "2024-01-19T16:00:00Z"
      }
    ],
    "total": 15,
    "page": 1,
    "limit": 20,
    "totalPages": 1
  }
}

6. 查询区域授权列表

按区域查询授权列表。

请求

GET /api/v1/admin/authorizations/region/:regionCode

响应

{
  "success": true,
  "data": [
    {
      "id": "auth-123",
      "userId": "user-001",
      "userName": "李四",
      "roleType": "AUTH_PROVINCE_COMPANY",
      "status": "ACTIVE",
      "provinceCode": "430000",
      "provinceName": "湖南省"
    }
  ]
}

考核接口

1. 获取我的考核记录

获取当前用户的考核历史。

请求

GET /api/v1/assessments/my?page=1&limit=12

响应

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "assess-001",
        "authorizationId": "auth-123",
        "roleType": "AUTH_PROVINCE_COMPANY",
        "assessmentMonth": "2024-01",
        "monthIndex": 1,
        "monthlyTarget": 150,
        "cumulativeTarget": 150,
        "monthlyCompleted": 180,
        "cumulativeCompleted": 180,
        "localPercentage": 35.5,
        "localPercentagePass": true,
        "exceedRatio": 1.2,
        "result": "PASS",
        "rankingInRegion": 3,
        "isFirstPlace": false,
        "isBypassed": false,
        "assessedAt": "2024-02-01T00:30:00Z"
      }
    ],
    "total": 6,
    "page": 1,
    "limit": 12
  }
}

2. 获取当月考核进度

获取当前授权的本月考核进度。

请求

GET /api/v1/assessments/current/:authorizationId

响应

{
  "success": true,
  "data": {
    "authorizationId": "auth-123",
    "roleType": "AUTH_PROVINCE_COMPANY",
    "currentMonth": "2024-02",
    "monthIndex": 2,
    "monthlyTarget": 300,
    "cumulativeTarget": 450,
    "currentProgress": 280,
    "cumulativeProgress": 460,
    "progressPercentage": 93.3,
    "cumulativePercentage": 102.2,
    "localTeamCount": 50,
    "totalTeamCount": 140,
    "localPercentage": 35.7,
    "requiredLocalPercentage": 30,
    "daysRemaining": 12
  }
}

3. 获取区域排名

获取指定区域的授权排名。

请求

GET /api/v1/assessments/rankings/:regionCode?month=2024-01

查询参数

参数	类型	必填	说明
month	string	否	考核月份（默认上月）

响应

{
  "success": true,
  "data": {
    "regionCode": "430000",
    "regionName": "湖南省",
    "month": "2024-01",
    "rankings": [
      {
        "rank": 1,
        "userId": "user-005",
        "userName": "王五",
        "exceedRatio": 1.85,
        "cumulativeCompleted": 277,
        "cumulativeTarget": 150,
        "isFirstPlace": true
      },
      {
        "rank": 2,
        "userId": "user-001",
        "userName": "李四",
        "exceedRatio": 1.20,
        "cumulativeCompleted": 180,
        "cumulativeTarget": 150,
        "isFirstPlace": false
      }
    ]
  }
}

管理员考核接口

需要 ADMIN 角色

1. 授予考核豁免

为指定用户的考核授予单月豁免。

请求

POST /api/v1/admin/assessments/:assessmentId/bypass
Content-Type: application/json

{
  "reason": "特殊情况豁免"
}

响应

{
  "success": true,
  "data": {
    "id": "assess-001",
    "result": "BYPASSED",
    "bypassedBy": "admin-001",
    "bypassedAt": "2024-02-15T10:00:00Z"
  },
  "message": "豁免已授予"
}

2. 手动执行月度考核

手动触发指定月份的考核计算。

请求

POST /api/v1/admin/assessments/run
Content-Type: application/json

{
  "month": "2024-01",
  "roleType": "AUTH_PROVINCE_COMPANY",
  "regionCode": "430000"
}

参数说明

参数	类型	必填	说明
month	string	是	考核月份（YYYY-MM）
roleType	string	否	角色类型（不填则全部）
regionCode	string	否	区域代码（不填则全部）

响应

{
  "success": true,
  "data": {
    "month": "2024-01",
    "processedCount": 45,
    "passedCount": 38,
    "failedCount": 7,
    "bypassedCount": 0
  },
  "message": "考核执行完成"
}

3. 查询区域考核汇总

查询指定区域的考核统计数据。

请求

GET /api/v1/admin/assessments/summary/:regionCode?month=2024-01

响应

{
  "success": true,
  "data": {
    "regionCode": "430000",
    "month": "2024-01",
    "totalAuthorizations": 50,
    "assessedCount": 48,
    "passedCount": 40,
    "failedCount": 6,
    "bypassedCount": 2,
    "passRate": 83.3,
    "averageExceedRatio": 1.15
  }
}

错误码

错误码	HTTP状态码	说明
UNAUTHORIZED	401	未认证或Token无效
FORBIDDEN	403	无权限访问
NOT_FOUND	404	资源不存在
VALIDATION_ERROR	400	请求参数验证失败
ALREADY_HAS_AUTHORIZATION	400	用户已有省代或市代授权
TEAM_CONFLICT	400	团队内存在冲突授权
INVALID_STATUS_TRANSITION	400	无效的状态转换
AUTHORIZATION_NOT_ACTIVE	400	授权未激活
ASSESSMENT_ALREADY_BYPASSED	400	考核已豁免
INTERNAL_ERROR	500	服务器内部错误

枚举值

RoleType（角色类型）

值	说明
AUTH_PROVINCE_COMPANY	省代公司
AUTH_CITY_COMPANY	市代公司
COMMUNITY	社区

AuthorizationStatus（授权状态）

值	说明
PENDING	待审核
APPROVED	已审核（待激活）
REJECTED	已拒绝
ACTIVE	已激活
REVOKED	已撤销

AssessmentResult（考核结果）

值	说明
NOT_ASSESSED	未考核
PASS	通过
FAIL	未通过
BYPASSED	已豁免

13 KiB Raw Blame History Unescape Escape

Authorization Service API 文档

目录

概述

认证

请求头

Token 结构

通用响应格式

成功响应

错误响应

用户授权接口

1. 获取我的授权列表

2. 申请省代公司授权

3. 申请市代公司授权

4. 申请社区授权

5. 获取授权详情

管理员授权接口

1. 创建省代公司授权（直接）

2. 创建市代公司授权（直接）

3. 审核授权申请

4. 撤销授权

5. 查询待审核列表

6. 查询区域授权列表

考核接口

1. 获取我的考核记录

2. 获取当月考核进度

3. 获取区域排名

管理员考核接口

1. 授予考核豁免

2. 手动执行月度考核

3. 查询区域考核汇总

错误码

枚举值

RoleType（角色类型）

AuthorizationStatus（授权状态）

AssessmentResult（考核结果）

13 KiB

Raw Blame History