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：

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 员工分页列表

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 创建员工

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 获取员工详情

GET /tenant/employees/{id}

路径参数:

参数	类型	说明
id	long	员工 ID

响应: ResultEmployeeVO

1.4 更新员工

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 删除员工

DELETE /tenant/employees/{id}

路径参数:

参数	类型	说明
id	long	员工 ID

响应: ResultVoid

1.6 按组织查员工分页

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

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

路径参数:

参数	类型	说明
orgId	long	组织 ID

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

响应: ResultPageResultEmployeeVO

1.7 按角色查员工分页

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

路径参数:

参数	类型	说明
roleId	long	角色 ID

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

响应: ResultPageResultEmployeeVO

1.8 统计角色关联的员工数

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

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

响应: ResultLong

1.9 导出员工（Excel）

GET /tenant/employees/export

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

Query 参数:

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

响应: Excel 文件流

1.10 批量导入员工（Excel）

POST /tenant/employees/import

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

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

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

2. 组织管理

2.1 创建组织

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 获取组织树

GET /tenant/organizations/tree

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

Query 参数:

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

响应: ResultListOrgVO

2.3 更新组织

PUT /tenant/organizations/{id}

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

请求体: OrgCreateDTO（同创建）

响应: ResultOrgVO

2.4 删除组织

DELETE /tenant/organizations/{id}

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

响应: ResultVoid

2.5 启用/停用组织

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

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

响应: ResultVoid

3. 租户角色管理

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

GET /tenant/roles

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

响应: ResultListRoleVO

3.2 获取角色详情

GET /tenant/roles/{id}

路径参数:

参数	类型	说明
id	long	角色 ID

响应: ResultRoleVO

3.3 启用/停用角色

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

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

响应: ResultVoid

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

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

GET /tenant/customers

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

Query 参数 (TenantCustomerPageQuery):

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

响应: ResultPageResultCustomerVO

4.2 客户详情（只读）

GET /tenant/customers/{id}

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

响应: ResultCustomerVO

4.3 客户跟进历史（只读）

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

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

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

响应: ResultPageResultFollowUpVO

5. 审计日志（租户端）

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

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 规范自动生成，内容以实际接口返回为准。

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

通用说明

认证

统一响应结构

分页结构 PageResult

通用错误码

接口列表

1. 员工管理

1.1 员工分页列表

1.2 创建员工

1.3 获取员工详情

1.4 更新员工

1.5 删除员工

1.6 按组织查员工分页

1.7 按角色查员工分页

1.8 统计角色关联的员工数

1.9 导出员工（Excel）

1.10 批量导入员工（Excel）

2. 组织管理

2.1 创建组织

2.2 获取组织树

2.3 更新组织

2.4 删除组织

2.5 启用/停用组织

3. 租户角色管理

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

3.2 获取角色详情

3.3 启用/停用角色

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

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

4.2 客户详情（只读）

4.3 客户跟进历史（只读）

5. 审计日志（租户端）

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

数据模型（Schemas）

EmployeeVO（员工响应体）

OrgVO（组织响应体）

RoleVO（角色响应体）

CustomerVO（客户响应体）

FollowUpVO（跟进记录响应体）

AuditLogVO（审计日志响应体）

权限说明

分页结构 `PageResult`