rwadurian/backend/services/authorization-service/docs/API.md

# Authorization Service API 文档

## 目录

1. [概述](#概述)
2. [认证](#认证)
3. [通用响应格式](#通用响应格式)
4. [用户授权接口](#用户授权接口)
5. [管理员授权接口](#管理员授权接口)
6. [考核接口](#考核接口)
7. [管理员考核接口](#管理员考核接口)
8. [错误码](#错误码)

---

## 概述

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

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

---

## 认证

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

### 请求头

```http
Authorization: Bearer <jwt_token>
```

### Token 结构

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

---

## 通用响应格式

### 成功响应

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

### 错误响应

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

---

## 用户授权接口

### 1. 获取我的授权列表

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

**请求**

```http
GET /api/v1/authorizations/my
```

**响应**

```json
{
  "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. 申请省代公司授权

用户申请成为省代公司。

**请求**

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

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

**参数说明**

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

**响应**

```json
{
  "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. 申请市代公司授权

用户申请成为市代公司。

**请求**

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

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

**参数说明**

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

**响应**

```json
{
  "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. 申请社区授权

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

**请求**

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

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

**参数说明**

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

**响应**

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

---

### 5. 获取授权详情

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

**请求**

```http
GET /api/v1/authorizations/:id
```

**响应**

```json
{
  "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. 创建省代公司授权（直接）

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

**请求**

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

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

**参数说明**

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

**响应**

```json
{
  "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. 创建市代公司授权（直接）

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

**请求**

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

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

---

### 3. 审核授权申请

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

**请求**

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

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

**参数说明**

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

**响应**

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

---

### 4. 撤销授权

撤销用户的授权角色。

**请求**

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

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

**响应**

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

---

### 5. 查询待审核列表

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

**请求**

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

**查询参数**

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

**响应**

```json
{
  "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. 查询区域授权列表

按区域查询授权列表。

**请求**

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

**响应**

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

---

## 考核接口

### 1. 获取我的考核记录

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

**请求**

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

**响应**

```json
{
  "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. 获取当月考核进度

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

**请求**

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

**响应**

```json
{
  "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. 获取区域排名

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

**请求**

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

**查询参数**

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

**响应**

```json
{
  "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. 授予考核豁免

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

**请求**

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

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

**响应**

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

---

### 2. 手动执行月度考核

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

**请求**

```http
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 | 否 | 区域代码（不填则全部） |

**响应**

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

---

### 3. 查询区域考核汇总

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

**请求**

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

**响应**

```json
{
  "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 | 已豁免 |