feat: first version of backend API

2026-08-09 20:51:28 +08:00
parent 905f1d897d
commit 8262b3469f
14 changed files with 1380 additions and 217 deletions
@@ -1,23 +1,43 @@
-package club.itstudio.itmanager.controller.v1
-
-import club.itstudio.itmanager.utils.Const
-import org.springframework.validation.annotation.Validated
-import org.springframework.web.bind.annotation.*
-import reactor.core.publisher.Mono
-
-@Validated
-@RestController
-@RequestMapping("/api/v1/email")
-class EmailController {
-
-    // notification-settings/ GET/POST 获取/更新通知设置和邮箱列表
-    @GetMapping("/notification-settings", "/notification-settings/")
-    fun getNotificationSettings(): Mono<String> = Const.INTERNAL_ERROR_MONO
-
-    @PostMapping("/notification-settings", "/notification-settings/")
-    fun updateNotificationSettings(): Mono<String> = Const.INTERNAL_ERROR_MONO
-
-    // toggle-email-status/ POST 切换邮箱启用/禁用状态
-    @PostMapping("/toggle-email-status", "/toggle-email-status/")
-    fun toggleEmailStatus(): Mono<String> = Const.INTERNAL_ERROR_MONO
-}
+package club.itstudio.itmanager.controller.v1
+
+import club.itstudio.itmanager.entity.ApiResponse
+import club.itstudio.itmanager.entity.dto.EmailNotice
+import club.itstudio.itmanager.service.v1.EmailApiService
+import club.itstudio.itmanager.utils.Const
+import jakarta.validation.Valid
+import org.slf4j.LoggerFactory
+import org.springframework.validation.annotation.Validated
+import org.springframework.web.bind.annotation.*
+import reactor.core.publisher.Mono
+
+@Validated
+@RestController
+@RequestMapping("/api/v1/email")
+class EmailController(
+    private val service: EmailApiService
+) {
+    private val logger = LoggerFactory.getLogger(this::class.java)
+
+    // notification-settings/ GET/POST 获取/更新通知设置和邮箱列表
+    @GetMapping("/notification-settings", "/notification-settings/")
+    fun getNotificationSettings(): Mono<ApiResponse<Any?>> {
+        logger.info("Trying to list notification settings")
+        return service.getNotificationSettings()
+            .map { ApiResponse.success(it) }
+    }
+
+    @PostMapping("/notification-settings", "/notification-settings/")
+    fun updateNotificationSettings(@RequestBody @Valid notice: EmailNotice): Mono<ApiResponse<Any?>> {
+        logger.info("Trying to update notification settings")
+        return service.updateNotificationSettings(notice)
+            .map(Const::messageHandler)
+    }
+
+    // toggle-email-status/ POST 切换邮箱启用/禁用状态
+    @PostMapping("/toggle-email-status", "/toggle-email-status/")
+    fun toggleEmailStatus(@RequestParam(required = false) id: Long?): Mono<ApiResponse<Any?>> {
+        logger.info("Trying to toggle email status")
+        return service.toggleEmailStatus(id)
+            .map(Const::messageHandler)
+    }
+}
@@ -1,46 +1,111 @@
-package club.itstudio.itmanager.controller.v1
-
-import club.itstudio.itmanager.utils.Const
-import org.springframework.validation.annotation.Validated
-import org.springframework.web.bind.annotation.*
-import reactor.core.publisher.Mono
-
-@Validated
-@RestController
-@RequestMapping("/api/v1/finance")
-class FinanceController {
-
-    // finance/ GET/POST/PUT/DELETE 财务记录 CRUD 操作
-    @GetMapping("", "/")
-    fun getFinanceRecords(): Mono<String> = Const.INTERNAL_ERROR_MONO
-
-    @PostMapping("", "/")
-    fun createFinanceRecord(): Mono<String> = Const.INTERNAL_ERROR_MONO
-
-    @PutMapping("", "/")
-    fun updateFinanceRecord(): Mono<String> = Const.INTERNAL_ERROR_MONO
-
-    @DeleteMapping("", "/")
-    fun deleteFinanceRecord(@RequestParam(required = false) id: String?): Mono<String> = Const.INTERNAL_ERROR_MONO
-
-    // finance/{id}/upload_images/ POST 上传财务凭证图片
-    @PostMapping("/{id}/upload_images", "/{id}/upload_images/")
-    fun uploadImages(@PathVariable("id") id: String): Mono<String> = Const.INTERNAL_ERROR_MONO
-
-    // finance/{id}/ DELETE 删除财务记录（发送邮件通知）
-    @DeleteMapping("/{id}", "/{id}/")
-    fun deleteById(@PathVariable("id") id: String): Mono<String> = Const.INTERNAL_ERROR_MONO
-
-    // finance/categories/ GET/POST/PUT/DELETE 财务分类 CRUD 操作
-    @GetMapping("/categories", "/categories/")
-    fun getFinanceCategories(): Mono<String> = Const.INTERNAL_ERROR_MONO
-
-    @PostMapping("/categories", "/categories/")
-    fun createFinanceCategory(): Mono<String> = Const.INTERNAL_ERROR_MONO
-
-    @PutMapping("/categories", "/categories/")
-    fun updateFinanceCategory(): Mono<String> = Const.INTERNAL_ERROR_MONO
-
-    @DeleteMapping("/categories", "/categories/")
-    fun deleteFinanceCategory(@RequestParam(required = false) id: String?): Mono<String> = Const.INTERNAL_ERROR_MONO
-}
+package club.itstudio.itmanager.controller.v1
+
+import club.itstudio.itmanager.entity.ApiResponse
+import club.itstudio.itmanager.entity.dto.Category
+import club.itstudio.itmanager.entity.dto.FinanceRecord
+import club.itstudio.itmanager.service.v1.FinanceApiService
+import club.itstudio.itmanager.utils.Const
+import com.baomidou.mybatisplus.extension.plugins.pagination.Page
+import jakarta.validation.Valid
+import org.slf4j.LoggerFactory
+import org.springframework.http.codec.multipart.FilePart
+import org.springframework.validation.annotation.Validated
+import org.springframework.web.bind.annotation.*
+import reactor.core.publisher.Flux
+import reactor.core.publisher.Mono
+
+@Validated
+@RestController
+@RequestMapping("/api/v1/finance")
+class FinanceController(
+    private val service: FinanceApiService
+) {
+    private val logger = LoggerFactory.getLogger(this::class.java)
+
+    // finance/ GET/POST/PUT/DELETE 财务记录 CRUD 操作
+    @GetMapping("", "/")
+    fun getFinanceRecords(
+        @RequestParam(defaultValue = "1") pageNum: Long,
+        @RequestParam(defaultValue = "10") pageSize: Long,
+        @RequestParam(required = false) keyword: String?,
+        @RequestParam(required = false) type: String?,
+        @RequestParam(required = false) start: String?,
+        @RequestParam(required = false) end: String?,
+        @RequestParam(required = false) vendor: String?,
+        @RequestParam(required = false) itemId: Long?
+    ): Mono<ApiResponse<Any?>> {
+        logger.info("Trying to list finance records")
+        val page = Page<FinanceRecord>(pageNum, pageSize)
+        return service.getFinanceRecords(page, keyword, type, start, end, vendor, itemId)
+            .map { ApiResponse.success(it) }
+    }
+
+    @PostMapping("", "/")
+    fun createFinanceRecord(@RequestBody @Valid record: FinanceRecord): Mono<ApiResponse<Any?>> {
+        logger.info("Trying to create finance record")
+        return service.createFinanceRecord(record)
+            .map(Const::messageHandler)
+    }
+
+    @PutMapping("", "/")
+    fun updateFinanceRecord(@RequestBody @Valid record: FinanceRecord): Mono<ApiResponse<Any?>> {
+        logger.info("Trying to update finance record")
+        return service.updateFinanceRecord(record)
+            .map(Const::messageHandler)
+    }
+
+    @DeleteMapping("", "/")
+    fun deleteFinanceRecord(@RequestParam(required = false) id: Long?): Mono<ApiResponse<Any?>> {
+        logger.info("Trying to delete finance record")
+        return service.deleteFinanceRecord(id)
+            .map(Const::messageHandler)
+    }
+
+    // finance/{id}/upload_images/ POST 上传财务凭证图片
+    @PostMapping("/{id}/upload_images", "/{id}/upload_images/")
+    fun uploadImages(
+        @PathVariable("id") id: Long,
+        @RequestPart("files") files: Flux<FilePart>
+    ): Mono<ApiResponse<Any?>> {
+        logger.info("Trying to upload images for finance record {}", id)
+        return service.uploadImages(id, files)
+            .map(Const::messageHandler)
+    }
+
+    // finance/{id}/ DELETE 删除财务记录（发送邮件通知）
+    @DeleteMapping("/{id}", "/{id}/")
+    fun deleteById(@PathVariable("id") id: Long): Mono<ApiResponse<Any?>> {
+        logger.info("Trying to delete finance record {} with email notification", id)
+        return service.deleteById(id)
+            .map(Const::messageHandler)
+    }
+
+    // finance/categories/ GET/POST/PUT/DELETE 财务分类 CRUD 操作
+    @GetMapping("/categories", "/categories/")
+    fun getFinanceCategories(): Mono<ApiResponse<Any?>> {
+        logger.info("Trying to list finance categories")
+        return service.getFinanceCategories()
+            .map { ApiResponse.success(it) }
+    }
+
+    @PostMapping("/categories", "/categories/")
+    fun createFinanceCategory(@RequestBody @Valid category: Category): Mono<ApiResponse<Any?>> {
+        logger.info("Trying to create finance category")
+        return service.createFinanceCategory(category)
+            .map(Const::messageHandler)
+    }
+
+    @PutMapping("/categories", "/categories/")
+    fun updateFinanceCategory(@RequestBody @Valid category: Category): Mono<ApiResponse<Any?>> {
+        logger.info("Trying to update finance category")
+        return service.updateFinanceCategory(category)
+            .map(Const::messageHandler)
+    }
+
+    @DeleteMapping("/categories", "/categories/")
+    fun deleteFinanceCategory(@RequestParam(required = false) id: Long?): Mono<ApiResponse<Any?>> {
+        logger.info("Trying to delete finance category")
+        return service.deleteFinanceCategory(id)
+            .map(Const::messageHandler)
+    }
+}
@@ -1,29 +1,57 @@
-package club.itstudio.itmanager.controller.v1
-
-import club.itstudio.itmanager.utils.Const
-import org.springframework.validation.annotation.Validated
-import org.springframework.web.bind.annotation.*
-import reactor.core.publisher.Mono
-
-@Validated
-@RestController
-@RequestMapping("/api/v1/proof-images")
-class ProofImagesController {
-
-    // proof-images/ GET/POST/PUT/DELETE 财务凭证图片 CRUD 操作
-    @GetMapping("", "/")
-    fun getProofImages(): Mono<String> = Const.INTERNAL_ERROR_MONO
-
-    @PostMapping("", "/")
-    fun createProofImage(): Mono<String> = Const.INTERNAL_ERROR_MONO
-
-    @PutMapping("", "/")
-    fun updateProofImage(): Mono<String> = Const.INTERNAL_ERROR_MONO
-
-    @DeleteMapping("", "/")
-    fun deleteProofImage(@RequestParam(required = false) id: String?): Mono<String> = Const.INTERNAL_ERROR_MONO
-
-    // proof-images/{id}/ DELETE 删除凭证图片（自动删除物理文件）
-    @DeleteMapping("/{id}", "/{id}/")
-    fun deleteById(@PathVariable("id") id: String): Mono<String> = Const.INTERNAL_ERROR_MONO
-}
+package club.itstudio.itmanager.controller.v1
+
+import club.itstudio.itmanager.entity.ApiResponse
+import club.itstudio.itmanager.entity.dto.Attachment
+import club.itstudio.itmanager.service.v1.ProofImagesApiService
+import club.itstudio.itmanager.utils.Const
+import jakarta.validation.Valid
+import org.slf4j.LoggerFactory
+import org.springframework.validation.annotation.Validated
+import org.springframework.web.bind.annotation.*
+import reactor.core.publisher.Mono
+
+@Validated
+@RestController
+@RequestMapping("/api/v1/proof-images")
+class ProofImagesController(
+    private val service: ProofImagesApiService
+) {
+    private val logger = LoggerFactory.getLogger(this::class.java)
+
+    // proof-images/ GET/POST/PUT/DELETE 财务凭证图片 CRUD 操作
+    @GetMapping("", "/")
+    fun getProofImages(): Mono<ApiResponse<Any?>> {
+        logger.info("Trying to list proof images")
+        return service.getProofImages()
+            .map { ApiResponse.success(it) }
+    }
+
+    @PostMapping("", "/")
+    fun createProofImage(@RequestBody @Valid attachment: Attachment): Mono<ApiResponse<Any?>> {
+        logger.info("Trying to create proof image")
+        return service.createProofImage(attachment)
+            .map(Const::messageHandler)
+    }
+
+    @PutMapping("", "/")
+    fun updateProofImage(@RequestBody @Valid attachment: Attachment): Mono<ApiResponse<Any?>> {
+        logger.info("Trying to update proof image")
+        return service.updateProofImage(attachment)
+            .map(Const::messageHandler)
+    }
+
+    @DeleteMapping("", "/")
+    fun deleteProofImage(@RequestParam(required = false) id: Long?): Mono<ApiResponse<Any?>> {
+        logger.info("Trying to delete proof image")
+        return service.deleteProofImage(id)
+            .map(Const::messageHandler)
+    }
+
+    // proof-images/{id}/ DELETE 删除凭证图片（自动删除物理文件）
+    @DeleteMapping("/{id}", "/{id}/")
+    fun deleteById(@PathVariable("id") id: Long): Mono<ApiResponse<Any?>> {
+        logger.info("Trying to delete proof image {}", id)
+        return service.deleteProofImage(id)
+            .map(Const::messageHandler)
+    }
+}
@@ -1,50 +1,115 @@
-package club.itstudio.itmanager.controller.v1
-
-import club.itstudio.itmanager.utils.Const
-import org.springframework.validation.annotation.Validated
-import org.springframework.web.bind.annotation.*
-import reactor.core.publisher.Mono
-
-@Validated
-@RestController
-@RequestMapping("/api/v1/usages")
-class UsagesController {
-
-    // usages/ GET/POST/PUT/DELETE 物品使用记录 CRUD 操作
-    @GetMapping("", "/")
-    fun getUsages(): Mono<String> = Const.INTERNAL_ERROR_MONO
-
-    @PostMapping("", "/")
-    fun createUsage(): Mono<String> = Const.INTERNAL_ERROR_MONO
-
-    @PutMapping("", "/")
-    fun updateUsage(): Mono<String> = Const.INTERNAL_ERROR_MONO
-
-    @DeleteMapping("", "/")
-    fun deleteUsage(@RequestParam(required = false) id: String?): Mono<String> = Const.INTERNAL_ERROR_MONO
-
-    // usages/{id}/upload_images/ POST 上传使用记录图片
-    @PostMapping("/{id}/upload_images", "/{id}/upload_images/")
-    fun uploadImages(@PathVariable("id") id: String): Mono<String> = Const.INTERNAL_ERROR_MONO
-
-    // usages/current/ GET 获取当前使用中的记录
-    @GetMapping("/current", "/current/")
-    fun getCurrentUsages(): Mono<String> = Const.INTERNAL_ERROR_MONO
-
-    // usages/by_user/ GET 根据用户姓名获取使用记录
-    @GetMapping("/by_user", "/by_user/")
-    fun getUsagesByUser(@RequestParam(required = false) name: String?): Mono<String> = Const.INTERNAL_ERROR_MONO
-
-    // usages/images/ GET/POST/PUT/DELETE 使用记录图片 CRUD 操作
-    @GetMapping("/images", "/images/")
-    fun getUsageImages(): Mono<String> = Const.INTERNAL_ERROR_MONO
-
-    @PostMapping("/images", "/images/")
-    fun createUsageImage(): Mono<String> = Const.INTERNAL_ERROR_MONO
-
-    @PutMapping("/images", "/images/")
-    fun updateUsageImage(): Mono<String> = Const.INTERNAL_ERROR_MONO
-
-    @DeleteMapping("/images", "/images/")
-    fun deleteUsageImage(@RequestParam(required = false) id: String?): Mono<String> = Const.INTERNAL_ERROR_MONO
-}
+package club.itstudio.itmanager.controller.v1
+
+import club.itstudio.itmanager.entity.ApiResponse
+import club.itstudio.itmanager.entity.dto.Attachment
+import club.itstudio.itmanager.entity.dto.BorrowRecord
+import club.itstudio.itmanager.service.v1.UsagesApiService
+import club.itstudio.itmanager.utils.Const
+import com.baomidou.mybatisplus.extension.plugins.pagination.Page
+import jakarta.validation.Valid
+import org.slf4j.LoggerFactory
+import org.springframework.http.codec.multipart.FilePart
+import org.springframework.validation.annotation.Validated
+import org.springframework.web.bind.annotation.*
+import reactor.core.publisher.Flux
+import reactor.core.publisher.Mono
+
+@Validated
+@RestController
+@RequestMapping("/api/v1/usages")
+class UsagesController(
+    private val service: UsagesApiService
+) {
+    private val logger = LoggerFactory.getLogger(this::class.java)
+
+    // usages/ GET/POST/PUT/DELETE 物品使用记录 CRUD 操作
+    @GetMapping("", "/")
+    fun getUsages(
+        @RequestParam(defaultValue = "1") pageNum: Long,
+        @RequestParam(defaultValue = "10") pageSize: Long,
+        @RequestParam(required = false) keyword: String?,
+        @RequestParam(required = false) status: String?
+    ): Mono<ApiResponse<Any?>> {
+        logger.info("Trying to list usages")
+        val page = Page<BorrowRecord>(pageNum, pageSize)
+        return service.getUsages(page, keyword, status)
+            .map { ApiResponse.success(it) }
+    }
+
+    @PostMapping("", "/")
+    fun createUsage(@RequestBody @Valid record: BorrowRecord): Mono<ApiResponse<Any?>> {
+        logger.info("Trying to create usage")
+        return service.createUsage(record)
+            .map(Const::messageHandler)
+    }
+
+    @PutMapping("", "/")
+    fun updateUsage(@RequestBody @Valid record: BorrowRecord): Mono<ApiResponse<Any?>> {
+        logger.info("Trying to update usage")
+        return service.updateUsage(record)
+            .map(Const::messageHandler)
+    }
+
+    @DeleteMapping("", "/")
+    fun deleteUsage(@RequestParam(required = false) id: Long?): Mono<ApiResponse<Any?>> {
+        logger.info("Trying to delete usage")
+        return service.deleteUsage(id)
+            .map(Const::messageHandler)
+    }
+
+    // usages/{id}/upload_images/ POST 上传使用记录图片
+    @PostMapping("/{id}/upload_images", "/{id}/upload_images/")
+    fun uploadImages(
+        @PathVariable("id") id: Long,
+        @RequestPart("files") files: Flux<FilePart>
+    ): Mono<ApiResponse<Any?>> {
+        logger.info("Trying to upload images for usage {}", id)
+        return service.uploadImages(id, files)
+            .map(Const::messageHandler)
+    }
+
+    // usages/current/ GET 获取当前使用中的记录
+    @GetMapping("/current", "/current/")
+    fun getCurrentUsages(): Mono<ApiResponse<Any?>> {
+        logger.info("Trying to list current usages")
+        return service.getCurrentUsages()
+            .map { ApiResponse.success(it) }
+    }
+
+    // usages/by_user/ GET 根据用户姓名获取使用记录
+    @GetMapping("/by_user", "/by_user/")
+    fun getUsagesByUser(@RequestParam(required = false) name: String?): Mono<ApiResponse<Any?>> {
+        logger.info("Trying to list usages by user")
+        return service.getUsagesByUser(name)
+            .map { ApiResponse.success(it) }
+    }
+
+    // usages/images/ GET/POST/PUT/DELETE 使用记录图片 CRUD 操作
+    @GetMapping("/images", "/images/")
+    fun getUsageImages(): Mono<ApiResponse<Any?>> {
+        logger.info("Trying to list usage images")
+        return service.getUsageImages()
+            .map { ApiResponse.success(it) }
+    }
+
+    @PostMapping("/images", "/images/")
+    fun createUsageImage(@RequestBody @Valid attachment: Attachment): Mono<ApiResponse<Any?>> {
+        logger.info("Trying to create usage image")
+        return service.createUsageImage(attachment)
+            .map(Const::messageHandler)
+    }
+
+    @PutMapping("/images", "/images/")
+    fun updateUsageImage(@RequestBody @Valid attachment: Attachment): Mono<ApiResponse<Any?>> {
+        logger.info("Trying to update usage image")
+        return service.updateUsageImage(attachment)
+            .map(Const::messageHandler)
+    }
+
+    @DeleteMapping("/images", "/images/")
+    fun deleteUsageImage(@RequestParam(required = false) id: Long?): Mono<ApiResponse<Any?>> {
+        logger.info("Trying to delete usage image")
+        return service.deleteUsageImage(id)
+            .map(Const::messageHandler)
+    }
+}
@@ -4,6 +4,7 @@ import com.baomidou.mybatisplus.annotation.IdType
 import com.baomidou.mybatisplus.annotation.TableId
 import com.baomidou.mybatisplus.annotation.TableName
 import club.itstudio.itmanager.entity.DataCopy
+import club.itstudio.itmanager.entity.enums.FinanceRecordType
 import kotlinx.datetime.LocalDateTime
 import kotlinx.serialization.Serializable
 import java.math.BigDecimal
@@ -14,7 +15,7 @@ data class FinanceRecord(
    @TableId(type = IdType.AUTO)
    val id: Long? = null,
    val recordNo: String? = null,
-    val type: String = "",  // PURCHASE / REFUND / REPAIR / DEPRECIATION / OTHER
+    val type: FinanceRecordType = FinanceRecordType.OTHER,
    val relatedItemId: Long? = null,
    val amount: BigDecimal = BigDecimal.ZERO,
    val currency: String = "CNY",
@@ -10,4 +10,7 @@ enum class EmailType {
    
    @SerialName("reset")
    RESET,
+    
+    @SerialName("finance-delete")
+    FINANCE_DELETE,
 }
@@ -0,0 +1,22 @@
+package club.itstudio.itmanager.entity.enums
+
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+
+@Serializable
+enum class FinanceRecordType {
+    @SerialName("PURCHASE")
+    PURCHASE,
+
+    @SerialName("REFUND")
+    REFUND,
+
+    @SerialName("REPAIR")
+    REPAIR,
+
+    @SerialName("DEPRECIATION")
+    DEPRECIATION,
+
+    @SerialName("OTHER")
+    OTHER,
+}
@@ -42,6 +42,12 @@ class MailQueueListener(
                        + "\nThis code is valid for 3 minutes.",
                email
            )
+
+            EmailType.FINANCE_DELETE -> createMailMessage(
+                "Finance Record Deleted",
+                "A finance record has been deleted. Record No: $code",
+                email
+            )
        }
        sender.send(message)
        logger.info("Email sent to $email.")
@@ -0,0 +1,56 @@
+package club.itstudio.itmanager.service.v1
+
+import club.itstudio.itmanager.entity.dto.EmailNotice
+import club.itstudio.itmanager.service.EmailNoticeService
+import club.itstudio.itmanager.utils.Const
+import club.itstudio.itmanager.utils.DateUtils.getCurrentDateTime
+import org.slf4j.LoggerFactory
+import org.springframework.stereotype.Service
+import reactor.core.publisher.Mono
+import java.util.NoSuchElementException
+
+@Service
+class EmailApiService(
+    private val emailNoticeService: EmailNoticeService
+) {
+    private val logger = LoggerFactory.getLogger(this::class.java)
+
+    fun getNotificationSettings(): Mono<List<EmailNotice>> {
+        logger.info("Listing notification settings and email list")
+        return emailNoticeService.listAllNotices()
+    }
+
+    fun updateNotificationSettings(notice: EmailNotice): Mono<String> {
+        logger.info("Updating notification settings")
+        if (notice.id == null) {
+            return emailNoticeService.createEmailNotice(
+                notice.copy(
+                    id = null,
+                    createdAt = getCurrentDateTime(),
+                    updatedAt = getCurrentDateTime()
+                )
+            ).flatMap { success ->
+                if (success) Mono.just("")
+                else Mono.just("notification settings create failed.")
+            }
+        }
+        return emailNoticeService.updateEmailNotice(
+            notice.copy(updatedAt = getCurrentDateTime())
+        ).flatMap { success ->
+            if (success) Mono.just("")
+            else Mono.just("notification settings update failed.")
+        }
+    }
+
+    fun toggleEmailStatus(id: Long?): Mono<String> {
+        logger.info("Toggling email status for id {}", id)
+        if (id == null) return Mono.just("email notice id is required.")
+        return emailNoticeService.toggleEnabled(id)
+            .flatMap { success ->
+                if (success) Mono.just("")
+                else Mono.just("email notice not found or toggle failed.")
+            }
+            .onErrorResume(NoSuchElementException::class.java) { Mono.just("email notice not found.") }
+            .onErrorResume { Mono.just(Const.INTERNAL_ERROR_STR) }
+    }
+}
@@ -0,0 +1,288 @@
+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.EmailVerificationMsg
+import club.itstudio.itmanager.entity.dto.FinanceRecord
+import club.itstudio.itmanager.entity.enums.EmailType
+import club.itstudio.itmanager.service.AccountService
+import club.itstudio.itmanager.service.AttachmentService
+import club.itstudio.itmanager.service.CategoryService
+import club.itstudio.itmanager.service.FinanceRecordService
+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.amqp.core.AmqpTemplate
+import org.springframework.beans.factory.annotation.Value
+import org.springframework.http.codec.multipart.FilePart
+import org.springframework.stereotype.Service
+import reactor.core.publisher.Flux
+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.NoSuchElementException
+import java.util.UUID
+
+@Service
+class FinanceApiService(
+    private val financeRecordService: FinanceRecordService,
+    private val categoryService: CategoryService,
+    private val attachmentService: AttachmentService,
+    private val accountService: AccountService,
+    private val amqpTemplate: AmqpTemplate,
+
+    @Value($$"${app.file.data-path}")
+    private val dataPath: String
+) {
+    private val logger = LoggerFactory.getLogger(this::class.java)
+
+    fun getFinanceRecords(
+        page: Page<FinanceRecord>,
+        keyword: String?,
+        type: String?,
+        start: String?,
+        end: String?,
+        vendor: String?,
+        itemId: Long?
+    ): Mono<Page<FinanceRecord>> {
+        logger.info("Listing finance records")
+        return pageFinanceRecords(page, keyword, type, start, end, vendor, itemId)
+    }
+
+    private fun pageFinanceRecords(
+        page: Page<FinanceRecord>,
+        keyword: String?,
+        type: String?,
+        start: String?,
+        end: String?,
+        vendor: String?,
+        itemId: Long?
+    ): Mono<Page<FinanceRecord>> =
+        Mono.fromCallable {
+            val wrapper = financeRecordService.ktQuery()
+            if (!keyword.isNullOrBlank()) {
+                wrapper.and {
+                    it.like(FinanceRecord::recordNo, keyword)
+                        .or().like(FinanceRecord::vendor, keyword)
+                        .or().like(FinanceRecord::note, keyword)
+                }
+            }
+            if (!type.isNullOrBlank()) {
+                wrapper.eq(FinanceRecord::type, type)
+            }
+            if (!start.isNullOrBlank() && !end.isNullOrBlank()) {
+                wrapper.apply("occurred_at BETWEEN {0} AND {1}", start, end)
+            } else if (!start.isNullOrBlank()) {
+                wrapper.ge(FinanceRecord::occurredAt, start)
+            } else if (!end.isNullOrBlank()) {
+                wrapper.le(FinanceRecord::occurredAt, end)
+            }
+            if (!vendor.isNullOrBlank()) {
+                wrapper.eq(FinanceRecord::vendor, vendor)
+            }
+            if (itemId != null) {
+                wrapper.eq(FinanceRecord::relatedItemId, itemId)
+            }
+            financeRecordService.page(page, wrapper)
+        }.subscribeOn(Schedulers.boundedElastic())
+
+    fun createFinanceRecord(record: FinanceRecord): Mono<String> {
+        logger.info("Creating finance record")
+        val rightNow = getCurrentDateTime()
+        return financeRecordService.createFinanceRecord(
+            record.copy(
+                id = null,
+                createdAt = rightNow
+            )
+        ).flatMap { success ->
+            if (success) Mono.just("")
+            else Mono.just("finance record create failed.")
+        }
+    }
+
+    fun updateFinanceRecord(record: FinanceRecord): Mono<String> {
+        logger.info("Updating finance record")
+        if (record.id == null) return Mono.just("finance record id is required.")
+        return financeRecordService.updateFinanceRecord(record).flatMap { success ->
+            if (success) Mono.just("")
+            else Mono.just("finance record update failed.")
+        }
+    }
+
+    fun deleteFinanceRecord(id: Long?): Mono<String> {
+        logger.info("Deleting finance record with id {}", id)
+        if (id == null) return Mono.just("finance record id is required.")
+        return financeRecordService.deleteFinanceRecord(id).flatMap { success ->
+            if (success) cleanupFinanceAttachments(id).thenReturn("")
+            else Mono.just("finance record delete failed.")
+        }
+    }
+
+    fun uploadImages(id: Long, files: Flux<FilePart>): Mono<String> {
+        logger.info("Uploading images for finance record {}", id)
+        return financeRecordService.getFinanceRecordById(id)
+            .flatMap { _ ->
+                files.flatMap { file -> saveFinanceImage(id, file) }
+                    .collectList()
+                    .flatMap { attachments ->
+                        if (attachments.isEmpty()) {
+                            Mono.just("no image files provided.")
+                        } else {
+                            Flux.fromIterable(attachments)
+                                .flatMap { attachmentService.createAttachment(it) }
+                                .collectList()
+                                .flatMap { results ->
+                                    if (results.any { !it }) {
+                                        Mono.just("finance image upload failed.")
+                                    } else {
+                                        Mono.just("")
+                                    }
+                                }
+                        }
+                    }
+            }
+            .onErrorResume(NoSuchElementException::class.java) { Mono.just("finance record not found.") }
+            .onErrorResume { Mono.just(Const.INTERNAL_ERROR_STR) }
+    }
+
+    fun deleteById(id: Long?): Mono<String> {
+        logger.info("Deleting finance record {} and notifying by email", id)
+        if (id == null) return Mono.just("finance record id is required.")
+        return financeRecordService.getFinanceRecordById(id)
+            .flatMap { record ->
+                financeRecordService.deleteFinanceRecord(id)
+                    .flatMap { success ->
+                        if (success) {
+                            cleanupFinanceAttachments(id)
+                                .then(sendFinanceDeleteNotification(record))
+                                .thenReturn("")
+                        } else {
+                            Mono.just("finance record delete failed.")
+                        }
+                    }
+            }
+            .onErrorResume(NoSuchElementException::class.java) { Mono.just("finance record not found.") }
+            .onErrorResume { Mono.just(Const.INTERNAL_ERROR_STR) }
+    }
+
+    fun getFinanceCategories(): Mono<List<Category>> {
+        logger.info("Listing finance categories")
+        return categoryService.listAllCategories()
+    }
+
+    fun createFinanceCategory(category: Category): Mono<String> {
+        logger.info("Creating finance category")
+        return categoryService.createCategory(
+            category.copy(
+                id = null,
+                createdAt = getCurrentDateTime(),
+                updatedAt = getCurrentDateTime()
+            )
+        ).flatMap { success ->
+            if (success) Mono.just("")
+            else Mono.just("category create failed.")
+        }
+    }
+
+    fun updateFinanceCategory(category: Category): Mono<String> {
+        logger.info("Updating finance category")
+        if (category.id == null) return Mono.just("category id is required.")
+        return categoryService.updateCategory(
+            category.copy(updatedAt = getCurrentDateTime())
+        ).flatMap { success ->
+            if (success) Mono.just("")
+            else Mono.just("category update failed.")
+        }
+    }
+
+    fun deleteFinanceCategory(id: Long?): Mono<String> {
+        logger.info("Deleting finance category with id {}", id)
+        if (id == null) return Mono.just("category id is required.")
+        return categoryService.deleteCategory(id).flatMap { success ->
+            if (success) Mono.just("")
+            else Mono.just("category delete failed.")
+        }
+    }
+
+    private fun saveFinanceImage(financeRecordId: Long, file: FilePart): Mono<Attachment> {
+        val directory = Paths.get(dataPath, Const.FILE_DIR_IMAGE, "finance", financeRecordId.toString())
+        val savedName = generateSafeFileName(file.filename())
+        val target = directory.resolve(savedName)
+        return Mono.fromCallable {
+            Files.createDirectories(directory)
+            file.transferTo(target)
+            Attachment(
+                relatedTable = "finance_records",
+                relatedId = financeRecordId,
+                fileName = savedName,
+                filePath = target.toString(),
+                fileSize = Files.size(target),
+                contentType = file.headers().contentType?.toString(),
+                uploadedAt = getCurrentDateTime()
+            )
+        }.subscribeOn(Schedulers.boundedElastic())
+    }
+
+    private fun generateSafeFileName(original: String?): String {
+        val extension = original
+            ?.substringAfterLast('.')
+            ?.lowercase()
+            ?.takeIf {
+                it.isNotBlank() &&
+                    it.length <= 10 &&
+                    it.all { ch -> ch.isLetterOrDigit() }
+            }
+        return if (extension != null) "${UUID.randomUUID()}.$extension" else UUID.randomUUID().toString()
+    }
+
+    private fun cleanupFinanceAttachments(financeRecordId: Long): Mono<Boolean> {
+        return attachmentService.listByRelated("finance_records", financeRecordId)
+            .flatMap { attachments ->
+                Flux.fromIterable(attachments)
+                    .flatMap { deletePhysicalFile(it.filePath) }
+                    .then(attachmentService.deleteByRelated("finance_records", financeRecordId))
+            }
+            .onErrorResume { error ->
+                logger.warn("Failed to clean up attachments for finance record {}: {}", financeRecordId, error.message)
+                Mono.just(false)
+            }
+    }
+
+    private fun sendFinanceDeleteNotification(record: FinanceRecord): Mono<Void> {
+        val recordedBy = record.recordedBy ?: return Mono.empty()
+        return Mono.fromCallable { accountService.getById(recordedBy) }
+            .subscribeOn(Schedulers.boundedElastic())
+            .flatMap { account ->
+                val email = account.email
+                if (email.isNullOrBlank()) {
+                    logger.warn("Skipping finance delete notification for record {}: no email for account {}", record.id, recordedBy)
+                    Mono.empty()
+                } else {
+                    Mono.fromRunnable<Void> {
+                        amqpTemplate.convertAndSend(
+                            "mail",
+                            EmailVerificationMsg(
+                                email = email,
+                                type = EmailType.FINANCE_DELETE,
+                                code = record.recordNo ?: record.id?.toString() ?: ""
+                            )
+                        )
+                    }.subscribeOn(Schedulers.boundedElastic())
+                }
+            }
+    }
+
+    private fun deletePhysicalFile(path: String?): Mono<Void> {
+        if (path.isNullOrBlank()) return Mono.empty()
+        return Mono.fromRunnable<Void> {
+            try {
+                Files.deleteIfExists(Paths.get(path))
+            } catch (e: IOException) {
+                logger.warn("Failed to delete file: {}", path, e)
+            }
+        }.subscribeOn(Schedulers.boundedElastic())
+    }
+}
@@ -0,0 +1,84 @@
+package club.itstudio.itmanager.service.v1
+
+import club.itstudio.itmanager.entity.dto.Attachment
+import club.itstudio.itmanager.service.AttachmentService
+import club.itstudio.itmanager.utils.Const
+import club.itstudio.itmanager.utils.DateUtils.getCurrentDateTime
+import org.slf4j.LoggerFactory
+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.NoSuchElementException
+
+@Service
+class ProofImagesApiService(
+    private val attachmentService: AttachmentService
+) {
+    private val logger = LoggerFactory.getLogger(this::class.java)
+
+    fun getProofImages(): Mono<List<Attachment>> {
+        logger.info("Listing proof images")
+        return attachmentService.exportAllAttachments()
+            .map { list -> list.filter { it.relatedTable == RELATED_TABLE } }
+    }
+
+    fun createProofImage(attachment: Attachment): Mono<String> {
+        logger.info("Creating proof image")
+        return attachmentService.createAttachment(
+            attachment.copy(
+                id = null,
+                uploadedAt = getCurrentDateTime()
+            )
+        ).flatMap { success ->
+            if (success) Mono.just("")
+            else Mono.just("proof image create failed.")
+        }.onErrorResume { Mono.just(Const.INTERNAL_ERROR_STR) }
+    }
+
+    fun updateProofImage(attachment: Attachment): Mono<String> {
+        logger.info("Updating proof image")
+        if (attachment.id == null) return Mono.just("proof image id is required.")
+        return Mono.fromCallable { attachmentService.updateById(attachment) }
+            .subscribeOn(Schedulers.boundedElastic())
+            .flatMap { success ->
+                if (success) Mono.just("")
+                else Mono.just("proof image update failed.")
+            }
+            .onErrorResume { Mono.just(Const.INTERNAL_ERROR_STR) }
+    }
+
+    fun deleteProofImage(id: Long?): Mono<String> {
+        logger.info("Deleting proof image with id {}", id)
+        if (id == null) return Mono.just("proof image id is required.")
+        return attachmentService.getAttachmentById(id)
+            .flatMap { attachment ->
+                attachmentService.deleteAttachment(id).flatMap { success ->
+                    if (success) {
+                        deletePhysicalFile(attachment.filePath).thenReturn("")
+                    } else {
+                        Mono.just("proof image delete failed.")
+                    }
+                }
+            }
+            .onErrorResume(NoSuchElementException::class.java) { Mono.just("proof image not found.") }
+            .onErrorResume { Mono.just(Const.INTERNAL_ERROR_STR) }
+    }
+
+    private fun deletePhysicalFile(path: String?): Mono<Void> {
+        if (path.isNullOrBlank()) return Mono.empty()
+        return Mono.fromRunnable<Void> {
+            try {
+                Files.deleteIfExists(Paths.get(path))
+            } catch (e: IOException) {
+                logger.warn("Failed to delete file: {}", path, e)
+            }
+        }.subscribeOn(Schedulers.boundedElastic())
+    }
+
+    companion object {
+        private const val RELATED_TABLE = "finance_records"
+    }
+}
@@ -0,0 +1,234 @@
+package club.itstudio.itmanager.service.v1
+
+import club.itstudio.itmanager.entity.dto.Attachment
+import club.itstudio.itmanager.entity.dto.BorrowRecord
+import club.itstudio.itmanager.service.AttachmentService
+import club.itstudio.itmanager.service.BorrowRecordService
+import club.itstudio.itmanager.utils.Const
+import club.itstudio.itmanager.utils.DateUtils.getCurrentDateTime
+import com.baomidou.mybatisplus.core.toolkit.Wrappers
+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.Flux
+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.NoSuchElementException
+import java.util.UUID
+
+@Service
+class UsagesApiService(
+    private val borrowRecordService: BorrowRecordService,
+    private val attachmentService: AttachmentService,
+
+    @Value($$"${app.file.data-path}")
+    private val dataPath: String
+) {
+    private val logger = LoggerFactory.getLogger(this::class.java)
+
+    fun getUsages(page: Page<BorrowRecord>, keyword: String?, status: String?): Mono<Page<BorrowRecord>> {
+        logger.info("Paging usages with keyword and status")
+        return Mono.fromCallable {
+            val wrapper = Wrappers.lambdaQuery<BorrowRecord>()
+            if (!keyword.isNullOrBlank()) {
+                wrapper.like(BorrowRecord::borrower, keyword)
+            }
+            if (!status.isNullOrBlank()) {
+                wrapper.eq(BorrowRecord::status, status)
+            }
+            wrapper.orderByDesc(BorrowRecord::createdAt)
+            borrowRecordService.page(page, wrapper)
+        }.subscribeOn(Schedulers.boundedElastic())
+    }
+
+    fun createUsage(record: BorrowRecord): Mono<String> {
+        logger.info("Creating usage")
+        val rightNow = getCurrentDateTime()
+        return borrowRecordService.createBorrowRecord(
+            record.copy(
+                id = null,
+                createdAt = rightNow,
+                updatedAt = rightNow
+            )
+        ).flatMap { success ->
+            if (success) Mono.just("")
+            else Mono.just("usage create failed.")
+        }.onErrorResume { Mono.just(Const.INTERNAL_ERROR_STR) }
+    }
+
+    fun updateUsage(record: BorrowRecord): Mono<String> {
+        logger.info("Updating usage")
+        if (record.id == null) return Mono.just("usage id is required.")
+        return borrowRecordService.updateBorrowRecord(
+            record.copy(updatedAt = getCurrentDateTime())
+        ).flatMap { success ->
+            if (success) Mono.just("")
+            else Mono.just("usage update failed.")
+        }.onErrorResume { Mono.just(Const.INTERNAL_ERROR_STR) }
+    }
+
+    fun deleteUsage(id: Long?): Mono<String> {
+        logger.info("Deleting usage with id {}", id)
+        if (id == null) return Mono.just("usage id is required.")
+        return borrowRecordService.deleteBorrowRecord(id).flatMap { success ->
+            if (success) {
+                cleanupUsageAttachments(id)
+            } else {
+                Mono.just("usage delete failed.")
+            }
+        }.onErrorResume { Mono.just(Const.INTERNAL_ERROR_STR) }
+    }
+
+    fun uploadImages(id: Long, files: Flux<FilePart>): Mono<String> {
+        logger.info("Uploading images for usage {}", id)
+        return borrowRecordService.getBorrowRecordById(id)
+            .flatMap { _ ->
+                files.flatMap { file -> saveUsageImage(id, file) }
+                    .collectList()
+                    .flatMap { attachments ->
+                        if (attachments.isEmpty()) {
+                            Mono.just("no image files provided.")
+                        } else {
+                            Flux.fromIterable(attachments)
+                                .flatMap { attachmentService.createAttachment(it) }
+                                .collectList()
+                                .flatMap { results ->
+                                    if (results.any { !it }) {
+                                        Mono.just("usage image upload failed.")
+                                    } else {
+                                        Mono.just("")
+                                    }
+                                }
+                        }
+                    }
+            }
+            .onErrorResume(NoSuchElementException::class.java) { Mono.just("usage not found.") }
+            .onErrorResume { Mono.just(Const.INTERNAL_ERROR_STR) }
+    }
+
+    fun getCurrentUsages(): Mono<List<BorrowRecord>> {
+        logger.info("Listing current usages")
+        return borrowRecordService.listByStatus(STATUS_BORROWED)
+            .zipWith(borrowRecordService.listOverdueRecords()) { borrowed, overdue -> borrowed + overdue }
+    }
+
+    fun getUsagesByUser(name: String?): Mono<List<BorrowRecord>> {
+        logger.info("Listing usages by user {}", name)
+        if (name.isNullOrBlank()) return Mono.just(emptyList())
+        return borrowRecordService.listByBorrower(name)
+    }
+
+    fun getUsageImages(): Mono<List<Attachment>> {
+        logger.info("Listing usage images")
+        return attachmentService.exportAllAttachments()
+            .map { list -> list.filter { it.relatedTable == RELATED_TABLE } }
+    }
+
+    fun createUsageImage(attachment: Attachment): Mono<String> {
+        logger.info("Creating usage image")
+        return attachmentService.createAttachment(
+            attachment.copy(
+                id = null,
+                uploadedAt = getCurrentDateTime()
+            )
+        ).flatMap { success ->
+            if (success) Mono.just("")
+            else Mono.just("usage image create failed.")
+        }.onErrorResume { Mono.just(Const.INTERNAL_ERROR_STR) }
+    }
+
+    fun updateUsageImage(attachment: Attachment): Mono<String> {
+        logger.info("Updating usage image")
+        if (attachment.id == null) return Mono.just("usage image id is required.")
+        return Mono.fromCallable { attachmentService.updateById(attachment) }
+            .subscribeOn(Schedulers.boundedElastic())
+            .flatMap { success ->
+                if (success) Mono.just("")
+                else Mono.just("usage image update failed.")
+            }
+            .onErrorResume { Mono.just(Const.INTERNAL_ERROR_STR) }
+    }
+
+    fun deleteUsageImage(id: Long?): Mono<String> {
+        logger.info("Deleting usage image with id {}", id)
+        if (id == null) return Mono.just("usage image id is required.")
+        return attachmentService.getAttachmentById(id)
+            .flatMap { attachment ->
+                attachmentService.deleteAttachment(id).flatMap { success ->
+                    if (success) {
+                        deletePhysicalFile(attachment.filePath).thenReturn("")
+                    } else {
+                        Mono.just("usage image delete failed.")
+                    }
+                }
+            }
+            .onErrorResume(NoSuchElementException::class.java) { Mono.just("usage image not found.") }
+            .onErrorResume { Mono.just(Const.INTERNAL_ERROR_STR) }
+    }
+
+    private fun saveUsageImage(usageId: Long, file: FilePart): Mono<Attachment> {
+        val directory = Paths.get(dataPath, Const.FILE_DIR_IMAGE, "borrow_records", usageId.toString())
+        val savedName = generateSafeFileName(file.filename())
+        val target = directory.resolve(savedName)
+        return Mono.fromCallable {
+            Files.createDirectories(directory)
+            file.transferTo(target)
+            Attachment(
+                relatedTable = RELATED_TABLE,
+                relatedId = usageId,
+                fileName = savedName,
+                filePath = target.toString(),
+                fileSize = Files.size(target),
+                contentType = file.headers().contentType?.toString(),
+                uploadedAt = getCurrentDateTime()
+            )
+        }.subscribeOn(Schedulers.boundedElastic())
+    }
+
+    private fun generateSafeFileName(original: String?): String {
+        val extension = original
+            ?.substringAfterLast('.')
+            ?.lowercase()
+            ?.takeIf {
+                it.isNotBlank() &&
+                    it.length <= 10 &&
+                    it.all { ch -> ch.isLetterOrDigit() }
+            }
+        return if (extension != null) "${UUID.randomUUID()}.$extension" else UUID.randomUUID().toString()
+    }
+
+    private fun cleanupUsageAttachments(usageId: Long): Mono<String> {
+        return attachmentService.listByRelated(RELATED_TABLE, usageId)
+            .flatMap { attachments ->
+                Flux.fromIterable(attachments)
+                    .flatMap { deletePhysicalFile(it.filePath) }
+                    .then(attachmentService.deleteByRelated(RELATED_TABLE, usageId))
+                    .thenReturn("")
+            }
+            .onErrorResume { error ->
+                logger.warn("Failed to clean up attachments for usage {}: {}", usageId, error.message)
+                Mono.just("")
+            }
+    }
+
+    private fun deletePhysicalFile(path: String?): Mono<Void> {
+        if (path.isNullOrBlank()) return Mono.empty()
+        return Mono.fromRunnable<Void> {
+            try {
+                Files.deleteIfExists(Paths.get(path))
+            } catch (e: IOException) {
+                logger.warn("Failed to delete file: {}", path, e)
+            }
+        }.subscribeOn(Schedulers.boundedElastic())
+    }
+
+    companion object {
+        private const val RELATED_TABLE = "borrow_records"
+        private const val STATUS_BORROWED = "BORROWED"
+    }
+}