From 18224b9a9702382941d87198586307817c0576a9 Mon Sep 17 00:00:00 2001
From: SOR <3272194354@qq.com>
Date: Fri, 31 Jul 2026 17:34:39 +0800
Subject: [PATCH 1/5] feat: ready for ItemApi

---
 .idea/inspectionProfiles/Project_Default.xml  |  5 ++++
 README.md                                     |  4 +--
 .../itmanager/service/v1/ItemsApiService.kt   | 26 +++++++++++++++++++
 .../src/main/resources/application.yaml       |  4 ++-
 4 files changed, 36 insertions(+), 3 deletions(-)
 create mode 100644 src/beckend/src/main/kotlin/club/itstudio/itmanager/service/v1/ItemsApiService.kt

diff --git a/.idea/inspectionProfiles/Project_Default.xml b/.idea/inspectionProfiles/Project_Default.xml
index 02d4983..44f93a1 100644
--- a/.idea/inspectionProfiles/Project_Default.xml
+++ b/.idea/inspectionProfiles/Project_Default.xml
@@ -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>
diff --git a/README.md b/README.md
index 8b9de9e..a5c768e 100644
--- a/README.md
+++ b/README.md
@@ -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 (组织/部门)
diff --git a/src/beckend/src/main/kotlin/club/itstudio/itmanager/service/v1/ItemsApiService.kt b/src/beckend/src/main/kotlin/club/itstudio/itmanager/service/v1/ItemsApiService.kt
new file mode 100644
index 0000000..127d375
--- /dev/null
+++ b/src/beckend/src/main/kotlin/club/itstudio/itmanager/service/v1/ItemsApiService.kt
@@ -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
\ No newline at end of file
diff --git a/src/beckend/src/main/resources/application.yaml b/src/beckend/src/main/resources/application.yaml
index d1c8bd8..748b836 100644
--- a/src/beckend/src/main/resources/application.yaml
+++ b/src/beckend/src/main/resources/application.yaml
@@ -41,4 +41,6 @@ app:
   flow-limit:
     count: 1000
     limit-time: 3
-    ban-time: 60
\ No newline at end of file
+    ban-time: 60
+  file:
+    upload-path: ./data/upload/
\ No newline at end of file

From 43139784b2ef21839f990be9102716414fcbb122 Mon Sep 17 00:00:00 2001
From: SOR <3272194354@qq.com>
Date: Fri, 31 Jul 2026 21:36:59 +0800
Subject: [PATCH 2/5] refactor: messageHandler

---
 .../controller/v1/AuthorizeController.kt          | 15 ++++-----------
 .../kotlin/club/itstudio/itmanager/utils/Const.kt | 10 ++++++++++
 2 files changed, 14 insertions(+), 11 deletions(-)

diff --git a/src/beckend/src/main/kotlin/club/itstudio/itmanager/controller/v1/AuthorizeController.kt b/src/beckend/src/main/kotlin/club/itstudio/itmanager/controller/v1/AuthorizeController.kt
index 9ca1444..77634b9 100644
--- a/src/beckend/src/main/kotlin/club/itstudio/itmanager/controller/v1/AuthorizeController.kt
+++ b/src/beckend/src/main/kotlin/club/itstudio/itmanager/controller/v1/AuthorizeController.kt
@@ -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)
-        }
-    }
 }
\ No newline at end of file
diff --git a/src/beckend/src/main/kotlin/club/itstudio/itmanager/utils/Const.kt b/src/beckend/src/main/kotlin/club/itstudio/itmanager/utils/Const.kt
index e461c5f..4cf60d5 100644
--- a/src/beckend/src/main/kotlin/club/itstudio/itmanager/utils/Const.kt
+++ b/src/beckend/src/main/kotlin/club/itstudio/itmanager/utils/Const.kt
@@ -1,5 +1,6 @@
 package club.itstudio.itmanager.utils
 
+import club.itstudio.itmanager.entity.ApiResponse
 import reactor.core.publisher.Mono
 
 object Const {
@@ -14,4 +15,13 @@ object Const {
 
     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)
+        }
+    }
 }
\ No newline at end of file

From 8195b8239690b9a7d615af31871d27a0a10bb6fb Mon Sep 17 00:00:00 2001
From: SOR <3272194354@qq.com>
Date: Sat, 1 Aug 2026 08:08:57 +0800
Subject: [PATCH 3/5] doc: API.md

---
 API.md | 357 ++++++++++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 289 insertions(+), 68 deletions(-)

diff --git a/API.md b/API.md
index c48015a..76df59f 100644
--- a/API.md
+++ b/API.md
@@ -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
\ No newline at end of file
+## 分组：物品管理 `/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` — 目前不支持

From 6ba540aab3689d9131c3523d33420397c0fa44c8 Mon Sep 17 00:00:00 2001
From: SOR <3272194354@qq.com>
Date: Sat, 1 Aug 2026 08:08:57 +0800
Subject: [PATCH 4/5] doc: API.md

---
 API.md | 357 ++++++++++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 289 insertions(+), 68 deletions(-)

diff --git a/API.md b/API.md
index c48015a..4fe00a0 100644
--- a/API.md
+++ b/API.md
@@ -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
\ No newline at end of file
+## 分组：物品管理 `/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` — 目前不支持

From 065b9f77e4435a88f906acc846fe2a0c9de00556 Mon Sep 17 00:00:00 2001
From: SOR <3272194354@qq.com>
Date: Sat, 1 Aug 2026 11:46:49 +0800
Subject: [PATCH 5/5] refactor: file dir structure

---
 .../src/main/kotlin/club/itstudio/itmanager/utils/Const.kt      | 2 ++
 src/beckend/src/main/resources/application.yaml                 | 2 +-
 2 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/beckend/src/main/kotlin/club/itstudio/itmanager/utils/Const.kt b/src/beckend/src/main/kotlin/club/itstudio/itmanager/utils/Const.kt
index 4cf60d5..5051d98 100644
--- a/src/beckend/src/main/kotlin/club/itstudio/itmanager/utils/Const.kt
+++ b/src/beckend/src/main/kotlin/club/itstudio/itmanager/utils/Const.kt
@@ -13,6 +13,8 @@ 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)
 
diff --git a/src/beckend/src/main/resources/application.yaml b/src/beckend/src/main/resources/application.yaml
index 748b836..8c9ef51 100644
--- a/src/beckend/src/main/resources/application.yaml
+++ b/src/beckend/src/main/resources/application.yaml
@@ -43,4 +43,4 @@ app:
     limit-time: 3
     ban-time: 60
   file:
-    upload-path: ./data/upload/
\ No newline at end of file
+    data-path: ./data
\ No newline at end of file