From e65a432f5c9fc11d15d53ae0e16e5f4b7d62400a Mon Sep 17 00:00:00 2001
From: wsj <593216709@qq.com>
Date: Sat, 17 Oct 2026 20:53:17 +0800
Subject: [PATCH] feat: api

---
 src/api/api-tenant.md | 1502 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 1,502 insertions(+), 0 deletions(-)

diff --git a/src/api/api-tenant.md b/src/api/api-tenant.md
new file mode 100644
index 0000000..95909ce
--- /dev/null
+++ b/src/api/api-tenant.md
@@ -0,0 +1,1502 @@
+# SaaS 系统管理服务 API（租户版）
+
+> **版本**: 1.0.0  
+> **描述**: 多租户 SaaS 平台 — 用户、角色、权限、租户管理接口  
+> **License**: Apache 2.0  
+> **Contact**: SaaS Platform Team
+
+---
+
+## 基本信息
+
+| 项目 | 说明 |
+|------|------|
+| Base URL | `http://121.41.54.56:9090` |
+| OpenAPI | 3.0.1 |
+| 认证方式 | Bearer JWT（Header: `Authorization: Bearer <token>`） |
+| 文档源 | `/tenant/v3/api-docs` |
+| Swagger UI | 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 |
+
+---
+
+## 通用响应结构
+
+几乎所有接口返回统一包装：
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": { ... },
+  "timestamp": 1690000000000,
+  "success": true
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `code` | integer | 业务状态码，通常 `0` 表示成功 |
+| `message` | string | 提示信息 |
+| `data` | object | 业务数据（见各接口返回模型） |
+| `timestamp` | long | 毫秒时间戳 |
+| `success` | boolean | 是否成功 |
+
+---
+
+## 接口列表
+
+### 租户角色管理
+
+#### `GET` `/tenant/roles`
+
+**当前租户角色列表（含预设角色）**
+
+- OperationId: `list`
+
+**响应 (Response)**
+
+**`200` OK**
+
+返回包装类型: [`ResultListRoleVO`](#model-resultlistrolevo)
+
+**统一包装字段：**
+
+> 统一响应包装字段
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `code` | integer (int32) | 否 |  |  |
+| `message` | string | 否 |  |  |
+| `timestamp` | integer (int64) | 否 |  |  |
+| `success` | boolean | 否 |  |  |
+
+**`data` 业务字段：**
+
+类型: `array\<RoleVO\>`
+- `400` Bad Request → [`ResultVoid`](#model-resultvoid)
+- `405` Method Not Allowed → [`ResultVoid`](#model-resultvoid)
+- `500` Internal Server Error → [`ResultVoid`](#model-resultvoid)
+
+#### `GET` `/tenant/roles/{id}`
+
+**获取角色详情**
+
+- OperationId: `getById`
+
+**请求参数**
+
+| 名称 | 位置 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|------|--------|------|
+| `id` | path | integer (int64) | 是 |  | 角色 id |
+
+**响应 (Response)**
+
+**`200` OK**
+
+返回包装类型: [`ResultRoleVO`](#model-resultrolevo)
+
+**统一包装字段：**
+
+> 统一响应包装字段
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `code` | integer (int32) | 否 |  |  |
+| `message` | string | 否 |  |  |
+| `timestamp` | integer (int64) | 否 |  |  |
+| `success` | boolean | 否 |  |  |
+
+**`data` 业务字段：**
+
+类型: [`RoleVO`](#model-rolevo)
+
+> 角色响应体
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `id` | integer (int64) | 否 | 主键 id |  |
+| `createdAt` | string (date-time) | 否 | 创建时间 |  |
+| `updatedAt` | string (date-time) | 否 | 更新时间 |  |
+| `createdBy` | string | 否 | 创建人(操作人标识,如 Sa-Token loginId 字符串或 system) |  |
+| `updatedBy` | string | 否 | 更新人 |  |
+| `tenantId` | string | 否 | 所属租户 id(平台管理员等跨租户场景为 null) |  |
+| `deleted` | integer (int32) | 否 | 软删除标记(0=未删除,1=已删除) |  |
+| `roleName` | string | 否 | 角色名称 | 租户管理员 |
+| `roleCode` | string | 否 | 角色编码(预置角色常量如 TENANT_ADMIN/PLATFORM_ADMIN;自建角色为自定义) | TENANT_ADMIN |
+| `description` | string | 否 | 角色描述 | 企业管理者 |
+| `roleType` | string<br>枚举: PRESET / CUSTOM | 否 | 角色类型(PRESET 预置,全租户共享 / CUSTOM 自建,本租户) | PRESET |
+| `status` | string<br>枚举: ENABLED / DISABLED / DELETED | 否 | 状态(ENABLED 启用 / DISABLED 停用 / DELETED 已删除) | ENABLED |
+- `400` Bad Request → [`ResultVoid`](#model-resultvoid)
+- `405` Method Not Allowed → [`ResultVoid`](#model-resultvoid)
+- `500` Internal Server Error → [`ResultVoid`](#model-resultvoid)
+
+#### `PUT` `/tenant/roles/{id}/toggle-status`
+
+**启用/停用角色**
+
+- OperationId: `toggleStatus`
+
+**请求参数**
+
+| 名称 | 位置 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|------|--------|------|
+| `id` | path | integer (int64) | 是 |  | 角色 id |
+
+**响应 (Response)**
+
+**`200` OK**
+
+返回包装类型: [`ResultVoid`](#model-resultvoid)
+
+**统一包装字段：**
+
+> 统一响应包装字段
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `code` | integer (int32) | 否 |  |  |
+| `message` | string | 否 |  |  |
+| `timestamp` | integer (int64) | 否 |  |  |
+| `success` | boolean | 否 |  |  |
+
+**`data` 业务字段：**
+
+类型: `object`
+- `400` Bad Request → [`ResultVoid`](#model-resultvoid)
+- `405` Method Not Allowed → [`ResultVoid`](#model-resultvoid)
+- `500` Internal Server Error → [`ResultVoid`](#model-resultvoid)
+
+### 组织管理
+
+#### `POST` `/tenant/organizations`
+
+**创建组织**
+
+- OperationId: `create`
+
+**请求体 (Request Body)**
+
+Content-Type: `application/json`
+
+类型: [`OrgCreateDTO`](#model-orgcreatedto)
+
+> 创建组织请求体
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `orgName` | string | 是 | 组织名称 | 华东分公司 |
+| `orgType` | string<br>枚举: HQ / BRANCH / DEALER / AGENT / DEPT / TEAM | 否 | 组织类型(HQ 公司本部 / BRANCH 分公司 / DEALER 经销商 / AGENT 代理商 / DEPT 部门 / TEAM 团队);默认 DEPT | BRANCH |
+| `parentId` | integer (int64) | 否 | 上级组织 id;根组织留空 |  |
+| `leaderId` | integer (int64) | 否 | 负责人员工 id;可空 |  |
+| `region` | string | 否 | 所在地区;可空 | 上海 |
+| `sortOrder` | integer (int32) | 否 | 同级内显示排序(数字越小越靠前);可空 | 1 |
+
+**响应 (Response)**
+
+**`200` OK**
+
+返回包装类型: [`ResultOrgVO`](#model-resultorgvo)
+
+**统一包装字段：**
+
+> 统一响应包装字段
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `code` | integer (int32) | 否 |  |  |
+| `message` | string | 否 |  |  |
+| `timestamp` | integer (int64) | 否 |  |  |
+| `success` | boolean | 否 |  |  |
+
+**`data` 业务字段：**
+
+类型: [`OrgVO`](#model-orgvo)
+
+> 组织响应体
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `id` | integer (int64) | 否 | 主键 id |  |
+| `createdAt` | string (date-time) | 否 | 创建时间 |  |
+| `updatedAt` | string (date-time) | 否 | 更新时间 |  |
+| `createdBy` | string | 否 | 创建人(操作人标识,如 Sa-Token loginId 字符串或 system) |  |
+| `updatedBy` | string | 否 | 更新人 |  |
+| `tenantId` | string | 否 | 所属租户 id(平台管理员等跨租户场景为 null) |  |
+| `deleted` | integer (int32) | 否 | 软删除标记(0=未删除,1=已删除) |  |
+| `orgName` | string | 否 | 组织名称 | 华东分公司 |
+| `orgType` | string<br>枚举: HQ / BRANCH / DEALER / AGENT / DEPT / TEAM | 否 | 组织类型(HQ 公司本部 / BRANCH 分公司 / DEALER 经销商 / AGENT 代理商 / DEPT 部门 / TEAM 团队) | BRANCH |
+| `parentId` | integer (int64) | 否 | 上级组织 id(根组织为 null) |  |
+| `orgPath` | string | 否 | 组织路径(从根到本节点的全路径,如 /默认租户/华东分公司) |  |
+| `leaderId` | integer (int64) | 否 | 负责人员工 id(可空) |  |
+| `region` | string | 否 | 所在地区 | 上海 |
+| `sortOrder` | integer (int32) | 否 | 同级内显示排序(数字越小越靠前) |  |
+| `status` | boolean | 否 | 启用状态(true 启用 / false 停用) |  |
+- `400` Bad Request → [`ResultVoid`](#model-resultvoid)
+- `405` Method Not Allowed → [`ResultVoid`](#model-resultvoid)
+- `500` Internal Server Error → [`ResultVoid`](#model-resultvoid)
+
+#### `GET` `/tenant/organizations/tree`
+
+**获取组织树**
+
+- OperationId: `getTree`
+
+**响应 (Response)**
+
+**`200` OK**
+
+返回包装类型: [`ResultListOrgVO`](#model-resultlistorgvo)
+
+**统一包装字段：**
+
+> 统一响应包装字段
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `code` | integer (int32) | 否 |  |  |
+| `message` | string | 否 |  |  |
+| `timestamp` | integer (int64) | 否 |  |  |
+| `success` | boolean | 否 |  |  |
+
+**`data` 业务字段：**
+
+类型: `array\<OrgVO\>`
+- `400` Bad Request → [`ResultVoid`](#model-resultvoid)
+- `405` Method Not Allowed → [`ResultVoid`](#model-resultvoid)
+- `500` Internal Server Error → [`ResultVoid`](#model-resultvoid)
+
+#### `PUT` `/tenant/organizations/{id}`
+
+**更新组织**
+
+- OperationId: `update`
+
+**请求参数**
+
+| 名称 | 位置 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|------|--------|------|
+| `id` | path | integer (int64) | 是 |  | 组织 id |
+
+**请求体 (Request Body)**
+
+Content-Type: `application/json`
+
+类型: [`OrgCreateDTO`](#model-orgcreatedto)
+
+> 创建组织请求体
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `orgName` | string | 是 | 组织名称 | 华东分公司 |
+| `orgType` | string<br>枚举: HQ / BRANCH / DEALER / AGENT / DEPT / TEAM | 否 | 组织类型(HQ 公司本部 / BRANCH 分公司 / DEALER 经销商 / AGENT 代理商 / DEPT 部门 / TEAM 团队);默认 DEPT | BRANCH |
+| `parentId` | integer (int64) | 否 | 上级组织 id;根组织留空 |  |
+| `leaderId` | integer (int64) | 否 | 负责人员工 id;可空 |  |
+| `region` | string | 否 | 所在地区;可空 | 上海 |
+| `sortOrder` | integer (int32) | 否 | 同级内显示排序(数字越小越靠前);可空 | 1 |
+
+**响应 (Response)**
+
+**`200` OK**
+
+返回包装类型: [`ResultOrgVO`](#model-resultorgvo)
+
+**统一包装字段：**
+
+> 统一响应包装字段
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `code` | integer (int32) | 否 |  |  |
+| `message` | string | 否 |  |  |
+| `timestamp` | integer (int64) | 否 |  |  |
+| `success` | boolean | 否 |  |  |
+
+**`data` 业务字段：**
+
+类型: [`OrgVO`](#model-orgvo)
+
+> 组织响应体
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `id` | integer (int64) | 否 | 主键 id |  |
+| `createdAt` | string (date-time) | 否 | 创建时间 |  |
+| `updatedAt` | string (date-time) | 否 | 更新时间 |  |
+| `createdBy` | string | 否 | 创建人(操作人标识,如 Sa-Token loginId 字符串或 system) |  |
+| `updatedBy` | string | 否 | 更新人 |  |
+| `tenantId` | string | 否 | 所属租户 id(平台管理员等跨租户场景为 null) |  |
+| `deleted` | integer (int32) | 否 | 软删除标记(0=未删除,1=已删除) |  |
+| `orgName` | string | 否 | 组织名称 | 华东分公司 |
+| `orgType` | string<br>枚举: HQ / BRANCH / DEALER / AGENT / DEPT / TEAM | 否 | 组织类型(HQ 公司本部 / BRANCH 分公司 / DEALER 经销商 / AGENT 代理商 / DEPT 部门 / TEAM 团队) | BRANCH |
+| `parentId` | integer (int64) | 否 | 上级组织 id(根组织为 null) |  |
+| `orgPath` | string | 否 | 组织路径(从根到本节点的全路径,如 /默认租户/华东分公司) |  |
+| `leaderId` | integer (int64) | 否 | 负责人员工 id(可空) |  |
+| `region` | string | 否 | 所在地区 | 上海 |
+| `sortOrder` | integer (int32) | 否 | 同级内显示排序(数字越小越靠前) |  |
+| `status` | boolean | 否 | 启用状态(true 启用 / false 停用) |  |
+- `400` Bad Request → [`ResultVoid`](#model-resultvoid)
+- `405` Method Not Allowed → [`ResultVoid`](#model-resultvoid)
+- `500` Internal Server Error → [`ResultVoid`](#model-resultvoid)
+
+#### `DELETE` `/tenant/organizations/{id}`
+
+**删除组织**
+
+- OperationId: `delete`
+
+**请求参数**
+
+| 名称 | 位置 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|------|--------|------|
+| `id` | path | integer (int64) | 是 |  | 组织 id |
+
+**响应 (Response)**
+
+**`200` OK**
+
+返回包装类型: [`ResultVoid`](#model-resultvoid)
+
+**统一包装字段：**
+
+> 统一响应包装字段
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `code` | integer (int32) | 否 |  |  |
+| `message` | string | 否 |  |  |
+| `timestamp` | integer (int64) | 否 |  |  |
+| `success` | boolean | 否 |  |  |
+
+**`data` 业务字段：**
+
+类型: `object`
+- `400` Bad Request → [`ResultVoid`](#model-resultvoid)
+- `405` Method Not Allowed → [`ResultVoid`](#model-resultvoid)
+- `500` Internal Server Error → [`ResultVoid`](#model-resultvoid)
+
+#### `PUT` `/tenant/organizations/{id}/toggle-status`
+
+**启用/停用组织**
+
+- OperationId: `toggleStatus_1`
+
+**请求参数**
+
+| 名称 | 位置 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|------|--------|------|
+| `id` | path | integer (int64) | 是 |  | 组织 id |
+
+**响应 (Response)**
+
+**`200` OK**
+
+返回包装类型: [`ResultVoid`](#model-resultvoid)
+
+**统一包装字段：**
+
+> 统一响应包装字段
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `code` | integer (int32) | 否 |  |  |
+| `message` | string | 否 |  |  |
+| `timestamp` | integer (int64) | 否 |  |  |
+| `success` | boolean | 否 |  |  |
+
+**`data` 业务字段：**
+
+类型: `object`
+- `400` Bad Request → [`ResultVoid`](#model-resultvoid)
+- `405` Method Not Allowed → [`ResultVoid`](#model-resultvoid)
+- `500` Internal Server Error → [`ResultVoid`](#model-resultvoid)
+
+### 员工管理
+
+#### `GET` `/tenant/employees`
+
+**员工分页列表**
+
+- OperationId: `list_1`
+
+**请求参数**
+
+| 名称 | 位置 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|------|--------|------|
+| `query` | query | EmployeePageQuery | 是 |  |  |
+
+**响应 (Response)**
+
+**`200` OK**
+
+返回包装类型: [`ResultPageResultEmployeeVO`](#model-resultpageresultemployeevo)
+
+**统一包装字段：**
+
+> 统一响应包装字段
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `code` | integer (int32) | 否 |  |  |
+| `message` | string | 否 |  |  |
+| `timestamp` | integer (int64) | 否 |  |  |
+| `success` | boolean | 否 |  |  |
+
+**`data` 业务字段：**
+
+类型: [`PageResultEmployeeVO`](#model-pageresultemployeevo)
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `page` | integer (int64) | 否 |  |  |
+| `size` | integer (int64) | 否 |  |  |
+| `total` | integer (int64) | 否 |  |  |
+| `totalPages` | integer (int64) | 否 |  |  |
+| `records` | array\<EmployeeVO\> | 否 |  |  |
+- `400` Bad Request → [`ResultVoid`](#model-resultvoid)
+- `405` Method Not Allowed → [`ResultVoid`](#model-resultvoid)
+- `500` Internal Server Error → [`ResultVoid`](#model-resultvoid)
+
+#### `POST` `/tenant/employees`
+
+**创建员工**
+
+- OperationId: `create_1`
+
+**请求体 (Request Body)**
+
+Content-Type: `application/json`
+
+类型: [`EmployeeCreateDTO`](#model-employeecreatedto)
+
+> 创建员工请求体
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `name` | string | 是 | 员工姓名 | 张三 |
+| `phone` | string | 是 | 登录/联系手机号(同租户内唯一建议) | 13800138000 |
+| `orgId` | integer (int64) | 是 | 所属组织 id | 1 |
+| `roleId` | integer (int64) | 是 | 角色 id(关联 crm_role.id;2 为 TENANT_ADMIN 预置角色) | 2 |
+| `position` | string | 否 | 职位 | 销售主管 |
+| `email` | string | 否 | 邮箱 | zhangsan@example.com |
+| `avatarUrl` | string | 否 | 头像 URL |  |
+| `holdLimit` | integer (int32) | 否 | 客户持有上限(可负责客户数) | 50 |
+| `region` | string | 否 | 负责区域 | 华东 |
+| `productTags` | string | 否 | 擅长产品标签(逗号分隔自由文本) | 汽车,零售 |
+
+**响应 (Response)**
+
+**`200` OK**
+
+返回包装类型: [`ResultEmployeeVO`](#model-resultemployeevo)
+
+**统一包装字段：**
+
+> 统一响应包装字段
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `code` | integer (int32) | 否 |  |  |
+| `message` | string | 否 |  |  |
+| `timestamp` | integer (int64) | 否 |  |  |
+| `success` | boolean | 否 |  |  |
+
+**`data` 业务字段：**
+
+类型: [`EmployeeVO`](#model-employeevo)
+
+> 员工响应体
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `id` | integer (int64) | 否 | 主键 id |  |
+| `createdAt` | string (date-time) | 否 | 创建时间 |  |
+| `updatedAt` | string (date-time) | 否 | 更新时间 |  |
+| `createdBy` | string | 否 | 创建人(操作人标识,如 Sa-Token loginId 字符串或 system) |  |
+| `updatedBy` | string | 否 | 更新人 |  |
+| `tenantId` | string | 否 | 所属租户 id(平台管理员等跨租户场景为 null) |  |
+| `deleted` | integer (int32) | 否 | 软删除标记(0=未删除,1=已删除) |  |
+| `name` | string | 否 | 员工姓名 | 张三 |
+| `phone` | string | 否 | 登录/联系手机号 | 13800138000 |
+| `orgId` | integer (int64) | 否 | 所属组织 id |  |
+| `roleId` | integer (int64) | 否 | 角色 id(关联 crm_role.id;为 2 即 TENANT_ADMIN 预置角色) |  |
+| `position` | string | 否 | 职位 | 销售主管 |
+| `email` | string | 否 | 邮箱 | zhangsan@example.com |
+| `avatarUrl` | string | 否 | 头像 URL |  |
+| `status` | string<br>枚举: ACTIVE / DISABLED | 否 | 状态(ACTIVE 在职 / DISABLED 停用) | ACTIVE |
+| `holdLimit` | integer (int32) | 否 | 客户持有上限(可负责的客户数) |  |
+| `region` | string | 否 | 负责区域 | 华东 |
+| `productTags` | string | 否 | 擅长产品标签(逗号分隔自由文本) | 汽车,零售 |
+| `hireDate` | string (date) | 否 | 入职日期 |  |
+- `400` Bad Request → [`ResultVoid`](#model-resultvoid)
+- `405` Method Not Allowed → [`ResultVoid`](#model-resultvoid)
+- `500` Internal Server Error → [`ResultVoid`](#model-resultvoid)
+
+#### `GET` `/tenant/employees/by-org/{orgId}`
+
+**按组织查询员工列表**
+
+- OperationId: `getByOrgId`
+
+**请求参数**
+
+| 名称 | 位置 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|------|--------|------|
+| `orgId` | path | integer (int64) | 是 |  | 组织 id |
+
+**响应 (Response)**
+
+**`200` OK**
+
+返回包装类型: [`ResultListEmployeeVO`](#model-resultlistemployeevo)
+
+**统一包装字段：**
+
+> 统一响应包装字段
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `code` | integer (int32) | 否 |  |  |
+| `message` | string | 否 |  |  |
+| `timestamp` | integer (int64) | 否 |  |  |
+| `success` | boolean | 否 |  |  |
+
+**`data` 业务字段：**
+
+类型: `array\<EmployeeVO\>`
+- `400` Bad Request → [`ResultVoid`](#model-resultvoid)
+- `405` Method Not Allowed → [`ResultVoid`](#model-resultvoid)
+- `500` Internal Server Error → [`ResultVoid`](#model-resultvoid)
+
+#### `GET` `/tenant/employees/by-role/{roleId}`
+
+**按角色查询员工列表**
+
+- OperationId: `getByRoleId`
+
+**请求参数**
+
+| 名称 | 位置 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|------|--------|------|
+| `roleId` | path | integer (int64) | 是 |  | 角色 id |
+
+**响应 (Response)**
+
+**`200` OK**
+
+返回包装类型: [`ResultListEmployeeVO`](#model-resultlistemployeevo)
+
+**统一包装字段：**
+
+> 统一响应包装字段
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `code` | integer (int32) | 否 |  |  |
+| `message` | string | 否 |  |  |
+| `timestamp` | integer (int64) | 否 |  |  |
+| `success` | boolean | 否 |  |  |
+
+**`data` 业务字段：**
+
+类型: `array\<EmployeeVO\>`
+- `400` Bad Request → [`ResultVoid`](#model-resultvoid)
+- `405` Method Not Allowed → [`ResultVoid`](#model-resultvoid)
+- `500` Internal Server Error → [`ResultVoid`](#model-resultvoid)
+
+#### `GET` `/tenant/employees/count-by-role/{roleId}`
+
+**统计角色关联的员工数**
+
+- OperationId: `countByRoleId`
+
+**请求参数**
+
+| 名称 | 位置 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|------|--------|------|
+| `roleId` | path | integer (int64) | 是 |  | 角色 id |
+
+**响应 (Response)**
+
+**`200` OK**
+
+返回包装类型: [`ResultLong`](#model-resultlong)
+
+**统一包装字段：**
+
+> 统一响应包装字段
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `code` | integer (int32) | 否 |  |  |
+| `message` | string | 否 |  |  |
+| `timestamp` | integer (int64) | 否 |  |  |
+| `success` | boolean | 否 |  |  |
+
+**`data` 业务字段：**
+
+类型: `integer (int64)`
+- `400` Bad Request → [`ResultVoid`](#model-resultvoid)
+- `405` Method Not Allowed → [`ResultVoid`](#model-resultvoid)
+- `500` Internal Server Error → [`ResultVoid`](#model-resultvoid)
+
+#### `GET` `/tenant/employees/export`
+
+**导出员工（Excel）**
+
+- OperationId: `exportEmployees`
+
+**请求参数**
+
+| 名称 | 位置 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|------|--------|------|
+| `orgId` | query | integer (int64) | 否 |  | 按组织 id 过滤;留空=全部 |
+
+**响应 (Response)**
+
+- `200` OK
+- `400` Bad Request → [`ResultVoid`](#model-resultvoid)
+- `405` Method Not Allowed → [`ResultVoid`](#model-resultvoid)
+- `500` Internal Server Error → [`ResultVoid`](#model-resultvoid)
+
+#### `POST` `/tenant/employees/import`
+
+**批量导入员工（Excel）**
+
+- OperationId: `importEmployees`
+
+**请求体 (Request Body)**
+
+> ⚠️ 规范中可能标注为 `application/json` + binary，实际调用请使用 `multipart/form-data` 上传 Excel，字段名 `file`。
+
+Content-Type: `multipart/form-data`
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `file` | string (binary) | 是 | Excel 文件(multipart 字段名 file) |  |
+
+**响应 (Response)**
+
+**`200` OK**
+
+返回包装类型: [`ResultInteger`](#model-resultinteger)
+
+**统一包装字段：**
+
+> 统一响应包装字段
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `code` | integer (int32) | 否 |  |  |
+| `message` | string | 否 |  |  |
+| `timestamp` | integer (int64) | 否 |  |  |
+| `success` | boolean | 否 |  |  |
+
+**`data` 业务字段：**
+
+类型: `integer (int32)`
+- `400` Bad Request → [`ResultVoid`](#model-resultvoid)
+- `405` Method Not Allowed → [`ResultVoid`](#model-resultvoid)
+- `500` Internal Server Error → [`ResultVoid`](#model-resultvoid)
+
+#### `GET` `/tenant/employees/{id}`
+
+**获取员工详情**
+
+- OperationId: `getById_1`
+
+**请求参数**
+
+| 名称 | 位置 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|------|--------|------|
+| `id` | path | integer (int64) | 是 |  | 员工 id |
+
+**响应 (Response)**
+
+**`200` OK**
+
+返回包装类型: [`ResultEmployeeVO`](#model-resultemployeevo)
+
+**统一包装字段：**
+
+> 统一响应包装字段
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `code` | integer (int32) | 否 |  |  |
+| `message` | string | 否 |  |  |
+| `timestamp` | integer (int64) | 否 |  |  |
+| `success` | boolean | 否 |  |  |
+
+**`data` 业务字段：**
+
+类型: [`EmployeeVO`](#model-employeevo)
+
+> 员工响应体
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `id` | integer (int64) | 否 | 主键 id |  |
+| `createdAt` | string (date-time) | 否 | 创建时间 |  |
+| `updatedAt` | string (date-time) | 否 | 更新时间 |  |
+| `createdBy` | string | 否 | 创建人(操作人标识,如 Sa-Token loginId 字符串或 system) |  |
+| `updatedBy` | string | 否 | 更新人 |  |
+| `tenantId` | string | 否 | 所属租户 id(平台管理员等跨租户场景为 null) |  |
+| `deleted` | integer (int32) | 否 | 软删除标记(0=未删除,1=已删除) |  |
+| `name` | string | 否 | 员工姓名 | 张三 |
+| `phone` | string | 否 | 登录/联系手机号 | 13800138000 |
+| `orgId` | integer (int64) | 否 | 所属组织 id |  |
+| `roleId` | integer (int64) | 否 | 角色 id(关联 crm_role.id;为 2 即 TENANT_ADMIN 预置角色) |  |
+| `position` | string | 否 | 职位 | 销售主管 |
+| `email` | string | 否 | 邮箱 | zhangsan@example.com |
+| `avatarUrl` | string | 否 | 头像 URL |  |
+| `status` | string<br>枚举: ACTIVE / DISABLED | 否 | 状态(ACTIVE 在职 / DISABLED 停用) | ACTIVE |
+| `holdLimit` | integer (int32) | 否 | 客户持有上限(可负责的客户数) |  |
+| `region` | string | 否 | 负责区域 | 华东 |
+| `productTags` | string | 否 | 擅长产品标签(逗号分隔自由文本) | 汽车,零售 |
+| `hireDate` | string (date) | 否 | 入职日期 |  |
+- `400` Bad Request → [`ResultVoid`](#model-resultvoid)
+- `405` Method Not Allowed → [`ResultVoid`](#model-resultvoid)
+- `500` Internal Server Error → [`ResultVoid`](#model-resultvoid)
+
+#### `PUT` `/tenant/employees/{id}`
+
+**更新员工**
+
+- OperationId: `update_1`
+
+**请求参数**
+
+| 名称 | 位置 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|------|--------|------|
+| `id` | path | integer (int64) | 是 |  | 员工 id |
+
+**请求体 (Request Body)**
+
+Content-Type: `application/json`
+
+类型: [`EmployeeUpdateDTO`](#model-employeeupdatedto)
+
+> 编辑员工请求体
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `name` | string | 否 | 员工姓名 | 张三 |
+| `phone` | string | 否 | 登录/联系手机号 | 13800138000 |
+| `orgId` | integer (int64) | 否 | 所属组织 id |  |
+| `roleId` | integer (int64) | 否 | 角色 id(关联 crm_role.id) |  |
+| `position` | string | 否 | 职位 | 销售主管 |
+| `email` | string | 否 | 邮箱 | zhangsan@example.com |
+| `holdLimit` | integer (int32) | 否 | 客户持有上限 | 50 |
+| `region` | string | 否 | 负责区域 | 华东 |
+| `productTags` | string | 否 | 擅长产品标签(逗号分隔自由文本) | 汽车,零售 |
+
+**响应 (Response)**
+
+**`200` OK**
+
+返回包装类型: [`ResultEmployeeVO`](#model-resultemployeevo)
+
+**统一包装字段：**
+
+> 统一响应包装字段
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `code` | integer (int32) | 否 |  |  |
+| `message` | string | 否 |  |  |
+| `timestamp` | integer (int64) | 否 |  |  |
+| `success` | boolean | 否 |  |  |
+
+**`data` 业务字段：**
+
+类型: [`EmployeeVO`](#model-employeevo)
+
+> 员工响应体
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `id` | integer (int64) | 否 | 主键 id |  |
+| `createdAt` | string (date-time) | 否 | 创建时间 |  |
+| `updatedAt` | string (date-time) | 否 | 更新时间 |  |
+| `createdBy` | string | 否 | 创建人(操作人标识,如 Sa-Token loginId 字符串或 system) |  |
+| `updatedBy` | string | 否 | 更新人 |  |
+| `tenantId` | string | 否 | 所属租户 id(平台管理员等跨租户场景为 null) |  |
+| `deleted` | integer (int32) | 否 | 软删除标记(0=未删除,1=已删除) |  |
+| `name` | string | 否 | 员工姓名 | 张三 |
+| `phone` | string | 否 | 登录/联系手机号 | 13800138000 |
+| `orgId` | integer (int64) | 否 | 所属组织 id |  |
+| `roleId` | integer (int64) | 否 | 角色 id(关联 crm_role.id;为 2 即 TENANT_ADMIN 预置角色) |  |
+| `position` | string | 否 | 职位 | 销售主管 |
+| `email` | string | 否 | 邮箱 | zhangsan@example.com |
+| `avatarUrl` | string | 否 | 头像 URL |  |
+| `status` | string<br>枚举: ACTIVE / DISABLED | 否 | 状态(ACTIVE 在职 / DISABLED 停用) | ACTIVE |
+| `holdLimit` | integer (int32) | 否 | 客户持有上限(可负责的客户数) |  |
+| `region` | string | 否 | 负责区域 | 华东 |
+| `productTags` | string | 否 | 擅长产品标签(逗号分隔自由文本) | 汽车,零售 |
+| `hireDate` | string (date) | 否 | 入职日期 |  |
+- `400` Bad Request → [`ResultVoid`](#model-resultvoid)
+- `405` Method Not Allowed → [`ResultVoid`](#model-resultvoid)
+- `500` Internal Server Error → [`ResultVoid`](#model-resultvoid)
+
+#### `DELETE` `/tenant/employees/{id}`
+
+**删除员工**
+
+- OperationId: `delete_1`
+
+**请求参数**
+
+| 名称 | 位置 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|------|--------|------|
+| `id` | path | integer (int64) | 是 |  | 员工 id |
+
+**响应 (Response)**
+
+**`200` OK**
+
+返回包装类型: [`ResultVoid`](#model-resultvoid)
+
+**统一包装字段：**
+
+> 统一响应包装字段
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `code` | integer (int32) | 否 |  |  |
+| `message` | string | 否 |  |  |
+| `timestamp` | integer (int64) | 否 |  |  |
+| `success` | boolean | 否 |  |  |
+
+**`data` 业务字段：**
+
+类型: `object`
+- `400` Bad Request → [`ResultVoid`](#model-resultvoid)
+- `405` Method Not Allowed → [`ResultVoid`](#model-resultvoid)
+- `500` Internal Server Error → [`ResultVoid`](#model-resultvoid)
+
+### 客户管理（后台 · 只读）
+
+#### `GET` `/tenant/customers`
+
+**本租户客户列表（只读）**
+
+- OperationId: `list_2`
+
+**请求参数**
+
+| 名称 | 位置 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|------|--------|------|
+| `query` | query | TenantCustomerPageQuery | 是 |  |  |
+
+**响应 (Response)**
+
+**`200` OK**
+
+返回包装类型: [`ResultPageResultCustomerVO`](#model-resultpageresultcustomervo)
+
+**统一包装字段：**
+
+> 统一响应包装字段
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `code` | integer (int32) | 否 |  |  |
+| `message` | string | 否 |  |  |
+| `timestamp` | integer (int64) | 否 |  |  |
+| `success` | boolean | 否 |  |  |
+
+**`data` 业务字段：**
+
+类型: [`PageResultCustomerVO`](#model-pageresultcustomervo)
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `page` | integer (int64) | 否 |  |  |
+| `size` | integer (int64) | 否 |  |  |
+| `total` | integer (int64) | 否 |  |  |
+| `totalPages` | integer (int64) | 否 |  |  |
+| `records` | array\<CustomerVO\> | 否 |  |  |
+- `400` Bad Request → [`ResultVoid`](#model-resultvoid)
+- `405` Method Not Allowed → [`ResultVoid`](#model-resultvoid)
+- `500` Internal Server Error → [`ResultVoid`](#model-resultvoid)
+
+#### `GET` `/tenant/customers/{id}`
+
+**客户详情（只读）**
+
+- OperationId: `detail`
+
+**请求参数**
+
+| 名称 | 位置 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|------|--------|------|
+| `id` | path | integer (int64) | 是 |  | 客户 id |
+
+**响应 (Response)**
+
+**`200` OK**
+
+返回包装类型: [`ResultCustomerVO`](#model-resultcustomervo)
+
+**统一包装字段：**
+
+> 统一响应包装字段
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `code` | integer (int32) | 否 |  |  |
+| `message` | string | 否 |  |  |
+| `timestamp` | integer (int64) | 否 |  |  |
+| `success` | boolean | 否 |  |  |
+
+**`data` 业务字段：**
+
+类型: [`CustomerVO`](#model-customervo)
+
+> 客户响应体(后台 · 只读)
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `id` | integer (int64) | 否 | 主键 id |  |
+| `createdAt` | string (date-time) | 否 | 创建时间 |  |
+| `updatedAt` | string (date-time) | 否 | 更新时间 |  |
+| `createdBy` | string | 否 | 创建人(操作人标识,如 Sa-Token loginId 字符串或 system) |  |
+| `updatedBy` | string | 否 | 更新人 |  |
+| `tenantId` | string | 否 | 所属租户 id(平台管理员等跨租户场景为 null) |  |
+| `deleted` | integer (int32) | 否 | 软删除标记(0=未删除,1=已删除) |  |
+| `name` | string | 否 | 客户名称(企业名或个人名) | 上海特斯拉 |
+| `customerType` | string<br>枚举: ENTERPRISE / PERSONAL | 否 | 客户类型(ENTERPRISE 企业 / PERSONAL 个人) | ENTERPRISE |
+| `industry` | string | 否 | 所属行业 | 汽车行业 |
+| `region` | string | 否 | 所在地区 | 上海 |
+| `contactName` | string | 否 | 主要联系人姓名 | 张经理 |
+| `contactPhone` | string | 否 | 主要联系电话(手机) | 13800138000 |
+| `contactPosition` | string | 否 | 主要联系人职位 | 采购经理 |
+| `contactTel` | string | 否 | 备用/座机电话 | 021-12345678 |
+| `email` | string | 否 | 客户邮箱 | contact@example.com |
+| `address` | string | 否 | 客户地址 | 上海市浦东新区 |
+| `source` | string<br>枚举: MINI_PROGRAM / SALES_INPUT / EXHIBITION / REFERRAL | 否 | 客户来源(小程序注册/销售录入/展会/转介绍) | SALES_INPUT |
+| `level` | string<br>枚举: VIP / A / B / C | 否 | 客户级别(VIP/A/B/C) | VIP |
+| `tags` | string | 否 | 标签(逗号分隔的自由文本) | 重点,高意向 |
+| `orgId` | integer (int64) | 否 | 所属组织 id(可空) |  |
+| `ownerId` | integer (int64) | 否 | 客户归属人(销售员)员工 id |  |
+| `stage` | string<br>枚举: NEW_LEAD / PENDING_ASSIGN / CONTACTING / NEEDS_COMM / QUOTING / NEGOTIATING / DEAL / LOST | 否 | 当前客户阶段(NEW_LEAD新线索 / PENDING_ASSIGN待分配 / CONTACTING接洽中 / NEEDS_COMM需求沟通 / QUOTING报价中 / NEGOTIATING议价中 / DEAL成交 / LOST流失) | NEW_LEAD |
+| `lastFollowAt` | string (date-time) | 否 | 最近一次跟进时间 |  |
+| `nextFollowAt` | string (date-time) | 否 | 下次计划跟进时间 |  |
+| `dealAt` | string (date-time) | 否 | 成交时间(阶段到 DEAL 时写入) |  |
+| `lostAt` | string (date-time) | 否 | 流失时间(阶段到 LOST 时写入) |  |
+| `lostReason` | string | 否 | 流失原因 |  |
+- `400` Bad Request → [`ResultVoid`](#model-resultvoid)
+- `405` Method Not Allowed → [`ResultVoid`](#model-resultvoid)
+- `500` Internal Server Error → [`ResultVoid`](#model-resultvoid)
+
+#### `GET` `/tenant/customers/{id}/follow-ups`
+
+**客户跟进历史（只读）**
+
+- OperationId: `followUps`
+
+**请求参数**
+
+| 名称 | 位置 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|------|--------|------|
+| `id` | path | integer (int64) | 是 |  | 客户 id |
+| `query` | query | FollowUpPageQuery | 是 |  |  |
+
+**响应 (Response)**
+
+**`200` OK**
+
+返回包装类型: [`ResultPageResultFollowUpVO`](#model-resultpageresultfollowupvo)
+
+**统一包装字段：**
+
+> 统一响应包装字段
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `code` | integer (int32) | 否 |  |  |
+| `message` | string | 否 |  |  |
+| `timestamp` | integer (int64) | 否 |  |  |
+| `success` | boolean | 否 |  |  |
+
+**`data` 业务字段：**
+
+类型: [`PageResultFollowUpVO`](#model-pageresultfollowupvo)
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `page` | integer (int64) | 否 |  |  |
+| `size` | integer (int64) | 否 |  |  |
+| `total` | integer (int64) | 否 |  |  |
+| `totalPages` | integer (int64) | 否 |  |  |
+| `records` | array\<FollowUpVO\> | 否 |  |  |
+- `400` Bad Request → [`ResultVoid`](#model-resultvoid)
+- `405` Method Not Allowed → [`ResultVoid`](#model-resultvoid)
+- `500` Internal Server Error → [`ResultVoid`](#model-resultvoid)
+
+---
+
+## 数据模型完整参考
+
+> 接口章节已内联展示 Request / Response 字段说明，此处便于全局查阅。
+
+### EmployeeCreateDTO
+
+<a id="model-employeecreatedto"></a>
+
+> 创建员工请求体
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `name` | string | 是 | 员工姓名 | 张三 |
+| `phone` | string | 是 | 登录/联系手机号(同租户内唯一建议) | 13800138000 |
+| `orgId` | integer (int64) | 是 | 所属组织 id | 1 |
+| `roleId` | integer (int64) | 是 | 角色 id(关联 crm_role.id;2 为 TENANT_ADMIN 预置角色) | 2 |
+| `position` | string | 否 | 职位 | 销售主管 |
+| `email` | string | 否 | 邮箱 | zhangsan@example.com |
+| `avatarUrl` | string | 否 | 头像 URL |  |
+| `holdLimit` | integer (int32) | 否 | 客户持有上限(可负责客户数) | 50 |
+| `region` | string | 否 | 负责区域 | 华东 |
+| `productTags` | string | 否 | 擅长产品标签(逗号分隔自由文本) | 汽车,零售 |
+
+### EmployeePageQuery
+
+<a id="model-employeepagequery"></a>
+
+> 员工分页查询条件
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `page` | integer (int32) | 否 |  |  |
+| `size` | integer (int32) | 否 |  |  |
+| `sortBy` | string | 否 |  |  |
+| `sortDir` | string | 否 |  |  |
+| `orgId` | integer (int64) | 否 | 按所属组织 id 过滤;留空=不按组织过滤 |  |
+| `roleId` | integer (int64) | 否 | 按角色 id 过滤;留空=不按角色过滤 |  |
+| `status` | string<br>枚举: ACTIVE / DISABLED | 否 | 按员工状态过滤(ACTIVE 在职 / DISABLED 停用);留空=全部 |  |
+| `keyword` | string | 否 | 关键词(模糊匹配员工姓名/手机号等);可空 | 张三 |
+| `offset` | integer (int32) | 否 |  |  |
+
+### EmployeeUpdateDTO
+
+<a id="model-employeeupdatedto"></a>
+
+> 编辑员工请求体
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `name` | string | 否 | 员工姓名 | 张三 |
+| `phone` | string | 否 | 登录/联系手机号 | 13800138000 |
+| `orgId` | integer (int64) | 否 | 所属组织 id |  |
+| `roleId` | integer (int64) | 否 | 角色 id(关联 crm_role.id) |  |
+| `position` | string | 否 | 职位 | 销售主管 |
+| `email` | string | 否 | 邮箱 | zhangsan@example.com |
+| `holdLimit` | integer (int32) | 否 | 客户持有上限 | 50 |
+| `region` | string | 否 | 负责区域 | 华东 |
+| `productTags` | string | 否 | 擅长产品标签(逗号分隔自由文本) | 汽车,零售 |
+
+### FollowUpPageQuery
+
+<a id="model-followuppagequery"></a>
+
+> 客户跟进历史分页查询条件(后台只读)
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `page` | integer (int32) | 否 |  |  |
+| `size` | integer (int32) | 否 |  |  |
+| `sortBy` | string | 否 |  |  |
+| `sortDir` | string | 否 |  |  |
+| `offset` | integer (int32) | 否 |  |  |
+
+### OrgCreateDTO
+
+<a id="model-orgcreatedto"></a>
+
+> 创建组织请求体
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `orgName` | string | 是 | 组织名称 | 华东分公司 |
+| `orgType` | string<br>枚举: HQ / BRANCH / DEALER / AGENT / DEPT / TEAM | 否 | 组织类型(HQ 公司本部 / BRANCH 分公司 / DEALER 经销商 / AGENT 代理商 / DEPT 部门 / TEAM 团队);默认 DEPT | BRANCH |
+| `parentId` | integer (int64) | 否 | 上级组织 id;根组织留空 |  |
+| `leaderId` | integer (int64) | 否 | 负责人员工 id;可空 |  |
+| `region` | string | 否 | 所在地区;可空 | 上海 |
+| `sortOrder` | integer (int32) | 否 | 同级内显示排序(数字越小越靠前);可空 | 1 |
+
+### TenantCustomerPageQuery
+
+<a id="model-tenantcustomerpagequery"></a>
+
+> 本租户客户分页查询条件(后台只读)
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `page` | integer (int32) | 否 |  |  |
+| `size` | integer (int32) | 否 |  |  |
+| `sortBy` | string | 否 |  |  |
+| `sortDir` | string | 否 |  |  |
+| `ownerId` | integer (int64) | 否 | 按客户归属人(销售员)员工 id 过滤;留空=全部 |  |
+| `offset` | integer (int32) | 否 |  |  |
+
+### CustomerVO
+
+<a id="model-customervo"></a>
+
+> 客户响应体(后台 · 只读)
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `id` | integer (int64) | 否 | 主键 id |  |
+| `createdAt` | string (date-time) | 否 | 创建时间 |  |
+| `updatedAt` | string (date-time) | 否 | 更新时间 |  |
+| `createdBy` | string | 否 | 创建人(操作人标识,如 Sa-Token loginId 字符串或 system) |  |
+| `updatedBy` | string | 否 | 更新人 |  |
+| `tenantId` | string | 否 | 所属租户 id(平台管理员等跨租户场景为 null) |  |
+| `deleted` | integer (int32) | 否 | 软删除标记(0=未删除,1=已删除) |  |
+| `name` | string | 否 | 客户名称(企业名或个人名) | 上海特斯拉 |
+| `customerType` | string<br>枚举: ENTERPRISE / PERSONAL | 否 | 客户类型(ENTERPRISE 企业 / PERSONAL 个人) | ENTERPRISE |
+| `industry` | string | 否 | 所属行业 | 汽车行业 |
+| `region` | string | 否 | 所在地区 | 上海 |
+| `contactName` | string | 否 | 主要联系人姓名 | 张经理 |
+| `contactPhone` | string | 否 | 主要联系电话(手机) | 13800138000 |
+| `contactPosition` | string | 否 | 主要联系人职位 | 采购经理 |
+| `contactTel` | string | 否 | 备用/座机电话 | 021-12345678 |
+| `email` | string | 否 | 客户邮箱 | contact@example.com |
+| `address` | string | 否 | 客户地址 | 上海市浦东新区 |
+| `source` | string<br>枚举: MINI_PROGRAM / SALES_INPUT / EXHIBITION / REFERRAL | 否 | 客户来源(小程序注册/销售录入/展会/转介绍) | SALES_INPUT |
+| `level` | string<br>枚举: VIP / A / B / C | 否 | 客户级别(VIP/A/B/C) | VIP |
+| `tags` | string | 否 | 标签(逗号分隔的自由文本) | 重点,高意向 |
+| `orgId` | integer (int64) | 否 | 所属组织 id(可空) |  |
+| `ownerId` | integer (int64) | 否 | 客户归属人(销售员)员工 id |  |
+| `stage` | string<br>枚举: NEW_LEAD / PENDING_ASSIGN / CONTACTING / NEEDS_COMM / QUOTING / NEGOTIATING / DEAL / LOST | 否 | 当前客户阶段(NEW_LEAD新线索 / PENDING_ASSIGN待分配 / CONTACTING接洽中 / NEEDS_COMM需求沟通 / QUOTING报价中 / NEGOTIATING议价中 / DEAL成交 / LOST流失) | NEW_LEAD |
+| `lastFollowAt` | string (date-time) | 否 | 最近一次跟进时间 |  |
+| `nextFollowAt` | string (date-time) | 否 | 下次计划跟进时间 |  |
+| `dealAt` | string (date-time) | 否 | 成交时间(阶段到 DEAL 时写入) |  |
+| `lostAt` | string (date-time) | 否 | 流失时间(阶段到 LOST 时写入) |  |
+| `lostReason` | string | 否 | 流失原因 |  |
+
+### EmployeeVO
+
+<a id="model-employeevo"></a>
+
+> 员工响应体
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `id` | integer (int64) | 否 | 主键 id |  |
+| `createdAt` | string (date-time) | 否 | 创建时间 |  |
+| `updatedAt` | string (date-time) | 否 | 更新时间 |  |
+| `createdBy` | string | 否 | 创建人(操作人标识,如 Sa-Token loginId 字符串或 system) |  |
+| `updatedBy` | string | 否 | 更新人 |  |
+| `tenantId` | string | 否 | 所属租户 id(平台管理员等跨租户场景为 null) |  |
+| `deleted` | integer (int32) | 否 | 软删除标记(0=未删除,1=已删除) |  |
+| `name` | string | 否 | 员工姓名 | 张三 |
+| `phone` | string | 否 | 登录/联系手机号 | 13800138000 |
+| `orgId` | integer (int64) | 否 | 所属组织 id |  |
+| `roleId` | integer (int64) | 否 | 角色 id(关联 crm_role.id;为 2 即 TENANT_ADMIN 预置角色) |  |
+| `position` | string | 否 | 职位 | 销售主管 |
+| `email` | string | 否 | 邮箱 | zhangsan@example.com |
+| `avatarUrl` | string | 否 | 头像 URL |  |
+| `status` | string<br>枚举: ACTIVE / DISABLED | 否 | 状态(ACTIVE 在职 / DISABLED 停用) | ACTIVE |
+| `holdLimit` | integer (int32) | 否 | 客户持有上限(可负责的客户数) |  |
+| `region` | string | 否 | 负责区域 | 华东 |
+| `productTags` | string | 否 | 擅长产品标签(逗号分隔自由文本) | 汽车,零售 |
+| `hireDate` | string (date) | 否 | 入职日期 |  |
+
+### FollowUpVO
+
+<a id="model-followupvo"></a>
+
+> 跟进记录响应体(后台 · 只读)
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `id` | integer (int64) | 否 | 主键 id |  |
+| `createdAt` | string (date-time) | 否 | 创建时间 |  |
+| `updatedAt` | string (date-time) | 否 | 更新时间 |  |
+| `createdBy` | string | 否 | 创建人(操作人标识,如 Sa-Token loginId 字符串或 system) |  |
+| `updatedBy` | string | 否 | 更新人 |  |
+| `tenantId` | string | 否 | 所属租户 id(平台管理员等跨租户场景为 null) |  |
+| `deleted` | integer (int32) | 否 | 软删除标记(0=未删除,1=已删除) |  |
+| `customerId` | integer (int64) | 否 | 关联客户 id |  |
+| `followerId` | integer (int64) | 否 | 跟进人(销售员)员工 id |  |
+| `followAt` | string (date-time) | 否 | 本次跟进实际发生时间 |  |
+| `followMethod` | string<br>枚举: PHONE / WECHAT / VISIT / EMAIL / MEETING | 否 | 跟进方式(PHONE 电话 / WECHAT 微信 / VISIT 上门拜访 / EMAIL 邮件 / MEETING 会议) | PHONE |
+| `content` | string | 否 | 跟进内容/沟通纪要 |  |
+| `nextFollowAt` | string (date-time) | 否 | 下次计划跟进时间(可空) |  |
+| `nextFollowPlan` | string | 否 | 下次跟进计划/备注(可空) |  |
+| `followStatus` | string<br>枚举: DONE / PENDING / OVERDUE | 否 | 跟进状态(DONE 已完成 / PENDING 待跟进 / OVERDUE 已超时) | DONE |
+
+### OrgVO
+
+<a id="model-orgvo"></a>
+
+> 组织响应体
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `id` | integer (int64) | 否 | 主键 id |  |
+| `createdAt` | string (date-time) | 否 | 创建时间 |  |
+| `updatedAt` | string (date-time) | 否 | 更新时间 |  |
+| `createdBy` | string | 否 | 创建人(操作人标识,如 Sa-Token loginId 字符串或 system) |  |
+| `updatedBy` | string | 否 | 更新人 |  |
+| `tenantId` | string | 否 | 所属租户 id(平台管理员等跨租户场景为 null) |  |
+| `deleted` | integer (int32) | 否 | 软删除标记(0=未删除,1=已删除) |  |
+| `orgName` | string | 否 | 组织名称 | 华东分公司 |
+| `orgType` | string<br>枚举: HQ / BRANCH / DEALER / AGENT / DEPT / TEAM | 否 | 组织类型(HQ 公司本部 / BRANCH 分公司 / DEALER 经销商 / AGENT 代理商 / DEPT 部门 / TEAM 团队) | BRANCH |
+| `parentId` | integer (int64) | 否 | 上级组织 id(根组织为 null) |  |
+| `orgPath` | string | 否 | 组织路径(从根到本节点的全路径,如 /默认租户/华东分公司) |  |
+| `leaderId` | integer (int64) | 否 | 负责人员工 id(可空) |  |
+| `region` | string | 否 | 所在地区 | 上海 |
+| `sortOrder` | integer (int32) | 否 | 同级内显示排序(数字越小越靠前) |  |
+| `status` | boolean | 否 | 启用状态(true 启用 / false 停用) |  |
+
+### ResultListRoleVO
+
+<a id="model-resultlistrolevo"></a>
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `code` | integer (int32) | 否 |  |  |
+| `message` | string | 否 |  |  |
+| `data` | array\<RoleVO\> | 否 |  |  |
+| `timestamp` | integer (int64) | 否 |  |  |
+| `success` | boolean | 否 |  |  |
+
+### ResultRoleVO
+
+<a id="model-resultrolevo"></a>
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `code` | integer (int32) | 否 |  |  |
+| `message` | string | 否 |  |  |
+| `data` | RoleVO | 否 |  |  |
+| `timestamp` | integer (int64) | 否 |  |  |
+| `success` | boolean | 否 |  |  |
+
+### RoleVO
+
+<a id="model-rolevo"></a>
+
+> 角色响应体
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `id` | integer (int64) | 否 | 主键 id |  |
+| `createdAt` | string (date-time) | 否 | 创建时间 |  |
+| `updatedAt` | string (date-time) | 否 | 更新时间 |  |
+| `createdBy` | string | 否 | 创建人(操作人标识,如 Sa-Token loginId 字符串或 system) |  |
+| `updatedBy` | string | 否 | 更新人 |  |
+| `tenantId` | string | 否 | 所属租户 id(平台管理员等跨租户场景为 null) |  |
+| `deleted` | integer (int32) | 否 | 软删除标记(0=未删除,1=已删除) |  |
+| `roleName` | string | 否 | 角色名称 | 租户管理员 |
+| `roleCode` | string | 否 | 角色编码(预置角色常量如 TENANT_ADMIN/PLATFORM_ADMIN;自建角色为自定义) | TENANT_ADMIN |
+| `description` | string | 否 | 角色描述 | 企业管理者 |
+| `roleType` | string<br>枚举: PRESET / CUSTOM | 否 | 角色类型(PRESET 预置,全租户共享 / CUSTOM 自建,本租户) | PRESET |
+| `status` | string<br>枚举: ENABLED / DISABLED / DELETED | 否 | 状态(ENABLED 启用 / DISABLED 停用 / DELETED 已删除) | ENABLED |
+
+### PageResultCustomerVO
+
+<a id="model-pageresultcustomervo"></a>
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `page` | integer (int64) | 否 |  |  |
+| `size` | integer (int64) | 否 |  |  |
+| `total` | integer (int64) | 否 |  |  |
+| `totalPages` | integer (int64) | 否 |  |  |
+| `records` | array\<CustomerVO\> | 否 |  |  |
+
+### PageResultEmployeeVO
+
+<a id="model-pageresultemployeevo"></a>
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `page` | integer (int64) | 否 |  |  |
+| `size` | integer (int64) | 否 |  |  |
+| `total` | integer (int64) | 否 |  |  |
+| `totalPages` | integer (int64) | 否 |  |  |
+| `records` | array\<EmployeeVO\> | 否 |  |  |
+
+### PageResultFollowUpVO
+
+<a id="model-pageresultfollowupvo"></a>
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `page` | integer (int64) | 否 |  |  |
+| `size` | integer (int64) | 否 |  |  |
+| `total` | integer (int64) | 否 |  |  |
+| `totalPages` | integer (int64) | 否 |  |  |
+| `records` | array\<FollowUpVO\> | 否 |  |  |
+
+### ResultCustomerVO
+
+<a id="model-resultcustomervo"></a>
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `code` | integer (int32) | 否 |  |  |
+| `message` | string | 否 |  |  |
+| `data` | CustomerVO | 否 |  |  |
+| `timestamp` | integer (int64) | 否 |  |  |
+| `success` | boolean | 否 |  |  |
+
+### ResultEmployeeVO
+
+<a id="model-resultemployeevo"></a>
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `code` | integer (int32) | 否 |  |  |
+| `message` | string | 否 |  |  |
+| `data` | EmployeeVO | 否 |  |  |
+| `timestamp` | integer (int64) | 否 |  |  |
+| `success` | boolean | 否 |  |  |
+
+### ResultInteger
+
+<a id="model-resultinteger"></a>
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `code` | integer (int32) | 否 |  |  |
+| `message` | string | 否 |  |  |
+| `data` | integer (int32) | 否 |  |  |
+| `timestamp` | integer (int64) | 否 |  |  |
+| `success` | boolean | 否 |  |  |
+
+### ResultListEmployeeVO
+
+<a id="model-resultlistemployeevo"></a>
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `code` | integer (int32) | 否 |  |  |
+| `message` | string | 否 |  |  |
+| `data` | array\<EmployeeVO\> | 否 |  |  |
+| `timestamp` | integer (int64) | 否 |  |  |
+| `success` | boolean | 否 |  |  |
+
+### ResultListOrgVO
+
+<a id="model-resultlistorgvo"></a>
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `code` | integer (int32) | 否 |  |  |
+| `message` | string | 否 |  |  |
+| `data` | array\<OrgVO\> | 否 |  |  |
+| `timestamp` | integer (int64) | 否 |  |  |
+| `success` | boolean | 否 |  |  |
+
+### ResultLong
+
+<a id="model-resultlong"></a>
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `code` | integer (int32) | 否 |  |  |
+| `message` | string | 否 |  |  |
+| `data` | integer (int64) | 否 |  |  |
+| `timestamp` | integer (int64) | 否 |  |  |
+| `success` | boolean | 否 |  |  |
+
+### ResultOrgVO
+
+<a id="model-resultorgvo"></a>
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `code` | integer (int32) | 否 |  |  |
+| `message` | string | 否 |  |  |
+| `data` | OrgVO | 否 |  |  |
+| `timestamp` | integer (int64) | 否 |  |  |
+| `success` | boolean | 否 |  |  |
+
+### ResultPageResultCustomerVO
+
+<a id="model-resultpageresultcustomervo"></a>
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `code` | integer (int32) | 否 |  |  |
+| `message` | string | 否 |  |  |
+| `data` | PageResultCustomerVO | 否 |  |  |
+| `timestamp` | integer (int64) | 否 |  |  |
+| `success` | boolean | 否 |  |  |
+
+### ResultPageResultEmployeeVO
+
+<a id="model-resultpageresultemployeevo"></a>
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `code` | integer (int32) | 否 |  |  |
+| `message` | string | 否 |  |  |
+| `data` | PageResultEmployeeVO | 否 |  |  |
+| `timestamp` | integer (int64) | 否 |  |  |
+| `success` | boolean | 否 |  |  |
+
+### ResultPageResultFollowUpVO
+
+<a id="model-resultpageresultfollowupvo"></a>
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `code` | integer (int32) | 否 |  |  |
+| `message` | string | 否 |  |  |
+| `data` | PageResultFollowUpVO | 否 |  |  |
+| `timestamp` | integer (int64) | 否 |  |  |
+| `success` | boolean | 否 |  |  |
+
+### ResultVoid
+
+<a id="model-resultvoid"></a>
+
+| 字段 | 类型 | 必填 | 说明 | 示例 |
+|------|------|------|------|------|
+| `code` | integer (int32) | 否 |  |  |
+| `message` | string | 否 |  |  |
+| `data` | object | 否 |  |  |
+| `timestamp` | integer (int64) | 否 |  |  |
+| `success` | boolean | 否 |  |  |
+
+---
+
+## 枚举值汇总
+
+| 模型.字段 | 枚举值 | 说明 |
+|-----------|--------|------|
+| `CustomerVO.customerType` | `ENTERPRISE` · `PERSONAL` | 客户类型(ENTERPRISE 企业 / PERSONAL 个人) |
+| `CustomerVO.level` | `VIP` · `A` · `B` · `C` | 客户级别(VIP/A/B/C) |
+| `CustomerVO.source` | `MINI_PROGRAM` · `SALES_INPUT` · `EXHIBITION` · `REFERRAL` | 客户来源(小程序注册/销售录入/展会/转介绍) |
+| `CustomerVO.stage` | `NEW_LEAD` · `PENDING_ASSIGN` · `CONTACTING` · `NEEDS_COMM` · `QUOTING` · `NEGOTIATING` · `DEAL` · `LOST` | 当前客户阶段(NEW_LEAD新线索 / PENDING_ASSIGN待分配 / CONTACTING接洽中 / NEEDS_COMM需求沟通 / QUOTING报价中 / NEGOTIATING议价中 / DEAL成交 / LOST流失) |
+| `EmployeePageQuery.status` | `ACTIVE` · `DISABLED` | 按员工状态过滤(ACTIVE 在职 / DISABLED 停用);留空=全部 |
+| `EmployeeVO.status` | `ACTIVE` · `DISABLED` | 状态(ACTIVE 在职 / DISABLED 停用) |
+| `FollowUpVO.followMethod` | `PHONE` · `WECHAT` · `VISIT` · `EMAIL` · `MEETING` | 跟进方式(PHONE 电话 / WECHAT 微信 / VISIT 上门拜访 / EMAIL 邮件 / MEETING 会议) |
+| `FollowUpVO.followStatus` | `DONE` · `PENDING` · `OVERDUE` | 跟进状态(DONE 已完成 / PENDING 待跟进 / OVERDUE 已超时) |
+| `OrgCreateDTO.orgType` | `HQ` · `BRANCH` · `DEALER` · `AGENT` · `DEPT` · `TEAM` | 组织类型(HQ 公司本部 / BRANCH 分公司 / DEALER 经销商 / AGENT 代理商 / DEPT 部门 / TEAM 团队);默认 DEPT |
+| `OrgVO.orgType` | `HQ` · `BRANCH` · `DEALER` · `AGENT` · `DEPT` · `TEAM` | 组织类型(HQ 公司本部 / BRANCH 分公司 / DEALER 经销商 / AGENT 代理商 / DEPT 部门 / TEAM 团队) |
+| `RoleVO.roleType` | `PRESET` · `CUSTOM` | 角色类型(PRESET 预置,全租户共享 / CUSTOM 自建,本租户) |
+| `RoleVO.status` | `ENABLED` · `DISABLED` · `DELETED` | 状态(ENABLED 启用 / DISABLED 停用 / DELETED 已删除) |
+
+---
+
+## 注意事项
+
+1. **认证**：所有接口需在 Header 中携带 `Authorization: Bearer <JWT>`。
+2. **多租户**：路径统一以 `/tenant/` 开头，租户上下文一般从 JWT 解析。
+3. **统一响应**：请以 `success` / `code` 判断业务结果，不要只依赖 HTTP 状态码。
+4. **分页**：分页参数默认 `page=1`，`size=20`。
+5. **员工导入**：实际请使用 `multipart/form-data` 上传 Excel，字段名 `file`。
+6. **员工导出**：返回 Excel 文件流。
+7. **字段说明**：Request / Response 字段的「说明」「示例」均来自 OpenAPI `description` 与 `example`。
+
+---
+
+*文档由 OpenAPI 规范自动生成（租户版）  
+源地址: `http://121.41.54.56:9090/tenant/v3/api-docs`*

--
Gitblit v1.9.3