API模块详情

参数名	必填	类型	示例	说明
Authorization	否	string	`Bearer <JWT token>`	用户登录后的 JWT 令牌。若已登录可直接使用，无需传 X-Client。。认证 Token，请在请求头中携带，推荐格式：Bearer {token}
X-Client	否	string	`<client key token>`	客户端密钥。当未携带或无法使用 Authorization 时必填，用于密钥认证。线上文档： http://localhost:5601/docs
X-Site	是	string	`<site key>`	站点标识（必填）。用于切换站点和对应的数据库上下文。所有 OpenAPI 接口必须提供有效的 X-Site header。
X-System-Code	是	string	`AUTH_MANAGEMENT`	系统编码（必填）。用于指定当前访问的业务系统（例如 AUTH_MANAGEMENT、CONTENT_MANAGEMENT）。当系统不支持时将返回“登录用户不支持当前系统，可联系管理员处理”。

POST 无状态会员权限校验 `/openapi/stateless-members/permissions/check`

查看详情

校验无状态会员是否具备访问指定系统模块的权限，适用于服务端到服务端的权限判断。

请求参数

参数名	必填	类型	示例	说明
Authorization	是	string	`Bearer {token}`	会员访问令牌，格式为 Bearer TOKEN

请求体

{
  "systemCode": "string｜必填，目标系统编码，如 AUTH",
  "moduleCode": "string｜必填，目标系统模块编码，如 AUTH_USER"
}

请按照示例结构封装请求体字段，并确保必填字段完整。

响应示例

{
  "success": {
    "code": "0000",
    "message": "权限校验通过",
    "data": {
      "member": {
        "code": "SM000001",
        "type": "VIP"
      },
      "system": {
        "code": "AUTH",
        "name": "权限管理系统"
      },
      "module": {
        "code": "AUTH_USER",
        "name": "用户管理模块"
      }
    }
  },
  "failure": {
    "code": "1008",
    "message": "系统模块未开放访问",
    "data": null
  }
}

注意事项

成功时会在响应 Header 中返回 X-OpenAPI-Result，用于客户端解密并记录审计信息。
失败时统一返回 HTTP 200，业务错误码位于 code 字段。

POST 无状态会员功能额度校验 `/openapi/stateless-members/modules/limits/check`

查看详情

在权限校验通过的前提下，进一步判断某个功能是否超出会员额度限制，常用于调用频率、可用次数等配额管控。

请求参数

参数名	必填	类型	示例	说明
Authorization	是	string	`Bearer {token}`	会员访问令牌，格式为 Bearer TOKEN

请求体

{
  "systemCode": "string｜必填，目标系统编码",
  "moduleCode": "string｜必填，目标模块编码",
  "currentCount": "number｜必填，当前已使用次数"
}

请按照示例结构封装请求体字段，并确保必填字段完整。

响应示例

{
  "success": {
    "code": "0000",
    "message": "权限及额度校验通过",
    "data": {
      "member": {
        "code": "SM000001",
        "type": "VIP"
      },
      "system": {
        "code": "AUTH",
        "name": "权限管理系统"
      },
      "module": {
        "code": "AUTH_USER",
        "name": "用户管理模块"
      },
      "limit": {
        "value": 100,
        "current": 80,
        "remaining": 20
      }
    }
  },
  "failure": {
    "code": "1010",
    "message": "当前模块的使用已达到上限100",
    "data": {
      "limitValue": 100
    }
  }
}

注意事项

若未配置额度限制，limit 字段为 null。
所有结果仍以 HTTP 200 返回，业务码请参考 code 字段。

POST 会员开通 `/openapi/memberships/activate`

查看详情

基于已支付订单为客户端用户开通会员资格，并自动同步会员用户记录和订单状态。

请求参数

参数名	必填	类型	示例	说明
Authorization	是	string	`Bearer {token}`	客户端登录令牌，格式为 Bearer TOKEN

请求体

{
  "memberType": "string｜必填，会员类型编码或名称，如 VIP",
  "orderNo": "string｜必填，已支付订单号"
}

请按照示例结构封装请求体字段，并确保必填字段完整。

响应示例

{
  "success": {
    "code": "0000",
    "message": "会员开通成功",
    "data": {
      "clientUser": {
        "id": "GplqNHbkcmcFa0sj",
        "code": "CU000009",
        "phone": "18347432461",
        "name": "Smkello"
      },
      "memberUser": {
        "id": "toiUHzFoO1xtmSkI",
        "memberType": "VIP"
      },
      "order": {
        "orderNo": "ORD-20250115-0010",
        "status": "COMPLETED"
      }
    }
  },
  "failure": {
    "code": "1107",
    "message": "订单尚未支付或已失效",
    "data": null
  }
}

注意事项

该接口会校验黑名单、订单手机号、订单状态与会员类型一致性。
响应 Header X-OpenAPI-Result 存放加密结果用于客户端追踪。

POST 会员注册 `/openapi/memberships/register`

查看详情

根据注册令牌中的信息自动落地企业或散客账号。如果启用了站点分配，会为用户创建个人站点和独立数据库，并自动创建超级管理员角色。

请求参数

参数名	必填	类型	示例	说明
Authorization	是	string	`Bearer {token}`	注册令牌，服务端提前生成，格式为 Bearer TOKEN
X-Site	是	string	-	所属站点标识，用户将注册到该站点

响应示例

{
  "success": {
    "code": "0000",
    "message": "会员注册成功",
    "data": {
      "accountType": "company",
      "user": {
        "id": "BAKj1wKp7etrmSAT",
        "code": "USER000001",
        "name": "企业管理员",
        "title": "企业管理员",
        "phone": "13800138000",
        "email": "admin@example.com",
        "phonePrefix": "+86",
        "individualism": true,
        "status": 1,
        "roles": [],
        "effectiveDate": "2025-01-21",
        "expiryDate": null,
        "createTime": "2025-01-21T10:00:00.000Z",
        "updateTime": "2025-01-21T10:00:00.000Z",
        "creator": "13800138000",
        "updater": "13800138000"
      },
      "organization": {
        "code": "ORG000001",
        "name": "靖苒数字"
      },
      "site": {
        "id": "site-id",
        "key": "A1B2C3D4-E5F6-7890-ABCD-EF1234567890-ABCDEF12",
        "name": "个人站点",
        "createTime": "2025-01-21T10:00:00.000Z"
      }
    }
  },
  "failure": {
    "code": "1203",
    "message": "公司信用代码已注册",
    "data": null
  }
}

注意事项

当注册信息包含公司名称与信用代码时将自动创建企业账号及组织根节点；否则注册为散客账号。
密码要求同时包含字母和数字，长度不少于 6 位。
如果启用了站点分配，系统会：1. 在所属站点数据库创建用户 2. 创建个人站点和独立数据库 3. 在独立数据库中创建用户副本和超级管理员角色
X-Site header 必传，用于指定用户所属的站点

POST 会员登录 `/openapi/memberships/login`

查看详情

同时支持企业账号与散客账号的登录校验，并返回加密的登录令牌。如果用户有多个可用站点，会返回站点信息。散客账号登录时必须包含同意协议字段。

请求参数

参数名	必填	类型	示例	说明
Authorization	是	string	`Bearer {token}`	登录令牌，包含手机号、密码和同意协议信息（散客账号必填），格式为 Bearer TOKEN。令牌 payload 应包含：phone（手机号）、password（密码）、agreeTerms（同意协议，散客账号必填且必须为 true）
X-System-Code	是	string	-	系统编码。用于指定当前登录的业务系统（例如 AUTH_MANAGEMENT、CONTENT_MANAGEMENT）。当系统不支持时将返回“登录用户不支持当前系统，可联系管理员处理”。

响应示例

有个人站点:

{
  "code": "0000",
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "user": {
      "id": "BAKj1wKp7etrmSAT",
      "code": "USER000001",
      "username": "企业管理员",
      "phone": "13800138000",
      "email": "admin@example.com",
      "individualism": true,
      "status": 1,
      "createTime": "2025-01-21T10:00:00.000Z",
      "accountType": "user",
      "type": "普通用户"
    },
    "companyName": "靖苒数字",
    "site": {
      "id": "MNFIOHH6QOA3kg0z",
      "key": "A1B2C3D4-E5F6-7890-ABCD-EF1234567890-ABCDEF12",
      "name": "个人站点",
      "createTime": "2025-01-21T10:00:00.000Z"
    }
  }
}

无个人站点:

{
  "code": "0000",
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "user": {
      "id": "BAKj1wKp7etrmSAT",
      "code": "USER000001",
      "username": "企业管理员",
      "phone": "13800138000",
      "email": "admin@example.com",
      "individualism": false,
      "status": 1,
      "createTime": "2025-01-21T10:00:00.000Z",
      "accountType": "user",
      "type": "普通用户"
    },
    "companyName": "靖苒数字",
    "site": null
  }
}

注意事项

优先尝试企业账号登录，失败后自动回退到散客账号校验。
散客账号登录时，登录令牌的 payload 中必须包含 agreeTerms 字段且值为 true，否则返回错误码 1303（请同意隐私等协议）。
企业账号登录时，agreeTerms 字段可选，不影响登录流程。
成功时 data.token 与响应 Header X-OpenAPI-Result 均为加密令牌。
响应中的 site 字段说明：
- site 字段只返回个人站点信息（如果用户有个人站点），不会返回所属站点信息
- 有个人站点时：site 字段包含个人站点的完整信息（id、key、name、createTime）
- 无个人站点时：site 字段为 null（无论用户是否有所属站点）
- 判断逻辑：只需判断 site 是否为 null 即可知道用户是否有个人站点
- 注意：用户可能既有所属站点（通过 user.siteKey 访问），也有个人站点（通过 site 字段访问）
后续请求可通过 X-Site header 切换站点，切换后使用对应站点的数据库。

POST 登录令牌校验 `/openapi/memberships/login/verify`

查看详情

对登录接口返回的访问令牌进行有效性校验，确认令牌是否过期、账号状态及黑名单状态。

请求参数

参数名	必填	类型	示例	说明
Authorization	是	string	`Bearer {token}`	登录接口返回的访问令牌，格式为 Bearer TOKEN
X-System-Code	是	string	-	系统编码。用于指定当前登录的业务系统（例如 AUTH_MANAGEMENT、CONTENT_MANAGEMENT）。当系统不支持时将返回“登录用户不支持当前系统，可联系管理员处理”。

响应示例

{
  "success": {
    "code": "0000",
    "message": "登录令牌校验成功",
    "data": {
      "phone": "13800138000",
      "id": "USER000001",
      "_id": "MNFIOHH6QOA3kg0z"
    }
  },
  "failure": {
    "code": "1300",
    "message": "登录令牌无效或已过期",
    "data": null
  }
}

注意事项

当令牌失效、对应账号被禁用或存在黑名单记录时也会返回 200，但 code 与 message 表示具体失败原因。
若需要补充返回字段，可在 data 中扩展 additional 信息。
支持通过 X-Site header 切换站点，切换后使用对应站点的数据库进行权限校验。

POST 资源权限校验 `/openapi/permissions/resource-check`

查看详情

基于登录令牌校验指定系统下用户是否拥有访问某接口所需的资源与权限。支持通过 X-Site header 切换站点。

请求参数

参数名	必填	类型	示例	说明
Authorization	是	string	`Bearer {token}`	登录接口返回的访问令牌，格式为 Bearer TOKEN
X-Site	否	string	-	站点标识。用于切换站点和对应的数据库上下文。如果用户有多个可用站点，可通过此 header 切换。

请求体

{
  "systemCode": "string｜必填，目标系统编码",
  "apiName": "string｜必填，接口标识（可使用资源 code、name、title 或 URL）",
  "requiredPermissions": "string[]｜选填，需要同时具备的权限编码数组"
}

请按照示例结构封装请求体字段，并确保必填字段完整。

响应示例

{
  "success": {
    "code": "0000",
    "message": "资源权限校验成功",
    "data": {
      "accessGranted": true,
      "user": {
        "id": "BAKj1wKp7etrmSAT",
        "phone": "13800138000",
        "type": "user"
      },
      "system": {
        "code": "AUTH",
        "name": "权限管理系统"
      },
      "resource": {
        "code": "API_CUSTOMER_DELETE",
        "url": "/api/customers/:id",
        "type": "api"
      },
      "checkedPermissions": [
        "CUSTOMER_DELETE"
      ]
    }
  },
  "failure": {
    "code": "1502",
    "message": "缺少必要权限: CUSTOMER_DELETE",
    "data": null
  }
}

注意事项

若找不到与 apiName 匹配的资源，将返回 code=1501。
requiredPermissions 未传时仅校验资源授权，传入时要求全部命中。
出于安全考虑，失败时同样返回 HTTP 200，但 code/message 用于区分失败原因。

POST 账户权限校验 `/openapi/permissions/check`

查看详情

根据访问令牌校验账户在指定系统下拥有的资源与权限。资源列表以树状结构返回，方便前端渲染菜单等场景。支持通过 X-Site header 切换站点。

请求参数

参数名	必填	类型	示例	说明
Authorization	是	string	`Bearer {token}`	访问令牌，支持系统用户与客户端用户，格式为 Bearer TOKEN
X-Site	否	string	-	站点标识。用于切换站点和对应的数据库上下文。如果用户有多个可用站点，可通过此 header 切换。

请求体

{
  "systemCode": "string｜必填，要校验的系统编码"
}

请按照示例结构封装请求体字段，并确保必填字段完整。

响应示例

{
  "success": {
    "code": "0000",
    "message": "权限校验成功",
    "data": {
      "user": {
        "id": "MNFIOHH6QOA3kg0z",
        "code": "USER000001",
        "username": "企业管理员",
        "type": "user"
      },
      "companyName": "靖苒数字",
      "system": {
        "code": "AUTH",
        "name": "权限管理系统"
      },
      "resources": [
        {
          "id": "RES001",
          "code": "RES001",
          "name": "内容管理",
          "title": "内容管理",
          "type": "page",
          "url": "/content",
          "parentId": null,
          "orderNum": 1,
          "children": [
            {
              "id": "RES002",
              "code": "RES002",
              "name": "文章管理",
              "title": "文章管理",
              "type": "page",
              "url": "/content/articles",
              "parentId": "RES001",
              "orderNum": 1,
              "children": []
            },
            {
              "id": "RES003",
              "code": "RES003",
              "name": "分类管理",
              "title": "分类管理",
              "type": "page",
              "url": "/content/categories",
              "parentId": "RES001",
              "orderNum": 2,
              "children": []
            }
          ]
        }
      ],
      "resourcesByType": {
        "page": [
          {
            "id": "RES001",
            "code": "RES001",
            "name": "内容管理",
            "title": "内容管理",
            "type": "page",
            "url": "/content",
            "parentId": null,
            "orderNum": 1,
            "children": [
              {
                "id": "RES002",
                "code": "RES002",
                "name": "文章管理",
                "title": "文章管理",
                "type": "page",
                "url": "/content/articles",
                "parentId": "RES001",
                "orderNum": 1,
                "children": []
              },
              {
                "id": "RES003",
                "code": "RES003",
                "name": "分类管理",
                "title": "分类管理",
                "type": "page",
                "url": "/content/categories",
                "parentId": "RES001",
                "orderNum": 2,
                "children": []
              }
            ]
          }
        ],
        "button": [
          {
            "id": "RES004",
            "code": "RES004",
            "name": "新增按钮",
            "title": "新增按钮",
            "type": "button",
            "url": "/api/content/create",
            "parentId": null,
            "orderNum": 1,
            "children": []
          }
        ]
      },
      "site": {
        "id": "site-id",
        "key": "A1B2C3D4-E5F6-7890-ABCD-EF1234567890-ABCDEF12",
        "name": "个人站点",
        "createTime": "2025-01-21T10:00:00.000Z"
      }
    }
  },
  "failure": {
    "code": "1402",
    "message": "系统未开放或已停用",
    "data": null
  }
}

注意事项

企业账号会同时合并个人权限与所属组织权限；散客账号仅返回个人权限。
权限列表来自角色继承链，请根据资源类型及 resourceUrls 进行前端路由控制。
resources 字段返回树状结构，每个资源节点包含 children 数组，用于前端渲染菜单树。树状结构按 orderNum 排序。
resourcesByType 字段按资源类型分组返回，每个类型下的资源也是树状结构，方便前端按类型渲染。
支持通过 X-Site header 切换站点，切换后使用对应站点的数据库进行权限查询，返回该站点下的角色和权限。

POST 激活无状态会员 `/openapi/stateless-members/activate`

查看详情

激活无状态会员，通过X-Member-Key header中的混合JWT解密得到密钥，校验会员有效性后生成新的密钥令牌返回。

请求参数

参数名	必填	类型	示例	说明
X-Member-Key	是	string	-	会员密钥令牌，通过混合JWT加密
X-System-Code	是	string	-	系统编码，用于判断会员类型是否支持当前系统
X-Site	是	string	-	站点标识

响应示例

{
  "success": {
    "code": "0000",
    "message": "激活成功",
    "data": {
      "keyToken": "新的密钥令牌（混合JWT加密）",
      "member": {
        "id": "xxx",
        "code": "SM0001",
        "name": "无状态会员",
        "memberTypeId": "yyy",
        "effectiveDate": "2025-01-01",
        "validityDays": 365
      }
    }
  },
  "failure": {
    "code": "1504",
    "message": "您绑定的会员码无效",
    "data": null
  },
  "failureExpired": {
    "code": "1501",
    "message": "激活已超时，请重新绑定激活",
    "data": null
  }
}

注意事项

如果X-Member-Key的JWT解析已过期，返回错误：激活已超时，请重新绑定激活
校验无状态密钥是否存在且有效，且没有过期
校验关联会员类型记录是否存在且有效
通过X-System-Code判断会员类型是否支持当前系统
校验通过后，用混合JWT加密生成新的密钥返回
不满足条件返回：您绑定的会员码无效

POST 检查无状态会员有效性 `/openapi/stateless-members/check`

查看详情

检查无状态会员是否还有效，通过X-Member-Key header中的混合JWT解密得到密钥，校验会员状态、过期时间、系统支持等，返回剩余天数。

请求参数

参数名	必填	类型	示例	说明
X-Member-Key	是	string	-	会员密钥令牌，通过混合JWT加密
X-System-Code	是	string	-	系统编码，用于判断会员类型是否支持当前系统
X-Site	是	string	-	站点标识

响应示例

{
  "success": {
    "code": "0000",
    "message": "校验通过",
    "data": {
      "valid": true,
      "remainingDays": 30,
      "member": {
        "id": "xxx",
        "code": "SM0001",
        "name": "无状态会员",
        "memberTypeId": "yyy",
        "effectiveDate": "2025-01-01",
        "validityDays": 365
      }
    }
  },
  "failure": {
    "code": "1506",
    "message": "您绑定的会员无效",
    "data": null
  },
  "failureExpired": {
    "code": "1505",
    "message": "传入的会员需要重新绑定",
    "data": null
  },
  "failureMemberExpired": {
    "code": "1507",
    "message": "会员已过期",
    "data": null
  }
}

注意事项

如果X-Member-Key的JWT解析已过期，返回错误：传入的会员需要重新绑定
判断无状态密钥是否存在且有效
关联会员类型记录是否存在且有效，不存在或无效返回：您绑定的会员无效
判断是否过期，已过期返回：会员已过期
通过X-System-Code判断会员类型是否支持当前系统，不支持返回：当前会员码不支持当前系统
返回会员还有多少天到期（基于会员有效期、当天日期、会员生效日期计算剩余时间按天计）
不满足条件返回：您绑定的会员码无效

POST 检查无状态会员功能有效性 `/openapi/stateless-members/functionCheck`

查看详情

在检查无状态会员有效性的基础上，额外通过X-Function header检查会员功能模块中是否有该功能。

请求参数

参数名	必填	类型	示例	说明
X-Member-Key	是	string	-	会员密钥令牌，通过混合JWT加密
X-System-Code	是	string	-	系统编码，用于判断会员类型是否支持当前系统
X-Function	是	string	-	功能代码，用于检查会员功能模块中是否有该功能
X-Site	是	string	-	站点标识

响应示例

{
  "success": {
    "code": "0000",
    "message": "校验通过",
    "data": {
      "valid": true,
      "remainingDays": 30,
      "member": {
        "id": "xxx",
        "code": "SM0001",
        "name": "无状态会员",
        "memberTypeId": "yyy",
        "effectiveDate": "2025-01-01",
        "validityDays": 365
      },
      "function": {
        "code": "FUNC001",
        "name": "功能名称",
        "type": "Resource"
      }
    }
  },
  "failure": {
    "code": "1508",
    "message": "当前会员不支持当前功能",
    "data": null
  }
}

注意事项

在/stateless-members/check功能基础上，通过Header的X-Function额外检查会员功能模块
如果会员功能模块中有该功能则通过，没有则返回：当前会员不支持当前功能
支持通过moduleCode或moduleId查找功能模块
功能模块类型可以是Resource（绑定资源）或Custom（自定义模块名称）

公共请求头（所有接口适用）

OpenAPI 接口

POST 无状态会员权限校验 /openapi/stateless-members/permissions/check

请求体

POST 无状态会员功能额度校验 /openapi/stateless-members/modules/limits/check

请求体

POST 会员开通 /openapi/memberships/activate

请求体

POST 会员注册 /openapi/memberships/register

POST 会员登录 /openapi/memberships/login

POST 登录令牌校验 /openapi/memberships/login/verify

POST 资源权限校验 /openapi/permissions/resource-check

请求体

POST 账户权限校验 /openapi/permissions/check

请求体

POST 激活无状态会员 /openapi/stateless-members/activate

POST 检查无状态会员有效性 /openapi/stateless-members/check

POST 检查无状态会员功能有效性 /openapi/stateless-members/functionCheck

POST 无状态会员权限校验 `/openapi/stateless-members/permissions/check`

POST 无状态会员功能额度校验 `/openapi/stateless-members/modules/limits/check`

POST 会员开通 `/openapi/memberships/activate`

POST 会员注册 `/openapi/memberships/register`

POST 会员登录 `/openapi/memberships/login`

POST 登录令牌校验 `/openapi/memberships/login/verify`

POST 资源权限校验 `/openapi/permissions/resource-check`

POST 账户权限校验 `/openapi/permissions/check`

POST 激活无状态会员 `/openapi/stateless-members/activate`

POST 检查无状态会员有效性 `/openapi/stateless-members/check`

POST 检查无状态会员功能有效性 `/openapi/stateless-members/functionCheck`