main: 增强会话功能，支持消息管理和接口文档
- 添加 `last_message_id` 字段至 `chat_sessions` 表，更新其关联索引 - 实现会话更新接口，支持修改名称与状态并添加验证逻辑 - 增加会话列表接口，支持状态过滤与关键字查询 - 提供会话和消息相关的资源类和请求验证类 - 扩展 `ChatService` 服务层逻辑以处理会话更新和消息附加 - 编写测试用例以验证新功能的正确性 - 增加接口文档及 OpenAPI 规范文件，覆盖新增功能 - 更新数据库播种器，添加默认用户
This commit is contained in:
84
docs/User/user-api.md
Normal file
84
docs/User/user-api.md
Normal file
@@ -0,0 +1,84 @@
|
||||
# 接口文档（JWT，无状态 API）
|
||||
|
||||
基地址：`http://localhost:8000/api`（容器默认映射 8000 端口）
|
||||
自然语言：中文
|
||||
|
||||
- 认证方式：在请求头添加 `Authorization: Bearer {token}`。
|
||||
- 默认账号（来自 `php artisan db:seed`）：`root@example.com` / `Root@123456`。
|
||||
- 所有接口均返回 JSON；失败时返回 `{ "message": "错误信息" }`。
|
||||
- 跨域：默认允许 `http://localhost:5173`，可通过环境变量 `CORS_ALLOWED_ORIGINS`（逗号分隔多个域名）调整。
|
||||
|
||||
## 健康检查
|
||||
- `GET /health`
|
||||
响应：`{ "status": "ok" }`
|
||||
|
||||
## 登录
|
||||
- `POST /login`
|
||||
- 请求体：
|
||||
```json
|
||||
{ "email": "user@example.com", "password": "Password123" }
|
||||
```
|
||||
- 响应 200：
|
||||
```json
|
||||
{
|
||||
"token": "jwt-token",
|
||||
"token_type": "bearer",
|
||||
"expires_in": 3600,
|
||||
"user": { "id": 1, "name": "root", "email": "root@example.com", "is_active": true }
|
||||
}
|
||||
```
|
||||
- 401：凭证无效；403：用户已停用。
|
||||
|
||||
## 当前用户
|
||||
- `GET /me`（需要 JWT）
|
||||
- 响应 200：当前登录用户信息。
|
||||
|
||||
## 用户管理（需 JWT）
|
||||
字段约束：`name` 必填字符串（<=255）、`email` 邮箱唯一、`password` 最少 8 字符。
|
||||
|
||||
### 用户列表
|
||||
- `GET /users`
|
||||
- 查询参数：`page`（默认 1）、`per_page`（默认 15，最大 100）
|
||||
- 响应 200：分页列表，`data` 为用户数组，包含 `id/name/email/is_active/created_at/updated_at`。
|
||||
|
||||
### 创建用户
|
||||
- `POST /users`
|
||||
- 请求体：
|
||||
```json
|
||||
{ "name": "Alice", "email": "alice@example.com", "password": "Password123" }
|
||||
```
|
||||
- 响应 201：新建用户（含 `is_active: true`）。
|
||||
|
||||
### 更新用户
|
||||
- `PUT /users/{id}`
|
||||
- 请求体（任意字段可选）：
|
||||
```json
|
||||
{ "name": "New Name", "email": "new@example.com", "password": "NewPass123" }
|
||||
```
|
||||
- 响应 200：更新后的用户。
|
||||
|
||||
### 停用用户
|
||||
- `POST /users/{id}/deactivate`
|
||||
- 响应 200：`is_active` 为 `false`。
|
||||
|
||||
### 启用用户
|
||||
- `POST /users/{id}/activate`
|
||||
- 响应 200：`is_active` 为 `true`。
|
||||
|
||||
## 示例（cURL）
|
||||
```bash
|
||||
# 登录
|
||||
curl -X POST http://localhost:8000/api/login \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"email":"root@example.com","password":"Root@123456"}'
|
||||
|
||||
# 创建用户（替换 TOKEN）
|
||||
curl -X POST http://localhost:8000/api/users \
|
||||
-H "Authorization: Bearer TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"name":"Alice","email":"alice@example.com","password":"Password123"}'
|
||||
|
||||
# 获取用户列表（替换 TOKEN）
|
||||
curl -X GET http://localhost:8000/api/users \
|
||||
-H "Authorization: Bearer TOKEN"
|
||||
```
|
||||
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