{
  "openapi": "3.1.0",
  "info": {
    "title": "Flashduty 开放 API",
    "description": "Flashduty 事件管理平台的公开 HTTP API —— 覆盖故障、通知模板、协作空间、值班排班、监控、RUM、以及平台管理。每次调用都需在 query 中携带 `app_key`，该 key 在 Flashduty 控制台 我的 → APP Key 中创建（也可放在请求头 `Fd-App-Key` 中）。所有响应使用统一结构：成功时为 `{ request_id, data }`，失败时为 `{ request_id, error }`。",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.flashcat.cloud",
      "description": "Flashduty Open API"
    }
  ],
  "security": [
    {
      "AppKeyAuth": []
    }
  ],
  "tags": [
    {
      "name": "平台/成员管理",
      "description": ""
    },
    {
      "name": "平台/团队管理",
      "description": ""
    },
    {
      "name": "平台/角色与权限",
      "description": ""
    },
    {
      "name": "平台/审计日志",
      "description": "检索和读取账户操作审计日志。"
    },
    {
      "name": "平台/账户设置",
      "description": "账户（主体）信息与设置"
    }
  ],
  "paths": {
    "/team/list": {
      "post": {
        "operationId": "team-read-list",
        "summary": "查看团队列表",
        "description": "分页返回当前账户下的团队列表。",
        "tags": [
          "平台/团队管理"
        ],
        "x-mint": {
          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 传 `person_id` 只返回该人员所在的团队；`query` 对团队名称或描述做子串匹配。\n- 已删除的团队不会出现在列表中。",
          "href": "/zh/api-reference/platform/teams/team-read-list",
          "metadata": {
            "sidebarTitle": "查看团队列表"
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/TeamListResponse"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                  "data": {
                    "p": 1,
                    "limit": 20,
                    "total": 1,
                    "items": [
                      {
                        "account_id": 10023,
                        "team_id": 1001,
                        "team_name": "Backend SRE",
                        "description": "Backend reliability engineering team",
                        "status": "enabled",
                        "updated_by_name": "alice",
                        "updated_by": 80011,
                        "creator_id": 80011,
                        "creator_name": "",
                        "created_at": 1710000000,
                        "updated_at": 1712000000,
                        "person_ids": [
                          80011,
                          80012
                        ],
                        "ref_id": ""
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TeamListRequest"
              },
              "example": {
                "p": 1,
                "limit": 20,
                "orderby": "created_at",
                "asc": false
              }
            }
          }
        }
      }
    },
    "/team/infos": {
      "post": {
        "operationId": "team-read-infos",
        "summary": "批量查看团队信息",
        "description": "一次请求按 ID 列表批量返回多个团队的基本信息。",
        "tags": [
          "平台/团队管理"
        ],
        "x-mint": {
          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 重复的 ID 会去重；不属于本账户任何团队的 ID 会被忽略。\n- 已删除的团队仍会返回（`person_ids` 为空），因此历史记录里保存的团队 ID 依然能解析出名称。\n- 没有任何 ID 匹配时，`items` 为 `null`。",
          "href": "/zh/api-reference/platform/teams/team-read-infos",
          "metadata": {
            "sidebarTitle": "批量查看团队信息"
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/TeamInfosResponse"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                  "data": {
                    "items": [
                      {
                        "team_id": 1001,
                        "team_name": "Backend SRE",
                        "person_ids": [
                          80011,
                          80012
                        ]
                      },
                      {
                        "team_id": 1002,
                        "team_name": "Frontend",
                        "person_ids": [
                          80013
                        ]
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TeamInfosRequest"
              },
              "example": {
                "team_ids": [
                  1001,
                  1002
                ]
              }
            }
          }
        }
      }
    },
    "/role/disable": {
      "post": {
        "operationId": "role-write-disable",
        "summary": "禁用角色",
        "description": "将自定义角色置为禁用状态，但不删除它。",
        "tags": [
          "平台/角色与权限"
        ],
        "x-mint": {
          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **角色管理**（`organization`） |\n\n## 使用说明\n\n- 只有 `enabled` 状态的角色可以禁用；对已禁用的角色调用会返回 `400 InvalidParameter`。\n- 内置角色（`2`、`6`、`8`）无法禁用：调用返回 `400 InvalidParameter`（`Preset roles cannot be modified.`）。\n- 角色 ID 不存在或已删除时不做任何操作，调用仍返回成功。\n- 禁用角色不会把它从持有该角色的成员身上解除，但已禁用的角色不提供任何权限：这些成员及其创建的 App Key 会失去该角色的权限，直到角色重新启用。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
          "href": "/zh/api-reference/platform/roles-permissions/role-write-disable",
          "metadata": {
            "sidebarTitle": "禁用角色"
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/PlatformEmptyObject"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                  "data": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RoleIDRequest"
              },
              "example": {
                "role_id": 150
              }
            }
          }
        }
      }
    },
    "/role/delete": {
      "post": {
        "operationId": "role-write-delete",
        "summary": "删除角色",
        "description": "删除自定义角色，可选择先从所有仍持有它的成员身上解除。",
        "tags": [
          "平台/角色与权限"
        ],
        "x-mint": {
          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **角色管理**（`organization`） |\n\n## 使用说明\n\n- 仍有成员持有该角色时，调用返回 `400 ReferenceExist`，并在 `data.refs` 中列出这些成员（`kind` 为 `member`）；设置 `is_force` 为 `true` 会先从所有持有成员解除该角色再删除。\n- 被单点登录配置选为默认角色的角色无法删除，即使设置 `is_force` 也一样；在单点登录配置中取消选择前，调用会返回 `400 ReferenceExist`。\n- 角色 ID 不存在或已删除时不做任何操作，调用仍返回成功。\n- 内置角色（`2`、`6`、`8`）不能删除：无论是否设置 `is_force`，调用都返回 `400 InvalidParameter`（`Preset roles cannot be modified.`）。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
          "href": "/zh/api-reference/platform/roles-permissions/role-write-delete",
          "metadata": {
            "sidebarTitle": "删除角色"
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/PlatformEmptyObject"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                  "data": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RoleDeleteRequest"
              },
              "example": {
                "role_id": 150
              }
            }
          }
        }
      }
    },
    "/person/infos": {
      "post": {
        "operationId": "personInfos",
        "summary": "批量获取人员信息",
        "description": "根据 ID 批量返回成员或账户的资料信息。",
        "tags": [
          "平台/成员管理"
        ],
        "x-mint": {
          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 传入账户 ID 会返回账户主体，`as` 为 `account`。其他 ID 在本账户成员中查找，包括已删除的成员（`status` 为 `deleted`），因此历史记录里保存的 ID 依然能解析。\n- 重复的 ID 会去重；两者都匹配不上的 ID 会被省略。",
          "href": "/zh/api-reference/platform/members/person-infos",
          "metadata": {
            "sidebarTitle": "批量获取人员信息"
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/PersonInfosResponse"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                  "data": {
                    "items": [
                      {
                        "account_id": 2451002751131,
                        "person_id": 2476444212131,
                        "person_name": "Alice",
                        "avatar": "/image/avatar1.png",
                        "locale": "zh-CN",
                        "time_zone": "Asia/Shanghai",
                        "email": "alice@example.com",
                        "phone_verified": false,
                        "email_verified": true,
                        "as": "member",
                        "status": "enabled"
                      },
                      {
                        "account_id": 2451002751131,
                        "person_id": 3790925372131,
                        "person_name": "Bob",
                        "email": "bob@example.com",
                        "phone_verified": false,
                        "email_verified": true,
                        "as": "member",
                        "status": "enabled"
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PersonInfosRequest"
              },
              "example": {
                "person_ids": [
                  2476444212131,
                  3790925372131
                ]
              }
            }
          }
        }
      }
    },
    "/member/info": {
      "post": {
        "operationId": "memberInfo",
        "summary": "获取当前成员信息",
        "description": "返回当前凭据所属成员的资料及其所在账户信息。",
        "tags": [
          "平台/成员管理"
        ],
        "x-mint": {
          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 但对调用凭据有要求，见使用说明 |\n\n## 使用说明\n\n- 需要成员凭据；使用账户主体凭据调用会返回 `400 BadRequest`。账户主体请使用 `POST /account/info`。\n- `time_zone` 是成员自己的设置（空字符串表示跟随账户），`account_time_zone` 是账户的设置，`resolved_time_zone` 是实际用于展示时间的时区。",
          "href": "/zh/api-reference/platform/members/member-info",
          "metadata": {
            "sidebarTitle": "获取当前成员信息"
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/MemberInfoResponse"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                  "data": {
                    "account_avatar": "",
                    "account_email": "alice@example.com",
                    "account_id": 2451002751131,
                    "account_locale": "en-US",
                    "account_name": "Acme Corp",
                    "account_role_ids": [
                      6
                    ],
                    "account_time_zone": "Asia/Shanghai",
                    "avatar": "/image/avatar1.png",
                    "country_code": "CN",
                    "created_at": 1701399971,
                    "domain": "acme",
                    "email": "alice@example.com",
                    "email_verified": true,
                    "is_external": false,
                    "locale": "zh-CN",
                    "member_id": 2476444212131,
                    "member_name": "Alice",
                    "phone": "+86185****0300",
                    "phone_verified": true,
                    "time_zone": "Asia/Shanghai",
                    "resolved_time_zone": "Asia/Shanghai"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MemberInfoRequest"
              },
              "example": {}
            }
          }
        }
      }
    },
    "/role/permission/list": {
      "post": {
        "operationId": "role-read-list-permission",
        "summary": "查看角色权限集合",
        "description": "列出权限项，并标记其中哪些由指定角色授予。",
        "tags": [
          "平台/角色与权限"
        ],
        "x-mint": {
          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `with_all: true` 时返回全部权限，`is_granted` 标记 `role_ids` 中任一角色授予的权限。\n- `with_all` 为 false（默认）时只返回 `role_ids` 授予的权限——不传 `role_ids` 会得到空列表。\n- `permission_name`、`description`、`class` 随请求语言变化（`Accept-Language` 请求头，或 `locale`/`lang` 查询参数）。",
          "href": "/zh/api-reference/platform/roles-permissions/role-read-list-permission",
          "metadata": {
            "sidebarTitle": "查看角色权限集合"
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/RolePermissionListResponse"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                  "data": {
                    "items": [
                      {
                        "id": 501,
                        "permission_name": "Templates Read",
                        "permission_type": "read",
                        "description": "View notification templates",
                        "class": "On-call",
                        "scope": "on-call",
                        "status": "enabled",
                        "is_granted": true,
                        "source": "system"
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RolePermissionListRequest"
              },
              "example": {
                "role_ids": [
                  150
                ],
                "with_all": true
              }
            }
          }
        }
      }
    },
    "/team/info": {
      "post": {
        "operationId": "team-read-info",
        "summary": "查看团队详情",
        "description": "按 ID、名称或外部引用 ID 返回单个团队的详细信息。",
        "tags": [
          "平台/团队管理"
        ],
        "x-mint": {
          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `team_id`、`team_name`、`ref_id` 三者提供其一；同时传多个时，`ref_id` 优先于 `team_name`，`team_name` 优先于 `team_id`。\n- 按 `team_name` 或 `ref_id` 查找只匹配未删除的团队；按 `team_id` 查找时已删除的团队也会返回，`status` 为 `deleted`。\n- 找不到团队时返回 `400 InvalidParameter`。",
          "href": "/zh/api-reference/platform/teams/team-read-info",
          "metadata": {
            "sidebarTitle": "查看团队详情"
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/TeamItem"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                  "data": {
                    "account_id": 10023,
                    "team_id": 1001,
                    "team_name": "Backend SRE",
                    "description": "Backend reliability engineering team",
                    "status": "enabled",
                    "updated_by_name": "alice",
                    "updated_by": 80011,
                    "creator_id": 80011,
                    "creator_name": "",
                    "created_at": 1710000000,
                    "updated_at": 1712000000,
                    "person_ids": [
                      80011,
                      80012
                    ],
                    "ref_id": ""
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TeamInfoRequest"
              },
              "example": {
                "team_id": 1001
              }
            }
          }
        }
      }
    },
    "/team/delete": {
      "post": {
        "operationId": "team-write-delete",
        "summary": "删除团队",
        "description": "按 ID、名称或外部引用 ID 删除团队，并移除其全部成员。",
        "tags": [
          "平台/团队管理"
        ],
        "x-mint": {
          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **团队管理**（`organization`） |\n\n## 使用说明\n\n- `team_id`、`team_name`、`ref_id` 三者提供其一；同时传多个时依次以 `team_id`、`team_name`、`ref_id` 为准。\n- 除上述权限外，调用者还必须是团队成员、团队创建者、账户主体或拥有 Admin 角色，否则返回 `403 AccessDenied`。\n- 团队仍被分派策略、值班表、协作空间、通知模板、映射规则、服务日历或单点登录配置的默认团队引用时，返回 `400 ReferenceExist`，`data.refs` 列出每条引用（`kind`、`name`、`href`）。\n- 删除为软删除：团队成员全部移除，团队不再出现在列表和按名称/`ref_id` 的查找中，名称可以重新使用；按 `team_id` 调用 `POST /team/info` 仍能查到，`status` 为 `deleted`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
          "href": "/zh/api-reference/platform/teams/team-write-delete",
          "metadata": {
            "sidebarTitle": "删除团队"
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/PlatformEmptyObject"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                  "data": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TeamDeleteRequest"
              },
              "example": {
                "team_id": 1001
              }
            }
          }
        }
      }
    },
    "/role/info": {
      "post": {
        "operationId": "role-read-info",
        "summary": "查看角色详情",
        "description": "按角色 ID 返回单个角色的详细信息。",
        "tags": [
          "平台/角色与权限"
        ],
        "x-mint": {
          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- ID `2`、`6`、`8` 返回内置的 Admin、Responder、Viewer 角色，其 `description` 随请求语言变化。\n- 角色 ID 不存在或已删除时返回 `400 InvalidParameter`。",
          "href": "/zh/api-reference/platform/roles-permissions/role-read-info",
          "metadata": {
            "sidebarTitle": "查看角色详情"
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/RoleItem"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                  "data": {
                    "role_id": 2,
                    "role_name": "Admin",
                    "description": "Account Administrator, has all account permissions and can assist the main account in managing all affairs.",
                    "status": "enabled",
                    "permission_ids": [
                      101,
                      102,
                      201,
                      701
                    ],
                    "editable": false,
                    "created_at": 1653530940,
                    "updated_at": 1653530940
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RoleInfoRequest"
              },
              "example": {
                "role_id": 2
              }
            }
          }
        }
      }
    },
    "/member/invite": {
      "post": {
        "operationId": "memberInvite",
        "summary": "邀请成员",
        "description": "通过邮箱或手机号批量邀请新成员加入组织。",
        "tags": [
          "平台/成员管理"
        ],
        "x-mint": {
          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **成员管理**（`organization`） |\n\n## 使用说明\n\n- 每个条目需要提供 `email`，或同时提供 `member_name` 和 `phone`。\n- 邮箱或手机号已属于本账户成员的条目会被静默跳过；`items` 只列出本次新建的成员，一个都没有创建时为 `null`。\n- 新成员以 `pending` 状态创建，并通过邮件或短信收到邀请。\n- 邮箱以小写存储。账户限制了成员邮箱域名时，不在白名单内的地址返回 `400`；同一请求内邮箱或手机号重复也返回 `400`。\n- `country_code` 必须是 ISO 3166-1 alpha-2 地区代码（如 \"CN\"）；写入前校验并统一转为大写，非法值返回 400。\n- 当成员的 `phone` 不带 \"+\" 前缀时，按该成员的 `country_code` 作为地区提示解析（未传时默认 \"CN\"）。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
          "href": "/zh/api-reference/platform/members/member-invite",
          "metadata": {
            "sidebarTitle": "邀请成员"
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/MemberInviteResponse"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                  "data": {
                    "items": [
                      {
                        "member_id": 5068740052131,
                        "member_name": "Charlie"
                      },
                      {
                        "member_id": 5068740052132,
                        "member_name": "Dave"
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MemberInviteRequest"
              },
              "example": {
                "members": [
                  {
                    "member_name": "Charlie",
                    "email": "charlie@example.com",
                    "locale": "en-US",
                    "time_zone": "Asia/Shanghai",
                    "role_ids": [
                      6
                    ],
                    "schedule_id": 5789640530410
                  },
                  {
                    "member_name": "Dave",
                    "phone": "13800138000",
                    "country_code": "CN",
                    "locale": "zh-CN",
                    "time_zone": "Asia/Shanghai"
                  }
                ]
              }
            }
          }
        }
      }
    },
    "/role/enable": {
      "post": {
        "operationId": "role-write-enable",
        "summary": "启用角色",
        "description": "重新启用已被禁用的自定义角色。",
        "tags": [
          "平台/角色与权限"
        ],
        "x-mint": {
          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **角色管理**（`organization`） |\n\n## 使用说明\n\n- 只有 `disabled` 状态的角色可以启用；对已启用的角色调用会返回 `400 InvalidParameter`。\n- 内置角色（`2`、`6`、`8`）不能启用或禁用：调用返回 `400 InvalidParameter`（`Preset roles cannot be modified.`）。\n- 启用后，持有该角色的成员及其创建的 App Key 重新获得该角色的权限。\n- 角色 ID 不存在或已删除时不做任何操作，调用仍返回成功。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
          "href": "/zh/api-reference/platform/roles-permissions/role-write-enable",
          "metadata": {
            "sidebarTitle": "启用角色"
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/PlatformEmptyObject"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                  "data": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RoleIDRequest"
              },
              "example": {
                "role_id": 150
              }
            }
          }
        }
      }
    },
    "/role/list": {
      "post": {
        "operationId": "role-read-list",
        "summary": "查看角色列表",
        "description": "返回当前账户下所有自定义及内置角色。",
        "tags": [
          "平台/角色与权限"
        ],
        "x-mint": {
          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 自定义角色（含启用和禁用）排在前面，按 `orderby`/`asc` 排序；三个内置角色——`2` Admin、`6` Responder、`8` Viewer——追加在末尾（`no_global` 为 true 时不返回），并计入 `total`。\n- 内置角色的 `editable` 为 false，其 `description` 随请求语言变化（`Accept-Language` 请求头，或 `locale`/`lang` 查询参数）。",
          "href": "/zh/api-reference/platform/roles-permissions/role-read-list",
          "metadata": {
            "sidebarTitle": "查看角色列表"
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/RoleListResponse"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                  "data": {
                    "total": 4,
                    "items": [
                      {
                        "role_id": 150,
                        "role_name": "On-call Manager",
                        "description": "Manage on-call rotations and incidents.",
                        "status": "enabled",
                        "permission_ids": [
                          501,
                          502
                        ],
                        "editable": true,
                        "created_at": 1710000000,
                        "updated_at": 1712000000
                      },
                      {
                        "role_id": 2,
                        "role_name": "Admin",
                        "description": "Account Administrator, has all account permissions and can assist the main account in managing all affairs.",
                        "status": "enabled",
                        "permission_ids": [
                          101,
                          102,
                          201,
                          701
                        ],
                        "editable": false,
                        "created_at": 1653530940,
                        "updated_at": 1653530940
                      },
                      {
                        "role_id": 6,
                        "role_name": "Responder",
                        "description": "Responder, has standard permissions except billing center, member management, role management and single sign-on management, suitable for members handling daily operations.",
                        "status": "enabled",
                        "permission_ids": [
                          201,
                          701
                        ],
                        "editable": false,
                        "created_at": 1653530940,
                        "updated_at": 1653530940
                      },
                      {
                        "role_id": 8,
                        "role_name": "Viewer",
                        "description": "Viewer, has most read-only permissions except audit and onboarding, suitable for members who only need to view data.",
                        "status": "enabled",
                        "permission_ids": [
                          103
                        ],
                        "editable": false,
                        "created_at": 1653530940,
                        "updated_at": 1653530940
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RoleListRequest"
              },
              "example": {
                "orderby": "created_at",
                "asc": false
              }
            }
          }
        }
      }
    },
    "/member/info/reset": {
      "post": {
        "operationId": "memberResetInfo",
        "summary": "重置成员信息",
        "description": "通过成员标识定位成员，并重置指定资料字段。",
        "tags": [
          "平台/成员管理"
        ],
        "x-mint": {
          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 使用 `member_id`、`member_name`、`email`、`phone` 或 `ref_id` 中任一字段定位成员；如果同时传多个字段，服务端按上述顺序匹配。\n- 调用者必须是账户主体、该成员本人或拥有 Admin 角色，否则返回 `403 AccessDenied`。\n- `updates` 承载要写入的新资料，支持 `member_name`、`password`、`phone`、`country_code`、`email`、`avatar`、`locale`、`time_zone`、`ref_id`。省略或为 `null` 的字段保持原值；`updates` 至少要带一个字段。\n- 新的 `member_name`、`email`、`phone` 不能已属于本账户其他成员，冲突时返回 `400`。修改后的 `email` 或 `phone` 会被标记为未验证，除非 `from` 为 `api`、账户关闭了成员邀请，且被修改的成员不是调用者本人。\n- `updates.time_zone` 传空字符串会清除成员自己的时区，使其跟随账户时区。\n- `updates.country_code` 为 ISO 3166-1 alpha-2 地区代码（如 \"CN\"、\"US\"）。它是独立可更新字段：无需同时传 `updates.phone`，即使手机号不变也会写入新的地区代码；显式传空字符串会被拒绝（400）。\n- 当 `updates.phone` 不带 \"+\" 前缀时，按 `updates.country_code` 作为地区提示解析；未传时依次回退到成员已存的地区代码、默认值 \"CN\"。\"86\" 等数字电话区号仅在解析场景兼容，存储值一律为 ISO 地区代码。\n- 顶层的 `country_code` 仅作为定位用 `phone` 的解析提示，不会被存储。\n- 各字段逐个写入；若后面的字段校验失败，同一次调用中已写入的字段不会回滚。\n- 通过单点登录同步的成员，在单点登录配置将其设为不可编辑，或账户已无生效的单点登录配置时无法修改。\n- 同一账户内并发的资料更新或成员邀请可能返回 `429 RequestTooFrequently`，请稍后重试。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
          "href": "/zh/api-reference/platform/members/member-reset-info",
          "metadata": {
            "sidebarTitle": "重置成员信息"
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/MemberEmptyObject"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                  "data": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MemberResetInfoRequest"
              },
              "example": {
                "member_id": 2476444212131,
                "updates": {
                  "member_name": "Alice Chen",
                  "locale": "zh-CN",
                  "time_zone": "Asia/Shanghai"
                }
              }
            }
          }
        }
      }
    },
    "/audit/search": {
      "post": {
        "operationId": "audit-read-search",
        "summary": "检索审计日志",
        "description": "按时间范围返回游标分页的操作审计日志列表。",
        "tags": [
          "平台/审计日志"
        ],
        "x-mint": {
          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **审计查看**（`organization`） |\n\n## 使用说明\n\n- 必须指定时间范围，跨度最长 90 天。`start_time` 和 `end_time` 均为 Unix 时间戳（**秒**）。\n- 使用上一次响应中的 `search_after_ctx` 获取下一页。该游标是不透明的，请勿自行构造。\n- 可查询的保留期取决于账户的 License。超出保留期的查询会直接返回空结果，而不是报错。\n- 建议显式传 `limit`（1–99）以便稳定分页；不传或为 0 时由服务端决定每页条数，可能一次返回全部结果。结果按时间倒序返回。",
          "href": "/zh/api-reference/platform/audit-logs/audit-read-search",
          "metadata": {
            "sidebarTitle": "检索审计日志"
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/AuditSearchResponse"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                  "data": {
                    "total": 2,
                    "search_after_ctx": "",
                    "docs": [
                      {
                        "created_at": 1712700123456,
                        "account_id": 10023,
                        "member_id": 80011,
                        "member_name": "Alice",
                        "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                        "ip": "203.0.113.42",
                        "operation": "template:write:create",
                        "operation_name": "创建模板",
                        "body": "{\"template_name\":\"Prod default\"}",
                        "params": [],
                        "is_dangerous": false,
                        "is_write": true,
                        "principal_kind": "member",
                        "credential_type": "",
                        "credential_id": 0
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AuditSearchRequest"
              },
              "example": {
                "start_time": 1712620800,
                "end_time": 1712707200,
                "limit": 20,
                "operations": [
                  "template:write:create",
                  "template:write:delete"
                ]
              }
            }
          }
        }
      }
    },
    "/role/member/grant": {
      "post": {
        "operationId": "role-write-grant-role",
        "summary": "授予成员账户权限",
        "description": "将角色授予一个或多个成员，赋予其该角色包含的权限。",
        "tags": [
          "平台/角色与权限"
        ],
        "x-mint": {
          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **角色管理**（`organization`） |\n\n## 使用说明\n\n- `member_ids` 中的每个 ID 都必须是本账户成员且不能重复，否则返回 `400`，不修改任何人。\n- `role_id` 必须是内置角色或未删除的自定义角色（已禁用的角色也可以授予，但启用前不提供任何权限），否则返回 `400`。\n- 通过单点登录同步的成员，在单点登录配置将其设为不可编辑，或账户已无生效的单点登录配置时无法修改，调用返回 `400`。\n- 已持有该角色的成员保持不变。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
          "href": "/zh/api-reference/platform/roles-permissions/role-write-grant-role",
          "metadata": {
            "sidebarTitle": "授予成员账户权限"
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/PlatformEmptyObject"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                  "data": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RoleGrantRequest"
              },
              "example": {
                "member_ids": [
                  80011,
                  80012
                ],
                "role_id": 150
              }
            }
          }
        }
      }
    },
    "/member/role/update": {
      "post": {
        "operationId": "memberUpdateRole",
        "summary": "更新成员角色",
        "description": "用给定的角色集合整体替换成员的角色。",
        "tags": [
          "平台/成员管理"
        ],
        "x-mint": {
          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **成员管理**（`organization`） |\n\n## 使用说明\n\n- `role_ids` 为空或不传时，分配内置的 Viewer 角色（`8`）。\n- 不存在的角色 ID 会被丢弃；若给定的 ID 全部不存在，成员最终将没有任何角色。\n- 通过单点登录同步的成员，在单点登录配置将其设为不可编辑，或账户已无生效的单点登录配置时无法修改，调用返回 `400`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
          "href": "/zh/api-reference/platform/members/member-update-role",
          "metadata": {
            "sidebarTitle": "更新成员角色"
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/MemberEmptyObject"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                  "data": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MemberRoleUpdateRequest"
              },
              "example": {
                "member_id": 5068740052131,
                "role_ids": [
                  2,
                  6
                ]
              }
            }
          }
        }
      }
    },
    "/role/upsert": {
      "post": {
        "operationId": "role-write-upsert",
        "summary": "创建或更新角色",
        "description": "创建新的自定义角色或更新已有角色，更新时传入 `role_id`。",
        "tags": [
          "平台/角色与权限"
        ],
        "x-mint": {
          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **角色管理**（`organization`） |\n\n## 使用说明\n\n- 省略 `role_id`（或置为 0）表示创建角色，总是分配新的 ID。传入本账户自定义角色的 ID 表示更新；其他 ID 返回 `400 InvalidParameter`（`no role found by id`），内置角色 ID（`2`、`6`、`8`）返回 `400 InvalidParameter`（`Preset roles cannot be modified.`）。\n- `role_name` 在账户内必须唯一，也不能与内置名称 `Admin`、`Responder`、`Viewer` 重复；冲突时返回 `400`。\n- 更新会同时覆盖 `role_name`、`description`、`permission_ids`：不传 `description` 会清空描述，不传 `permission_ids` 会移除该角色的全部权限。\n- 更新已禁用的角色不会改变其状态，角色仍为禁用；如需启用请调用 `POST /role/enable`。\n- `permission_ids` 中的每个 ID 都必须是 `POST /role/permission/list`（`with_all: true`）返回的权限，否则返回 `400`，不做任何修改。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
          "href": "/zh/api-reference/platform/roles-permissions/role-write-upsert",
          "metadata": {
            "sidebarTitle": "创建或更新角色"
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/RoleUpsertResponse"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                  "data": {
                    "role_id": 150,
                    "role_name": "On-call Manager"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RoleUpsertRequest"
              },
              "example": {
                "role_name": "On-call Manager",
                "description": "Manage on-call rotations and incidents.",
                "permission_ids": [
                  501,
                  502
                ]
              }
            }
          }
        }
      }
    },
    "/role/permission/factor/list": {
      "post": {
        "operationId": "role-read-list-permission-factor",
        "summary": "查看权限因子集合",
        "description": "列出调用成员通过其角色获得的权限因子。",
        "tags": [
          "平台/角色与权限"
        ],
        "x-mint": {
          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 但对调用凭据有要求，见使用说明 |\n\n## 使用说明\n\n- 需要成员凭据：使用账户主体凭据调用会返回 `400 InvalidParameter`，因为账户主体天然拥有全部权限。\n- 权限因子来自调用成员持有的所有角色，并已去重；返回顺序不固定。没有角色的成员得到空数组。\n- `factor_types` 按类型过滤（`api`、`button`、`visit`、`menu`、`url`）；不传则返回全部类型。传入不支持的类型返回 `400`。",
          "href": "/zh/api-reference/platform/roles-permissions/role-read-list-permission-factor",
          "metadata": {
            "sidebarTitle": "查看权限因子集合"
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/PermissionFactorListResponse"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                  "data": [
                    {
                      "factor_name": "template:read:info",
                      "factor_type": "api",
                      "source": "system"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PermissionFactorListRequest"
              },
              "example": {
                "factor_types": [
                  "api"
                ]
              }
            }
          }
        }
      }
    },
    "/role/member/revoke": {
      "post": {
        "operationId": "role-write-revoke-role",
        "summary": "解除成员账户权限",
        "description": "从一个或多个成员处撤销角色授权。",
        "tags": [
          "平台/角色与权限"
        ],
        "x-mint": {
          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **角色管理**（`organization`） |\n\n## 使用说明\n\n- `member_ids` 中的每个 ID 都必须是本账户成员且不能重复，否则返回 `400`，不修改任何人。\n- `role_id` 必须是内置角色或未删除的自定义角色（已禁用的角色也可以），否则返回 `400`。\n- 通过单点登录同步的成员，在单点登录配置将其设为不可编辑，或账户已无生效的单点登录配置时无法修改，调用返回 `400`。\n- 未持有该角色的成员保持不变；解除成员的最后一个角色后，该成员将没有任何角色。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
          "href": "/zh/api-reference/platform/roles-permissions/role-write-revoke-role",
          "metadata": {
            "sidebarTitle": "解除成员账户权限"
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/PlatformEmptyObject"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                  "data": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RoleGrantRequest"
              },
              "example": {
                "member_ids": [
                  80011
                ],
                "role_id": 150
              }
            }
          }
        }
      }
    },
    "/audit/operation/list": {
      "post": {
        "operationId": "audit-read-operation-list",
        "summary": "查看事件类型列表",
        "description": "返回所有会记录到审计日志中的操作名称，可用于 `operations` 过滤参数。",
        "tags": [
          "平台/审计日志"
        ],
        "x-mint": {
          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **审计查看**（`organization`） |\n\n## 使用说明\n\n- 将响应中的 `name` 值作为 `POST /audit/search` 的 `operations` 过滤值。\n- `name_cn` 是控制台中显示的中文标签，不随请求语言变化；`name` 是用于过滤的稳定值。",
          "href": "/zh/api-reference/platform/audit-logs/audit-read-operation-list",
          "metadata": {
            "sidebarTitle": "查看事件类型列表"
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/AuditOperationListResponse"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                  "data": {
                    "items": [
                      {
                        "name": "template:write:create",
                        "name_cn": "创建模板"
                      },
                      {
                        "name": "template:write:delete",
                        "name_cn": "删除模板"
                      },
                      {
                        "name": "incident:write:acknowledge",
                        "name_cn": "认领故障"
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AuditOperationListRequest"
              },
              "example": {}
            }
          }
        }
      }
    },
    "/team/upsert": {
      "post": {
        "operationId": "team-write-upsert",
        "summary": "变更团队信息",
        "description": "创建新团队或更新已有团队，更新时传入 `team_id`。",
        "tags": [
          "平台/团队管理"
        ],
        "x-mint": {
          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **团队管理**（`organization`） |\n\n## 使用说明\n\n- 省略 `team_id`（或置为 0）表示创建团队；传入已有的 `team_id` 表示更新。`team_id` 找不到团队时返回 `400`。\n- `team_name` 在账户内的团队中必须唯一。名称已被其他团队使用时返回 `400`；但当 `team_id` 为 0 且 `reset_if_name_exist` 为 true 时，会更新该同名团队。\n- 成员列表总是整体替换：团队成员变为 `person_ids`、`emails`、`phones` 三者解析结果的并集。更新时三者都不传会清空所有成员。\n- 解析不到本账户成员（或账户主体）的条目会被静默丢弃，不会发出邀请。\n- 更新时 `description` 和 `ref_id` 也会被覆盖——不传即清空原值。\n- 更新团队时，调用者还必须是团队成员、团队创建者、账户主体或拥有 Admin 角色。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
          "href": "/zh/api-reference/platform/teams/team-write-upsert",
          "metadata": {
            "sidebarTitle": "变更团队信息"
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/TeamUpsertResponse"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                  "data": {
                    "team_id": 1001,
                    "team_name": "Backend SRE"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TeamUpsertRequest"
              },
              "example": {
                "team_name": "Backend SRE",
                "description": "Backend reliability engineering team",
                "person_ids": [
                  80011,
                  80012
                ]
              }
            }
          }
        }
      }
    },
    "/member/role/grant": {
      "post": {
        "operationId": "memberGrantRole",
        "summary": "授予成员角色",
        "description": "为成员在现有角色之外追加一个或多个角色。",
        "tags": [
          "平台/成员管理"
        ],
        "x-mint": {
          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **成员管理**（`organization`） |\n\n## 使用说明\n\n- 不存在的角色 ID 会被忽略；全部不存在时调用成功但不做任何修改。\n- 成员已持有的角色只保留一份，不会重复添加。\n- 通过单点登录同步的成员，在单点登录配置将其设为不可编辑，或账户已无生效的单点登录配置时无法修改，调用返回 `400`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
          "href": "/zh/api-reference/platform/members/member-grant-role",
          "metadata": {
            "sidebarTitle": "授予成员角色"
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/MemberEmptyObject"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                  "data": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MemberRoleGrantRequest"
              },
              "example": {
                "member_id": 5068740052131,
                "role_ids": [
                  6
                ]
              }
            }
          }
        }
      }
    },
    "/member/role/revoke": {
      "post": {
        "operationId": "memberRevokeRole",
        "summary": "解除成员角色",
        "description": "从成员的角色中移除一个或多个角色。",
        "tags": [
          "平台/成员管理"
        ],
        "x-mint": {
          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **成员管理**（`organization`） |\n\n## 使用说明\n\n- 不存在的角色 ID 会被忽略；全部不存在时调用成功但不做任何修改。\n- 解除全部角色后成员将没有任何角色，不会回退为 Viewer。\n- 通过单点登录同步的成员，在单点登录配置将其设为不可编辑，或账户已无生效的单点登录配置时无法修改，调用返回 `400`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
          "href": "/zh/api-reference/platform/members/member-revoke-role",
          "metadata": {
            "sidebarTitle": "解除成员角色"
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/MemberEmptyObject"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                  "data": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MemberRoleRevokeRequest"
              },
              "example": {
                "member_id": 5068740052131,
                "role_ids": [
                  6
                ]
              }
            }
          }
        }
      }
    },
    "/member/delete": {
      "post": {
        "operationId": "memberDelete",
        "summary": "删除成员",
        "description": "通过 ID、邮箱、手机号或名称从组织中移除成员。",
        "tags": [
          "平台/成员管理"
        ],
        "x-mint": {
          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **300 次/分钟**；**20 次/秒** |\n| 权限要求 | **成员管理**（`organization`） |\n\n## 使用说明\n\n- 使用任一查找字段定位成员；同时传多个时，按 `member_id`、`member_name`、`email`、`phone`、`ref_id` 的顺序取第一个非空字段。\n- 除非 `is_force` 为 true，成员仍属于某个团队、被分派策略直接指定或在值班表中时，调用返回 `400 ReferenceExist`，`data.refs` 列出每条引用。强制删除会跳过检查，且不会清理这些引用。\n- 删除为软删除：成员状态变为 `deleted`，释放其占用的 License 席位，并移除其单点登录身份关联。之后仍可通过 `POST /person/infos` 解析该成员。\n- 通过单点登录同步的成员，在单点登录配置将其设为不可编辑，或账户已无生效的单点登录配置时无法删除，调用返回 `400`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。",
          "href": "/zh/api-reference/platform/members/member-delete",
          "metadata": {
            "sidebarTitle": "删除成员"
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/MemberEmptyObject"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                  "data": {}
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MemberDeleteRequest"
              },
              "example": {
                "member_id": 5068740052131
              }
            }
          }
        }
      }
    },
    "/member/list": {
      "post": {
        "operationId": "memberList",
        "summary": "查询成员列表",
        "description": "返回组织成员的分页列表。",
        "tags": [
          "平台/成员管理"
        ],
        "x-mint": {
          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 返回 `enabled` 或 `pending` 状态的成员。已删除的成员和账户主体不会出现在列表中，可用 `POST /person/infos` 解析其 ID。\n- `role_id` 返回持有该角色的成员；`member_id` 最多返回该成员一人。",
          "href": "/zh/api-reference/platform/members/member-list",
          "metadata": {
            "sidebarTitle": "查询成员列表"
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/MemberListResponse"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                  "data": {
                    "p": 1,
                    "limit": 5,
                    "total": 148,
                    "items": [
                      {
                        "account_id": 2451002751131,
                        "member_id": 5068740052131,
                        "member_name": "Bob",
                        "country_code": "",
                        "phone": "+86151****6519",
                        "email": "bob@example.com",
                        "phone_verified": true,
                        "email_verified": true,
                        "avatar": "",
                        "status": "enabled",
                        "account_role_ids": [
                          2,
                          6
                        ],
                        "created_at": 1752030749,
                        "updated_at": 1775962064,
                        "ref_id": "",
                        "is_external": false
                      },
                      {
                        "account_id": 2451002751131,
                        "member_id": 2476444212131,
                        "member_name": "Alice",
                        "country_code": "CN",
                        "phone": "+86185****0300",
                        "email": "alice@example.com",
                        "phone_verified": true,
                        "email_verified": true,
                        "avatar": "/image/avatar1.png",
                        "status": "enabled",
                        "account_role_ids": [
                          6
                        ],
                        "created_at": 1701399971,
                        "updated_at": 1775809507,
                        "ref_id": "",
                        "is_external": false
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MemberListRequest"
              },
              "example": {
                "p": 1,
                "limit": 5
              }
            }
          }
        }
      }
    },
    "/account/info": {
      "post": {
        "summary": "查看主体信息",
        "description": "返回当前主体（账户）的基本信息与设置。",
        "operationId": "account-read-info",
        "tags": [
          "平台/账户设置"
        ],
        "security": [
          {
            "AppKeyAuth": []
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "example": {}
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/AccountInfo"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                  "data": {
                    "account_id": 1001,
                    "account_name": "acme",
                    "domain": "acme",
                    "extra_domains": [
                      "acme-corp"
                    ],
                    "phone": "138****8000",
                    "country_code": "CN",
                    "email": "ops@acme.example",
                    "avatar": "https://example.com/avatar/acme.png",
                    "locale": "zh-CN",
                    "time_zone": "Asia/Shanghai",
                    "created_at": 1716960000,
                    "restrictions": {
                      "ips": [
                        "203.0.113.0/24"
                      ],
                      "email_domains": [
                        "acme.example"
                      ],
                      "allow_subdomain": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-mint": {
          "metadata": {
            "sidebarTitle": "查看主体信息"
          },
          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 但对调用凭据有要求，见使用说明 |\n\n## 使用说明\n\n- 需要账户主体的凭据（如账户主体创建的 App Key）；使用成员凭据调用会返回 `401 Unauthorized`。成员可改用 `POST /member/info`。\n- `restrictions` 仅在配置过加入限制或访问限制时返回；`mp_plat`、`mp_account_id` 仅对通过云市场开通的账户返回。",
          "href": "/zh/api-reference/platform/account/account-read-info"
        }
      }
    },
    "/member/notify": {
      "post": {
        "operationId": "memberNotify",
        "summary": "通知成员",
        "description": "以调用方 AI SRE 会话的身份，向账户成员发送其撰写的邮件。",
        "tags": [
          "平台/成员管理"
        ],
        "x-mint": {
          "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **200 次/分钟**；**10 次/秒** |\n| 权限要求 | 无 —— 但对调用凭据有要求，见使用说明 |\n\n## 使用说明\n\n- 仅可使用 AI SRE 会话凭据调用；使用其他凭据调用会返回 `AccessDenied`。\n- 邮件投递是异步的——`accepted` 表示邮件已入队，并不代表已送达。\n- 不是调用方账户内活跃成员、或没有邮箱地址的收件人会被跳过，不会导致整个请求失败。\n- 是否发送邮件取决于每个收件人针对此类消息的通知偏好设置；未设置偏好的收件人默认会收到邮件。\n- 收件人收到的邮件正文就是清洗后的 `html`，平台不会在其前后添加可见内容；发件人名称显示为调用方姓名加“(via AI SRE)”。\n- 发送前，服务端会检查提交的 `html`，如果其中包含移除后会改变收件人所见内容的构造（`<style>`、`<svg>`、`<iframe>`、`<object>`、`<embed>`、`<form>`、`<input>`、`<button>`、`src` 缺失或不是 `https` 的 `<img>`，或 href 不属于 `http`/`https`/`mailto` 的 `<a>`），会返回 `400` / `InvalidParameter` 并拒绝请求；错误消息会逐一列出触发的构造及需要如何修改，且不会入队——不占用每小时限额，也不占用同轮次去重。不影响渲染效果的标签（`<script>`、`<meta>`、`<link>`、`<base>`、`on*` 事件属性）仍会被静默清洗，不会触发拒绝。\n- 同一收件人通过该接口每小时最多收到 20 封邮件；超出后同一窗口内该收件人的后续投递会被跳过并返回 `rate_limited`。\n- 在同一个 AI SRE 会话轮次内重复调用，不会向已收到邮件的收件人重复发送；重复的收件人会被跳过并返回 `duplicate`。",
          "href": "/zh/api-reference/platform/members/member-notify",
          "metadata": {
            "sidebarTitle": "通知成员"
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/MemberNotifyResponse"
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                  "data": {
                    "recipients": [
                      {
                        "person_id": 5068740052131,
                        "status": "accepted"
                      },
                      {
                        "person_id": 5068740052132,
                        "status": "skipped",
                        "reason": "email_disabled"
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "description": "提交的 `html` 中包含移除后会改变收件人所见内容的构造（完整列表见 `html` 字段的描述），请求会被拒绝而不是静默移除，且不会入队。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                  "error": {
                    "code": "InvalidParameter",
                    "message": "email html contains 2 construct(s) the sanitizer removes, which would change what recipients see. Fix and send again: <style> x2 - move these rules into inline style=\"...\" attributes; <img> without an https src x3 - host the image over https, or drop it"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MemberNotifyRequest"
              },
              "example": {
                "person_ids": [
                  5068740052131,
                  5068740052132
                ],
                "subject": "Incident 20260914-1 needs your input",
                "html": "<p>Can you confirm the rollback window?</p>"
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "AppKeyAuth": {
        "type": "apiKey",
        "in": "query",
        "name": "app_key",
        "description": "在 Flashduty 控制台 我的 → APP Key 中创建的 APP Key。可通过 query 参数 `app_key` 或请求头 `Fd-App-Key` 传入。实际可访问范围是该 APP Key 的权限范围与创建者当前角色权限的交集，请妥善保管。"
      }
    },
    "responses": {
      "BadRequest": {
        "description": "请求非法 — 通常是参数缺失或格式不正确。",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "missingParameter": {
                "value": {
                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                  "error": {
                    "code": "InvalidParameter",
                    "message": "The specified parameter is not valid."
                  }
                }
              }
            }
          }
        }
      },
      "Unauthorized": {
        "description": "app_key 缺失或无效。",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "missingAppKey": {
                "value": {
                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                  "error": {
                    "code": "Unauthorized",
                    "message": "You are unauthorized."
                  }
                }
              }
            }
          }
        }
      },
      "Forbidden": {
        "description": "app_key 有效，但其权限范围或创建者角色不允许该操作或该对象。",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "noEditPermission": {
                "value": {
                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                  "error": {
                    "code": "AccessDenied",
                    "message": "Access Denied."
                  }
                }
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "目标资源不存在或已被删除。注意：Flashduty 对业务实体的缺失通常返回 HTTP 400 + code=`ResourceNotFound`，真正的 404 只用于未知路由。",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "resourceMissing": {
                "value": {
                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                  "error": {
                    "code": "ResourceNotFound",
                    "message": "The resource you request is not found"
                  }
                }
              }
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "触发频率限制。请等待响应头 `Flashcat-Request-Rate-Limit-Delay` 给出的秒数后重试。",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "rateLimited": {
                "value": {
                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                  "error": {
                    "code": "RequestTooFrequently",
                    "message": "Request too frequently."
                  }
                }
              }
            }
          }
        },
        "headers": {
          "Flashcat-Request-Rate-Limit-Delay": {
            "description": "距当前限流窗口重置的秒数。请求被网关全局保护限流拒绝时不返回该响应头。",
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          }
        }
      },
      "ServerError": {
        "description": "服务端未预期错误。反馈问题时请携带 request_id。",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "internal": {
                "value": {
                  "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
                  "error": {
                    "code": "InternalError",
                    "message": "We encountered an internal error, and it has been reported. Please try again later."
                  }
                }
              }
            }
          }
        }
      }
    },
    "schemas": {
      "AuditLog": {
        "type": "object",
        "description": "单条审计日志。",
        "required": [
          "created_at",
          "account_id",
          "member_id",
          "member_name",
          "request_id",
          "ip",
          "operation",
          "operation_name",
          "body",
          "params",
          "is_dangerous",
          "is_write",
          "principal_kind",
          "credential_type",
          "credential_id"
        ],
        "properties": {
          "created_at": {
            "type": "integer",
            "format": "int64",
            "description": "操作时间，Unix 毫秒时间戳。"
          },
          "account_id": {
            "type": "integer",
            "format": "uint64",
            "description": "该条记录所属账户的 ID。"
          },
          "member_id": {
            "type": "integer",
            "format": "uint64",
            "description": "执行操作的成员 ID。由账户主体（owner）亲自执行时为 0。"
          },
          "member_name": {
            "type": "string",
            "description": "成员显示名称。`member_id` 为 0 时为空字符串。"
          },
          "request_id": {
            "type": "string",
            "description": "用于关联的唯一请求 ID。"
          },
          "ip": {
            "type": "string",
            "description": "调用者的客户端 IP 地址。"
          },
          "operation": {
            "type": "string",
            "description": "稳定的机器可读操作名称，如 `template:write:create`。"
          },
          "operation_name": {
            "type": "string",
            "description": "操作的可读中文名称（如 `创建模板`）。"
          },
          "body": {
            "type": "string",
            "description": "JSON 编码的请求体。包含敏感字段时整体改为 base64url 编码存储；超过 10 KB 时以截断占位说明替代。"
          },
          "params": {
            "type": [
              "array",
              "string"
            ],
            "items": {
              "type": "object",
              "properties": {
                "Key": {
                  "type": "string",
                  "description": "URL 路径参数名（路由中 `:xxx` 占位符的名称）。"
                },
                "Value": {
                  "type": "string",
                  "description": "该路径参数在本次请求中的实际取值。"
                }
              }
            },
            "description": "URL 路径参数，为 `Key`/`Value` 键值对数组（没有时为空数组）。部分部署形态会以 JSON 编码的字符串形式返回同一数组。"
          },
          "is_dangerous": {
            "type": "boolean",
            "description": "是否被标记为高危操作。"
          },
          "is_write": {
            "type": "boolean",
            "description": "是否为写操作；false 表示只读操作。"
          },
          "principal_kind": {
            "type": "string",
            "enum": [
              "member",
              "service"
            ],
            "description": "调用方类型。`member`——成员或账户主体的会话；`service`——App Key，或签发给 AI SRE 的短期密钥。"
          },
          "credential_type": {
            "type": "string",
            "description": "调用使用的凭据类型。控制台长期有效的 App Key 为 `app_key`，AI SRE 签发的短期 Key 为 `ephemeral_app_key`，成员会话为空字符串。"
          },
          "credential_id": {
            "type": "integer",
            "format": "uint64",
            "description": "凭据 ID（App Key 的 ID）；`credential_type` 非 `app_key` 时为 0。"
          }
        }
      },
      "AuditOperationListRequest": {
        "type": "object",
        "description": "不需要任何参数。",
        "additionalProperties": false
      },
      "AuditOperationListResponse": {
        "type": "object",
        "description": "可审计操作类型列表。",
        "required": [
          "items"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AuditOperationTypeItem"
            },
            "description": "所有可审计操作类型的数组（仅含标记为需审计的 API），始终为数组，可能为空。"
          }
        }
      },
      "AuditOperationTypeItem": {
        "type": "object",
        "description": "一条可审计的操作类型。",
        "required": [
          "name",
          "name_cn"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "用于过滤的稳定机器可读操作名称。",
            "example": "template:write:create"
          },
          "name_cn": {
            "type": "string",
            "description": "控制台显示的中文标签。",
            "example": "创建模板"
          }
        }
      },
      "AuditSearchRequest": {
        "type": "object",
        "description": "审计日志检索的过滤条件，时间范围必填。",
        "required": [
          "start_time",
          "end_time"
        ],
        "properties": {
          "start_time": {
            "type": "integer",
            "format": "int64",
            "description": "检索窗口起点，Unix 秒级时间戳（不含该秒本身）。",
            "example": 1712620800,
            "minimum": 1
          },
          "end_time": {
            "type": "integer",
            "format": "int64",
            "description": "检索窗口终点，Unix 秒级时间戳（含该秒）。必须大于 `start_time`，最大跨度 90 天。",
            "example": 1712707200,
            "minimum": 1
          },
          "limit": {
            "type": "integer",
            "description": "每页条数，0–99。不传或为 0 时由服务端决定每页条数（可能返回全部匹配条目）。",
            "minimum": 0,
            "maximum": 99,
            "example": 20
          },
          "request_id": {
            "type": "string",
            "description": "按唯一请求 ID 过滤到单条记录。"
          },
          "search_after_ctx": {
            "type": "string",
            "description": "上次响应返回的不透明分页游标。首页留空。"
          },
          "operations": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "按操作名称过滤。合法值可通过 `POST /audit/operation/list` 获取。"
          },
          "person_id": {
            "type": "integer",
            "format": "uint64",
            "description": "按操作人过滤，取成员 ID（可通过 `POST /member/list` 获取）；传账户 ID 则匹配账户主体自身的操作。"
          },
          "is_dangerous": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "为 true 时只返回高危操作。"
          },
          "is_write": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "为 true 时只返回写操作；为 false 时只返回读操作。"
          }
        }
      },
      "AuditSearchResponse": {
        "type": "object",
        "description": "游标分页的审计日志检索结果。",
        "required": [
          "total",
          "search_after_ctx"
        ],
        "properties": {
          "total": {
            "type": "integer",
            "format": "int64",
            "description": "检索窗口内符合条件的总条数。",
            "example": 2
          },
          "search_after_ctx": {
            "type": "string",
            "description": "用于获取下一页的不透明游标。没有更多结果时为空字符串。"
          },
          "docs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AuditLog"
            },
            "description": "本页的审计日志，按时间倒序。本页为空时不返回。"
          }
        }
      },
      "DutyError": {
        "type": "object",
        "description": "响应结构中的错误 payload，仅在非 2xx 响应时出现。",
        "properties": {
          "code": {
            "$ref": "#/components/schemas/ErrorCode"
          },
          "message": {
            "type": "string",
            "description": "按响应语言（query 参数 `locale` / `lang` 或请求头 `Accept-Language`）返回的错误描述，可能包含出错的字段名，请不要解析它。",
            "example": "The specified parameter template_id is not valid."
          }
        },
        "required": [
          "code",
          "message"
        ]
      },
      "ErrorCode": {
        "type": "string",
        "description": "错误码。所有失败响应都会把 `error.code` 设为下列稳定字符串之一，请以它而不是 HTTP 状态码做判断。\n\n| 错误码 | HTTP | 含义 |\n|---|---|---|\n| `OK` | 200 | 保留值，失败的请求不会返回。 |\n| `InvalidParameter` | 400 | 参数缺失、类型错误或未通过校验，`message` 通常会指出字段名。 |\n| `BadRequest` | 400 | 请求违反业务规则或与对象当前状态冲突，`message` 会说明原因。 |\n| `InvalidContentType` | 400 | 请求体没有以 `application/json` 发送。 |\n| `ResourceNotFound` | 400 | 引用的对象在本账户中不存在或已删除。注意 HTTP 状态码是 400 而不是 404。 |\n| `NoLicense` | 400 | 账户套餐不包含该功能、套餐配额已用完、套餐已过期或额度不足。 |\n| `ReferenceExist` | 400 | 对象仍被其他对象引用，无法删除。 |\n| `Unauthorized` | 401 | APP Key 缺失、无效或已删除。 |\n| `BalanceNotEnough` | 402 | 仅用于控制台计费流程，Open API 接口不会返回。 |\n| `AccessDenied` | 403 | APP Key 的权限范围或创建者角色不允许该操作或该对象。 |\n| `RouteNotFound` | 404 | 没有与该 HTTP 方法和路径匹配的接口。 |\n| `MethodNotAllowed` | 405 | 路径存在，但不支持该 HTTP 方法。 |\n| `UndonedOrderExist` | 409 | 仅用于控制台计费流程，Open API 接口不会返回。 |\n| `EntityTooLarge` | 413 | 请求体超出大小限制。 |\n| `RequestLocked` | 423 | 仅用于控制台登录保护，Open API 接口不会返回。 |\n| `RequestVerifyRequired` | 428 | 仅用于控制台验证码流程，Open API 接口不会返回。 |\n| `DangerousOperation` | 428 | 仅用于控制台高风险操作的 MFA 校验，Open API 接口不会返回。 |\n| `RequestTooFrequently` | 429 | 触发频率限制；请等待响应头 `Flashcat-Request-Rate-Limit-Delay` 给出的秒数后再重试。 |\n| `InternalError` | 500 | 服务端意外错误；请退避后重试，反馈问题时附上 `request_id`。 |\n| `ServiceUnavailable` | 503 | 后端依赖过载或不可用，请退避后重试。 |",
        "enum": [
          "OK",
          "InvalidParameter",
          "BadRequest",
          "InvalidContentType",
          "ResourceNotFound",
          "NoLicense",
          "ReferenceExist",
          "Unauthorized",
          "BalanceNotEnough",
          "AccessDenied",
          "RouteNotFound",
          "MethodNotAllowed",
          "UndonedOrderExist",
          "EntityTooLarge",
          "RequestLocked",
          "RequestVerifyRequired",
          "DangerousOperation",
          "RequestTooFrequently",
          "InternalError",
          "ServiceUnavailable"
        ],
        "x-enumDescriptions": {
          "OK": "保留值，失败的请求不会返回。",
          "InvalidParameter": "参数缺失、类型错误或未通过校验，`message` 通常会指出字段名。",
          "BadRequest": "请求违反业务规则或与对象当前状态冲突，`message` 会说明原因。",
          "InvalidContentType": "请求体没有以 `application/json` 发送。",
          "ResourceNotFound": "引用的对象在本账户中不存在或已删除。注意 HTTP 状态码是 400 而不是 404。",
          "NoLicense": "账户套餐不包含该功能、套餐配额已用完、套餐已过期或额度不足。",
          "ReferenceExist": "对象仍被其他对象引用，无法删除。",
          "Unauthorized": "APP Key 缺失、无效或已删除。",
          "BalanceNotEnough": "仅用于控制台计费流程，Open API 接口不会返回。",
          "AccessDenied": "APP Key 的权限范围或创建者角色不允许该操作或该对象。",
          "RouteNotFound": "没有与该 HTTP 方法和路径匹配的接口。",
          "MethodNotAllowed": "路径存在，但不支持该 HTTP 方法。",
          "UndonedOrderExist": "仅用于控制台计费流程，Open API 接口不会返回。",
          "EntityTooLarge": "请求体超出大小限制。",
          "RequestLocked": "仅用于控制台登录保护，Open API 接口不会返回。",
          "RequestVerifyRequired": "仅用于控制台验证码流程，Open API 接口不会返回。",
          "DangerousOperation": "仅用于控制台高风险操作的 MFA 校验，Open API 接口不会返回。",
          "RequestTooFrequently": "触发频率限制；请等待响应头 `Flashcat-Request-Rate-Limit-Delay` 给出的秒数后再重试。",
          "InternalError": "服务端意外错误；请退避后重试，反馈问题时附上 `request_id`。",
          "ServiceUnavailable": "后端依赖过载或不可用，请退避后重试。"
        },
        "example": "InvalidParameter"
      },
      "ErrorResponse": {
        "type": "object",
        "description": "错误响应结构。`error` 必填，`data` 不存在。",
        "properties": {
          "request_id": {
            "type": "string",
            "example": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
            "description": "本次请求的唯一追踪 ID（trace ID），反馈问题时请提供该值以便检索日志。"
          },
          "error": {
            "$ref": "#/components/schemas/DutyError"
          }
        },
        "required": [
          "request_id",
          "error"
        ]
      },
      "InviteMemberItem": {
        "type": "object",
        "description": "待邀请的成员。只需提供 `email`，或同时提供 `member_name` 与 `phone`。",
        "properties": {
          "member_name": {
            "type": "string",
            "minLength": 2,
            "maxLength": 39,
            "description": "显示名称，2–39 个字符。未提供 `email` 时必填；省略时取邮箱前缀作为名称。"
          },
          "email": {
            "type": "string",
            "description": "邮箱地址，以小写存储。未提供 `phone` 时必填。"
          },
          "phone": {
            "type": "string",
            "description": "手机号。未提供 `email` 时必填。"
          },
          "country_code": {
            "type": "string",
            "description": "`phone` 的 ISO 3166-1 alpha-2 地区代码（如 \"CN\"）；写入前校验并统一转为大写，非法值返回 400。当 `phone` 不带 \"+\" 前缀时兼作解析提示（未传时默认 \"CN\"）。"
          },
          "role_ids": {
            "type": "array",
            "items": {
              "type": "integer",
              "format": "uint64"
            },
            "description": "要分配的角色 ID：内置的 `2`（Admin）、`6`（Responder）、`8`（Viewer），或 `POST /role/list` 中的自定义角色 ID。不传时默认为 Viewer（`8`）；不存在的 ID 返回 `400`。"
          },
          "locale": {
            "type": "string",
            "enum": [
              "zh-CN",
              "en-US"
            ],
            "description": "语言：`zh-CN`（简体中文）或 `en-US`（英文），其他值返回 400。不传时使用账户的语言设置。"
          },
          "time_zone": {
            "type": "string",
            "description": "IANA 时区名称，如 `Asia/Shanghai`。不传则成员跟随账户时区；名称无效时返回 `400`。"
          },
          "ref_id": {
            "type": "string",
            "description": "外部引用 ID（如 HR 系统中的员工号），之后可在 `POST /member/delete`、`POST /member/info/reset` 中作为查找键。"
          },
          "schedule_id": {
            "type": "integer",
            "format": "uint64",
            "description": "成员创建或接受邀请后要加入的值班排班 ID。加入动作以调用方身份执行；调用方无权编辑排班、排班已删除或没有可加入的层级时，邀请仍会成功，但成员不会加入该排班。不传表示邀请不带排班。"
          }
        }
      },
      "MemberDeleteRequest": {
        "type": "object",
        "description": "删除成员请求（提供其中一个查找字段）",
        "properties": {
          "member_id": {
            "type": "integer",
            "format": "uint64",
            "description": "成员 ID。同时提供多个查找字段时，按 `member_id` > `member_name` > `email` > `phone` > `ref_id` 的优先级取第一个非空值"
          },
          "member_name": {
            "type": "string",
            "description": "成员名称。仅在未提供 `member_id` 时生效"
          },
          "email": {
            "type": "string",
            "description": "邮箱地址。仅在 `member_id`、`member_name` 均未提供时生效"
          },
          "phone": {
            "type": "string",
            "description": "手机号。仅在 `member_id`、`member_name`、`email` 均未提供时生效"
          },
          "country_code": {
            "type": "string",
            "description": "当 `phone` 不带 \"+\" 前缀时的解析地区提示 —— ISO 3166-1 alpha-2 地区代码（如 \"CN\"，未传时默认 \"CN\"）。此解析场景仍兼容 \"86\" 等数字电话区号。"
          },
          "ref_id": {
            "type": "string",
            "description": "外部引用 ID。仅在其他查找字段均未提供时生效"
          },
          "is_force": {
            "type": "boolean",
            "description": "跳过引用检查。为 false（默认）时，若成员属于某个团队、被分派策略指定或在值班表中，调用返回 `ReferenceExist`。强制删除不会移除这些引用。",
            "default": false
          }
        },
        "anyOf": [
          {
            "required": [
              "member_id"
            ]
          },
          {
            "required": [
              "member_name"
            ]
          },
          {
            "required": [
              "email"
            ]
          },
          {
            "required": [
              "phone"
            ]
          },
          {
            "required": [
              "ref_id"
            ]
          }
        ]
      },
      "MemberEmptyObject": {
        "type": "object",
        "description": "空响应",
        "properties": {}
      },
      "MemberInfoRequest": {
        "type": "object",
        "description": "获取成员信息请求",
        "properties": {}
      },
      "MemberInfoResponse": {
        "type": "object",
        "description": "当前成员资料",
        "properties": {
          "account_id": {
            "type": "integer",
            "format": "uint64",
            "description": "成员所属账户的 ID。"
          },
          "account_name": {
            "type": "string",
            "description": "账户（组织）名称。"
          },
          "account_avatar": {
            "type": "string",
            "description": "账户头像 URL"
          },
          "account_email": {
            "type": "string",
            "description": "账户主体的联系邮箱。"
          },
          "account_role_ids": {
            "type": "array",
            "items": {
              "type": "integer",
              "format": "uint64"
            },
            "description": "成员被分配的角色 ID，可通过 `POST /role/list` 解析。"
          },
          "account_locale": {
            "type": "string",
            "description": "账户级语言偏好（如 zh-CN、en-US）。账户未设置时不返回。"
          },
          "account_time_zone": {
            "type": "string",
            "description": "账户设置的 IANA 时区；账户未设置时为空字符串。始终返回。"
          },
          "resolved_time_zone": {
            "type": "string",
            "description": "实际生效的时区：成员的 `time_zone` 有效时取它，否则取账户时区，再否则为 `Asia/Shanghai`。始终返回。"
          },
          "domain": {
            "type": "string",
            "description": "账户域名，即登录控制台所用的子域名。"
          },
          "member_id": {
            "type": "integer",
            "format": "uint64",
            "description": "调用成员的 ID。"
          },
          "member_name": {
            "type": "string",
            "description": "成员显示名称"
          },
          "phone": {
            "type": "string",
            "description": "脱敏手机号"
          },
          "phone_verified": {
            "type": "boolean",
            "description": "手机号是否已验证"
          },
          "email": {
            "type": "string",
            "description": "邮箱地址"
          },
          "email_verified": {
            "type": "boolean",
            "description": "邮箱是否已验证"
          },
          "country_code": {
            "type": "string",
            "description": "成员联系手机的 ISO 3166-1 alpha-2 地区代码（如 \"CN\"、\"US\"、\"HK\"）。"
          },
          "avatar": {
            "type": "string",
            "description": "成员头像 URL"
          },
          "locale": {
            "type": "string",
            "description": "成员语言偏好。成员未设置时不返回。"
          },
          "time_zone": {
            "type": "string",
            "description": "成员自己设置的 IANA 时区；跟随账户时区时为空字符串。始终返回。"
          },
          "is_external": {
            "type": "boolean",
            "description": "是否通过 SSO 创建"
          },
          "created_at": {
            "type": "integer",
            "format": "int64",
            "description": "成员创建时间，Unix 秒级时间戳。"
          },
          "mp_plat": {
            "type": "string",
            "description": "账户开通来源的云市场：`aws`——AWS Marketplace。账户并非来自云市场时省略。",
            "enum": [
              "aws"
            ]
          },
          "mp_account_id": {
            "type": "string",
            "description": "账户在云市场平台上的标识。与 `mp_plat` 一起省略。"
          }
        },
        "required": [
          "account_id",
          "account_name",
          "account_avatar",
          "account_email",
          "account_role_ids",
          "domain",
          "member_id",
          "member_name",
          "phone",
          "phone_verified",
          "email",
          "email_verified",
          "country_code",
          "avatar",
          "is_external",
          "created_at",
          "time_zone",
          "account_time_zone",
          "resolved_time_zone"
        ]
      },
      "MemberInviteRequest": {
        "type": "object",
        "description": "邀请成员请求",
        "required": [
          "members"
        ],
        "properties": {
          "members": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/InviteMemberItem"
            },
            "description": "单次邀请的成员列表，至少 1 个。每个成员要么提供 `email`，要么同时提供 `member_name` 和 `phone`。",
            "minItems": 1
          },
          "from": {
            "type": "string",
            "description": "邀请来源。仅当账户已关闭成员邀请且值为 `api` 时生效：直接创建已激活成员并将邮箱/手机标记为已验证，不发送邀请；其他取值按正常邀请流程处理"
          }
        }
      },
      "MemberInviteResponse": {
        "type": "object",
        "description": "邀请成员响应",
        "properties": {
          "items": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/NewMemberItem"
            },
            "description": "本次新建的成员；因已存在而跳过的条目不会列出。一个都没有创建时为 `null`。"
          }
        }
      },
      "MemberItem": {
        "type": "object",
        "description": "成员条目",
        "required": [
          "account_id",
          "member_id",
          "member_name",
          "country_code",
          "phone",
          "email",
          "phone_verified",
          "email_verified",
          "avatar",
          "status",
          "account_role_ids",
          "created_at",
          "updated_at",
          "ref_id",
          "is_external"
        ],
        "properties": {
          "account_id": {
            "type": "integer",
            "format": "uint64",
            "description": "成员所属账户的 ID。"
          },
          "member_id": {
            "type": "integer",
            "format": "uint64",
            "description": "成员 ID；在其他接口中同一值即人员 ID（如 `person_ids`）。"
          },
          "member_name": {
            "type": "string",
            "description": "显示名称，在账户内唯一。"
          },
          "country_code": {
            "type": "string",
            "description": "成员联系手机的 ISO 3166-1 alpha-2 地区代码（如 \"CN\"、\"US\"、\"HK\"）。"
          },
          "phone": {
            "type": "string",
            "description": "E.164 格式的手机号，中间几位已打码（如 `+86151****6519`）；未设置时为空字符串。"
          },
          "email": {
            "type": "string",
            "description": "邮箱地址（小写）；未设置时为空字符串。"
          },
          "locale": {
            "type": "string",
            "description": "语言偏好。`POST /member/list` 不填充该字段，因此始终省略。"
          },
          "time_zone": {
            "type": "string",
            "description": "成员自己设置的 IANA 时区（如 `Asia/Shanghai`）。未设置时省略，表示跟随账户时区；生效时区可通过 `POST /member/info` 获取。"
          },
          "phone_verified": {
            "type": "boolean",
            "description": "成员已验证手机号时为 `true`。"
          },
          "email_verified": {
            "type": "boolean",
            "description": "成员已验证邮箱时为 `true`。"
          },
          "avatar": {
            "type": "string",
            "description": "头像图片 URL 或路径；未设置时为空字符串。"
          },
          "status": {
            "type": "string",
            "enum": [
              "enabled",
              "pending"
            ],
            "description": "成员状态。`enabled`——正常成员；`pending`——已邀请但尚未接受。已删除的成员不会列出。"
          },
          "account_role_ids": {
            "type": "array",
            "items": {
              "type": "integer",
              "format": "uint64"
            },
            "description": "成员被分配的角色 ID：内置的 `2`（Admin）、`6`（Responder）、`8`（Viewer），或 `POST /role/list` 中的自定义角色 ID。"
          },
          "is_external": {
            "type": "boolean",
            "description": "成员通过单点登录同步创建（而非邀请或注册）时为 `true`。"
          },
          "ref_id": {
            "type": "string",
            "description": "外部引用 ID（如 HR 系统中的员工号）；未设置时为空字符串。"
          },
          "created_at": {
            "type": "integer",
            "format": "int64",
            "description": "创建时间（Unix 秒）"
          },
          "updated_at": {
            "type": "integer",
            "format": "int64",
            "description": "更新时间（Unix 秒）"
          }
        }
      },
      "MemberListRequest": {
        "type": "object",
        "description": "查询成员列表请求",
        "properties": {
          "role_id": {
            "type": "integer",
            "format": "uint64",
            "description": "按角色 ID 过滤，角色 ID 可通过 `POST /role/list` 获取（内置角色：2=Admin、6=Responder、8=Viewer）"
          },
          "member_id": {
            "type": "integer",
            "format": "uint64",
            "description": "按成员 ID 过滤，仅返回该成员。"
          },
          "p": {
            "type": "integer",
            "minimum": 1,
            "description": "页码，从 1 开始。默认第一页。"
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "description": "每页条数，省略或传 0 时服务端默认 100",
            "default": 100
          },
          "orderby": {
            "type": "string",
            "enum": [
              "created_at",
              "updated_at"
            ],
            "description": "排序字段，默认 `updated_at`"
          },
          "asc": {
            "type": "boolean",
            "description": "是否升序，默认 false（降序）"
          },
          "query": {
            "type": "string",
            "description": "搜索关键字。对成员名称或邮箱做子串匹配；纯数字关键字还会精确匹配成员 ID；能解析为手机号的关键字（不带 `+` 时按中国号码解析）还会精确匹配手机号。"
          }
        }
      },
      "MemberListResponse": {
        "type": "object",
        "description": "成员列表响应",
        "properties": {
          "p": {
            "type": "integer",
            "description": "请求中的页码；未传 `p` 时为 `0`（返回的是第一页）。"
          },
          "limit": {
            "type": "integer",
            "description": "实际使用的每页条数；未传 `limit` 时为 100。"
          },
          "total": {
            "type": "integer",
            "description": "符合筛选条件的成员总数（跨所有页）。"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MemberItem"
            },
            "description": "当前页的成员；没有匹配时为空数组。"
          }
        },
        "required": [
          "p",
          "limit",
          "total",
          "items"
        ]
      },
      "MemberResetInfoRequest": {
        "type": "object",
        "description": "重置成员信息请求。外层字段用于定位成员，updates 用于传入要写入的新资料。",
        "required": [
          "updates"
        ],
        "anyOf": [
          {
            "required": [
              "member_id"
            ]
          },
          {
            "required": [
              "member_name"
            ]
          },
          {
            "required": [
              "email"
            ]
          },
          {
            "required": [
              "phone"
            ]
          },
          {
            "required": [
              "ref_id"
            ]
          }
        ],
        "properties": {
          "member_id": {
            "type": "integer",
            "format": "uint64",
            "description": "用于定位成员的成员 ID。"
          },
          "member_name": {
            "type": "string",
            "description": "用于定位成员的成员名称。"
          },
          "email": {
            "type": "string",
            "description": "用于定位成员的邮箱地址。"
          },
          "phone": {
            "type": "string",
            "description": "用于定位成员的手机号；如不是 E.164 格式，可同时传 country_code。"
          },
          "country_code": {
            "type": "string",
            "description": "当 `phone` 不带 \"+\" 前缀时的解析地区提示 —— ISO 3166-1 alpha-2 地区代码（如 \"CN\"，未传时默认 \"CN\"）。此解析场景仍兼容 \"86\" 等数字电话区号。"
          },
          "ref_id": {
            "type": "string",
            "description": "用于定位成员的外部引用 ID。"
          },
          "from": {
            "type": "string",
            "description": "传 `api` 可将更新后的手机号或邮箱标记为已验证。仅在账户关闭成员邀请且被修改的成员不是调用者本人时生效，其他取值均被忽略。"
          },
          "updates": {
            "$ref": "#/components/schemas/MemberResetInfoUpdates",
            "description": "要写入的成员资料新值，至少包含一个字段。"
          }
        }
      },
      "MemberResetInfoUpdates": {
        "type": "object",
        "description": "要写入的成员资料字段。未传的字段保持不变。",
        "properties": {
          "member_name": {
            "type": [
              "string",
              "null"
            ],
            "minLength": 2,
            "maxLength": 39,
            "description": "新的显示名称，2–39 个字符，在账户内唯一。"
          },
          "password": {
            "type": [
              "string",
              "null"
            ],
            "description": "按前端加密格式传入的新登录密码。"
          },
          "phone": {
            "type": [
              "string",
              "null"
            ],
            "description": "新的手机号；非 E.164 格式时请同时传 `country_code`。不能已属于其他成员；新号码会被标记为未验证（见 `from`）。"
          },
          "country_code": {
            "type": [
              "string",
              "null"
            ],
            "description": "ISO 3166-1 alpha-2 地区代码（如 \"CN\"、\"US\"）。可独立更新（无需同时传 `phone`），并兼作解析 `phone` 的地区提示；非法值返回 400，显式传空字符串也会被拒绝。"
          },
          "email": {
            "type": [
              "string",
              "null"
            ],
            "description": "新的邮箱地址。不能已属于其他成员；新地址会被标记为未验证（见 `from`）。"
          },
          "avatar": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 499,
            "description": "新的头像 URL。"
          },
          "locale": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "zh-CN",
              "en-US"
            ],
            "description": "新的语言偏好。可选值：`zh-CN`（简体中文）、`en-US`（英文）；非法值返回 400。"
          },
          "time_zone": {
            "type": [
              "string",
              "null"
            ],
            "description": "新的 IANA 时区名称，如 `Asia/Shanghai`；传空字符串会清除该设置，使成员跟随账户时区。名称无效时返回 `400`。"
          },
          "ref_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "新的外部引用 ID；传空字符串会清空。"
          }
        }
      },
      "MemberRoleGrantRequest": {
        "type": "object",
        "description": "授予成员角色请求",
        "required": [
          "member_id",
          "role_ids"
        ],
        "properties": {
          "member_id": {
            "type": "integer",
            "format": "uint64",
            "description": "要修改角色的成员 ID（取自 `POST /member/list`）。"
          },
          "role_ids": {
            "type": "array",
            "items": {
              "type": "integer",
              "format": "uint64"
            },
            "description": "要授予的角色 ID 列表，将追加到成员现有角色集合（自动去重）。"
          }
        }
      },
      "MemberRoleRevokeRequest": {
        "type": "object",
        "description": "解除成员角色请求",
        "required": [
          "member_id",
          "role_ids"
        ],
        "properties": {
          "member_id": {
            "type": "integer",
            "format": "uint64",
            "description": "要修改角色的成员 ID（取自 `POST /member/list`）。"
          },
          "role_ids": {
            "type": "array",
            "items": {
              "type": "integer",
              "format": "uint64"
            },
            "description": "要从成员处撤销的角色 ID 列表。"
          }
        }
      },
      "MemberRoleUpdateRequest": {
        "type": "object",
        "description": "更新成员角色请求",
        "required": [
          "member_id"
        ],
        "properties": {
          "member_id": {
            "type": "integer",
            "format": "uint64",
            "description": "要修改角色的成员 ID（取自 `POST /member/list`）。"
          },
          "role_ids": {
            "type": "array",
            "items": {
              "type": "integer",
              "format": "uint64"
            },
            "description": "新的角色 ID 集合，整体替换成员现有角色（不是追加）。ID 可通过 `POST /role/list` 获取。"
          }
        }
      },
      "NewMemberItem": {
        "type": "object",
        "description": "新建成员信息",
        "properties": {
          "member_id": {
            "type": "integer",
            "format": "uint64",
            "description": "新建成员的 ID。"
          },
          "member_name": {
            "type": "string",
            "description": "为成员保存的显示名称；未传 `member_name` 时取邮箱前缀。"
          }
        }
      },
      "PermissionFactorItem": {
        "type": "object",
        "description": "一个权限因子。",
        "required": [
          "factor_name",
          "factor_type"
        ],
        "properties": {
          "factor_name": {
            "type": "string",
            "description": "因子标识符（如 'template:read:info'）。"
          },
          "factor_type": {
            "type": "string",
            "enum": [
              "api",
              "button",
              "visit",
              "menu",
              "url"
            ],
            "description": "因子类型。`api`：后端 API 因子，`factor_name` 为接口名（如 `skill:write:upload`），由网关强制校验；`button`：前端操作因子，用于角色配置页渲染操作开关；`visit`：页面访问因子（自定义菜单页面即此类型）；`menu`：菜单可见性因子（历史类型，当前无种子数据）；`url`：页面路由地址因子（历史类型，当前无种子数据）。"
          },
          "source": {
            "type": "string",
            "enum": [
              "system",
              "account"
            ],
            "description": "因子来源。`system` —— 内置种子因子；`account` —— 账户级动态因子（如自定义菜单）。"
          },
          "source_ref": {
            "type": "string",
            "description": "账户级因子来源对象的主键（如自定义菜单 ID）。为空时不返回。"
          }
        }
      },
      "PermissionFactorListRequest": {
        "type": "object",
        "description": "查询权限因子列表的过滤参数。",
        "properties": {
          "factor_types": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "api",
                "button",
                "visit",
                "menu",
                "url"
              ]
            },
            "description": "按因子类型过滤。"
          }
        }
      },
      "PermissionFactorListResponse": {
        "type": "array",
        "description": "权限因子列表。",
        "items": {
          "$ref": "#/components/schemas/PermissionFactorItem"
        }
      },
      "PermissionItem": {
        "type": "object",
        "description": "一个权限条目。",
        "required": [
          "id",
          "permission_name",
          "permission_type",
          "description",
          "class",
          "scope",
          "status",
          "source",
          "is_granted"
        ],
        "properties": {
          "id": {
            "type": "integer",
            "format": "uint64",
            "description": "唯一权限 ID。"
          },
          "permission_name": {
            "type": "string",
            "description": "权限显示名称。"
          },
          "permission_type": {
            "type": "string",
            "enum": [
              "read",
              "manage"
            ],
            "description": "查看权限或管理权限。`read`：只读查看类权限（查看、查询）；`manage`：管理变更类权限（创建、修改、删除、设置等写操作）。"
          },
          "description": {
            "type": "string",
            "description": "权限的用户可读描述。"
          },
          "class": {
            "type": "string",
            "description": "权限分类（如 'On-call'、'Organization'）。"
          },
          "scope": {
            "type": "string",
            "description": "权限生效的功能范围。\n\n| 值 | 含义 |\n| --- | --- |\n| `account` | 账户设置与 API 密钥 |\n| `organization` | 成员、团队、角色、审计 |\n| `on-call` | 值班与故障管理 |\n| `monit` | 监控 |\n| `rum` | 真实用户监控 |\n| `ai-sre` | AI SRE 功能 |\n| `custom_menu` | 账户自定义菜单页面（仅私有化部署） |",
            "enum": [
              "account",
              "organization",
              "on-call",
              "monit",
              "rum",
              "ai-sre",
              "custom_menu"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "enabled",
              "deleted"
            ],
            "description": "权限状态。`enabled` —— 生效；`deleted` —— 已删除（已删除的权限会被过滤，不会出现在响应中）。"
          },
          "is_granted": {
            "type": "boolean",
            "description": "该权限是否已授予 `role_ids` 指定的角色。本接口的响应中始终存在；仅当 `with_all` 为 true 时才会出现 `false` 的条目。"
          },
          "account_id": {
            "type": "integer",
            "format": "uint64",
            "description": "所属账户 ID。为 0（系统级权限）时不返回。"
          },
          "source": {
            "type": "string",
            "enum": [
              "system",
              "account"
            ],
            "description": "权限来源。`system` —— 内置种子权限；`account` —— 账户级动态权限（如自定义菜单）。"
          },
          "source_ref": {
            "type": "string",
            "description": "账户级权限来源对象的主键（如自定义菜单 ID）。为空时不返回。"
          }
        }
      },
      "PersonInfosRequest": {
        "type": "object",
        "description": "批量获取人员信息请求",
        "required": [
          "person_ids"
        ],
        "properties": {
          "person_ids": {
            "type": "array",
            "items": {
              "type": "integer",
              "format": "uint64"
            },
            "description": "人员 ID 列表，即成员 ID（可通过 `POST /member/list` 获取）；传账户 ID 返回账户主体信息，不存在的 ID 会被忽略"
          }
        }
      },
      "PersonInfosResponse": {
        "type": "object",
        "description": "批量人员信息响应",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PersonItem"
            },
            "description": "人员资料列表"
          }
        },
        "required": [
          "items"
        ]
      },
      "PersonItem": {
        "type": "object",
        "description": "人员资料",
        "required": [
          "account_id",
          "person_id",
          "phone_verified",
          "email_verified"
        ],
        "properties": {
          "account_id": {
            "type": "integer",
            "format": "uint64",
            "description": "人员所属账户的 ID。"
          },
          "person_id": {
            "type": "integer",
            "format": "uint64",
            "description": "人员 ID：账户主体为账户 ID，其他人为成员 ID。"
          },
          "person_name": {
            "type": "string",
            "description": "显示名称。为空时不返回。"
          },
          "avatar": {
            "type": "string",
            "description": "头像 URL。为空时不返回。"
          },
          "locale": {
            "type": "string",
            "description": "语言偏好（`zh-CN` 或 `en-US`）。未设置时省略。"
          },
          "time_zone": {
            "type": "string",
            "description": "IANA 时区设置：成员为其自己的设置，账户主体为账户设置。未设置时省略（未设置的成员跟随账户时区）。"
          },
          "email": {
            "type": "string",
            "description": "邮箱地址。为空时不返回。"
          },
          "phone": {
            "type": "string",
            "description": "手机号。为空时不返回——本接口不填充该字段。"
          },
          "phone_verified": {
            "type": "boolean",
            "description": "手机号是否已验证。本接口的响应中恒为 false。"
          },
          "email_verified": {
            "type": "boolean",
            "description": "邮箱已验证时为 `true`；账户主体只要设置了邮箱即为 `true`。"
          },
          "as": {
            "type": "string",
            "description": "主体类型：`account` —— 账户主体（注册人）；`member` —— 组织成员。",
            "enum": [
              "account",
              "member"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "enabled",
              "pending",
              "deleted"
            ],
            "description": "人员状态。`enabled` — 已激活；`pending` — 已邀请但尚未接受；`deleted` — 已移除。为空时不返回。"
          }
        }
      },
      "PlatformEmptyObject": {
        "type": "object",
        "description": "成功时返回的空对象，适用于无实质 payload 的操作。",
        "additionalProperties": false
      },
      "RoleGrantRequest": {
        "type": "object",
        "required": [
          "member_ids",
          "role_id"
        ],
        "description": "向成员授予或撤销角色的请求。",
        "properties": {
          "member_ids": {
            "type": "array",
            "items": {
              "type": "integer",
              "format": "uint64"
            },
            "description": "要授予或解除该角色的成员 ID（取自 `POST /member/list`）。必须全部是本账户成员，不能重复。"
          },
          "role_id": {
            "type": "integer",
            "format": "uint64",
            "description": "要授予或撤销的角色 ID，可通过 `POST /role/list` 获取。"
          }
        }
      },
      "RoleIDRequest": {
        "type": "object",
        "required": [
          "role_id"
        ],
        "properties": {
          "role_id": {
            "type": "integer",
            "format": "uint64",
            "description": "要操作的角色 ID，可通过 `POST /role/list` 获取（含内置角色：2=Admin、6=Responder、8=Viewer）。"
          }
        }
      },
      "RoleInfoRequest": {
        "type": "object",
        "required": [
          "role_id"
        ],
        "properties": {
          "role_id": {
            "type": "integer",
            "format": "uint64",
            "description": "要查询的角色 ID，可通过 `POST /role/list` 获取（含内置角色：2=Admin、6=Responder、8=Viewer）。"
          }
        }
      },
      "RoleItem": {
        "type": "object",
        "description": "角色及其权限集合。",
        "required": [
          "role_id",
          "role_name",
          "description",
          "status",
          "permission_ids",
          "editable",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "role_id": {
            "type": "integer",
            "format": "uint64",
            "description": "角色 ID。内置角色使用固定 ID：`2`（Admin）、`6`（Responder）、`8`（Viewer）。"
          },
          "role_name": {
            "type": "string",
            "description": "角色名称，在账户内唯一。内置角色在所有语言下都命名为 `Admin`、`Responder`、`Viewer`。"
          },
          "description": {
            "type": "string",
            "description": "角色描述。内置角色的描述随请求语言本地化。"
          },
          "status": {
            "type": "string",
            "enum": [
              "enabled",
              "disabled"
            ],
            "description": "角色状态。`enabled`——启用；`disabled`——已通过 `POST /role/disable` 禁用，持有它的成员不会获得其权限。内置角色始终为 `enabled`；已删除的角色不会返回。"
          },
          "permission_ids": {
            "type": "array",
            "items": {
              "type": "integer",
              "format": "uint64"
            },
            "description": "该角色授予的权限 ID，升序排列，可通过 `POST /role/permission/list` 解析。没有权限时为空数组。"
          },
          "editable": {
            "type": "boolean",
            "description": "内置角色（Admin、Responder、Viewer）为 `false`；自定义角色为 `true`。"
          },
          "created_at": {
            "type": "integer",
            "format": "int64",
            "description": "角色创建时间，Unix 时间戳（秒）。内置角色为固定值。"
          },
          "updated_at": {
            "type": "integer",
            "format": "int64",
            "description": "最近更新时间（Unix 秒）。"
          }
        }
      },
      "RoleListRequest": {
        "type": "object",
        "description": "查询角色列表的过滤参数。",
        "properties": {
          "orderby": {
            "type": "string",
            "enum": [
              "created_at",
              "updated_at"
            ],
            "description": "排序字段，默认 `updated_at`。"
          },
          "asc": {
            "type": "boolean",
            "description": "升序排序，默认 false（降序）。"
          },
          "no_global": {
            "type": "boolean",
            "description": "为 true 时排除内置全局角色（Admin、Responder、Viewer），只返回自定义角色。默认 false。"
          }
        }
      },
      "RoleListResponse": {
        "type": "object",
        "description": "角色列表结果。",
        "required": [
          "total",
          "items"
        ],
        "properties": {
          "total": {
            "type": "integer",
            "description": "返回的角色数：自定义角色数加上 3 个内置角色（`no_global` 为 true 时不含内置角色）。"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RoleItem"
            },
            "description": "角色数组；默认包含账户自建角色和内置全局角色（`no_global=true` 时不含全局角色），无结果时为空数组。"
          }
        }
      },
      "RolePermissionListRequest": {
        "type": "object",
        "description": "查询权限列表的过滤参数。",
        "properties": {
          "role_ids": {
            "type": "array",
            "items": {
              "type": "integer",
              "format": "uint64"
            },
            "description": "要返回或标记其已授予权限的角色 ID（内置或自定义）。不存在的 ID 会被忽略。"
          },
          "with_all": {
            "type": "boolean",
            "description": "为 true 时返回全部权限，并用 `is_granted` 标记 `role_ids` 授予的权限。为 false（默认）时只返回已授予的权限。"
          }
        }
      },
      "RolePermissionListResponse": {
        "type": "object",
        "description": "权限列表结果。",
        "required": [
          "items"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PermissionItem"
            },
            "description": "权限点数组，含系统级权限与当前账户的自定义菜单权限（不含其他账户的权限）。"
          }
        }
      },
      "RoleUpsertRequest": {
        "type": "object",
        "required": [
          "role_name"
        ],
        "description": "创建或更新自定义角色的参数。",
        "properties": {
          "role_id": {
            "type": "integer",
            "format": "uint64",
            "description": "要更新的自定义角色 ID。省略或置为 0 表示创建新角色。不要传内置角色 ID `2`、`6`、`8`。"
          },
          "role_name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 39,
            "description": "角色显示名称，1–39 个字符。"
          },
          "description": {
            "type": "string",
            "maxLength": 499,
            "description": "角色描述，最多 499 个字符。更新时不传会清空原有描述。"
          },
          "permission_ids": {
            "type": "array",
            "items": {
              "type": "integer",
              "format": "uint64"
            },
            "description": "角色授予的权限 ID（取自 `POST /role/permission/list`）。整体替换原有权限；不传或传空数组会使角色没有任何权限。"
          }
        }
      },
      "RoleUpsertResponse": {
        "type": "object",
        "description": "角色创建/更新结果。",
        "required": [
          "role_id",
          "role_name"
        ],
        "properties": {
          "role_id": {
            "type": "integer",
            "format": "uint64",
            "description": "创建或更新的角色 ID。"
          },
          "role_name": {
            "type": "string",
            "description": "从请求中回显的角色名称。"
          }
        }
      },
      "SuccessEnvelope": {
        "type": "object",
        "description": "成功响应结构。2xx 响应中 `request_id` 标识本次调用（同时出现在 `Flashcat-Request-Id` 响应头中），`data` 为接口业务 payload。失败响应使用不同结构，参见 `ErrorResponse`。",
        "properties": {
          "request_id": {
            "type": "string",
            "description": "本次请求的唯一 ID，也会在 Flashcat-Request-Id 响应头中返回。反馈问题时请一并附上。",
            "example": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
          },
          "data": {
            "description": "接口返回的数据，格式见各接口的 200 响应。没有返回数据的接口会返回 `{}` 或完全不带 `data`。"
          }
        },
        "required": [
          "request_id"
        ]
      },
      "TeamBriefItem": {
        "type": "object",
        "description": "批量响应中的团队简要信息。",
        "properties": {
          "team_id": {
            "type": "integer",
            "format": "uint64",
            "description": "团队 ID，取自请求中的 `team_ids`。"
          },
          "team_name": {
            "type": "string",
            "description": "团队名称。结果包含已删除的团队，因此可能是已不在 `POST /team/list` 中出现的团队名称。"
          },
          "person_ids": {
            "type": "array",
            "items": {
              "type": "integer",
              "format": "uint64"
            },
            "description": "团队成员的人员 ID 数组；团队无成员时为空数组（不为 null）。"
          }
        },
        "required": [
          "team_id",
          "team_name",
          "person_ids"
        ]
      },
      "TeamDeleteRequest": {
        "type": "object",
        "description": "标识要删除的团队的请求。",
        "properties": {
          "team_id": {
            "type": "integer",
            "format": "uint64",
            "description": "团队 ID。三个定位字段至少提供一个；同时提供多个时优先使用 `team_id`。"
          },
          "team_name": {
            "type": "string",
            "description": "团队名称。仅在未提供 `team_id` 时用于定位。"
          },
          "ref_id": {
            "type": "string",
            "description": "外部引用 ID。仅在 `team_id`、`team_name` 均未提供时用于定位。"
          }
        },
        "anyOf": [
          {
            "required": [
              "team_id"
            ]
          },
          {
            "required": [
              "team_name"
            ]
          },
          {
            "required": [
              "ref_id"
            ]
          }
        ]
      },
      "TeamInfoRequest": {
        "type": "object",
        "description": "通过 ID、名称或外部引用标识团队的请求。",
        "properties": {
          "team_id": {
            "type": "integer",
            "format": "uint64",
            "description": "团队 ID。三个定位字段至少提供一个；优先级最低，仅在 `ref_id`、`team_name` 均未提供时生效。"
          },
          "team_name": {
            "type": "string",
            "description": "团队名称。仅在未提供 `ref_id` 时生效，优先级高于 `team_id`。"
          },
          "ref_id": {
            "type": "string",
            "description": "外部引用 ID。提供时优先于 `team_name` 和 `team_id` 生效。"
          }
        },
        "anyOf": [
          {
            "required": [
              "team_id"
            ]
          },
          {
            "required": [
              "team_name"
            ]
          },
          {
            "required": [
              "ref_id"
            ]
          }
        ]
      },
      "TeamInfosRequest": {
        "type": "object",
        "required": [
          "team_ids"
        ],
        "description": "按 ID 列表批量查询团队的请求。",
        "properties": {
          "team_ids": {
            "type": "array",
            "items": {
              "type": "integer",
              "format": "uint64"
            },
            "description": "要查询的团队 ID 列表。"
          }
        }
      },
      "TeamInfosResponse": {
        "type": "object",
        "description": "批量团队查询结果。",
        "required": [
          "items"
        ],
        "properties": {
          "items": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/TeamBriefItem"
            },
            "description": "匹配到的团队简要信息（包括已删除的团队）；没有任何 ID 匹配时为 `null`。"
          }
        }
      },
      "TeamItem": {
        "type": "object",
        "description": "团队及其成员信息。",
        "required": [
          "account_id",
          "team_id",
          "team_name",
          "description",
          "status",
          "updated_by_name",
          "updated_by",
          "creator_id",
          "creator_name",
          "created_at",
          "updated_at",
          "person_ids",
          "ref_id"
        ],
        "properties": {
          "account_id": {
            "type": "integer",
            "format": "uint64",
            "description": "所属账户 ID。"
          },
          "team_id": {
            "type": "integer",
            "format": "uint64",
            "description": "唯一团队 ID。"
          },
          "team_name": {
            "type": "string",
            "description": "团队显示名称，1–39 个字符，账户内唯一。"
          },
          "description": {
            "type": "string",
            "description": "自定义描述。"
          },
          "status": {
            "type": "string",
            "enum": [
              "enabled",
              "deleted"
            ],
            "description": "团队状态。`enabled` —— 正常；`deleted` —— 已删除（仅按 `team_id` 查询已删除团队时可能返回；列表及按名称/ref_id 查询均排除已删除团队）。"
          },
          "updated_by_name": {
            "type": "string",
            "description": "最后编辑人的名称：成员名称；账户主体编辑时为账户名称；无法解析时为空字符串。"
          },
          "updated_by": {
            "type": "integer",
            "format": "uint64",
            "description": "最后修改人成员 ID。"
          },
          "creator_id": {
            "type": "integer",
            "format": "uint64",
            "description": "创建人成员 ID。"
          },
          "creator_name": {
            "type": "string",
            "description": "创建者显示名称。当前接口不填充该字段，恒为空字符串；请用 `creator_id` 调用 `POST /person/infos` 解析。"
          },
          "created_at": {
            "type": "integer",
            "format": "int64",
            "description": "创建时间（Unix 秒）。"
          },
          "updated_at": {
            "type": "integer",
            "format": "int64",
            "description": "最近更新时间（Unix 秒）。"
          },
          "person_ids": {
            "type": "array",
            "items": {
              "type": "integer",
              "format": "uint64"
            },
            "description": "团队成员的人员 ID（即成员 ID；账户主体在团队中时为账户 ID）。团队没有成员时为空数组。"
          },
          "ref_id": {
            "type": "string",
            "description": "外部引用 ID，用于与第三方 HR 系统集成。"
          }
        }
      },
      "TeamListRequest": {
        "type": "object",
        "description": "查询团队列表的过滤参数。",
        "properties": {
          "p": {
            "type": "integer",
            "description": "页码，从 1 开始，默认 1。",
            "minimum": 1,
            "default": 1
          },
          "limit": {
            "type": "integer",
            "description": "分页大小，最大 100，默认 20。",
            "minimum": 1,
            "maximum": 100,
            "default": 20
          },
          "orderby": {
            "type": "string",
            "description": "排序字段，默认 `updated_at`。",
            "enum": [
              "created_at",
              "updated_at",
              "team_name"
            ]
          },
          "asc": {
            "type": "boolean",
            "description": "升序排序，默认 false（降序）。"
          },
          "person_id": {
            "type": "integer",
            "format": "uint64",
            "description": "按成员 ID 过滤，只返回该成员所属的团队。"
          },
          "query": {
            "type": "string",
            "description": "按团队名称或描述做子串匹配。"
          }
        }
      },
      "TeamListResponse": {
        "type": "object",
        "description": "分页团队列表。",
        "required": [
          "p",
          "limit",
          "total",
          "items"
        ],
        "properties": {
          "p": {
            "type": "integer",
            "description": "请求中的页码；未传 `p` 时为 `0`（返回的是第一页）。"
          },
          "limit": {
            "type": "integer",
            "description": "实际使用的每页条数；未传 `limit` 时为 20。"
          },
          "total": {
            "type": "integer",
            "description": "符合筛选条件的未删除团队总数（跨所有页）。"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TeamItem"
            },
            "description": "当前页的团队数组，与 `p`、`limit`、`total` 配合分页；空页时为空数组。"
          }
        }
      },
      "TeamUpsertRequest": {
        "type": "object",
        "required": [
          "team_name"
        ],
        "description": "创建或更新团队的参数。",
        "properties": {
          "team_id": {
            "type": "integer",
            "format": "uint64",
            "description": "要更新的团队 ID。省略或置为 0 表示创建新团队；非 0 时必须是本账户已有团队的 ID。"
          },
          "team_name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 39,
            "description": "团队显示名称，1–39 个字符。"
          },
          "description": {
            "type": "string",
            "maxLength": 500,
            "description": "自由文本描述，最多 500 个字符。更新时不传会清空原有描述。"
          },
          "person_ids": {
            "type": "array",
            "items": {
              "type": "integer",
              "format": "uint64"
            },
            "description": "要加入团队的人员 ID（成员 ID；账户主体使用账户 ID）。与 `emails`、`phones` 合并后整体替换成员列表；不是本账户成员的 ID 会被忽略。"
          },
          "emails": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "email"
            },
            "description": "要加入团队的已有成员邮箱，与 `person_ids`、`phones` 合并。匹配不到成员的邮箱会被忽略，不会发出邀请。"
          },
          "phones": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "要加入团队的已有成员手机号，与 `person_ids`、`emails` 合并。不带 `+` 前缀的号码按 `countryCode` 解析；无法解析的号码会使整个请求返回 `400`，匹配不到成员的号码会被忽略。"
          },
          "countryCode": {
            "type": "string",
            "description": "`phones` 中不带 `+` 前缀号码的地区提示：ISO 3166-1 alpha-2 地区代码（如 `CN`，未传时默认）或数字区号（如 `86`）。"
          },
          "ref_id": {
            "type": "string",
            "description": "外部引用 ID（如 HR 系统中的部门 ID），可在 `POST /team/info`、`POST /team/delete` 中作为查找键。更新时不传会清空原值。"
          },
          "reset_if_name_exist": {
            "type": "boolean",
            "description": "为 true 且 `team_id` 为 0 时，若已存在同名团队，则原地更新该团队，而不是返回名称冲突错误。"
          }
        }
      },
      "TeamUpsertResponse": {
        "type": "object",
        "description": "创建或更新团队的结果。",
        "required": [
          "team_id",
          "team_name"
        ],
        "properties": {
          "team_id": {
            "type": "integer",
            "format": "uint64",
            "description": "创建或更新的团队 ID。"
          },
          "team_name": {
            "type": "string",
            "description": "从请求中回显的团队名称。"
          }
        }
      },
      "AccountInfo": {
        "type": "object",
        "properties": {
          "account_id": {
            "type": "integer",
            "description": "主体（账户）标识。",
            "format": "uint64"
          },
          "account_name": {
            "type": "string",
            "description": "在控制台中显示的账户（组织）名称。"
          },
          "domain": {
            "type": "string",
            "description": "主体主域名（登录子域名）。"
          },
          "extra_domains": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "主体的附加域名。"
          },
          "phone": {
            "type": "string",
            "description": "主体联系电话，已做隐私脱敏处理。"
          },
          "country_code": {
            "type": "string",
            "description": "联系手机的 ISO 3166-1 alpha-2 地区代码（如 \"CN\"、\"US\"、\"HK\"）。"
          },
          "email": {
            "type": "string",
            "description": "主体联系邮箱。"
          },
          "avatar": {
            "type": "string",
            "description": "主体头像 URL。"
          },
          "locale": {
            "type": "string",
            "description": "账户语言偏好（`zh-CN` 或 `en-US`）；未设置时为空字符串。"
          },
          "time_zone": {
            "type": "string",
            "description": "账户默认时区（IANA 名称，如 `Asia/Shanghai`），未设置个人时区的成员跟随该时区。未设置时为空字符串。"
          },
          "created_at": {
            "type": "integer",
            "format": "int64",
            "description": "主体创建时间，Unix 时间戳（秒）。"
          },
          "restrictions": {
            "type": "object",
            "description": "账户访问限制。未配置时不返回。",
            "properties": {
              "ips": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "string"
                },
                "description": "允许访问本账户控制台和 API 的来源 IP 或 CIDR 网段；不限制时为 `null` 或空。"
              },
              "email_domains": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "string"
                },
                "description": "允许新成员使用的邮箱域名；邀请其他域名的地址会被拒绝。不限制时为 `null` 或空。"
              },
              "allow_subdomain": {
                "type": "boolean",
                "description": "是否同时接受允许邮箱域名的子域名。"
              }
            }
          },
          "mp_plat": {
            "type": "string",
            "description": "账户开通来源的云市场：`aws`——AWS Marketplace。账户并非来自云市场时省略。",
            "enum": [
              "aws"
            ]
          },
          "mp_account_id": {
            "type": "string",
            "description": "账户在云市场平台上的标识。与 `mp_plat` 一起省略。"
          }
        },
        "required": [
          "account_id",
          "account_name",
          "domain",
          "extra_domains",
          "phone",
          "country_code",
          "email",
          "avatar",
          "locale",
          "time_zone",
          "created_at"
        ]
      },
      "RoleDeleteRequest": {
        "type": "object",
        "required": [
          "role_id"
        ],
        "description": "删除角色请求。",
        "properties": {
          "role_id": {
            "type": "integer",
            "format": "uint64",
            "description": "要删除的角色 ID。可通过 `POST /role/list` 获取（内置角色：2=Admin，6=Responder，8=Viewer）。"
          },
          "is_force": {
            "type": "boolean",
            "default": false,
            "description": "为 false（默认）时，只要还有成员持有该角色，删除就会失败并返回 `ReferenceExist`，持有成员列在 `data.refs` 中。为 true 时，先从所有持有成员解除该角色再删除。不会跳过单点登录默认角色检查。"
          }
        }
      },
      "MemberNotifyRequest": {
        "type": "object",
        "description": "邮件通知成员请求",
        "required": [
          "subject",
          "html"
        ],
        "properties": {
          "person_ids": {
            "type": "array",
            "items": {
              "type": "integer",
              "format": "int64"
            },
            "maxItems": 20,
            "description": "收件人成员 ID 列表。可选，最多 20 个；重复 ID 和非正数 ID 会被忽略；省略或为空时仅发送给调用方本人。"
          },
          "subject": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200,
            "description": "邮件主题，按原样使用。必填，1–200 个字符；换行会被替换为空格，首尾空白会被去除。"
          },
          "html": {
            "type": "string",
            "maxLength": 102400,
            "description": "邮件正文，HTML 片段（无需 `<html>`/`<head>`/`<body>` 包裹），即收件人看到的完整邮件正文。必填，原始 UTF-8 内容不超过 102,400 字节（更大的正文会被常见邮件客户端截断），且清洗后不能为空。`<script>`、`<meta>`、`<link>`、`<base>` 标签及所有 `on*` 事件处理属性会在发送前被静默移除——邮件客户端本就不会执行它们；内联 `style` 属性按原样保留。`<style>`、`<svg>`、`<iframe>`、`<object>`、`<embed>`、`<form>`、`<input>`、`<button>` 标签，`src` 缺失或不是 `https`（包括 `data:`）的 `<img>`，以及 href 不属于 `http`、`https`、`mailto` 的 `<a>`，会被直接拒绝而非静默清洗：请求会返回 `400`，而不是悄悄改变收件人看到的内容。"
          }
        }
      },
      "MemberNotifyResponse": {
        "type": "object",
        "description": "邮件通知成员响应",
        "properties": {
          "recipients": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MemberNotifyResultItem"
            },
            "description": "每个已解析收件人对应一条结果，顺序与解析后的收件人列表一致。"
          },
          "agent_instructions": {
            "type": "string",
            "description": "当提交的 HTML 正文不符合默认邮件版式（缺少 `max-width:600px` 外层包裹表格）时返回：告知调用的 AI SRE agent 如何对齐的指引。仅为建议——调用方有意选择的格式无需改动。"
          }
        }
      },
      "MemberNotifyResultItem": {
        "type": "object",
        "description": "单个收件人的通知结果",
        "required": [
          "person_id",
          "status"
        ],
        "properties": {
          "person_id": {
            "type": "integer",
            "format": "int64",
            "description": "收件人成员 ID。"
          },
          "status": {
            "type": "string",
            "enum": [
              "accepted",
              "skipped"
            ],
            "description": "投递状态。`accepted` —— 邮件已入队等待异步投递；`skipped` —— 未入队，具体原因见 `reason`。"
          },
          "reason": {
            "type": "string",
            "enum": [
              "not_member",
              "no_email",
              "email_disabled",
              "duplicate",
              "rate_limited",
              "send_failed"
            ],
            "description": "跳过原因，仅当 `status` 为 `skipped` 时出现。`not_member` —— 不是调用方账户的活跃成员；`no_email` —— 该成员没有邮箱地址；`email_disabled` —— 该成员针对此类消息的通知偏好中未包含邮件；`duplicate` —— 该收件人在同一个 AI SRE 会话轮次中已经收到过一次消息；`rate_limited` —— 该收件人通过该接口在过去一小时内已被发送 20 封邮件；`send_failed` —— 邮件入队失败。"
          }
        }
      }
    }
  }
}
