feat: ready for ItemApi #4

Merged
SOR2171 merged 6 commits from backend-dev into main 2026-08-01 11:49:03 +08:00
7 changed files with 341 additions and 82 deletions
+5
View File
@@ -1,6 +1,11 @@
<component name="InspectionProjectProfileManager"> <component name="InspectionProjectProfileManager">
<profile version="1.0"> <profile version="1.0">
<option name="myName" value="Project Default" /> <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"> <inspection_tool class="PyShadowingBuiltinsInspection" enabled="true" level="WEAK WARNING" enabled_by_default="true">
<option name="ignoredNames"> <option name="ignoredNames">
<list> <list>
+289 -68
View File
@@ -1,44 +1,69 @@
# http://localhost:8080/api # API 文档
所有返回的json对象总有如下格式 Base URL:`http://localhost:8080/api`
## 通用约定
所有接口均返回统一 JSON 结构:
```typescript ```typescript
class respose<T> { class Response<T> {
"code": number; "code": number;
"message": string; "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 ### GET /hello
Authorization: Bearer $Token 公开接口。
key: 无 **响应**
回复:
```typescript ```typescript
"Hello Kotlin WebFlux!" "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 ### POST /login
Authorization: 无 **请求参数**
key: username, password | 字段 | 类型 | 说明 |
|----------|--------|----------|
| username | string | 用户名 |
| password | string | 密码 |
data: **响应 data**
```typescript ```typescript
class data { class data {
@@ -51,79 +76,275 @@ class data {
### GET /logout ### 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: 无 **响应 data**:`null`
key: 无
data:
```typescript
null
```
### GET /ask-code?email=******&type=reset
Authorization: 无
key: 无
data:
```typescript
null
```
### POST /register ### POST /register
Authorization: 无 **请求体字段**:`email`、`code`、`username`、`password`
key: 无 **响应 data**:`null`
data:email, code, username, password
```typescript
null
```
### POST /reset ### POST /reset
Authorization: 无 **请求体字段**:`email`、`code`、`password`
key: email, code, password **响应 data**:`null`
data:
```typescript
null
```
### GET /relogin ### GET /relogin
Authorization: Bearer $Token **请求参数**:无
key: 无 **响应 data**
data:
```typescript ```typescript
class data { class data {
"token": sting; "token": string;
"expire": time "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` — 目前不支持
+2 -2
View File
@@ -144,7 +144,7 @@
#### 认证方式 #### 认证方式
所有 API 均使用 **JWT 认证**(除了需要特殊处理的端点): 所有 API 均使用 **JWT 认证**(除了需要特殊处理的端点)
``` ```
Authorization: Bearer <token> Authorization: Bearer <token>
@@ -152,7 +152,7 @@ Authorization: Bearer <token>
## 数据库结构 ## 数据库结构
[schema.sql](./schema.sql)。 [schema.sql](./schema.sql)
- users (系统用户/认证信息) - users (系统用户/认证信息)
- departments (组织/部门) - departments (组织/部门)
@@ -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.EmailRegisterVO
import club.itstudio.itmanager.entity.vo.request.PasswordResetVO import club.itstudio.itmanager.entity.vo.request.PasswordResetVO
import club.itstudio.itmanager.service.v1.AuthorizationService import club.itstudio.itmanager.service.v1.AuthorizationService
import club.itstudio.itmanager.utils.Const
import jakarta.validation.Valid import jakarta.validation.Valid
import jakarta.validation.constraints.Email import jakarta.validation.constraints.Email
import jakarta.validation.constraints.NotBlank import jakarta.validation.constraints.NotBlank
@@ -31,21 +32,21 @@ class AuthorizeController(
logger.info("Trying to ask code") logger.info("Trying to ask code")
val ip = exchange.request.remoteAddress?.address?.hostAddress ?: "unknown" val ip = exchange.request.remoteAddress?.address?.hostAddress ?: "unknown"
return service.askEmailVerifyCode(type, email, ip) return service.askEmailVerifyCode(type, email, ip)
.map(::messageHandler) .map(Const::messageHandler)
} }
@PostMapping("/register") @PostMapping("/register")
fun emailRegister(@RequestBody @Valid vo: EmailRegisterVO): Mono<ApiResponse<Any?>> { fun emailRegister(@RequestBody @Valid vo: EmailRegisterVO): Mono<ApiResponse<Any?>> {
logger.info("Trying to register") logger.info("Trying to register")
return service.registerEmailAccount(vo) return service.registerEmailAccount(vo)
.map(::messageHandler) .map(Const::messageHandler)
} }
@PostMapping("/reset") @PostMapping("/reset")
fun emailResetPassword(@RequestBody @Valid vo: PasswordResetVO): Mono<ApiResponse<Any?>> { fun emailResetPassword(@RequestBody @Valid vo: PasswordResetVO): Mono<ApiResponse<Any?>> {
logger.info("Trying to reset password") logger.info("Trying to reset password")
return service.resetEmailAccountPassword(vo) return service.resetEmailAccountPassword(vo)
.map(::messageHandler) .map(Const::messageHandler)
} }
@GetMapping("/logout") @GetMapping("/logout")
@@ -68,12 +69,4 @@ class AuthorizeController(
?.map { ApiResponse.success(it) } ?.map { ApiResponse.success(it) }
?: Mono.just(ApiResponse.failure(401, null, "Please login with password.")) ?: 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 package club.itstudio.itmanager.utils
import club.itstudio.itmanager.entity.ApiResponse
import reactor.core.publisher.Mono import reactor.core.publisher.Mono
object Const { object Const {
@@ -12,6 +13,17 @@ object Const {
const val FLOW_LIMIT_COUNTER = "flow:counter:" const val FLOW_LIMIT_COUNTER = "flow:counter:"
const val FLOW_LIMIT_BLOCK = "flow:block:" 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." const val INTERNAL_ERROR_STR = "something went wrong. Please contact the administrator."
val INTERNAL_ERROR_MONO = Mono.just(INTERNAL_ERROR_STR) 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 count: 1000
limit-time: 3 limit-time: 3
ban-time: 60 ban-time: 60
file:
data-path: ./data