vitepress-template

Appearance

系统服务API ​

**本文引用的文件** - [[bi-sys/api/sys/v1/user.proto]](../api/file/bi-sys/api/sys/v1/user.proto) - [[bi-sys/api/sys/v1/role.proto]](../api/file/bi-sys/api/sys/v1/role.proto) - [[bi-sys/api/sys/v1/dept.proto]](../api/file/bi-sys/api/sys/v1/dept.proto) - [[bi-tenant/api/tenant/v1/user.proto]](../api/file/bi-tenant/api/tenant/v1/user.proto) - [[bi-tenant/api/tenant/v1/org.proto]](../api/file/bi-tenant/api/tenant/v1/org.proto) - [[bi-notify/api/notify/v1/notification.proto]](../api/file/bi-notify/api/notify/v1/notification.proto) - [[bi-notify/api/notify/v1/template.proto]](../api/file/bi-notify/api/notify/v1/template.proto) - [[bi-notify/api/notify/v1/tag.proto]](../api/file/bi-notify/api/notify/v1/tag.proto) - [[bi-common/auth/rbac.go]](../api/file/bi-common/auth/rbac.go) - [[bi-common/auth/middleware.go]](../api/file/bi-common/auth/middleware.go) - [[ui-web-admin/src/lib/api.ts]](../api/file/ui-web-admin/src/lib/api.ts)

目录 ​

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能考虑
  8. 故障排查指南
  9. 结论
  10. 附录

简介 ​

本文件面向系统管理、租户管理与通知服务，提供统一的API规范说明与集成指南。内容涵盖：

  • 系统管理：用户、角色、部门的增删改查与状态管理
  • 租户管理：用户、组织的多租户隔离与权限分配
  • 通知服务：消息发送、模板与标签管理
  • RBAC权限控制与数据隔离机制
  • 完整的调用示例与集成步骤

项目结构 ​

系统服务API主要分布在以下模块：

  • 系统管理（bi-sys）：用户、角色、部门管理
  • 租户管理（bi-tenant）：租户侧用户与组织管理
  • 通知服务（bi-notify）：通知发送、模板与标签
  • 通用鉴权（bi-common）：JWT、RBAC中间件与权限提供者

图表来源

章节来源

核心组件 ​

  • 系统管理（bi-sys）
    • 用户服务：分页查询、详情、创建、更新、删除、批量删除、状态变更、密码重置/修改、分配角色、当前用户信息、用户选项
    • 角色服务：角色列表/详情、创建/更新/删除、批量删除、状态变更、分配菜单、设置数据范围、角色用户列表、角色选项
    • 部门服务：部门列表/树、详情、创建/更新/删除、部门选项树
  • 租户管理（bi-tenant）
    • 用户服务：分页查询、详情、创建/更新/删除、批量删除、导出、分配角色/门店/代理、重置密码、状态变更、管理员状态变更、用户选项
    • 组织服务：组织树/选项树、详情、创建/更新/删除
  • 通知服务（bi-notify）
    • 通知：发送、查询
    • 模板：创建/更新/删除、查询
    • 标签：创建/更新/删除、查询
  • 鉴权与权限控制（bi-common）
    • JWT认证中间件
    • RBAC权限中间件：路径白名单、管理端/客户端区分、权限提供者、权限缓存、默认权限映射规则

章节来源

架构总览 ​

系统采用“微服务+HTTP/gRPC网关”的混合架构，前端通过HTTP调用各服务；通用鉴权中间件在服务入口统一处理JWT与RBAC权限。

图表来源

详细组件分析 ​

系统管理（bi-sys） ​

用户管理（/api/v1/sys/users） ​

  • 列表查询：支持按用户名、昵称、手机号、状态、部门、时间范围分页查询
  • 详情查询：获取用户详情与角色信息
  • 创建用户：用户名唯一，需设置基础信息与初始角色
  • 更新用户：更新基本信息（不含密码）
  • 删除/批量删除：软删除
  • 状态变更：启用/禁用
  • 密码管理：管理员重置密码；用户修改自己的密码
  • 当前用户：获取当前用户信息与权限
  • 分配角色：为用户分配一个或多个角色
  • 用户选项：获取下拉选项列表

图表来源

章节来源

角色管理（/api/v1/sys/roles） ​

  • 列表/详情：支持按角色名称/编码、状态、时间范围查询
  • 创建/更新/删除：角色编码唯一；已分配用户的角色禁止删除
  • 批量删除：软删除
  • 状态变更：启用/禁用
  • 菜单分配：覆盖式分配菜单权限
  • 数据范围：设置数据权限范围（全部/本部门/本部门及以下/仅本人/自定义）
  • 角色用户：分页查询已分配该角色的用户
  • 角色选项：获取下拉选项

图表来源

章节来源

部门管理（/api/v1/sys/depts） ​

  • 列表/树：扁平列表与树形结构查询
  • 详情：获取部门信息
  • 创建/更新/删除：支持父部门、负责人、联系方式、排序、状态、备注
  • 部门选项：获取下拉选项树

图表来源

章节来源

租户管理（bi-tenant） ​

租户用户管理（/api/v1/tenant/users） ​

  • 列表/详情：支持按组织、用户名、手机号、真实姓名、状态分页查询
  • 创建/更新/删除：支持设置组织、昵称、邮箱、手机、性别、备注
  • 批量删除：软删除
  • 导出：导出用户列表
  • 权限分配：分配角色、门店权限、数据代理
  • 密码重置：管理员重置密码并返回新密码
  • 状态变更：启用/禁用
  • 管理员状态：变更用户管理员身份
  • 用户选项：按组织与状态筛选的下拉选项

图表来源

章节来源

租户组织管理（/api/v1/tenant/orgs） ​

  • 组织树/选项树：按状态筛选的树形结构
  • 详情：获取组织详情
  • 创建/更新/删除：支持父组织、类型、负责人、联系方式、排序、状态、备注

图表来源

章节来源

通知服务（bi-notify） ​

通知发送（/api/v1/notify/notifications） ​

  • 发送通知：支持模板与渠道配置，返回发送结果
  • 查询通知：按条件分页查询

模板管理（/api/v1/notify/templates） ​

  • 创建/更新/删除：维护通知模板
  • 查询：分页查询模板列表

标签管理（/api/v1/notify/tags） ​

  • 创建/更新/删除：维护标签
  • 查询：分页查询标签列表

章节来源

RBAC权限控制与数据隔离 ​

权限中间件（JWT + RBAC） ​

  • 路径区分：包含“-m”的路径视为管理端API（如/tenant-m/），否则为客户端API
  • 管理端访问限制：仅系统用户（TenantID=0）可访问管理端API
  • 权限提供者：客户端API使用本地或bi-tenant RPC获取权限；管理端API使用bi-sys RPC
  • 权限映射：默认规则将路径映射为“模块:资源”或“模块:资源:动作”
  • 权限缓存：可选缓存策略减少权限查询开销

图表来源

章节来源

依赖关系分析 ​

  • 鉴权中间件依赖：
    • JWT配置与黑名单
    • 权限提供者（客户端/管理端）
    • 权限缓存（可选）
  • 服务间依赖：
    • 管理端API通过RPC调用bi-sys进行权限校验
    • 客户端API通过RPC调用bi-tenant或本地权限提供者
  • 前端依赖：
    • ui-web-admin通过封装的api.ts调用系统管理与租户管理API

图表来源

章节来源

性能考虑 ​

  • 权限缓存：启用权限缓存可显著降低权限查询次数，建议对高频权限点进行缓存
  • 分页查询：列表接口均支持分页，建议前端合理设置page/size，避免一次性加载过多数据
  • 路径映射优化：默认权限映射规则简单高效，若自定义映射函数，应确保复杂度可控
  • 管理端访问限制：管理端API仅系统用户可访问，避免非授权流量进入

故障排查指南 ​

  • 未登录/Token无效：检查JWT中间件配置与Token有效性
  • 无权限访问：确认用户角色与权限提供者返回的权限集合；管理端需系统用户身份
  • 路径映射错误：确认URL是否包含“-m”，以及默认权限映射规则是否符合预期
  • 权限缓存异常：检查缓存实现与失效策略，必要时清理缓存后重试

章节来源

结论 ​

本API文档梳理了系统管理、租户管理与通知服务的核心接口，并明确了RBAC权限控制与数据隔离机制。通过统一的鉴权中间件与清晰的路径区分，系统实现了客户端与管理端的差异化权限控制，满足多租户场景下的安全与合规要求。

附录 ​

调用示例与集成指南 ​

  • 前端集成
    • 使用ui-web-admin中的api.ts封装调用系统管理与租户管理API，参考如下路径：
      • 系统菜单：/api/v1/sys/menus、/api/v1/sys/menus/tree
      • 租户菜单：/api/v1/tenant-m/menus/tree、/api/v1/tenant-m/menus
      • 租户切换状态：/api/v1/tenant-m/tenants/{id}/status
  • 系统管理
    • 用户：/api/v1/sys/users、/api/v1/sys/users/{id}、/api/v1/sys/users/{id}/status、/api/v1/sys/users/{id}/roles
    • 角色：/api/v1/sys/roles、/api/v1/sys/roles/{id}、/api/v1/sys/roles/{id}/menus、/api/v1/sys/roles/{id}/data-scope
    • 部门：/api/v1/sys/depts、/api/v1/sys/depts/tree、/api/v1/sys/depts/options
  • 租户管理
    • 用户：/api/v1/tenant/users、/api/v1/tenant/users/{id}、/api/v1/tenant/users/{id}/stores、/api/v1/tenant/users/{id}/reset-password
    • 组织：/api/v1/tenant/orgs、/api/v1/tenant/orgs/
  • 通知服务
    • 通知：/api/v1/notify/notifications
    • 模板：/api/v1/notify/templates
    • 标签：/api/v1/notify/tags

章节来源