Stev_Wang
4d9eb980af
ci / 质量门禁 (push) Canceled after 0s
背景： - 开发计划 A1 批次要求登录/刷新/登出、用户生命周期、路由与按钮权限、 权限三态用例；视觉已选定方案 B（主从分栏 + 分屏登录）。 改动： - packages/shared：新增 identity 契约（User/Me/Login/Refresh/Department/Role） 与 user:view 权限点；写接口 strict 校验。 - apps/api：新增 identity 模块与 Prisma expand 迁移（departments/users/roles/ user_roles/role_permissions/refresh_tokens）；Argon2id、JWT access+refresh 旋转与 jti 吊销、登录失败锁定、首登强改、守卫链、/me、@Audit 上下文、幂等种子。 - apps/web：按方案 B 落地 /users、/users/new、/users/:id、分屏登录与 403； usePermission/<Can>、路由守卫、401 单飞刷新、停用会话兜底、Semi + token。 - e2e：新增 A1-QA-01 六类端到端用例（A1_E2E 门控）。 - openapi 与前端生成类型同步；.env.example 登记认证变量；实施报告入库。 影响面： - 新增运行时依赖 @nestjs/jwt、argon2（计划 A1-BE-02 已批准，版本精确锁定）。 - 迁移为 expand，不改既有表；本地需 prisma migrate 后重新 seed。 - 平台导航「用户与组织」由 /platform/users 调整为 /users。 回滚方式： - 代码整体回滚本提交；迁移为 expand，回滚代码不需删表； - 本地如需彻底回退按实施报告 §6 处理。 验证证据： - pnpm format:check / lint / typecheck 通过； - pnpm test：shared 95 / api 60 / web 55； - pnpm test:int：7 个（真实 PG/Redis）； - A1_E2E=1 playwright test e2e/a1-identity.spec.ts：6/6； - 报告：docs/开发计划/灵犀_A1身份认证与用户管理_实施报告_V0.1.md
593 lines
13 KiB
JSON
593 lines
13 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": {
|
|
"operationId": "RolesController_list",
|
|
"parameters": [],
|
|
"responses": {
|
|
"200": {
|
|
"description": ""
|
|
}
|
|
},
|
|
"security": [
|
|
{
|
|
"bearer": []
|
|
}
|
|
],
|
|
"summary": "角色列表（绑定用）",
|
|
"tags": [
|
|
"identity-roles"
|
|
]
|
|
}
|
|
},
|
|
"/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
|
|
}
|
|
}
|