# SaaS 系统管理服务 API（租户管理服务）

> **版本**: 1.0.0  
> **OpenAPI**: 3.0.1  
> **Base Path**: `/`  
> **认证方式**: Bearer JWT  
> **许可证**: Apache 2.0  

**描述**: 多租户 SaaS 平台 — 用户、角色、权限、租户管理接口

**Swagger 源地址**:  
http://121.41.54.56:9090/webjars/swagger-ui/index.html?urls.primaryName=%E7%A7%9F%E6%88%B7%E7%AE%A1%E7%90%86%E6%9C%8D%E5%8A%A1

**OpenAPI JSON**:  
http://121.41.54.56:9090/tenant/v3/api-docs

---

## 通用说明

### 认证

所有接口默认需要在请求头中携带 JWT Token：

```http
Authorization: Bearer <your-jwt-token>
```

### 统一响应结构

绝大多数接口返回统一的 `Result` 封装：

| 字段 | 类型 | 说明 |
|------|------|------|
| `code` | integer | 业务状态码 |
| `message` | string | 提示信息 |
| `data` | object / array / null | 业务数据 |
| `timestamp` | long | 时间戳 |
| `success` | boolean | 是否成功 |

### 分页结构 `PageResult`

| 字段 | 类型 | 说明 |
|------|------|------|
| `page` | long | 当前页 |
| `size` | long | 每页条数 |
| `total` | long | 总记录数 |
| `totalPages` | long | 总页数 |
| `records` | array | 数据列表 |

### 通用错误码

| HTTP Status | 说明 |
|-------------|------|
| 200 | 成功 |
| 400 | 请求参数错误 |
| 405 | 方法不允许 |
| 500 | 服务器内部错误 |

---

## 接口列表

### 1. 员工管理

#### 1.1 员工分页列表

```http
GET /tenant/employees
```

**说明**: 按条件分页查询本租户员工。需 `TENANT_ADMIN` 或平台管理员权限。

**Query 参数** (`EmployeePageQuery`):

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | integer | 否 | 页码 |
| size | integer | 否 | 每页条数 |
| sortBy | string | 否 | 排序字段 |
| sortDir | string | 否 | 排序方向 |
| orgId | long | 否 | 所属组织 ID |
| roleId | long | 否 | 角色 ID |
| status | string | 否 | 状态：`ACTIVE` / `DISABLED` |
| keyword | string | 否 | 关键词（姓名/手机号模糊匹配） |

**响应**: `ResultPageResultEmployeeVO`

---

#### 1.2 创建员工

```http
POST /tenant/employees
```

**说明**: 在当前租户下创建员工，`tenant_id` 由服务端自动填充。

**请求体** (`EmployeeCreateDTO`):

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | string | ✅ | 员工姓名 |
| phone | string | ✅ | 登录/联系手机号（同租户建议唯一） |
| orgId | long | ✅ | 所属组织 ID |
| roleId | long | ✅ | 角色 ID（预置 `TENANT_ADMIN` = 2） |
| position | string | 否 | 职位 |
| email | string | 否 | 邮箱 |
| avatarUrl | string | 否 | 头像 URL |
| holdLimit | integer | 否 | 客户持有上限 |
| region | string | 否 | 负责区域 |

**响应**: `ResultEmployeeVO`

---

#### 1.3 获取员工详情

```http
GET /tenant/employees/{id}
```

**路径参数**:

| 参数 | 类型 | 说明 |
|------|------|------|
| id | long | 员工 ID |

**响应**: `ResultEmployeeVO`

---

#### 1.4 更新员工

```http
PUT /tenant/employees/{id}
```

**说明**: 更新员工基本信息（不包含 password / avatarUrl / hireDate）。

**请求体** (`EmployeeUpdateDTO`):

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | string | 否 | 员工姓名 |
| phone | string | 否 | 登录/联系手机号 |
| orgId | long | 否 | 所属组织 ID |
| roleId | long | 否 | 角色 ID |
| position | string | 否 | 职位 |
| email | string | 否 | 邮箱 |
| holdLimit | integer | 否 | 客户持有上限 |
| region | string | 否 | 负责区域 |

**响应**: `ResultEmployeeVO`

---

#### 1.5 删除员工

```http
DELETE /tenant/employees/{id}
```

**路径参数**:

| 参数 | 类型 | 说明 |
|------|------|------|
| id | long | 员工 ID |

**响应**: `ResultVoid`

---

#### 1.6 按组织查员工分页

```http
GET /tenant/employees/by-org/{orgId}
```

**说明**: 分页返回指定组织下的**直接**员工（不含子孙组织）。

**路径参数**:

| 参数 | 类型 | 说明 |
|------|------|------|
| orgId | long | 组织 ID |

**Query 参数** (`EmployeeSubListQuery`): page / size / sortBy / sortDir

**响应**: `ResultPageResultEmployeeVO`

---

#### 1.7 按角色查员工分页

```http
GET /tenant/employees/by-role/{roleId}
```

**路径参数**:

| 参数 | 类型 | 说明 |
|------|------|------|
| roleId | long | 角色 ID |

**Query 参数** (`EmployeeSubListQuery`): page / size / sortBy / sortDir

**响应**: `ResultPageResultEmployeeVO`

---

#### 1.8 统计角色关联的员工数

```http
GET /tenant/employees/count-by-role/{roleId}
```

**说明**: 返回该角色下本租户员工数，可用于删除角色前校验。

**响应**: `ResultLong`

---

#### 1.9 导出员工（Excel）

```http
GET /tenant/employees/export
```

**说明**: 导出员工为 Excel 文件流（非标准 Result 封装）。

**Query 参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| orgId | long | 否 | 不填导出全部，填则仅导出指定组织 |

**响应**: Excel 文件流

---

#### 1.10 批量导入员工（Excel）

```http
POST /tenant/employees/import
```

**说明**: 上传 Excel 文件批量创建员工。

**请求**: `multipart/form-data`，字段名 `file`

**响应**: `ResultInteger`（成功导入行数）

---

### 2. 组织管理

#### 2.1 创建组织

```http
POST /tenant/organizations
```

**说明**: 创建组织节点。`orgPath` 由服务端根据 `parentId` 自动生成，`status` 初始为 `true`。

**请求体** (`OrgCreateDTO`):

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| orgName | string | ✅ | 组织名称 |
| orgType | string | 否 | 类型：`HQ` / `BRANCH` / `DEALER` / `AGENT` / `DEPT` / `TEAM`（默认 `DEPT`） |
| parentId | long | 否 | 上级组织 ID（根组织留空） |
| leaderId | long | 否 | 负责人员工 ID |
| region | string | 否 | 所在地区 |
| sortOrder | integer | 否 | 同级排序（数字越小越靠前） |

**响应**: `ResultOrgVO`

---

#### 2.2 获取组织树

```http
GET /tenant/organizations/tree
```

**说明**: 返回当前租户组织嵌套树。需 `TENANT_ADMIN` 或平台管理员。

**Query 参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| orgId | long | 否 | 传入则返回以该节点为根的子树；不传返回所有根组织 |

**响应**: `ResultListOrgVO`

---

#### 2.3 更新组织

```http
PUT /tenant/organizations/{id}
```

**说明**: 更新组织基本信息。`parentId` 变更后 `orgPath` 由服务端重算。

**请求体**: `OrgCreateDTO`（同创建）

**响应**: `ResultOrgVO`

---

#### 2.4 删除组织

```http
DELETE /tenant/organizations/{id}
```

**说明**: 删除组织。若存在子组织可能被拒绝。

**响应**: `ResultVoid`

---

#### 2.5 启用/停用组织

```http
PUT /tenant/organizations/{id}/toggle-status
```

**说明**: 在启用/停用之间切换。

**响应**: `ResultVoid`

---

### 3. 租户角色管理

#### 3.1 当前租户角色列表（含预设角色）

```http
GET /tenant/roles
```

**说明**: 返回本租户自建角色 + SYSTEM 全租户共享的预置角色（如 `TENANT_ADMIN` / `PLATFORM_ADMIN`）。预置角色置前。需 `TENANT_ADMIN` 登录。

**响应**: `ResultListRoleVO`

---

#### 3.2 获取角色详情

```http
GET /tenant/roles/{id}
```

**路径参数**:

| 参数 | 类型 | 说明 |
|------|------|------|
| id | long | 角色 ID |

**响应**: `ResultRoleVO`

---

#### 3.3 启用/停用角色

```http
PUT /tenant/roles/{id}/toggle-status
```

**说明**:  
- 仅允许租户管理员操作本租户的**自建角色**  
- 预置角色（`roleType=PRESET`）及跨租户角色会被拒绝（403）

**响应**: `ResultVoid`

---

### 4. 客户管理（后台 · 只读）

#### 4.1 本租户客户列表（只读）

```http
GET /tenant/customers
```

**说明**: 分页返回本租户所有客户（只读）。`ownerId` 不填=全部。

**Query 参数** (`TenantCustomerPageQuery`):

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | integer | 否 | 页码 |
| size | integer | 否 | 每页条数 |
| ownerId | long | 否 | 按归属销售员过滤 |

**响应**: `ResultPageResultCustomerVO`

---

#### 4.2 客户详情（只读）

```http
GET /tenant/customers/{id}
```

**说明**: 租户管理员可见本租户任意客户（未做归属校验）。

**响应**: `ResultCustomerVO`

---

#### 4.3 客户跟进历史（只读）

```http
GET /tenant/customers/{id}/follow-ups
```

**说明**: 分页返回该客户的跟进历史，按 `followAt` 倒序。

**Query 参数** (`FollowUpPageQuery`): page / size / sortBy / sortDir

**响应**: `ResultPageResultFollowUpVO`

---

### 5. 审计日志（租户端）

#### 5.1 本租户审计日志分页查询

```http
GET /tenant/audit-logs
```

**说明**: 强制按当前登录租户查询。需 `TENANT_ADMIN` 或平台管理员。

**Query 参数** (`AuditLogPageQuery`):

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | integer | 否 | 页码 |
| size | integer | 否 | 每页条数 |
| module | string | 否 | 模块过滤（EMPLOYEE / ORG / ROLE / CUSTOMER / FOLLOW_UP / TENANT / SYSTEM 等） |
| action | string | 否 | 操作动作（CREATE / UPDATE / DELETE / IMPORT 等） |
| entityType | string | 否 | 实体类型 |
| resultStatus | string | 否 | 结果状态（SUCCESS / FAILURE） |
| operatorId | long | 否 | 操作人 ID |
| start | date-time | 否 | 开始时间（yyyy-MM-dd HH:mm） |
| end | date-time | 否 | 结束时间（yyyy-MM-dd HH:mm） |

**响应**: `ResultPageResultAuditLogVO`

---

## 数据模型（Schemas）

### EmployeeVO（员工响应体）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | long | 主键 |
| createdAt | date-time | 创建时间 |
| updatedAt | date-time | 更新时间 |
| createdBy | string | 创建人 |
| updatedBy | string | 更新人 |
| tenantId | string | 所属租户 ID |
| deleted | integer | 软删除标记（0=未删除，1=已删除） |
| name | string | 员工姓名 |
| phone | string | 手机号 |
| orgId | long | 所属组织 ID |
| roleId | long | 角色 ID |
| position | string | 职位 |
| email | string | 邮箱 |
| avatarUrl | string | 头像 URL |
| status | string | `ACTIVE` / `DISABLED` |
| holdLimit | integer | 客户持有上限 |
| region | string | 负责区域 |
| hireDate | date | 入职日期 |

---

### OrgVO（组织响应体）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | long | 主键 |
| orgName | string | 组织名称 |
| orgType | string | `HQ` / `BRANCH` / `DEALER` / `AGENT` / `DEPT` / `TEAM` |
| parentId | long | 上级组织 ID |
| orgPath | string | 组织路径（如 `/默认租户/华东分公司`） |
| leaderId | long | 负责人 ID |
| region | string | 所在地区 |
| sortOrder | integer | 排序 |
| status | boolean | 启用状态 |
| children | array\<OrgVO\> | 直接子节点列表 |

---

### RoleVO（角色响应体）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | long | 主键 |
| roleName | string | 角色名称 |
| roleCode | string | 角色编码（预置如 `TENANT_ADMIN`） |
| description | string | 描述 |
| roleType | string | `PRESET`（预置） / `CUSTOM`（自建） |
| status | string | `ENABLED` / `DISABLED` / `DELETED` |

---

### CustomerVO（客户响应体）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | long | 主键 |
| name | string | 客户名称 |
| customerType | string | `ENTERPRISE` / `PERSONAL` |
| industry | string | 所属行业 |
| region | string | 所在地区 |
| contactName | string | 主要联系人 |
| contactPhone | string | 主要联系电话 |
| contactPosition | string | 职位 |
| contactTel | string | 备用电话 |
| email | string | 邮箱 |
| address | string | 地址 |
| demand | string | 需求描述 |
| source | string | `MINI_PROGRAM` / `SALES_INPUT` / `EXHIBITION` / `REFERRAL` / `WEBSITE` |
| level | string | `VIP` / `A` / `B` / `C` |
| tags | string | 标签（逗号分隔） |
| orgId | long | 所属组织 |
| ownerId | long | 归属销售员 ID |
| stage | string | `NEW_LEAD` / `PENDING_ASSIGN` / `CONTACTING` / `NEEDS_COMM` / `QUOTING` / `NEGOTIATING` / `DEAL` / `LOST` |
| lastFollowAt | date-time | 最近跟进时间 |
| nextFollowAt | date-time | 下次计划跟进时间 |
| dealAt | date-time | 成交时间 |
| lostAt | date-time | 流失时间 |
| lostReason | string | 流失原因 |

---

### FollowUpVO（跟进记录响应体）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | long | 主键 |
| customerId | long | 关联客户 ID |
| followerId | long | 跟进人 ID |
| followAt | date-time | 跟进实际时间 |
| followMethod | string | `PHONE` / `WECHAT` / `VISIT` / `EMAIL` / `MEETING` |
| content | string | 跟进内容 |
| nextFollowAt | date-time | 下次计划时间 |
| nextFollowPlan | string | 下次计划备注 |
| followStatus | string | `DONE` / `PENDING` / `OVERDUE` |
| recordType | string | `FOLLOW` / `PLAN` / `STAGE_CHANGE` |
| stageFrom | string | 阶段变化来源 |
| stageTo | string | 阶段变化目标 |

---

### AuditLogVO（审计日志响应体）

| 字段 | 类型 | 说明 |
|------|------|------|
| logId | long | 日志主键 |
| tenantId | string | 租户 ID |
| operatorId | long | 操作人 ID |
| operatorName | string | 操作人姓名 |
| operatorRole | string | 操作人角色 |
| module | string | 业务模块 |
| action | string | 操作动作 |
| operationDesc | string | 操作描述（中文摘要） |
| entityType | string | 实体类型 |
| entityId | string | 实体 ID |
| entityName | string | 实体名称 |
| changeDetail | string | 变更明细 |
| requestIp | string | 请求 IP |
| userAgent | string | User-Agent |
| requestPath | string | 请求路径 |
| requestMethod | string | 请求方法 |
| resultStatus | string | `SUCCESS` / `FAILURE` |
| errorMessage | string | 失败错误消息 |
| createdAt | date-time | 创建时间 |

---

## 权限说明

| 角色/权限 | 可访问接口 |
|-----------|------------|
| TENANT_ADMIN | 本租户员工、组织、角色、客户（只读）、审计日志 |
| 平台管理员 | 以上所有 + 跨租户能力 |
| 普通员工 | 根据业务接口权限控制 |

---

*文档根据 OpenAPI 规范自动生成，内容以实际接口返回为准。*