itstudio_manager/API.md

API 文档

Base URL：http://localhost:8080/api

通用约定

所有接口均返回统一 JSON 结构：

class Response<T> {
    "code": number;
    "message": string;
    "data": T | null;
}

• code === 200 表示成功；code !== 200 时 data 恒为 null
• 除特别标注（公开）外，接口需在请求头携带 Authorization: Bearer <token>
• 下文路径均省略 /api 前缀，data 仅给出 T 的声明
• 部分 /test 接口的返回值不遵循上述格式

接口总览

分组	路径前缀	说明
测试	/test	连通性测试
认证	/v1/auth	登录 / 注册 / 验证码 / Token 管理
物品管理	/v1/items	物品 / 类别 / 图片 CRUD、借还、上下架查询

---

分组：测试 /test

GET /hello

公开接口。

响应

"Hello Kotlin WebFlux!"

---

分组：认证 /v1/auth

方法	路径	认证	说明
POST	/login	公开	登录，获取 Token
GET	/logout	需要	注销，Token 加入黑名单
GET	/ask-code	公开	发送邮箱验证码
POST	/register	公开	邮箱注册
POST	/reset	公开	重置密码
GET	/relogin	需要	用旧 Token 换取新 Token

POST /login

请求参数

字段	类型	说明
username	string	用户名
password	string	密码

响应 data

class data {
    "username": string;
    "role": string;
    "token": string;
    "expire": Date;
}

GET /logout

请求参数：无

响应 data：null

GET /ask-code

请求参数

字段	类型	说明
email	string	接收验证码的邮箱
type	register | reset	验证码用途（注册 / 重置密码）

响应 data：null

POST /register

请求体字段：email、code、username、password

响应 data：null

POST /reset

请求体字段：email、code、password

响应 data：null

GET /relogin

请求参数：无

响应 data

class data {
    "token": string;
    "expire": time;
}

---

分组：物品管理 /v1/items

方法	路径	认证	说明
GET	/items	需要	分页查询物品
POST	/items	需要	创建物品
PUT	/items	需要	更新物品
DELETE	/items	需要	删除物品（同时清理其图片）
POST	/items/{id}/upload_images	需要	上传物品图片（multipart）
POST	/items/{id}/set_primary_image	需要	设置物品主图
POST	/items/{id}/borrow	需要	借用物品（扣减可用库存）
POST	/items/{id}/return_item	需要	归还物品（恢复可用库存）
GET	/items/available	需要	获取可用物品列表
GET	/items/in_use	需要	获取使用中物品列表
GET	/items/categories	需要	查询物品类别列表
POST	/items/categories	需要	创建物品类别
PUT	/items/categories	需要	更新物品类别
DELETE	/items/categories	需要	删除物品类别
GET	/items/images	需要	查询物品图片列表
POST	/items/images	需要	创建物品图片
PUT	/items/images	需要	更新物品图片
DELETE	/items/images	需要	删除物品图片（同时删除物理文件）

实体定义

class Item {
    "id": number | null;
    "code": string;                 // 物品编号 / 资产编号
    "name": string;
    "categoryId": number | null;
    "model": string | null;
    "brand": string | null;
    "location": string | null;
    "totalQuantity": number;
    "availableQuantity": number;
    "unit": string;                 // 默认 "件"
    "price": number | null;
    "purchaseDate": string | null;
    "supplier": string | null;
    "status": string;               // normal / disabled / lost / repair
    "description": string | null;
    "imagePath": string | null;
    "createdBy": number | null;
    "createdAt": string | null;
    "updatedAt": string | null;
}

class Category {
    "id": number | null;
    "name": string;
    "parentId": number | null;
    "description": string | null;
    "createdAt": string | null;
    "updatedAt": string | null;
}

class Attachment {
    "id": number | null;
    "relatedTable": string | null;  // 关联表名，如 "items"
    "relatedId": number | null;     // 关联记录 ID
    "fileName": string | null;
    "filePath": string | null;
    "fileSize": number | null;
    "contentType": string | null;
    "uploadedBy": number | null;
    "uploadedAt": string | null;
}

class Page<T> {
    "records": T[];
    "total": number;
    "size": number;
    "current": number;
    "pages": number;
}

GET /items

请求参数

字段	类型	说明
pageNum	number	页码，默认 1
pageSize	number	每页条数，默认 10
keyword	string?	按名称 / 编号模糊搜索
status	string?	按状态过滤，如 normal

响应 data：Page<Item>

POST /items

请求体：Item（id / createdAt / updatedAt 由服务端填充）

响应 data：null

PUT /items

请求体：Item（须包含 id）

响应 data：null

DELETE /items

请求参数

字段	类型	说明
id	number	物品 ID

响应 data：null

POST /items/{id}/upload_images

请求：multipart/form-data，字段名 files，可传多个图片文件

响应 data：null

POST /items/{id}/set_primary_image

请求参数

字段	类型	说明
imageId	number	附件 ID，须属于该物品

响应 data：null

POST /items/{id}/borrow

请求参数

字段	类型	说明
quantity	number	借用数量，默认 1

响应 data：null

POST /items/{id}/return_item

请求参数

字段	类型	说明
quantity	number	归还数量，默认 1

响应 data：null

GET /items/available

请求参数：无

响应 data：Item[]

GET /items/in_use

请求参数：无

响应 data：Item[]

GET /items/categories

请求参数：无

响应 data：Category[]

POST /items/categories

请求体：Category（id / createdAt / updatedAt 由服务端填充）

响应 data：null

PUT /items/categories

请求体：Category（须包含 id）

响应 data：null

DELETE /items/categories

请求参数

字段	类型	说明
id	number	类别 ID

响应 data：null

GET /items/images

请求参数：无

响应 data：Attachment[]（relatedTable 为 "items" 的图片）

POST /items/images

请求体：Attachment（id / uploadedAt 由服务端填充）

响应 data：null

PUT /items/images

请求体：Attachment（须包含 id）

响应 data：null

DELETE /items/images

请求参数

字段	类型	说明
id	number	图片 ID

响应 data：null

---

其他

WebSocket

ws://localhost:8080/ws — 目前不支持