forked from ITStudio_OUC/itstudio_manager
Merge pull request 'feat: ready for ItemApi' (#4) from backend-dev into main
Reviewed-on: ITStudio_OUC/itstudio_manager#4
This commit is contained in:
+5
@@ -1,6 +1,11 @@
|
||||
<component name="InspectionProjectProfileManager">
|
||||
<profile version="1.0">
|
||||
<option name="myName" value="Project Default" />
|
||||
<inspection_tool class="DuplicatedCode" enabled="true" level="WEAK WARNING" enabled_by_default="true">
|
||||
<Languages>
|
||||
<language minSize="49" name="Kotlin" />
|
||||
</Languages>
|
||||
</inspection_tool>
|
||||
<inspection_tool class="PyShadowingBuiltinsInspection" enabled="true" level="WEAK WARNING" enabled_by_default="true">
|
||||
<option name="ignoredNames">
|
||||
<list>
|
||||
|
||||
@@ -1,44 +1,69 @@
|
||||
# http://localhost:8080/api
|
||||
# API 文档
|
||||
|
||||
所有返回的json对象总有如下格式
|
||||
Base URL：`http://localhost:8080/api`
|
||||
|
||||
## 通用约定
|
||||
|
||||
所有接口均返回统一 JSON 结构：
|
||||
|
||||
```typescript
|
||||
class respose<T> {
|
||||
class Response<T> {
|
||||
"code": number;
|
||||
"message": string;
|
||||
"data": T
|
||||
"data": T | null;
|
||||
}
|
||||
```
|
||||
|
||||
接下来将省略`/api`并只给出`T`的类声明
|
||||
- `code === 200` 表示成功；**`code !== 200` 时 `data` 恒为 `null`**
|
||||
- 除特别标注（公开）外，接口需在请求头携带 `Authorization: Bearer <token>`
|
||||
- 下文路径均省略 `/api` 前缀，`data` 仅给出 `T` 的声明
|
||||
- 部分 `/test` 接口的返回值不遵循上述格式
|
||||
|
||||
当`"code"`不是`200`时，`"data"`必定为`null`
|
||||
## 接口总览
|
||||
|
||||
部分`/api/test`的返回值不遵循上述格式
|
||||
| 分组 | 路径前缀 | 说明 |
|
||||
|----------|-------------|-------------------------------------------|
|
||||
| 测试 | `/test` | 连通性测试 |
|
||||
| 认证 | `/v1/auth` | 登录 / 注册 / 验证码 / Token 管理 |
|
||||
| 物品管理 | `/v1/items` | 物品 / 类别 / 图片 CRUD、借还、上下架查询 |
|
||||
|
||||
## /test
|
||||
---
|
||||
|
||||
## 分组：测试 `/test`
|
||||
|
||||
### GET /hello
|
||||
|
||||
Authorization: Bearer $Token
|
||||
公开接口。
|
||||
|
||||
key: 无
|
||||
|
||||
回复：
|
||||
**响应**
|
||||
|
||||
```typescript
|
||||
"Hello Kotlin WebFlux!"
|
||||
```
|
||||
|
||||
## /v1/auth
|
||||
---
|
||||
|
||||
## 分组：认证 `/v1/auth`
|
||||
|
||||
| 方法 | 路径 | 认证 | 说明 |
|
||||
|--------|---------------------------|------|--------------------------|
|
||||
| POST | `/login` | 公开 | 登录，获取 Token |
|
||||
| GET | `/logout` | 需要 | 注销，Token 加入黑名单 |
|
||||
| GET | `/ask-code` | 公开 | 发送邮箱验证码 |
|
||||
| POST | `/register` | 公开 | 邮箱注册 |
|
||||
| POST | `/reset` | 公开 | 重置密码 |
|
||||
| GET | `/relogin` | 需要 | 用旧 Token 换取新 Token |
|
||||
|
||||
### POST /login
|
||||
|
||||
Authorization: 无
|
||||
**请求参数**
|
||||
|
||||
key: username, password
|
||||
| 字段 | 类型 | 说明 |
|
||||
|----------|--------|----------|
|
||||
| username | string | 用户名 |
|
||||
| password | string | 密码 |
|
||||
|
||||
data：
|
||||
**响应 data**
|
||||
|
||||
```typescript
|
||||
class data {
|
||||
@@ -51,79 +76,275 @@ class data {
|
||||
|
||||
### GET /logout
|
||||
|
||||
Authorization: Bearer $Token
|
||||
**请求参数**：无
|
||||
|
||||
key: 无
|
||||
**响应 data**：`null`
|
||||
|
||||
data：
|
||||
### GET /ask-code
|
||||
|
||||
```typescript
|
||||
null
|
||||
```
|
||||
**请求参数**
|
||||
|
||||
### GET /ask-code?email=******&type=register
|
||||
| 字段 | 类型 | 说明 |
|
||||
|-------|-----------------------------|------------------------------------|
|
||||
| email | string | 接收验证码的邮箱 |
|
||||
| type | `register` \| `reset` | 验证码用途（注册 / 重置密码） |
|
||||
|
||||
Authorization: 无
|
||||
|
||||
key: 无
|
||||
|
||||
data：
|
||||
|
||||
```typescript
|
||||
null
|
||||
```
|
||||
|
||||
### GET /ask-code?email=******&type=reset
|
||||
|
||||
Authorization: 无
|
||||
|
||||
key: 无
|
||||
|
||||
data：
|
||||
|
||||
```typescript
|
||||
null
|
||||
```
|
||||
**响应 data**：`null`
|
||||
|
||||
### POST /register
|
||||
|
||||
Authorization: 无
|
||||
**请求体字段**：`email`、`code`、`username`、`password`
|
||||
|
||||
key: 无
|
||||
|
||||
data：email, code, username, password
|
||||
|
||||
```typescript
|
||||
null
|
||||
```
|
||||
**响应 data**：`null`
|
||||
|
||||
### POST /reset
|
||||
|
||||
Authorization: 无
|
||||
**请求体字段**：`email`、`code`、`password`
|
||||
|
||||
key: email, code, password
|
||||
|
||||
data：
|
||||
|
||||
```typescript
|
||||
null
|
||||
```
|
||||
**响应 data**：`null`
|
||||
|
||||
### GET /relogin
|
||||
|
||||
Authorization: Bearer $Token
|
||||
**请求参数**：无
|
||||
|
||||
key: 无
|
||||
|
||||
data：
|
||||
**响应 data**
|
||||
|
||||
```typescript
|
||||
class data {
|
||||
"token": sting;
|
||||
"expire": time
|
||||
"token": string;
|
||||
"expire": time;
|
||||
}
|
||||
```
|
||||
|
||||
# ws://localhost:8080/ws
|
||||
---
|
||||
|
||||
目前不支持WS
|
||||
## 分组：物品管理 `/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` | 需要 | 删除物品图片（同时删除物理文件） |
|
||||
|
||||
### 实体定义
|
||||
|
||||
```typescript
|
||||
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;
|
||||
}
|
||||
```
|
||||
|
||||
```typescript
|
||||
class Category {
|
||||
"id": number | null;
|
||||
"name": string;
|
||||
"parentId": number | null;
|
||||
"description": string | null;
|
||||
"createdAt": string | null;
|
||||
"updatedAt": string | null;
|
||||
}
|
||||
```
|
||||
|
||||
```typescript
|
||||
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;
|
||||
}
|
||||
```
|
||||
|
||||
```typescript
|
||||
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` — 目前不支持
|
||||
|
||||
@@ -144,7 +144,7 @@
|
||||
|
||||
#### 认证方式
|
||||
|
||||
所有 API 均使用 **JWT 认证**（除了需要特殊处理的端点）：
|
||||
所有 API 均使用 **JWT 认证**（除了需要特殊处理的端点）
|
||||
|
||||
```
|
||||
Authorization: Bearer <token>
|
||||
@@ -152,7 +152,7 @@ Authorization: Bearer <token>
|
||||
|
||||
## 数据库结构
|
||||
|
||||
[schema.sql](./schema.sql)。
|
||||
[schema.sql](./schema.sql)
|
||||
|
||||
- users (系统用户/认证信息)
|
||||
- departments (组织/部门)
|
||||
|
||||
+4
-11
@@ -5,6 +5,7 @@ import club.itstudio.itmanager.entity.enums.EmailType
|
||||
import club.itstudio.itmanager.entity.vo.request.EmailRegisterVO
|
||||
import club.itstudio.itmanager.entity.vo.request.PasswordResetVO
|
||||
import club.itstudio.itmanager.service.v1.AuthorizationService
|
||||
import club.itstudio.itmanager.utils.Const
|
||||
import jakarta.validation.Valid
|
||||
import jakarta.validation.constraints.Email
|
||||
import jakarta.validation.constraints.NotBlank
|
||||
@@ -31,21 +32,21 @@ class AuthorizeController(
|
||||
logger.info("Trying to ask code")
|
||||
val ip = exchange.request.remoteAddress?.address?.hostAddress ?: "unknown"
|
||||
return service.askEmailVerifyCode(type, email, ip)
|
||||
.map(::messageHandler)
|
||||
.map(Const::messageHandler)
|
||||
}
|
||||
|
||||
@PostMapping("/register")
|
||||
fun emailRegister(@RequestBody @Valid vo: EmailRegisterVO): Mono<ApiResponse<Any?>> {
|
||||
logger.info("Trying to register")
|
||||
return service.registerEmailAccount(vo)
|
||||
.map(::messageHandler)
|
||||
.map(Const::messageHandler)
|
||||
}
|
||||
|
||||
@PostMapping("/reset")
|
||||
fun emailResetPassword(@RequestBody @Valid vo: PasswordResetVO): Mono<ApiResponse<Any?>> {
|
||||
logger.info("Trying to reset password")
|
||||
return service.resetEmailAccountPassword(vo)
|
||||
.map(::messageHandler)
|
||||
.map(Const::messageHandler)
|
||||
}
|
||||
|
||||
@GetMapping("/logout")
|
||||
@@ -68,12 +69,4 @@ class AuthorizeController(
|
||||
?.map { ApiResponse.success(it) }
|
||||
?: Mono.just(ApiResponse.failure(401, null, "Please login with password."))
|
||||
}
|
||||
|
||||
private fun messageHandler(wrongMessage: String): ApiResponse<Any?> {
|
||||
return if (wrongMessage.isBlank()) {
|
||||
ApiResponse.success()
|
||||
} else {
|
||||
ApiResponse.failure(400, null, wrongMessage)
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,26 @@
|
||||
package club.itstudio.itmanager.service.v1
|
||||
|
||||
import club.itstudio.itmanager.entity.dto.Attachment
|
||||
import club.itstudio.itmanager.entity.dto.Category
|
||||
import club.itstudio.itmanager.entity.dto.Item
|
||||
import club.itstudio.itmanager.entity.dto.ItemTransaction
|
||||
import club.itstudio.itmanager.service.AttachmentService
|
||||
import club.itstudio.itmanager.service.CategoryService
|
||||
import club.itstudio.itmanager.service.ItemService
|
||||
import club.itstudio.itmanager.service.ItemTransactionService
|
||||
import club.itstudio.itmanager.utils.Const
|
||||
import club.itstudio.itmanager.utils.DateUtils.getCurrentDateTime
|
||||
import com.baomidou.mybatisplus.extension.plugins.pagination.Page
|
||||
import org.slf4j.LoggerFactory
|
||||
import org.springframework.beans.factory.annotation.Value
|
||||
import org.springframework.http.codec.multipart.FilePart
|
||||
import org.springframework.stereotype.Service
|
||||
import reactor.core.publisher.Mono
|
||||
import reactor.core.scheduler.Schedulers
|
||||
import java.io.IOException
|
||||
import java.nio.file.Files
|
||||
import java.nio.file.Paths
|
||||
import java.util.UUID
|
||||
|
||||
@Service
|
||||
class ItemsApiService
|
||||
@@ -1,5 +1,6 @@
|
||||
package club.itstudio.itmanager.utils
|
||||
|
||||
import club.itstudio.itmanager.entity.ApiResponse
|
||||
import reactor.core.publisher.Mono
|
||||
|
||||
object Const {
|
||||
@@ -12,6 +13,17 @@ object Const {
|
||||
const val FLOW_LIMIT_COUNTER = "flow:counter:"
|
||||
const val FLOW_LIMIT_BLOCK = "flow:block:"
|
||||
|
||||
const val FILE_DIR_IMAGE = "image"
|
||||
|
||||
const val INTERNAL_ERROR_STR = "something went wrong. Please contact the administrator."
|
||||
val INTERNAL_ERROR_MONO = Mono.just(INTERNAL_ERROR_STR)
|
||||
|
||||
// for Controllers
|
||||
fun messageHandler(wrongMessage: String): ApiResponse<Any?> {
|
||||
return if (wrongMessage.isBlank()) {
|
||||
ApiResponse.success()
|
||||
} else {
|
||||
ApiResponse.failure(400, null, wrongMessage)
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -42,3 +42,5 @@ app:
|
||||
count: 1000
|
||||
limit-time: 3
|
||||
ban-time: 60
|
||||
file:
|
||||
data-path: ./data
|
||||
Reference in New Issue
Block a user