Stev_Wang
6661c42e84
ci / 质量门禁 (push) Canceled after 0s
背景：
- A1 只实现了部门树读取与新建 / 改名接口，没有部门管理入口，
负责人、排序、停用状态都无法维护；
- 用户必须关联部门，部门无法维护会让 A2 的数据范围缺少组织基础。
改动：
- shared：DepartmentNode 增加 status / sortOrder / directMemberCount；
新增 createDepartmentInput / updateDepartmentInput / departmentTreeQuery 契约；
- api：GET /departments/tree?include_disabled；POST/PATCH /departments
（名称 / 负责人 / 排序）；POST /departments/{id}/disable|enable；
只停用不删除，有在职成员 / 启用子部门 / 下级在职成员时禁止停用；
新建 / 编辑用户校验部门必须启用；@Audit 与 OpenAPI 同步；
- web：管理中心新增「部门管理」/system/departments，左两级组织树 +
右详情 / 内联编辑 + 新建部门/小组 + 停用启用二次确认；显示已停用、
?id= 选中可恢复、无 user:manage 只读；用户页部门选择仍只取启用部门；
- 测试：shared 契约、api 单测 + int、web 树/表单/接口单测同步。
影响面：
- 新增部门写接口与页面；GET tree 默认仍只返回启用部门，对用户页无破坏；
- 权限复用 user:view / user:manage，不新增权限点；
- 无数据库迁移（status / leader_user_id / sort_order 列已存在）。
回滚方式：
- 回滚本提交即移除部门管理页与写接口，保留原只读树；数据库无需回滚。
验证证据：
- pnpm format:check / lint / typecheck 全绿；
- pnpm test：shared 121 / api 90 / web 120；test:int 4 files / 33 tests；
- pnpm openapi:diff：无破坏性变更；
- 真实 API + 浏览器（jiang.lan）：新建一级部门 / 小组、改名、停用空小组、
重名 40903、树/详情/停用确认均正常；
截图 design/a1-ui-v1/shots/impl/70-departments.png。
749 lines
17 KiB
JSON
749 lines
17 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": {
|
|
"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"
|
|
]
|
|
}
|
|
},
|
|
"/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
|
|
}
|
|
}
|