{"openapi":"3.0.1","info":{"title":"SaaS 系统管理服务 API","description":"多租户 SaaS 平台 — 用户、角色、权限、租户管理接口","contact":{"name":"SaaS Platform Team"},"license":{"name":"Apache 2.0"},"version":"1.0.0"},"servers":[{"url":"/","description":"Generated server url"}],"security":[{"Bearer JWT":[]}],"paths":{"/tenant/roles/{id}/toggle-status":{"put":{"tags":["租户角色管理"],"summary":"启用/停用角色","description":"在启用/停用之间切换。受保护:预置角色(roleType=PRESET,SYSTEM 全租户共享)与不属于本租户的自建角色会被拒绝(403),只允许租户管理员改本租户的自建角色。","operationId":"toggleStatus","parameters":[{"name":"id","in":"path","description":"角色 id","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"405":{"description":"Method Not Allowed","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}}}}},"/tenant/organizations/{id}":{"put":{"tags":["组织管理"],"summary":"更新组织","description":"更新组织基本信息(orgName/orgType/parentId/leaderId/region/sortOrder)。parentId 变更后 orgPath 由 service 重算。","operationId":"update","parameters":[{"name":"id","in":"path","description":"组织 id","required":true,"schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgCreateDTO"}}},"required":true},"responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"405":{"description":"Method Not Allowed","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultOrgVO"}}}}}},"delete":{"tags":["组织管理"],"summary":"删除组织","description":"按 id 删除组织(具体软删/物理删由 service 决定)。子组织存在时可能被拒,行为以 service 实现为准。","operationId":"delete","parameters":[{"name":"id","in":"path","description":"组织 id","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"405":{"description":"Method Not Allowed","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}}}}},"/tenant/organizations/{id}/toggle-status":{"put":{"tags":["组织管理"],"summary":"启用/停用组织","description":"在启用/停用组织之间切换。","operationId":"toggleStatus_1","parameters":[{"name":"id","in":"path","description":"组织 id","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"405":{"description":"Method Not Allowed","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}}}}},"/tenant/employees/{id}":{"get":{"tags":["员工管理"],"summary":"获取员工详情","description":"按 id 取单个员工;返回 EmployeeVO。","operationId":"getById_1","parameters":[{"name":"id","in":"path","description":"员工 id","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"405":{"description":"Method Not Allowed","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultEmployeeVO"}}}}}},"put":{"tags":["员工管理"],"summary":"更新员工","description":"更新员工基本信息(name/phone/orgId/roleId/position/email/holdLimit/region);password/avatarUrl/hireDate 不在此接口改。","operationId":"update_1","parameters":[{"name":"id","in":"path","description":"员工 id","required":true,"schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmployeeUpdateDTO"}}},"required":true},"responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"405":{"description":"Method Not Allowed","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultEmployeeVO"}}}}}},"delete":{"tags":["员工管理"],"summary":"删除员工","description":"删除员工(软删/物理删由 service 决定)。","operationId":"delete_1","parameters":[{"name":"id","in":"path","description":"员工 id","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"405":{"description":"Method Not Allowed","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}}}}},"/tenant/organizations":{"post":{"tags":["组织管理"],"summary":"创建组织","description":"创建一个组织节点;orgPath 由 service 按 parentId 与父组织 orgPath 拼接生成(请求体传的 orgPath 会被忽略)。status 初始 true。tenant_id 据 TenantContext 填充。","operationId":"create","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgCreateDTO"}}},"required":true},"responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"405":{"description":"Method Not Allowed","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultOrgVO"}}}}}}},"/tenant/employees":{"get":{"tags":["员工管理"],"summary":"员工分页列表","description":"按 EmployeePageQuery 过滤(orgId/roleId/status/keyword)分页返回本租户员工;PageResult 统一分页结构。tenantFilter 限定当前租户;需 TENANT_ADMIN 或平台管理员。ownerId 因后台口径不过滤(本接口租户管理员视角)。","operationId":"list_1","parameters":[{"name":"query","in":"query","required":true,"schema":{"$ref":"#/components/schemas/EmployeePageQuery"}}],"responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"405":{"description":"Method Not Allowed","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultPageResultEmployeeVO"}}}}}},"post":{"tags":["员工管理"],"summary":"创建员工","description":"在当前租户下创建员工;tenant_id 由服务端据 TenantContext 填充;roleId 关联本租户自建角色或 SYSTEM 预置角色(如 TENANT_ADMIN=2)。","operationId":"create_1","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmployeeCreateDTO"}}},"required":true},"responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"405":{"description":"Method Not Allowed","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultEmployeeVO"}}}}}}},"/tenant/employees/import":{"post":{"tags":["员工管理"],"summary":"批量导入员工（Excel）","description":"上传 Excel 文件批量建员工;请求类型 multipart/form-data,字段名 file。返回成功导入行数。Excel 表头/字段映射以 service.importEmployees 实现为准。","operationId":"importEmployees","requestBody":{"content":{"application/json":{"schema":{"required":["file"],"type":"object","properties":{"file":{"type":"string","description":"Excel 文件(multipart 字段名 file)","format":"binary"}}}}}},"responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"405":{"description":"Method Not Allowed","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultInteger"}}}}}}},"/tenant/roles":{"get":{"tags":["租户角色管理"],"summary":"当前租户角色列表（含预设角色）","description":"返回当前租户可用角色 = 本租户自建角色 + SYSTEM 全租户共享的预置角色(如 TENANT_ADMIN/PLATFORM_ADMIN)。预置角色置前,可用于建员工时分配。需 TENANT_ADMIN 登录。响应为 RoleVO 列表。","operationId":"list","responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"405":{"description":"Method Not Allowed","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultListRoleVO"}}}}}}},"/tenant/roles/{id}":{"get":{"tags":["租户角色管理"],"summary":"获取角色详情","description":"按 id 取单个角色。响应为 RoleVO。本接口未做跨租户校验,但配合角色列表使用,主要用于查看列表中已暴露的角色。","operationId":"getById","parameters":[{"name":"id","in":"path","description":"角色 id","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"405":{"description":"Method Not Allowed","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultRoleVO"}}}}}}},"/tenant/organizations/tree":{"get":{"tags":["组织管理"],"summary":"获取组织树","description":"返回当前租户组织嵌套树(每个节点 children 含直接下级,按 sortOrder 排序)。tenantFilter 限定当前租户。参数 orgId 可选:传入则返回以该节点为根的子树(单元素列表),不传则返回所有根组织(parentId 为 null)的子树列表。节点不存在返业务异常。需 TENANT_ADMIN 或平台管理员。","operationId":"getTree","parameters":[{"name":"orgId","in":"query","description":"子树根节点 id;不传=返回所有根组织及其全部子节点","required":false,"schema":{"type":"integer","format":"int64"}}],"responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"405":{"description":"Method Not Allowed","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultListOrgVO"}}}}}}},"/tenant/employees/export":{"get":{"tags":["员工管理"],"summary":"导出员工（Excel）","description":"导出员工为 Excel 文件流(Content-Type 由 service 设定到 HttpServletResponse)。orgId 不填=导出本租户全部员工;填则仅导出指定组织下员工(以 service 实现为准)。响应通过原始 ServletOutputStream 输出,非标准 Result 封装。","operationId":"exportEmployees","parameters":[{"name":"orgId","in":"query","description":"按组织 id 过滤;留空=全部","required":false,"schema":{"type":"integer","format":"int64"}}],"responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"405":{"description":"Method Not Allowed","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"200":{"description":"OK"}}}},"/tenant/employees/count-by-role/{roleId}":{"get":{"tags":["员工管理"],"summary":"统计角色关联的员工数","description":"返回该角色下本租户员工数;可用于删除角色前校验是否仍有人引用。","operationId":"countByRoleId","parameters":[{"name":"roleId","in":"path","description":"角色 id","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"405":{"description":"Method Not Allowed","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultLong"}}}}}}},"/tenant/employees/by-role/{roleId}":{"get":{"tags":["员工管理"],"summary":"按角色查员工分页","description":"分页返回绑定指定角色的本租户员工。page/size 经 @Valid + @Min(1) 校验。","operationId":"getByRoleId","parameters":[{"name":"roleId","in":"path","description":"角色 id","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"query","in":"query","required":true,"schema":{"$ref":"#/components/schemas/EmployeeSubListQuery"}}],"responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"405":{"description":"Method Not Allowed","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultPageResultEmployeeVO"}}}}}}},"/tenant/employees/by-org/{orgId}":{"get":{"tags":["员工管理"],"summary":"按组织查员工分页","description":"分页返回指定组织下的员工(直接子组织,不含子孙;tenantFilter 限本租户)。page/size 经 @Valid + @Min(1) 校验,非法返 400。","operationId":"getByOrgId","parameters":[{"name":"orgId","in":"path","description":"组织 id","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"query","in":"query","required":true,"schema":{"$ref":"#/components/schemas/EmployeeSubListQuery"}}],"responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"405":{"description":"Method Not Allowed","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultPageResultEmployeeVO"}}}}}}},"/tenant/customers":{"get":{"tags":["客户管理（后台 · 只读）"],"summary":"本租户客户列表（只读）","description":"分页返回本租户所有客户(tenantFilter 已限定当前租户);ownerId 不填=全部,填则按归属销售员过滤。供租户管理员/平台管理员查看,只读。响应为 CustomerVO(继承 BaseVO 含 6 个公共列)。page/size 经 @Valid + PageQuery.@Min(1) 校验,非法返 400。","operationId":"list_2","parameters":[{"name":"query","in":"query","required":true,"schema":{"$ref":"#/components/schemas/TenantCustomerPageQuery"}}],"responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"405":{"description":"Method Not Allowed","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultPageResultCustomerVO"}}}}}}},"/tenant/customers/{id}":{"get":{"tags":["客户管理（后台 · 只读）"],"summary":"客户详情（只读）","description":"按 id 取单个客户详情(只读)。响应为 CustomerVO。注:未做归属/SELF 校验,租户管理员可见本租户任意客户。","operationId":"detail","parameters":[{"name":"id","in":"path","description":"客户 id","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"405":{"description":"Method Not Allowed","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultCustomerVO"}}}}}}},"/tenant/customers/{id}/follow-ups":{"get":{"tags":["客户管理（后台 · 只读）"],"summary":"客户跟进历史（只读）","description":"分页返回该客户的跟进历史,按跟进实际时间 followAt 倒序(只读)。响应为 FollowUpVO。page/size 经 @Valid + PageQuery.@Min(1) 校验,非法返 400。","operationId":"followUps","parameters":[{"name":"id","in":"path","description":"客户 id","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"query","in":"query","required":true,"schema":{"$ref":"#/components/schemas/FollowUpPageQuery"}}],"responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"405":{"description":"Method Not Allowed","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultPageResultFollowUpVO"}}}}}}},"/tenant/audit-logs":{"get":{"tags":["审计日志（租户端）"],"summary":"本租户审计日志分页查询","description":"强制按当前登录租户查询 audit_log(tenantId 由服务端强制,前端传无效)。支持按 module/action/entityType/resultStatus/operatorId/start/end 组合过滤,按 createdAt 倒序分页。响应为 AuditLogVO。需 TENANT_ADMIN 或平台管理员。","operationId":"list_3","parameters":[{"name":"query","in":"query","required":true,"schema":{"$ref":"#/components/schemas/AuditLogPageQuery"}}],"responses":{"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"405":{"description":"Method Not Allowed","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"500":{"description":"Internal Server Error","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultVoid"}}}},"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResultPageResultAuditLogVO"}}}}}}}},"components":{"schemas":{"ResultVoid":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"data":{"type":"object"},"timestamp":{"type":"integer","format":"int64"},"success":{"type":"boolean"}}},"OrgCreateDTO":{"required":["orgName"],"type":"object","properties":{"orgName":{"type":"string","description":"组织名称","example":"华东分公司"},"orgType":{"type":"string","description":"组织类型(HQ 公司本部 / BRANCH 分公司 / DEALER 经销商 / AGENT 代理商 / DEPT 部门 / TEAM 团队);默认 DEPT","example":"BRANCH","enum":["HQ","BRANCH","DEALER","AGENT","DEPT","TEAM"]},"parentId":{"type":"integer","description":"上级组织 id;根组织留空","format":"int64"},"leaderId":{"type":"integer","description":"负责人员工 id;可空","format":"int64"},"region":{"type":"string","description":"所在地区;可空","example":"上海"},"sortOrder":{"type":"integer","description":"同级内显示排序(数字越小越靠前);可空","format":"int32","example":1}},"description":"创建组织请求体"},"OrgVO":{"type":"object","properties":{"id":{"type":"integer","description":"主键 id","format":"int64"},"createdAt":{"type":"string","description":"创建时间","format":"date-time"},"updatedAt":{"type":"string","description":"更新时间","format":"date-time"},"createdBy":{"type":"string","description":"创建人(操作人标识,如 Sa-Token loginId 字符串或 system)"},"updatedBy":{"type":"string","description":"更新人"},"tenantId":{"type":"string","description":"所属租户 id(平台管理员等跨租户场景为 null)"},"deleted":{"type":"integer","description":"软删除标记(0=未删除,1=已删除)","format":"int32"},"orgName":{"type":"string","description":"组织名称","example":"华东分公司"},"orgType":{"type":"string","description":"组织类型(HQ 公司本部 / BRANCH 分公司 / DEALER 经销商 / AGENT 代理商 / DEPT 部门 / TEAM 团队)","example":"BRANCH","enum":["HQ","BRANCH","DEALER","AGENT","DEPT","TEAM"]},"parentId":{"type":"integer","description":"上级组织 id(根组织为 null)","format":"int64"},"orgPath":{"type":"string","description":"组织路径(从根到本节点的全路径,如 /默认租户/华东分公司)"},"leaderId":{"type":"integer","description":"负责人员工 id(可空)","format":"int64"},"region":{"type":"string","description":"所在地区","example":"上海"},"sortOrder":{"type":"integer","description":"同级内显示排序(数字越小越靠前)","format":"int32"},"status":{"type":"boolean","description":"启用状态(true 启用 / false 停用)"},"children":{"type":"array","description":"直接子节点列表(按 sortOrder 排序);无子节点为空列表","items":{"$ref":"#/components/schemas/OrgVO"}}},"description":"组织响应体"},"ResultOrgVO":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/OrgVO"},"timestamp":{"type":"integer","format":"int64"},"success":{"type":"boolean"}}},"EmployeeUpdateDTO":{"type":"object","properties":{"name":{"type":"string","description":"员工姓名","example":"张三"},"phone":{"type":"string","description":"登录/联系手机号","example":"13800138000"},"orgId":{"type":"integer","description":"所属组织 id","format":"int64"},"roleId":{"type":"integer","description":"角色 id(关联 crm_role.id)","format":"int64"},"position":{"type":"string","description":"职位","example":"销售主管"},"email":{"type":"string","description":"邮箱","example":"zhangsan@example.com"},"holdLimit":{"type":"integer","description":"客户持有上限","format":"int32","example":50},"region":{"type":"string","description":"负责区域","example":"华东"}},"description":"编辑员工请求体"},"EmployeeVO":{"type":"object","properties":{"id":{"type":"integer","description":"主键 id","format":"int64"},"createdAt":{"type":"string","description":"创建时间","format":"date-time"},"updatedAt":{"type":"string","description":"更新时间","format":"date-time"},"createdBy":{"type":"string","description":"创建人(操作人标识,如 Sa-Token loginId 字符串或 system)"},"updatedBy":{"type":"string","description":"更新人"},"tenantId":{"type":"string","description":"所属租户 id(平台管理员等跨租户场景为 null)"},"deleted":{"type":"integer","description":"软删除标记(0=未删除,1=已删除)","format":"int32"},"name":{"type":"string","description":"员工姓名","example":"张三"},"phone":{"type":"string","description":"登录/联系手机号","example":"13800138000"},"orgId":{"type":"integer","description":"所属组织 id","format":"int64"},"roleId":{"type":"integer","description":"角色 id(关联 crm_role.id;为 2 即 TENANT_ADMIN 预置角色)","format":"int64"},"position":{"type":"string","description":"职位","example":"销售主管"},"email":{"type":"string","description":"邮箱","example":"zhangsan@example.com"},"avatarUrl":{"type":"string","description":"头像 URL"},"status":{"type":"string","description":"状态(ACTIVE 在职 / DISABLED 停用)","example":"ACTIVE","enum":["ACTIVE","DISABLED"]},"holdLimit":{"type":"integer","description":"客户持有上限(可负责的客户数)","format":"int32"},"region":{"type":"string","description":"负责区域","example":"华东"},"hireDate":{"type":"string","description":"入职日期","format":"date"}},"description":"员工响应体"},"ResultEmployeeVO":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/EmployeeVO"},"timestamp":{"type":"integer","format":"int64"},"success":{"type":"boolean"}}},"EmployeeCreateDTO":{"required":["name","orgId","phone","roleId"],"type":"object","properties":{"name":{"type":"string","description":"员工姓名","example":"张三"},"phone":{"type":"string","description":"登录/联系手机号(同租户内唯一建议)","example":"13800138000"},"orgId":{"type":"integer","description":"所属组织 id","format":"int64","example":1},"roleId":{"type":"integer","description":"角色 id(关联 crm_role.id;2 为 TENANT_ADMIN 预置角色)","format":"int64","example":2},"position":{"type":"string","description":"职位","example":"销售主管"},"email":{"type":"string","description":"邮箱","example":"zhangsan@example.com"},"avatarUrl":{"type":"string","description":"头像 URL"},"holdLimit":{"type":"integer","description":"客户持有上限(可负责客户数)","format":"int32","example":50},"region":{"type":"string","description":"负责区域","example":"华东"}},"description":"创建员工请求体"},"ResultInteger":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"data":{"type":"integer","format":"int32"},"timestamp":{"type":"integer","format":"int64"},"success":{"type":"boolean"}}},"ResultListRoleVO":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/RoleVO"}},"timestamp":{"type":"integer","format":"int64"},"success":{"type":"boolean"}}},"RoleVO":{"type":"object","properties":{"id":{"type":"integer","description":"主键 id","format":"int64"},"createdAt":{"type":"string","description":"创建时间","format":"date-time"},"updatedAt":{"type":"string","description":"更新时间","format":"date-time"},"createdBy":{"type":"string","description":"创建人(操作人标识,如 Sa-Token loginId 字符串或 system)"},"updatedBy":{"type":"string","description":"更新人"},"tenantId":{"type":"string","description":"所属租户 id(平台管理员等跨租户场景为 null)"},"deleted":{"type":"integer","description":"软删除标记(0=未删除,1=已删除)","format":"int32"},"roleName":{"type":"string","description":"角色名称","example":"租户管理员"},"roleCode":{"type":"string","description":"角色编码(预置角色常量如 TENANT_ADMIN/PLATFORM_ADMIN;租户自建角色为自定义)","example":"TENANT_ADMIN"},"description":{"type":"string","description":"角色描述","example":"企业管理者"},"roleType":{"type":"string","description":"角色类型(PRESET 预置,全租户共享 / CUSTOM 自建,本租户)","example":"PRESET","enum":["PRESET","CUSTOM"]},"status":{"type":"string","description":"状态(ENABLED 启用 / DISABLED 停用 / DELETED 已删除)","example":"ENABLED","enum":["ENABLED","DISABLED","DELETED"]}},"description":"角色响应体"},"ResultRoleVO":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/RoleVO"},"timestamp":{"type":"integer","format":"int64"},"success":{"type":"boolean"}}},"ResultListOrgVO":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/OrgVO"}},"timestamp":{"type":"integer","format":"int64"},"success":{"type":"boolean"}}},"EmployeePageQuery":{"type":"object","properties":{"page":{"minimum":1,"type":"integer","format":"int32"},"size":{"minimum":1,"type":"integer","format":"int32"},"sortBy":{"type":"string"},"sortDir":{"type":"string"},"orgId":{"type":"integer","description":"按所属组织 id 过滤;留空=不按组织过滤","format":"int64"},"roleId":{"type":"integer","description":"按角色 id 过滤;留空=不按角色过滤","format":"int64"},"status":{"type":"string","description":"按员工状态过滤(ACTIVE 在职 / DISABLED 停用);留空=全部","enum":["ACTIVE","DISABLED"]},"keyword":{"type":"string","description":"关键词(模糊匹配员工姓名/手机号等);可空","example":"张三"},"offset":{"type":"integer","format":"int32"},"pageIndex":{"type":"integer","format":"int32"}},"description":"员工分页查询条件"},"PageResultEmployeeVO":{"type":"object","properties":{"page":{"type":"integer","format":"int64"},"size":{"type":"integer","format":"int64"},"total":{"type":"integer","format":"int64"},"totalPages":{"type":"integer","format":"int64"},"records":{"type":"array","items":{"$ref":"#/components/schemas/EmployeeVO"}}}},"ResultPageResultEmployeeVO":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/PageResultEmployeeVO"},"timestamp":{"type":"integer","format":"int64"},"success":{"type":"boolean"}}},"ResultLong":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"data":{"type":"integer","format":"int64"},"timestamp":{"type":"integer","format":"int64"},"success":{"type":"boolean"}}},"EmployeeSubListQuery":{"type":"object","properties":{"page":{"minimum":1,"type":"integer","format":"int32"},"size":{"minimum":1,"type":"integer","format":"int32"},"sortBy":{"type":"string"},"sortDir":{"type":"string"},"offset":{"type":"integer","format":"int32"},"pageIndex":{"type":"integer","format":"int32"}},"description":"按组织/角色查员工列表的分页查询条件"},"TenantCustomerPageQuery":{"type":"object","properties":{"page":{"minimum":1,"type":"integer","format":"int32"},"size":{"minimum":1,"type":"integer","format":"int32"},"sortBy":{"type":"string"},"sortDir":{"type":"string"},"ownerId":{"type":"integer","description":"按客户归属人(销售员)员工 id 过滤;留空=全部","format":"int64"},"offset":{"type":"integer","format":"int32"},"pageIndex":{"type":"integer","format":"int32"}},"description":"本租户客户分页查询条件(后台只读)"},"CustomerVO":{"type":"object","properties":{"id":{"type":"integer","description":"主键 id","format":"int64"},"createdAt":{"type":"string","description":"创建时间","format":"date-time"},"updatedAt":{"type":"string","description":"更新时间","format":"date-time"},"createdBy":{"type":"string","description":"创建人(操作人标识,如 Sa-Token loginId 字符串或 system)"},"updatedBy":{"type":"string","description":"更新人"},"tenantId":{"type":"string","description":"所属租户 id(平台管理员等跨租户场景为 null)"},"deleted":{"type":"integer","description":"软删除标记(0=未删除,1=已删除)","format":"int32"},"name":{"type":"string","description":"客户名称(企业名或个人名)","example":"上海特斯拉"},"customerType":{"type":"string","description":"客户类型(ENTERPRISE 企业 / PERSONAL 个人)","example":"ENTERPRISE","enum":["ENTERPRISE","PERSONAL"]},"industry":{"type":"string","description":"所属行业","example":"汽车行业"},"region":{"type":"string","description":"所在地区","example":"上海"},"contactName":{"type":"string","description":"主要联系人姓名","example":"张经理"},"contactPhone":{"type":"string","description":"主要联系电话(手机)","example":"13800138000"},"contactPosition":{"type":"string","description":"主要联系人职位","example":"采购经理"},"contactTel":{"type":"string","description":"备用/座机电话","example":"021-12345678"},"email":{"type":"string","description":"客户邮箱","example":"contact@example.com"},"address":{"type":"string","description":"客户地址","example":"上海市浦东新区"},"demand":{"type":"string","description":"需求描述(官网线索主存,可空)","example":"想了解 SaaS CRM 报价方案"},"source":{"type":"string","description":"客户来源(小程序注册/销售录入/展会/转介绍)","example":"SALES_INPUT","enum":["MINI_PROGRAM","SALES_INPUT","EXHIBITION","REFERRAL","WEBSITE"]},"level":{"type":"string","description":"客户级别(VIP/A/B/C)","example":"VIP","enum":["VIP","A","B","C"]},"tags":{"type":"string","description":"标签(逗号分隔的自由文本)","example":"重点,高意向"},"orgId":{"type":"integer","description":"所属组织 id(可空)","format":"int64"},"ownerId":{"type":"integer","description":"客户归属人(销售员)员工 id","format":"int64"},"ownerName":{"type":"string","description":"归属销售姓名(字符串直传,非实体关联;仅 tenant 端 list 接口当前回填)"},"stage":{"type":"string","description":"当前客户阶段(NEW_LEAD新线索 / PENDING_ASSIGN待分配 / CONTACTING接洽中 / NEEDS_COMM需求沟通 / QUOTING报价中 / NEGOTIATING议价中 / DEAL成交 / LOST流失)","example":"NEW_LEAD","enum":["NEW_LEAD","PENDING_ASSIGN","CONTACTING","NEEDS_COMM","QUOTING","NEGOTIATING","DEAL","LOST"]},"lastFollowAt":{"type":"string","description":"最近一次跟进时间","format":"date-time"},"nextFollowAt":{"type":"string","description":"下次计划跟进时间","format":"date-time"},"dealAt":{"type":"string","description":"成交时间(阶段到 DEAL 时写入)","format":"date-time"},"lostAt":{"type":"string","description":"流失时间(阶段到 LOST 时写入)","format":"date-time"},"lostReason":{"type":"string","description":"流失原因"}},"description":"客户响应体"},"PageResultCustomerVO":{"type":"object","properties":{"page":{"type":"integer","format":"int64"},"size":{"type":"integer","format":"int64"},"total":{"type":"integer","format":"int64"},"totalPages":{"type":"integer","format":"int64"},"records":{"type":"array","items":{"$ref":"#/components/schemas/CustomerVO"}}}},"ResultPageResultCustomerVO":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/PageResultCustomerVO"},"timestamp":{"type":"integer","format":"int64"},"success":{"type":"boolean"}}},"ResultCustomerVO":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/CustomerVO"},"timestamp":{"type":"integer","format":"int64"},"success":{"type":"boolean"}}},"FollowUpPageQuery":{"type":"object","properties":{"page":{"minimum":1,"type":"integer","format":"int32"},"size":{"minimum":1,"type":"integer","format":"int32"},"sortBy":{"type":"string"},"sortDir":{"type":"string"},"offset":{"type":"integer","format":"int32"},"pageIndex":{"type":"integer","format":"int32"}},"description":"客户跟进历史分页查询条件(后台只读)"},"FollowUpVO":{"type":"object","properties":{"id":{"type":"integer","description":"主键 id","format":"int64"},"createdAt":{"type":"string","description":"创建时间","format":"date-time"},"updatedAt":{"type":"string","description":"更新时间","format":"date-time"},"createdBy":{"type":"string","description":"创建人(操作人标识,如 Sa-Token loginId 字符串或 system)"},"updatedBy":{"type":"string","description":"更新人"},"tenantId":{"type":"string","description":"所属租户 id(平台管理员等跨租户场景为 null)"},"deleted":{"type":"integer","description":"软删除标记(0=未删除,1=已删除)","format":"int32"},"customerId":{"type":"integer","description":"关联客户 id","format":"int64"},"followerId":{"type":"integer","description":"跟进人(销售员)员工 id","format":"int64"},"followAt":{"type":"string","description":"本次跟进实际发生时间","format":"date-time"},"followMethod":{"type":"string","description":"跟进方式(PHONE 电话 / WECHAT 微信 / VISIT 上门拜访 / EMAIL 邮件 / MEETING 会议)","example":"PHONE","enum":["PHONE","WECHAT","VISIT","EMAIL","MEETING"]},"content":{"type":"string","description":"跟进内容/沟通纪要"},"nextFollowAt":{"type":"string","description":"下次计划跟进时间(可空)","format":"date-time"},"nextFollowPlan":{"type":"string","description":"下次跟进计划/备注(可空)"},"followStatus":{"type":"string","description":"跟进状态(DONE 已完成 / PENDING 待跟进 / OVERDUE 已超时)","example":"DONE","enum":["DONE","PENDING","OVERDUE"]},"recordType":{"type":"string","description":"记录类型(FOLLOW 跟进纪要 / PLAN 跟进计划 / STAGE_CHANGE 阶段变化)","example":"FOLLOW","enum":["FOLLOW","PLAN","STAGE_CHANGE"]},"stageFrom":{"type":"string","description":"阶段变化来源(stage code,仅 STAGE_CHANGE 行有值)","example":"QUOTING"},"stageTo":{"type":"string","description":"阶段变化目标(stage code,仅 STAGE_CHANGE 行有值)","example":"DEAL"}},"description":"跟进记录响应体"},"PageResultFollowUpVO":{"type":"object","properties":{"page":{"type":"integer","format":"int64"},"size":{"type":"integer","format":"int64"},"total":{"type":"integer","format":"int64"},"totalPages":{"type":"integer","format":"int64"},"records":{"type":"array","items":{"$ref":"#/components/schemas/FollowUpVO"}}}},"ResultPageResultFollowUpVO":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/PageResultFollowUpVO"},"timestamp":{"type":"integer","format":"int64"},"success":{"type":"boolean"}}},"AuditLogPageQuery":{"type":"object","properties":{"page":{"minimum":1,"type":"integer","format":"int32"},"size":{"minimum":1,"type":"integer","format":"int32"},"sortBy":{"type":"string"},"sortDir":{"type":"string"},"tenantId":{"type":"string","description":"租户 id;tenant 端由 service 强制当前租户(前端传无效),platform 端可选过滤指定租户","example":"default"},"module":{"type":"string","description":"按模块过滤(EMPLOYEE / ORG / ROLE / CUSTOMER / FOLLOW_UP / TENANT / SYSTEM 等);可空","example":"EMPLOYEE"},"action":{"type":"string","description":"按操作动作过滤(CREATE / UPDATE / DELETE / IMPORT 等);可空","example":"CREATE"},"entityType":{"type":"string","description":"按实体类型过滤;可空","example":"EMPLOYEE"},"resultStatus":{"type":"string","description":"按结果状态过滤(SUCCESS / FAILURE);可空","example":"SUCCESS"},"operatorId":{"type":"integer","description":"按操作人 id 过滤;可空","format":"int64"},"start":{"type":"string","description":"时间范围始(createdAt >= start);可空,格式 yyyy-MM-dd HH:mm(如 2026-11-01 09:00)","format":"date-time"},"end":{"type":"string","description":"时间范围止(createdAt <= end);可空,格式 yyyy-MM-dd HH:mm(如 2026-11-01 18:00)","format":"date-time"},"offset":{"type":"integer","format":"int32"},"pageIndex":{"type":"integer","format":"int32"}},"description":"审计日志分页查询条件"},"AuditLogVO":{"type":"object","properties":{"logId":{"type":"integer","description":"日志主键(log_id,自增,可能跳号属 InnoDB AUTO_INCREMENT 正常行为)","format":"int64"},"tenantId":{"type":"string","description":"所属租户 id"},"operatorId":{"type":"integer","description":"操作人 id(Sa-Token loginId 字符串或 system)","format":"int64"},"operatorName":{"type":"string","description":"操作人姓名"},"operatorRole":{"type":"string","description":"操作人角色(EMPLOYEE / PLATFORM_ADMIN 等)"},"module":{"type":"string","description":"业务模块(EMPLOYEE / ORG / ROLE / CUSTOMER / FOLLOW_UP / TENANT / SYSTEM 等)"},"action":{"type":"string","description":"操作动作(CREATE / UPDATE / DELETE / IMPORT 等)"},"operationDesc":{"type":"string","description":"操作描述(后端拼好的中文摘要,如'创建 员工 张三','删除 角色 租户管理员')"},"entityType":{"type":"string","description":"被操作实体类型"},"entityId":{"type":"string","description":"被操作实体 id(字符串)"},"entityName":{"type":"string","description":"被操作实体名称"},"changeDetail":{"type":"string","description":"变更明细(透传 DTO 中非 null 属性名)"},"requestIp":{"type":"string","description":"请求来源 IP"},"userAgent":{"type":"string","description":"客户端 User-Agent(截断 256)"},"requestPath":{"type":"string","description":"请求路径"},"requestMethod":{"type":"string","description":"请求方法(GET / POST / PUT / DELETE 等)"},"resultStatus":{"type":"string","description":"执行结果(SUCCESS / FAILURE)"},"errorMessage":{"type":"string","description":"失败时的错误消息(SUCCESS 时为 null)"},"createdAt":{"type":"string","description":"记录创建时间","format":"date-time"}},"description":"审计日志响应体"},"PageResultAuditLogVO":{"type":"object","properties":{"page":{"type":"integer","format":"int64"},"size":{"type":"integer","format":"int64"},"total":{"type":"integer","format":"int64"},"totalPages":{"type":"integer","format":"int64"},"records":{"type":"array","items":{"$ref":"#/components/schemas/AuditLogVO"}}}},"ResultPageResultAuditLogVO":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/PageResultAuditLogVO"},"timestamp":{"type":"integer","format":"int64"},"success":{"type":"boolean"}}}},"securitySchemes":{"Bearer JWT":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}}}}