main: 增强会话功能，支持消息管理和接口文档
- 添加 `last_message_id` 字段至 `chat_sessions` 表，更新其关联索引 - 实现会话更新接口，支持修改名称与状态并添加验证逻辑 - 增加会话列表接口，支持状态过滤与关键字查询 - 提供会话和消息相关的资源类和请求验证类 - 扩展 `ChatService` 服务层逻辑以处理会话更新和消息附加 - 编写测试用例以验证新功能的正确性 - 增加接口文档及 OpenAPI 规范文件，覆盖新增功能 - 更新数据库播种器，添加默认用户
This commit is contained in:
365
docs/User/user-openapi.yaml
Normal file
365
docs/User/user-openapi.yaml
Normal file
@@ -0,0 +1,365 @@
|
||||
openapi: 3.0.3
|
||||
info:
|
||||
title: ars-backend API (JWT)
|
||||
version: 1.0.0
|
||||
description: |
|
||||
ars-backend 无状态 API，认证方式为 JWT Bearer。自然语言：中文。
|
||||
servers:
|
||||
- url: http://localhost:8000/api
|
||||
description: 本地开发（FrankenPHP Octane，Docker）
|
||||
tags:
|
||||
- name: System
|
||||
description: 系统与健康检查
|
||||
- name: Auth
|
||||
description: 认证相关接口
|
||||
- name: Users
|
||||
description: 用户管理接口（需 JWT）
|
||||
paths:
|
||||
/health:
|
||||
get:
|
||||
tags: [System]
|
||||
summary: 健康检查
|
||||
responses:
|
||||
"200":
|
||||
description: 服务可用
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
status:
|
||||
type: string
|
||||
example: ok
|
||||
/login:
|
||||
post:
|
||||
tags: [Auth]
|
||||
summary: 用户登录
|
||||
description: 使用邮箱和密码换取 JWT，停用用户返回 403。
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/LoginRequest'
|
||||
responses:
|
||||
"200":
|
||||
description: 登录成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/AuthResponse'
|
||||
"401":
|
||||
description: 凭证无效
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Error'
|
||||
"403":
|
||||
description: 用户已停用
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Error'
|
||||
/me:
|
||||
get:
|
||||
tags: [Auth]
|
||||
summary: 获取当前用户
|
||||
security:
|
||||
- bearerAuth: []
|
||||
responses:
|
||||
"200":
|
||||
description: 当前登录用户
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/User'
|
||||
"401":
|
||||
description: 未授权或 token 失效
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Error'
|
||||
/users:
|
||||
get:
|
||||
tags: [Users]
|
||||
summary: 用户列表
|
||||
security:
|
||||
- bearerAuth: []
|
||||
parameters:
|
||||
- in: query
|
||||
name: page
|
||||
schema:
|
||||
type: integer
|
||||
default: 1
|
||||
description: 页码（默认 1）
|
||||
- in: query
|
||||
name: per_page
|
||||
schema:
|
||||
type: integer
|
||||
default: 15
|
||||
maximum: 100
|
||||
description: 每页数量（1-100，默认 15）
|
||||
responses:
|
||||
"200":
|
||||
description: 分页用户列表
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/UserPagination'
|
||||
"401":
|
||||
description: 未授权
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Error'
|
||||
post:
|
||||
tags: [Users]
|
||||
summary: 创建用户
|
||||
security:
|
||||
- bearerAuth: []
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/CreateUserRequest'
|
||||
responses:
|
||||
"201":
|
||||
description: 创建成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/User'
|
||||
"401":
|
||||
description: 未授权
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Error'
|
||||
"422":
|
||||
description: 参数校验失败
|
||||
/users/{id}:
|
||||
put:
|
||||
tags: [Users]
|
||||
summary: 更新用户
|
||||
security:
|
||||
- bearerAuth: []
|
||||
parameters:
|
||||
- name: id
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: integer
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/UpdateUserRequest'
|
||||
responses:
|
||||
"200":
|
||||
description: 更新成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/User'
|
||||
"401":
|
||||
description: 未授权
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Error'
|
||||
"422":
|
||||
description: 参数校验失败
|
||||
/users/{id}/deactivate:
|
||||
post:
|
||||
tags: [Users]
|
||||
summary: 停用用户
|
||||
security:
|
||||
- bearerAuth: []
|
||||
parameters:
|
||||
- name: id
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: integer
|
||||
responses:
|
||||
"200":
|
||||
description: 已停用
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/User'
|
||||
"401":
|
||||
description: 未授权
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Error'
|
||||
/users/{id}/activate:
|
||||
post:
|
||||
tags: [Users]
|
||||
summary: 启用用户
|
||||
security:
|
||||
- bearerAuth: []
|
||||
parameters:
|
||||
- name: id
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: integer
|
||||
responses:
|
||||
"200":
|
||||
description: 已启用
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/User'
|
||||
"401":
|
||||
description: 未授权
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Error'
|
||||
components:
|
||||
securitySchemes:
|
||||
bearerAuth:
|
||||
type: http
|
||||
scheme: bearer
|
||||
bearerFormat: JWT
|
||||
schemas:
|
||||
User:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
type: integer
|
||||
example: 1
|
||||
name:
|
||||
type: string
|
||||
example: root
|
||||
email:
|
||||
type: string
|
||||
format: email
|
||||
example: root@example.com
|
||||
is_active:
|
||||
type: boolean
|
||||
example: true
|
||||
created_at:
|
||||
type: string
|
||||
format: date-time
|
||||
example: 2025-12-14T05:37:47.000000Z
|
||||
updated_at:
|
||||
type: string
|
||||
format: date-time
|
||||
example: 2025-12-14T05:37:47.000000Z
|
||||
LoginRequest:
|
||||
type: object
|
||||
required: [email, password]
|
||||
properties:
|
||||
email:
|
||||
type: string
|
||||
format: email
|
||||
example: root@example.com
|
||||
password:
|
||||
type: string
|
||||
format: password
|
||||
example: Root@123456
|
||||
CreateUserRequest:
|
||||
type: object
|
||||
required: [name, email, password]
|
||||
properties:
|
||||
name:
|
||||
type: string
|
||||
example: Alice
|
||||
email:
|
||||
type: string
|
||||
format: email
|
||||
example: alice@example.com
|
||||
password:
|
||||
type: string
|
||||
format: password
|
||||
example: Password123
|
||||
UpdateUserRequest:
|
||||
type: object
|
||||
properties:
|
||||
name:
|
||||
type: string
|
||||
example: Alice Updated
|
||||
email:
|
||||
type: string
|
||||
format: email
|
||||
example: alice.updated@example.com
|
||||
password:
|
||||
type: string
|
||||
format: password
|
||||
example: NewPassword123
|
||||
AuthResponse:
|
||||
type: object
|
||||
properties:
|
||||
token:
|
||||
type: string
|
||||
example: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
|
||||
token_type:
|
||||
type: string
|
||||
example: bearer
|
||||
expires_in:
|
||||
type: integer
|
||||
example: 3600
|
||||
user:
|
||||
$ref: '#/components/schemas/User'
|
||||
Error:
|
||||
type: object
|
||||
properties:
|
||||
message:
|
||||
type: string
|
||||
example: 凭证无效
|
||||
UserPagination:
|
||||
type: object
|
||||
properties:
|
||||
data:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/User'
|
||||
links:
|
||||
$ref: '#/components/schemas/PaginationLinks'
|
||||
meta:
|
||||
$ref: '#/components/schemas/PaginationMeta'
|
||||
PaginationLinks:
|
||||
type: object
|
||||
properties:
|
||||
first:
|
||||
type: string
|
||||
example: http://localhost:8000/api/users?page=1
|
||||
last:
|
||||
type: string
|
||||
example: http://localhost:8000/api/users?page=1
|
||||
prev:
|
||||
type: string
|
||||
nullable: true
|
||||
next:
|
||||
type: string
|
||||
nullable: true
|
||||
PaginationMeta:
|
||||
type: object
|
||||
properties:
|
||||
current_page:
|
||||
type: integer
|
||||
example: 1
|
||||
from:
|
||||
type: integer
|
||||
example: 1
|
||||
last_page:
|
||||
type: integer
|
||||
example: 1
|
||||
path:
|
||||
type: string
|
||||
example: http://localhost:8000/api/users
|
||||
per_page:
|
||||
type: integer
|
||||
example: 15
|
||||
to:
|
||||
type: integer
|
||||
example: 3
|
||||
total:
|
||||
type: integer
|
||||
example: 3
|
||||
Reference in New Issue
Block a user