Stev_Wang
e4330a43e4
背景：A4 需要字典三层合并、配置单一来源与阈值同源。\n改动：新增 catalog 模块（类型/条目/三层合并/编码不可改/快照工具）；platform 新增 SystemConfigService/Controller、NamingService 与配置版本历史；roles/users/customers/customer-fields 改为读 system_configs 上限。\n影响面：新增 13 个 REST 端点与 4 个模块注入；system_configs 写入走事务/乐观锁/版本历史；OpenAPI 快照更新。\n回滚：回滚本提交并恢复 shared 契约；新增表可保留。\n验证：api typecheck/build；单测 137；集成 58；OpenAPI diff 无破坏性变更。
1460 lines
33 KiB
JSON
1460 lines
33 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/departments/tree": {
|
||
"get": {
|
||
"description": "memberCount 含下级成员、directMemberCount 仅本部门直属成员；默认只返回启用部门，管理页传 include_disabled=true",
|
||
"operationId": "DepartmentsController_tree",
|
||
"parameters": [
|
||
{
|
||
"name": "include_disabled",
|
||
"required": false,
|
||
"in": "query",
|
||
"schema": {
|
||
"enum": [
|
||
"true",
|
||
"false"
|
||
],
|
||
"type": "string"
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": ""
|
||
}
|
||
},
|
||
"security": [
|
||
{
|
||
"bearer": []
|
||
}
|
||
],
|
||
"summary": "部门树（两级）",
|
||
"tags": [
|
||
"identity-departments"
|
||
]
|
||
}
|
||
},
|
||
"/api/v1/departments": {
|
||
"post": {
|
||
"description": "最多两级；父级必须启用；负责人必须是启用用户；同级重名返回 40903",
|
||
"operationId": "DepartmentsController_create",
|
||
"parameters": [],
|
||
"responses": {
|
||
"201": {
|
||
"description": ""
|
||
}
|
||
},
|
||
"security": [
|
||
{
|
||
"bearer": []
|
||
}
|
||
],
|
||
"summary": "新建部门 / 小组",
|
||
"tags": [
|
||
"identity-departments"
|
||
]
|
||
}
|
||
},
|
||
"/api/v1/departments/{id}": {
|
||
"patch": {
|
||
"description": "上级关系创建后不可移动；负责人必须是启用用户",
|
||
"operationId": "DepartmentsController_update",
|
||
"parameters": [],
|
||
"responses": {
|
||
"200": {
|
||
"description": ""
|
||
}
|
||
},
|
||
"security": [
|
||
{
|
||
"bearer": []
|
||
}
|
||
],
|
||
"summary": "更新部门（名称 / 负责人 / 排序）",
|
||
"tags": [
|
||
"identity-departments"
|
||
]
|
||
}
|
||
},
|
||
"/api/v1/departments/{id}/disable": {
|
||
"post": {
|
||
"description": "本部门仍有在职成员、或一级部门存在启用中的下级小组 / 下级在职成员时返回 42201；已停用返回 40903",
|
||
"operationId": "DepartmentsController_disable",
|
||
"parameters": [],
|
||
"responses": {
|
||
"200": {
|
||
"description": ""
|
||
}
|
||
},
|
||
"security": [
|
||
{
|
||
"bearer": []
|
||
}
|
||
],
|
||
"summary": "停用部门",
|
||
"tags": [
|
||
"identity-departments"
|
||
]
|
||
}
|
||
},
|
||
"/api/v1/departments/{id}/enable": {
|
||
"post": {
|
||
"description": "上级必须启用；已启用返回 40903",
|
||
"operationId": "DepartmentsController_enable",
|
||
"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"
|
||
]
|
||
}
|
||
},
|
||
"/api/v1/industries": {
|
||
"get": {
|
||
"operationId": "IndustriesController_list",
|
||
"parameters": [],
|
||
"responses": {
|
||
"200": {
|
||
"description": ""
|
||
}
|
||
},
|
||
"security": [
|
||
{
|
||
"bearer": []
|
||
}
|
||
],
|
||
"summary": "两级行业树（一级 → 二级）",
|
||
"tags": [
|
||
"client-industries"
|
||
]
|
||
},
|
||
"post": {
|
||
"operationId": "IndustriesController_create",
|
||
"parameters": [],
|
||
"responses": {
|
||
"201": {
|
||
"description": ""
|
||
}
|
||
},
|
||
"security": [
|
||
{
|
||
"bearer": []
|
||
}
|
||
],
|
||
"summary": "新建一级 / 二级行业",
|
||
"tags": [
|
||
"client-industries"
|
||
]
|
||
}
|
||
},
|
||
"/api/v1/industries/{id}": {
|
||
"get": {
|
||
"operationId": "IndustriesController_detail",
|
||
"parameters": [],
|
||
"responses": {
|
||
"200": {
|
||
"description": ""
|
||
}
|
||
},
|
||
"security": [
|
||
{
|
||
"bearer": []
|
||
}
|
||
],
|
||
"summary": "行业详情与引用（子行业 / 客户 / 资产）",
|
||
"tags": [
|
||
"client-industries"
|
||
]
|
||
},
|
||
"patch": {
|
||
"operationId": "IndustriesController_update",
|
||
"parameters": [],
|
||
"responses": {
|
||
"200": {
|
||
"description": ""
|
||
}
|
||
},
|
||
"security": [
|
||
{
|
||
"bearer": []
|
||
}
|
||
],
|
||
"summary": "更新行业名称 / 排序 / 备注（层级与上级不可变）",
|
||
"tags": [
|
||
"client-industries"
|
||
]
|
||
},
|
||
"delete": {
|
||
"operationId": "IndustriesController_remove",
|
||
"parameters": [],
|
||
"responses": {
|
||
"204": {
|
||
"description": ""
|
||
}
|
||
},
|
||
"security": [
|
||
{
|
||
"bearer": []
|
||
}
|
||
],
|
||
"summary": "删除行业（仅无子行业 / 客户 / 资产时）",
|
||
"tags": [
|
||
"client-industries"
|
||
]
|
||
}
|
||
},
|
||
"/api/v1/industries/{id}/status": {
|
||
"patch": {
|
||
"operationId": "IndustriesController_setStatus",
|
||
"parameters": [],
|
||
"responses": {
|
||
"200": {
|
||
"description": ""
|
||
}
|
||
},
|
||
"security": [
|
||
{
|
||
"bearer": []
|
||
}
|
||
],
|
||
"summary": "停用 / 启用行业（有启用子行业时禁止停用）",
|
||
"tags": [
|
||
"client-industries"
|
||
]
|
||
}
|
||
},
|
||
"/api/v1/customers": {
|
||
"get": {
|
||
"operationId": "CustomersController_list",
|
||
"parameters": [],
|
||
"responses": {
|
||
"200": {
|
||
"description": ""
|
||
}
|
||
},
|
||
"security": [
|
||
{
|
||
"bearer": []
|
||
}
|
||
],
|
||
"summary": "客户列表（游标分页 + 行业 / 状态 / 负责人 / 客户组筛选）",
|
||
"tags": [
|
||
"client-customers"
|
||
]
|
||
},
|
||
"post": {
|
||
"operationId": "CustomersController_create",
|
||
"parameters": [],
|
||
"responses": {
|
||
"201": {
|
||
"description": ""
|
||
}
|
||
},
|
||
"security": [
|
||
{
|
||
"bearer": []
|
||
}
|
||
],
|
||
"summary": "新建客户（简称必填；行业必须为末级行业）",
|
||
"tags": [
|
||
"client-customers"
|
||
]
|
||
}
|
||
},
|
||
"/api/v1/customers/{id}": {
|
||
"get": {
|
||
"operationId": "CustomersController_detail",
|
||
"parameters": [],
|
||
"responses": {
|
||
"200": {
|
||
"description": ""
|
||
}
|
||
},
|
||
"security": [
|
||
{
|
||
"bearer": []
|
||
}
|
||
],
|
||
"summary": "客户详情（跨客户访问统一 404）",
|
||
"tags": [
|
||
"client-customers"
|
||
]
|
||
},
|
||
"patch": {
|
||
"operationId": "CustomersController_update",
|
||
"parameters": [],
|
||
"responses": {
|
||
"200": {
|
||
"description": ""
|
||
}
|
||
},
|
||
"security": [
|
||
{
|
||
"bearer": []
|
||
}
|
||
],
|
||
"summary": "更新客户档案（所属行业不可改；暂停 / 结束只读）",
|
||
"tags": [
|
||
"client-customers"
|
||
]
|
||
}
|
||
},
|
||
"/api/v1/customers/{id}/status": {
|
||
"patch": {
|
||
"operationId": "CustomersController_setStatus",
|
||
"parameters": [],
|
||
"responses": {
|
||
"200": {
|
||
"description": ""
|
||
}
|
||
},
|
||
"security": [
|
||
{
|
||
"bearer": []
|
||
}
|
||
],
|
||
"summary": "客户状态：在服务 ⇄ 暂停 → 结束（结束不可逆）",
|
||
"tags": [
|
||
"client-customers"
|
||
]
|
||
}
|
||
},
|
||
"/api/v1/customers/{id}/transfer": {
|
||
"post": {
|
||
"operationId": "CustomersController_transfer",
|
||
"parameters": [],
|
||
"responses": {
|
||
"200": {
|
||
"description": ""
|
||
}
|
||
},
|
||
"security": [
|
||
{
|
||
"bearer": []
|
||
}
|
||
],
|
||
"summary": "变更客户负责人（写审计）",
|
||
"tags": [
|
||
"client-customers"
|
||
]
|
||
}
|
||
},
|
||
"/api/v1/customers/{id}/groups": {
|
||
"put": {
|
||
"operationId": "CustomersController_setGroups",
|
||
"parameters": [],
|
||
"responses": {
|
||
"200": {
|
||
"description": ""
|
||
}
|
||
},
|
||
"security": [
|
||
{
|
||
"bearer": []
|
||
}
|
||
],
|
||
"summary": "设置客户所属客户组（覆盖式）",
|
||
"tags": [
|
||
"client-customers"
|
||
]
|
||
}
|
||
},
|
||
"/api/v1/customers/{id}/apply-industry-pack": {
|
||
"post": {
|
||
"operationId": "CustomersController_applyIndustryPack",
|
||
"parameters": [],
|
||
"responses": {
|
||
"200": {
|
||
"description": ""
|
||
}
|
||
},
|
||
"security": [
|
||
{
|
||
"bearer": []
|
||
}
|
||
],
|
||
"summary": "套用行业资产包（B0 批次提供；当前返回业务提示）",
|
||
"tags": [
|
||
"client-customers"
|
||
]
|
||
}
|
||
},
|
||
"/api/v1/users/{id}/transfer-customers": {
|
||
"post": {
|
||
"operationId": "CustomerTransferController_transfer",
|
||
"parameters": [],
|
||
"responses": {
|
||
"200": {
|
||
"description": ""
|
||
}
|
||
},
|
||
"security": [
|
||
{
|
||
"bearer": []
|
||
}
|
||
],
|
||
"summary": "把用户名下客户转交给另一负责人",
|
||
"tags": [
|
||
"client-customers"
|
||
]
|
||
}
|
||
},
|
||
"/api/v1/customer-groups": {
|
||
"get": {
|
||
"operationId": "CustomerGroupsController_list",
|
||
"parameters": [],
|
||
"responses": {
|
||
"200": {
|
||
"description": ""
|
||
}
|
||
},
|
||
"security": [
|
||
{
|
||
"bearer": []
|
||
}
|
||
],
|
||
"summary": "客户组列表（授权与数据范围最小单位）",
|
||
"tags": [
|
||
"client-customer-groups"
|
||
]
|
||
},
|
||
"post": {
|
||
"operationId": "CustomerGroupsController_create",
|
||
"parameters": [],
|
||
"responses": {
|
||
"201": {
|
||
"description": ""
|
||
}
|
||
},
|
||
"security": [
|
||
{
|
||
"bearer": []
|
||
}
|
||
],
|
||
"summary": "新建客户组",
|
||
"tags": [
|
||
"client-customer-groups"
|
||
]
|
||
}
|
||
},
|
||
"/api/v1/customer-groups/{id}": {
|
||
"get": {
|
||
"operationId": "CustomerGroupsController_detail",
|
||
"parameters": [],
|
||
"responses": {
|
||
"200": {
|
||
"description": ""
|
||
}
|
||
},
|
||
"security": [
|
||
{
|
||
"bearer": []
|
||
}
|
||
],
|
||
"summary": "客户组详情与成员",
|
||
"tags": [
|
||
"client-customer-groups"
|
||
]
|
||
},
|
||
"patch": {
|
||
"operationId": "CustomerGroupsController_update",
|
||
"parameters": [],
|
||
"responses": {
|
||
"200": {
|
||
"description": ""
|
||
}
|
||
},
|
||
"security": [
|
||
{
|
||
"bearer": []
|
||
}
|
||
],
|
||
"summary": "更新客户组名称 / 说明",
|
||
"tags": [
|
||
"client-customer-groups"
|
||
]
|
||
},
|
||
"delete": {
|
||
"operationId": "CustomerGroupsController_remove",
|
||
"parameters": [],
|
||
"responses": {
|
||
"204": {
|
||
"description": ""
|
||
}
|
||
},
|
||
"security": [
|
||
{
|
||
"bearer": []
|
||
}
|
||
],
|
||
"summary": "删除客户组（被角色数据范围引用时拒绝）",
|
||
"tags": [
|
||
"client-customer-groups"
|
||
]
|
||
}
|
||
},
|
||
"/api/v1/customer-groups/{id}/members": {
|
||
"post": {
|
||
"operationId": "CustomerGroupsController_updateMembers",
|
||
"parameters": [],
|
||
"responses": {
|
||
"200": {
|
||
"description": ""
|
||
}
|
||
},
|
||
"security": [
|
||
{
|
||
"bearer": []
|
||
}
|
||
],
|
||
"summary": "批量添加 / 移除成员（幂等）",
|
||
"tags": [
|
||
"client-customer-groups"
|
||
]
|
||
}
|
||
},
|
||
"/api/v1/customer-fields": {
|
||
"get": {
|
||
"operationId": "CustomerFieldsController_list",
|
||
"parameters": [],
|
||
"responses": {
|
||
"200": {
|
||
"description": ""
|
||
}
|
||
},
|
||
"security": [
|
||
{
|
||
"bearer": []
|
||
}
|
||
],
|
||
"summary": "字段审批队列（待审批 / 已生效 / 已驳回）",
|
||
"tags": [
|
||
"client-customer-fields"
|
||
]
|
||
}
|
||
},
|
||
"/api/v1/customer-fields/{id}/approve": {
|
||
"post": {
|
||
"operationId": "CustomerFieldsController_approve",
|
||
"parameters": [],
|
||
"responses": {
|
||
"200": {
|
||
"description": ""
|
||
}
|
||
},
|
||
"security": [
|
||
{
|
||
"bearer": []
|
||
}
|
||
],
|
||
"summary": "审批客户级字段（通过 / 驳回；驳回原因必填）",
|
||
"tags": [
|
||
"client-customer-fields"
|
||
]
|
||
}
|
||
},
|
||
"/api/v1/customers/{id}/fields": {
|
||
"get": {
|
||
"operationId": "CustomerFieldsOfCustomerController_list",
|
||
"parameters": [],
|
||
"responses": {
|
||
"200": {
|
||
"description": ""
|
||
}
|
||
},
|
||
"security": [
|
||
{
|
||
"bearer": []
|
||
}
|
||
],
|
||
"summary": "客户级字段列表（基础字段在 customers.custom_fields）",
|
||
"tags": [
|
||
"client-customer-fields"
|
||
]
|
||
},
|
||
"post": {
|
||
"operationId": "CustomerFieldsOfCustomerController_apply",
|
||
"parameters": [],
|
||
"responses": {
|
||
"201": {
|
||
"description": ""
|
||
}
|
||
},
|
||
"security": [
|
||
{
|
||
"bearer": []
|
||
}
|
||
],
|
||
"summary": "申请客户级字段（进入生成字段需审批；每客户 ≤ 5）",
|
||
"tags": [
|
||
"client-customer-fields"
|
||
]
|
||
}
|
||
},
|
||
"/api/v1/dicts": {
|
||
"get": {
|
||
"operationId": "DictsController_list",
|
||
"parameters": [],
|
||
"responses": {
|
||
"200": {
|
||
"description": ""
|
||
}
|
||
},
|
||
"security": [
|
||
{
|
||
"bearer": []
|
||
}
|
||
],
|
||
"summary": "字典类型列表（分组顺序 + 排序；含条目 / 行业层统计）",
|
||
"tags": [
|
||
"catalog-dicts"
|
||
]
|
||
},
|
||
"post": {
|
||
"operationId": "DictsController_create",
|
||
"parameters": [],
|
||
"responses": {
|
||
"201": {
|
||
"description": ""
|
||
}
|
||
},
|
||
"security": [
|
||
{
|
||
"bearer": []
|
||
}
|
||
],
|
||
"summary": "新建字典类型（编码唯一；builtin=false）",
|
||
"tags": [
|
||
"catalog-dicts"
|
||
]
|
||
}
|
||
},
|
||
"/api/v1/dicts/{code}": {
|
||
"get": {
|
||
"operationId": "DictsController_detail",
|
||
"parameters": [],
|
||
"responses": {
|
||
"200": {
|
||
"description": ""
|
||
}
|
||
},
|
||
"security": [
|
||
{
|
||
"bearer": []
|
||
}
|
||
],
|
||
"summary": "字典类型详情（不存在 40401）",
|
||
"tags": [
|
||
"catalog-dicts"
|
||
]
|
||
},
|
||
"patch": {
|
||
"operationId": "DictsController_update",
|
||
"parameters": [],
|
||
"responses": {
|
||
"200": {
|
||
"description": ""
|
||
}
|
||
},
|
||
"security": [
|
||
{
|
||
"bearer": []
|
||
}
|
||
],
|
||
"summary": "更新字典类型（编码 / 形态 / 行业作用域不可改）",
|
||
"tags": [
|
||
"catalog-dicts"
|
||
]
|
||
},
|
||
"delete": {
|
||
"operationId": "DictsController_remove",
|
||
"parameters": [],
|
||
"responses": {
|
||
"204": {
|
||
"description": ""
|
||
}
|
||
},
|
||
"security": [
|
||
{
|
||
"bearer": []
|
||
}
|
||
],
|
||
"summary": "删除自定义字典类型（内置 / 有子条目时不可删）",
|
||
"tags": [
|
||
"catalog-dicts"
|
||
]
|
||
}
|
||
},
|
||
"/api/v1/dicts/{code}/status": {
|
||
"patch": {
|
||
"operationId": "DictsController_setStatus",
|
||
"parameters": [],
|
||
"responses": {
|
||
"200": {
|
||
"description": ""
|
||
}
|
||
},
|
||
"security": [
|
||
{
|
||
"bearer": []
|
||
}
|
||
],
|
||
"summary": "启用 / 停用字典类型（内置类型允许停用）",
|
||
"tags": [
|
||
"catalog-dicts"
|
||
]
|
||
}
|
||
},
|
||
"/api/v1/dicts/{code}/items": {
|
||
"get": {
|
||
"operationId": "DictsController_listItems",
|
||
"parameters": [],
|
||
"responses": {
|
||
"200": {
|
||
"description": ""
|
||
}
|
||
},
|
||
"security": [
|
||
{
|
||
"bearer": []
|
||
}
|
||
],
|
||
"summary": "生效条目列表（industry_id 三层合并；非行业类型忽略该参数）",
|
||
"tags": [
|
||
"catalog-dicts"
|
||
]
|
||
},
|
||
"post": {
|
||
"operationId": "DictsController_createItem",
|
||
"parameters": [],
|
||
"responses": {
|
||
"201": {
|
||
"description": ""
|
||
}
|
||
},
|
||
"security": [
|
||
{
|
||
"bearer": []
|
||
}
|
||
],
|
||
"summary": "新建字典条目（编码 / 父级 / 行业校验；编码创建后不可改）",
|
||
"tags": [
|
||
"catalog-dicts"
|
||
]
|
||
}
|
||
},
|
||
"/api/v1/dicts/{code}/items/{itemId}": {
|
||
"patch": {
|
||
"operationId": "DictsController_updateItem",
|
||
"parameters": [],
|
||
"responses": {
|
||
"200": {
|
||
"description": ""
|
||
}
|
||
},
|
||
"security": [
|
||
{
|
||
"bearer": []
|
||
}
|
||
],
|
||
"summary": "更新字典条目（仅名称 / 排序 / 启停 / 备注）",
|
||
"tags": [
|
||
"catalog-dicts"
|
||
]
|
||
}
|
||
},
|
||
"/api/v1/system/configs": {
|
||
"get": {
|
||
"operationId": "SystemConfigController_list",
|
||
"parameters": [],
|
||
"responses": {
|
||
"200": {
|
||
"description": ""
|
||
}
|
||
},
|
||
"security": [
|
||
{
|
||
"bearer": []
|
||
}
|
||
],
|
||
"summary": "全量系统配置（定义元数据 + 当前值 / 版本）",
|
||
"tags": [
|
||
"platform-system-configs"
|
||
]
|
||
},
|
||
"put": {
|
||
"operationId": "SystemConfigController_update",
|
||
"parameters": [],
|
||
"responses": {
|
||
"200": {
|
||
"description": ""
|
||
}
|
||
},
|
||
"security": [
|
||
{
|
||
"bearer": []
|
||
}
|
||
],
|
||
"summary": "批量保存配置（乐观锁 expectedVersion；写版本历史与审计）",
|
||
"tags": [
|
||
"platform-system-configs"
|
||
]
|
||
}
|
||
},
|
||
"/api/v1/system/configs/effective": {
|
||
"get": {
|
||
"operationId": "SystemConfigController_effective",
|
||
"parameters": [],
|
||
"responses": {
|
||
"200": {
|
||
"description": ""
|
||
}
|
||
},
|
||
"security": [
|
||
{
|
||
"bearer": []
|
||
}
|
||
],
|
||
"summary": "生效配置（仅登录；只返回 public 项，前端上限读取入口）",
|
||
"tags": [
|
||
"platform-system-configs"
|
||
]
|
||
}
|
||
},
|
||
"/api/v1/system/configs/history": {
|
||
"get": {
|
||
"operationId": "SystemConfigController_history",
|
||
"parameters": [],
|
||
"responses": {
|
||
"200": {
|
||
"description": ""
|
||
}
|
||
},
|
||
"security": [
|
||
{
|
||
"bearer": []
|
||
}
|
||
],
|
||
"summary": "配置变更记录（按变更时间倒序；操作人为用户姓名）",
|
||
"tags": [
|
||
"platform-system-configs"
|
||
]
|
||
}
|
||
},
|
||
"/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
|
||
}
|
||
}
|