Stev_Wang
61894df401
背景：A2 开卡前完成 H1 权限门，确认权限点目录、特殊权限、SoD 三对、六类数据范围与超管隐式全集口径（ADR-001）。 改动： - shared：30 权限点 / 10 模块目录与元数据、特殊权限 6 编码、SoD 三对、角色与权限树契约；/me 改 dataScopes 多角色并集。 - prisma：expand 迁移新增 permissions / data_scopes；种子按原型口径重写角色权限、数据范围与 8 项特殊授予。 - api：角色 CRUD / 复制 / 停用 / 删除、权限点启动同步、SoD 40304、系统角色保护、六类范围 ScopeContext 与 CustomerDirectory 端口、变更审计与 outbox。 - web：方案 B 主从分栏三角色页面（列表 / 编辑器 / 新建），权限树、范围选择、特殊权限二次确认、保存影响、SoD 冲突、只读态与模板预填。 - 测试：角色集成 13 条 + A2 e2e 1 条；A1 全量回归。 验证：format:check / lint / typecheck / test（306）/ test:int（27）/ A2 e2e（1，复跑通过）/ openapi:export 全绿。
692 lines
15 KiB
JSON
692 lines
15 KiB
JSON
{
|
|
"openapi": "3.1.0",
|
|
"paths": {
|
|
"/api/v1/auth/login": {
|
|
"post": {
|
|
"description": "返回 accessToken / refreshToken / expiresIn / me",
|
|
"operationId": "AuthController_login",
|
|
"parameters": [],
|
|
"responses": {
|
|
"200": {
|
|
"description": ""
|
|
}
|
|
},
|
|
"summary": "账号密码登录",
|
|
"tags": [
|
|
"identity-auth"
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/auth/refresh": {
|
|
"post": {
|
|
"operationId": "AuthController_refresh",
|
|
"parameters": [],
|
|
"responses": {
|
|
"200": {
|
|
"description": ""
|
|
}
|
|
},
|
|
"summary": "刷新令牌（旋转，旧 refresh 立即失效）",
|
|
"tags": [
|
|
"identity-auth"
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/auth/logout": {
|
|
"post": {
|
|
"description": "吊销 refresh 令牌所在家族",
|
|
"operationId": "AuthController_logout",
|
|
"parameters": [],
|
|
"responses": {
|
|
"204": {
|
|
"description": ""
|
|
}
|
|
},
|
|
"summary": "登出",
|
|
"tags": [
|
|
"identity-auth"
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/auth/change-password": {
|
|
"post": {
|
|
"operationId": "AuthController_changePassword",
|
|
"parameters": [],
|
|
"responses": {
|
|
"204": {
|
|
"description": ""
|
|
}
|
|
},
|
|
"summary": "修改密码（首登强改）",
|
|
"tags": [
|
|
"identity-auth"
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/me": {
|
|
"get": {
|
|
"operationId": "MeController_current",
|
|
"parameters": [],
|
|
"responses": {
|
|
"200": {
|
|
"description": ""
|
|
}
|
|
},
|
|
"security": [
|
|
{
|
|
"bearer": []
|
|
}
|
|
],
|
|
"summary": "当前用户、角色、权限点、数据范围（多角色并集）",
|
|
"tags": [
|
|
"identity-me"
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/users": {
|
|
"get": {
|
|
"description": "status 默认 active（停用默认隐藏）；sort/order 走白名单；手机号仅返回掩码",
|
|
"operationId": "UsersController_list",
|
|
"parameters": [],
|
|
"responses": {
|
|
"200": {
|
|
"description": ""
|
|
}
|
|
},
|
|
"security": [
|
|
{
|
|
"bearer": []
|
|
}
|
|
],
|
|
"summary": "用户列表（游标分页）",
|
|
"tags": [
|
|
"identity-users"
|
|
]
|
|
},
|
|
"post": {
|
|
"description": "初始密码由管理员设定，首登强制修改",
|
|
"operationId": "UsersController_create",
|
|
"parameters": [],
|
|
"responses": {
|
|
"201": {
|
|
"description": ""
|
|
}
|
|
},
|
|
"security": [
|
|
{
|
|
"bearer": []
|
|
}
|
|
],
|
|
"summary": "新建用户",
|
|
"tags": [
|
|
"identity-users"
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/users/{id}": {
|
|
"get": {
|
|
"description": "仅 user:manage 返回 phone 全号",
|
|
"operationId": "UsersController_detail",
|
|
"parameters": [],
|
|
"responses": {
|
|
"200": {
|
|
"description": ""
|
|
}
|
|
},
|
|
"security": [
|
|
{
|
|
"bearer": []
|
|
}
|
|
],
|
|
"summary": "用户详情",
|
|
"tags": [
|
|
"identity-users"
|
|
]
|
|
},
|
|
"patch": {
|
|
"operationId": "UsersController_update",
|
|
"parameters": [],
|
|
"responses": {
|
|
"200": {
|
|
"description": ""
|
|
}
|
|
},
|
|
"security": [
|
|
{
|
|
"bearer": []
|
|
}
|
|
],
|
|
"summary": "更新用户（不含账号 / 状态 / 密码）",
|
|
"tags": [
|
|
"identity-users"
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/users/{id}/disable": {
|
|
"post": {
|
|
"description": "停用后旧令牌立即失效；可指定客户转交人",
|
|
"operationId": "UsersController_disable",
|
|
"parameters": [],
|
|
"responses": {
|
|
"200": {
|
|
"description": ""
|
|
}
|
|
},
|
|
"security": [
|
|
{
|
|
"bearer": []
|
|
}
|
|
],
|
|
"summary": "停用用户",
|
|
"tags": [
|
|
"identity-users"
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/users/{id}/enable": {
|
|
"post": {
|
|
"operationId": "UsersController_enable",
|
|
"parameters": [],
|
|
"responses": {
|
|
"200": {
|
|
"description": ""
|
|
}
|
|
},
|
|
"security": [
|
|
{
|
|
"bearer": []
|
|
}
|
|
],
|
|
"summary": "启用用户",
|
|
"tags": [
|
|
"identity-users"
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/users/{id}/transfer-customers": {
|
|
"post": {
|
|
"description": "A3 客户模块落地前返回 42201",
|
|
"operationId": "UsersController_transferCustomers",
|
|
"parameters": [],
|
|
"responses": {
|
|
"200": {
|
|
"description": ""
|
|
}
|
|
},
|
|
"security": [
|
|
{
|
|
"bearer": []
|
|
}
|
|
],
|
|
"summary": "客户转交（占位）",
|
|
"tags": [
|
|
"identity-users"
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/departments/tree": {
|
|
"get": {
|
|
"operationId": "DepartmentsController_tree",
|
|
"parameters": [],
|
|
"responses": {
|
|
"200": {
|
|
"description": ""
|
|
}
|
|
},
|
|
"security": [
|
|
{
|
|
"bearer": []
|
|
}
|
|
],
|
|
"summary": "部门树（两级，含成员数与负责人）",
|
|
"tags": [
|
|
"identity-departments"
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/departments": {
|
|
"post": {
|
|
"description": "最多两级，在小组下新建返回 42201",
|
|
"operationId": "DepartmentsController_create",
|
|
"parameters": [],
|
|
"responses": {
|
|
"201": {
|
|
"description": ""
|
|
}
|
|
},
|
|
"security": [
|
|
{
|
|
"bearer": []
|
|
}
|
|
],
|
|
"summary": "新建部门 / 小组",
|
|
"tags": [
|
|
"identity-departments"
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/departments/{id}": {
|
|
"patch": {
|
|
"operationId": "DepartmentsController_rename",
|
|
"parameters": [],
|
|
"responses": {
|
|
"200": {
|
|
"description": ""
|
|
}
|
|
},
|
|
"security": [
|
|
{
|
|
"bearer": []
|
|
}
|
|
],
|
|
"summary": "部门改名",
|
|
"tags": [
|
|
"identity-departments"
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/roles": {
|
|
"get": {
|
|
"description": "默认 status=active（兼容 A1 用户管理的角色多选）；含权限点统计、用户数与数据范围",
|
|
"operationId": "RolesController_list",
|
|
"parameters": [],
|
|
"responses": {
|
|
"200": {
|
|
"description": ""
|
|
}
|
|
},
|
|
"security": [
|
|
{
|
|
"bearer": []
|
|
}
|
|
],
|
|
"summary": "角色列表（游标分页 + 筛选 + 排序）",
|
|
"tags": [
|
|
"identity-roles"
|
|
]
|
|
},
|
|
"post": {
|
|
"description": "权限点默认全空、code 自动生成；保存即做 SoD 校验（40304）；特殊权限单独授予",
|
|
"operationId": "RolesController_create",
|
|
"parameters": [],
|
|
"responses": {
|
|
"201": {
|
|
"description": ""
|
|
}
|
|
},
|
|
"security": [
|
|
{
|
|
"bearer": []
|
|
}
|
|
],
|
|
"summary": "新建角色",
|
|
"tags": [
|
|
"identity-roles"
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/roles/{id}": {
|
|
"get": {
|
|
"operationId": "RolesController_detail",
|
|
"parameters": [],
|
|
"responses": {
|
|
"200": {
|
|
"description": ""
|
|
}
|
|
},
|
|
"security": [
|
|
{
|
|
"bearer": []
|
|
}
|
|
],
|
|
"summary": "角色详情（权限点、特殊权限、数据范围、绑定用户）",
|
|
"tags": [
|
|
"identity-roles"
|
|
]
|
|
},
|
|
"patch": {
|
|
"description": "系统角色仅显示名可改；status=enabled/disabled；返回 affectedUserCount 与软提示",
|
|
"operationId": "RolesController_update",
|
|
"parameters": [],
|
|
"responses": {
|
|
"200": {
|
|
"description": ""
|
|
}
|
|
},
|
|
"security": [
|
|
{
|
|
"bearer": []
|
|
}
|
|
],
|
|
"summary": "更新角色 / 启停",
|
|
"tags": [
|
|
"identity-roles"
|
|
]
|
|
},
|
|
"delete": {
|
|
"description": "系统角色拒绝；有绑定用户（40903）只能停用",
|
|
"operationId": "RolesController_remove",
|
|
"parameters": [],
|
|
"responses": {
|
|
"204": {
|
|
"description": ""
|
|
}
|
|
},
|
|
"security": [
|
|
{
|
|
"bearer": []
|
|
}
|
|
],
|
|
"summary": "删除角色",
|
|
"tags": [
|
|
"identity-roles"
|
|
]
|
|
}
|
|
},
|
|
"/api/v1/permissions": {
|
|
"get": {
|
|
"description": "模块顺序与 design/a2-ui-v1/brief.md 对齐；特殊权限默认关闭、单独授予",
|
|
"operationId": "PermissionsController_getTree",
|
|
"parameters": [],
|
|
"responses": {
|
|
"200": {
|
|
"description": ""
|
|
}
|
|
},
|
|
"security": [
|
|
{
|
|
"bearer": []
|
|
}
|
|
],
|
|
"summary": "权限点目录（10 模块树 + 特殊权限 + SoD 对）",
|
|
"tags": [
|
|
"identity-permissions"
|
|
]
|
|
}
|
|
},
|
|
"/health": {
|
|
"get": {
|
|
"description": "真实检查 PostgreSQL 与 Redis；任一不可用返回 503 与统一错误体。",
|
|
"operationId": "HealthController_check",
|
|
"parameters": [],
|
|
"responses": {
|
|
"200": {
|
|
"description": "全部依赖健康",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/HealthResponseDto"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"503": {
|
|
"description": "依赖不可用（错误码 50002），details 内附各依赖检查结果"
|
|
}
|
|
},
|
|
"summary": "健康检查",
|
|
"tags": [
|
|
"platform"
|
|
]
|
|
}
|
|
}
|
|
},
|
|
"info": {
|
|
"title": "灵犀 API",
|
|
"description": "信息流广告素材生产平台后端 API。\n\n统一约定：\n- 前缀 /api/v1（健康检查 /health 除外）\n- 错误体 { code, message, details, trace_id }\n- 列表响应 { items, next_cursor }",
|
|
"version": "0.1.0",
|
|
"contact": {}
|
|
},
|
|
"tags": [],
|
|
"servers": [
|
|
{
|
|
"url": "/api/v1",
|
|
"description": "API v1"
|
|
}
|
|
],
|
|
"components": {
|
|
"securitySchemes": {
|
|
"bearer": {
|
|
"scheme": "bearer",
|
|
"bearerFormat": "JWT",
|
|
"type": "http"
|
|
}
|
|
},
|
|
"schemas": {
|
|
"ComponentHealthDto": {
|
|
"type": "object",
|
|
"properties": {
|
|
"status": {
|
|
"type": "string",
|
|
"enum": [
|
|
"up",
|
|
"down"
|
|
],
|
|
"example": "up"
|
|
},
|
|
"latencyMs": {
|
|
"type": "number",
|
|
"description": "检查耗时（毫秒）",
|
|
"example": 3
|
|
},
|
|
"error": {
|
|
"type": "string",
|
|
"description": "失败原因（仅 down 时返回）"
|
|
}
|
|
},
|
|
"required": [
|
|
"status",
|
|
"latencyMs"
|
|
]
|
|
},
|
|
"HealthChecksDto": {
|
|
"type": "object",
|
|
"properties": {
|
|
"database": {
|
|
"$ref": "#/components/schemas/ComponentHealthDto"
|
|
},
|
|
"redis": {
|
|
"$ref": "#/components/schemas/ComponentHealthDto"
|
|
}
|
|
},
|
|
"required": [
|
|
"database",
|
|
"redis"
|
|
]
|
|
},
|
|
"HealthResponseDto": {
|
|
"type": "object",
|
|
"properties": {
|
|
"status": {
|
|
"type": "string",
|
|
"enum": [
|
|
"ok",
|
|
"degraded"
|
|
],
|
|
"example": "ok"
|
|
},
|
|
"env": {
|
|
"type": "string",
|
|
"example": "development"
|
|
},
|
|
"version": {
|
|
"type": "string",
|
|
"example": "0.1.0"
|
|
},
|
|
"uptimeSeconds": {
|
|
"type": "number",
|
|
"description": "进程运行秒数",
|
|
"example": 128
|
|
},
|
|
"checks": {
|
|
"$ref": "#/components/schemas/HealthChecksDto"
|
|
},
|
|
"timestamp": {
|
|
"type": "string",
|
|
"example": "2026-11-02T08:00:00.000Z"
|
|
}
|
|
},
|
|
"required": [
|
|
"status",
|
|
"env",
|
|
"version",
|
|
"uptimeSeconds",
|
|
"checks",
|
|
"timestamp"
|
|
]
|
|
},
|
|
"ErrorResponseDto": {
|
|
"type": "object",
|
|
"properties": {
|
|
"code": {
|
|
"type": "number",
|
|
"description": "错误码（见 ErrorCode 常量）",
|
|
"example": 42202
|
|
},
|
|
"message": {
|
|
"type": "string",
|
|
"description": "可直接展示给用户的提示",
|
|
"example": "内容触发合规拦截"
|
|
},
|
|
"details": {
|
|
"type": "object",
|
|
"description": "补充信息（字段错误、命中规则等），结构由错误码决定",
|
|
"example": {
|
|
"issues": [
|
|
{
|
|
"path": "name",
|
|
"message": "Required"
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"trace_id": {
|
|
"type": "string",
|
|
"description": "请求追踪 ID，与日志同源",
|
|
"example": "01JABCDEF0123456789ABCDEFG"
|
|
}
|
|
},
|
|
"required": [
|
|
"code",
|
|
"message",
|
|
"trace_id"
|
|
]
|
|
},
|
|
"ErrorCode": {
|
|
"type": "integer",
|
|
"description": "业务错误码（只允许使用 @lingxi/shared 中登记的错误码）",
|
|
"enum": [
|
|
40001,
|
|
40101,
|
|
40102,
|
|
40103,
|
|
40301,
|
|
40302,
|
|
40303,
|
|
40304,
|
|
40401,
|
|
40901,
|
|
40902,
|
|
40903,
|
|
42201,
|
|
42202,
|
|
42203,
|
|
42901,
|
|
42902,
|
|
50001,
|
|
50002,
|
|
50003
|
|
]
|
|
},
|
|
"ErrorResponse": {
|
|
"type": "object",
|
|
"required": [
|
|
"code",
|
|
"message",
|
|
"trace_id"
|
|
],
|
|
"properties": {
|
|
"code": {
|
|
"$ref": "#/components/schemas/ErrorCode"
|
|
},
|
|
"message": {
|
|
"type": "string"
|
|
},
|
|
"details": {
|
|
"description": "补充信息，结构由错误码决定"
|
|
},
|
|
"trace_id": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-error-codes": [
|
|
{
|
|
"code": 40001
|
|
},
|
|
{
|
|
"code": 40101
|
|
},
|
|
{
|
|
"code": 40102
|
|
},
|
|
{
|
|
"code": 40103
|
|
},
|
|
{
|
|
"code": 40301
|
|
},
|
|
{
|
|
"code": 40302
|
|
},
|
|
{
|
|
"code": 40303
|
|
},
|
|
{
|
|
"code": 40304
|
|
},
|
|
{
|
|
"code": 40401
|
|
},
|
|
{
|
|
"code": 40901
|
|
},
|
|
{
|
|
"code": 40902
|
|
},
|
|
{
|
|
"code": 40903
|
|
},
|
|
{
|
|
"code": 42201
|
|
},
|
|
{
|
|
"code": 42202
|
|
},
|
|
{
|
|
"code": 42203
|
|
},
|
|
{
|
|
"code": 42901
|
|
},
|
|
{
|
|
"code": 42902
|
|
},
|
|
{
|
|
"code": 50001
|
|
},
|
|
{
|
|
"code": 50002
|
|
},
|
|
{
|
|
"code": 50003
|
|
}
|
|
],
|
|
"x-api-config": {
|
|
"env": "development",
|
|
"featureVideo": false
|
|
}
|
|
}
|