From b32f062594cf587b6473a51825d434bd00fa397a Mon Sep 17 00:00:00 2001 From: FatttSnake Date: Thu, 15 Feb 2024 23:59:21 +0800 Subject: [PATCH] Add kdoc --- .../controller/tool/ManagementController.kt | 6 ++ .../api/converter/tool/ToolConverter.kt | 12 ++++ .../api/mapper/permission/UserMapper.kt | 2 +- .../oxygen/api/mapper/tool/EditMapper.kt | 44 +++++++++++++- .../api/mapper/tool/ManagementMapper.kt | 30 ++++++++++ .../oxygen/api/mapper/tool/ToolBaseMapper.kt | 9 +++ .../api/mapper/tool/ToolTemplateMapper.kt | 17 ++++++ .../param/api/v1/avatar/AvatarGitHubParam.kt | 1 + .../api/param/permission/ForgetParam.kt | 1 + .../oxygen/api/param/permission/LoginParam.kt | 1 + .../api/param/permission/RegisterParam.kt | 1 + .../api/param/permission/RetrieveParam.kt | 1 + .../api/param/tool/ToolManagementGetParam.kt | 7 +++ .../oxygen/api/service/tool/IEditService.kt | 26 ++++++++- .../api/service/tool/IManagementService.kt | 57 +++++++++++++++++++ .../api/service/tool/impl/EditServiceImpl.kt | 4 +- src/main/resources/mapper/tool/EditMapper.xml | 4 +- 17 files changed, 215 insertions(+), 8 deletions(-) diff --git a/src/main/kotlin/top/fatweb/oxygen/api/controller/tool/ManagementController.kt b/src/main/kotlin/top/fatweb/oxygen/api/controller/tool/ManagementController.kt index 24e2715..c518250 100644 --- a/src/main/kotlin/top/fatweb/oxygen/api/controller/tool/ManagementController.kt +++ b/src/main/kotlin/top/fatweb/oxygen/api/controller/tool/ManagementController.kt @@ -12,6 +12,12 @@ import top.fatweb.oxygen.api.service.tool.IManagementService import top.fatweb.oxygen.api.vo.PageVo import top.fatweb.oxygen.api.vo.tool.ToolVo +/** + * Tool management controller + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ @BaseController(path = ["/system/tool"], name = "工具管理", description = "工具管理相关接口") class ManagementController( private val managementService: IManagementService diff --git a/src/main/kotlin/top/fatweb/oxygen/api/converter/tool/ToolConverter.kt b/src/main/kotlin/top/fatweb/oxygen/api/converter/tool/ToolConverter.kt index 9d273b6..b5b378d 100644 --- a/src/main/kotlin/top/fatweb/oxygen/api/converter/tool/ToolConverter.kt +++ b/src/main/kotlin/top/fatweb/oxygen/api/converter/tool/ToolConverter.kt @@ -43,6 +43,18 @@ object ToolConverter { updateTime = tool.updateTime ) + /** + * Convert Page object into PageVo object + * + * @param toolPage Page object + * @return PageVo object + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + * @see Page + * @see Tool + * @see PageVo + * @see ToolVo + */ fun toolPageToToolPageVo(toolPage: Page): PageVo = PageVo( total = toolPage.total, pages = toolPage.pages, diff --git a/src/main/kotlin/top/fatweb/oxygen/api/mapper/permission/UserMapper.kt b/src/main/kotlin/top/fatweb/oxygen/api/mapper/permission/UserMapper.kt index 1f91df6..836b217 100644 --- a/src/main/kotlin/top/fatweb/oxygen/api/mapper/permission/UserMapper.kt +++ b/src/main/kotlin/top/fatweb/oxygen/api/mapper/permission/UserMapper.kt @@ -28,7 +28,7 @@ interface UserMapper : BaseMapper { fun selectOneWithPowerInfoByAccount(@Param("account") account: String): User? /** - * Select user in page + * Select user ID in page * * @param page Pagination * @param searchType Type of search diff --git a/src/main/kotlin/top/fatweb/oxygen/api/mapper/tool/EditMapper.kt b/src/main/kotlin/top/fatweb/oxygen/api/mapper/tool/EditMapper.kt index d31a8eb..3cfca8b 100644 --- a/src/main/kotlin/top/fatweb/oxygen/api/mapper/tool/EditMapper.kt +++ b/src/main/kotlin/top/fatweb/oxygen/api/mapper/tool/EditMapper.kt @@ -16,13 +16,53 @@ import top.fatweb.oxygen.api.entity.tool.ToolTemplate */ @Mapper interface EditMapper : BaseMapper { - fun getTemplate(@Param("id") id: Long): ToolTemplate? + /** + * Select tool template by ID + * + * @param id Template ID + * @return ToolTemplate object + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + * @see ToolTemplate + */ + fun selectTemplate(@Param("id") id: Long): ToolTemplate? + /** + * Select tool by ID and user ID + * + * @param id Tool ID + * @param userId User ID + * @return Tool object + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + * @see Tool + */ fun selectOne(@Param("id") id: Long, @Param("userId") userId: Long): Tool? + /** + * Select tool in list by User ID + * + * @param userId User ID + * @return List of tool object + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + * @see Tool + */ fun selectPersonal(@Param("userId") userId: Long): List - fun detail( + /** + * Select tool detail + * + * @param username Username + * @param toolId Tool ID + * @param ver Tool version + * @param operator Operator username + * @return List of tool object + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + * @see Tool + */ + fun selectDetail( @Param("username") username: String, @Param("toolId") toolId: String, @Param("ver") ver: String, diff --git a/src/main/kotlin/top/fatweb/oxygen/api/mapper/tool/ManagementMapper.kt b/src/main/kotlin/top/fatweb/oxygen/api/mapper/tool/ManagementMapper.kt index 185bc30..f29865b 100644 --- a/src/main/kotlin/top/fatweb/oxygen/api/mapper/tool/ManagementMapper.kt +++ b/src/main/kotlin/top/fatweb/oxygen/api/mapper/tool/ManagementMapper.kt @@ -16,8 +16,30 @@ import top.fatweb.oxygen.api.entity.tool.Tool */ @Mapper interface ManagementMapper : BaseMapper { + /** + * Select tool by ID + * + * @param id Tool ID + * @return Tool object + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + * @see Tool + */ fun selectOne(@Param("id") id: Long): Tool? + /** + * Select tool ID in page + * + * @param page Pagination + * @param review Review + * @param searchType Type of search + * @param searchValue Value to search for + * @param searchRegex Use regex + * @return Tool object in page + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + * @see IPage + */ fun selectPage( page: IPage, @Param("review") review: List?, @@ -26,5 +48,13 @@ interface ManagementMapper : BaseMapper { @Param("searchRegex") searchRegex: Boolean ): IPage + /** + * Select tool in list by tool IDs + * + * @param ids List of tool IDs + * @return List of tool object + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ fun selectListByIds(@Param("ids") ids: List): List } \ No newline at end of file diff --git a/src/main/kotlin/top/fatweb/oxygen/api/mapper/tool/ToolBaseMapper.kt b/src/main/kotlin/top/fatweb/oxygen/api/mapper/tool/ToolBaseMapper.kt index 51f9d82..26f470f 100644 --- a/src/main/kotlin/top/fatweb/oxygen/api/mapper/tool/ToolBaseMapper.kt +++ b/src/main/kotlin/top/fatweb/oxygen/api/mapper/tool/ToolBaseMapper.kt @@ -15,5 +15,14 @@ import top.fatweb.oxygen.api.entity.tool.ToolBase */ @Mapper interface ToolBaseMapper : BaseMapper { + /** + * Select tool base by ID + * + * @param id Tool base ID + * @return ToolBase object + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + * @see ToolBase + */ fun selectOne(@Param("id") id: Long): ToolBase? } \ No newline at end of file diff --git a/src/main/kotlin/top/fatweb/oxygen/api/mapper/tool/ToolTemplateMapper.kt b/src/main/kotlin/top/fatweb/oxygen/api/mapper/tool/ToolTemplateMapper.kt index a11ce86..e50c009 100644 --- a/src/main/kotlin/top/fatweb/oxygen/api/mapper/tool/ToolTemplateMapper.kt +++ b/src/main/kotlin/top/fatweb/oxygen/api/mapper/tool/ToolTemplateMapper.kt @@ -15,7 +15,24 @@ import top.fatweb.oxygen.api.entity.tool.ToolTemplate */ @Mapper interface ToolTemplateMapper : BaseMapper { + /** + * Select tool template by ID + * + * @param id Tool template ID + * @return ToolTemplate object + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + * @see ToolTemplate + */ fun selectOne(@Param("id") id: Long): ToolTemplate? + /** + * Select tool template in list + * + * @return List of ToolTemplate object + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + * @see ToolTemplate + */ fun selectList(): List } \ No newline at end of file diff --git a/src/main/kotlin/top/fatweb/oxygen/api/param/api/v1/avatar/AvatarGitHubParam.kt b/src/main/kotlin/top/fatweb/oxygen/api/param/api/v1/avatar/AvatarGitHubParam.kt index 58e4908..6ea06a5 100644 --- a/src/main/kotlin/top/fatweb/oxygen/api/param/api/v1/avatar/AvatarGitHubParam.kt +++ b/src/main/kotlin/top/fatweb/oxygen/api/param/api/v1/avatar/AvatarGitHubParam.kt @@ -8,6 +8,7 @@ import jakarta.validation.constraints.Max * * @author FatttSnake, fatttsnake@gmail.com * @since 1.0.0 + * @see AvatarBaseParam */ data class AvatarGitHubParam( /** diff --git a/src/main/kotlin/top/fatweb/oxygen/api/param/permission/ForgetParam.kt b/src/main/kotlin/top/fatweb/oxygen/api/param/permission/ForgetParam.kt index e6ff4ce..de70365 100644 --- a/src/main/kotlin/top/fatweb/oxygen/api/param/permission/ForgetParam.kt +++ b/src/main/kotlin/top/fatweb/oxygen/api/param/permission/ForgetParam.kt @@ -10,6 +10,7 @@ import top.fatweb.oxygen.api.param.CaptchaCodeParam * * @author FatttSnake, fatttsnake@gmail.com * @since 1.0.0 + * @see CaptchaCodeParam */ @Schema(description = "忘记密码请求参数") data class ForgetParam( diff --git a/src/main/kotlin/top/fatweb/oxygen/api/param/permission/LoginParam.kt b/src/main/kotlin/top/fatweb/oxygen/api/param/permission/LoginParam.kt index 8112d73..df53af9 100644 --- a/src/main/kotlin/top/fatweb/oxygen/api/param/permission/LoginParam.kt +++ b/src/main/kotlin/top/fatweb/oxygen/api/param/permission/LoginParam.kt @@ -9,6 +9,7 @@ import top.fatweb.oxygen.api.param.CaptchaCodeParam * * @author FatttSnake, fatttsnake@gmail.com * @since 1.0.0 + * @see CaptchaCodeParam */ @Schema(description = "登录请求参数") data class LoginParam( diff --git a/src/main/kotlin/top/fatweb/oxygen/api/param/permission/RegisterParam.kt b/src/main/kotlin/top/fatweb/oxygen/api/param/permission/RegisterParam.kt index 47af7de..88f017a 100644 --- a/src/main/kotlin/top/fatweb/oxygen/api/param/permission/RegisterParam.kt +++ b/src/main/kotlin/top/fatweb/oxygen/api/param/permission/RegisterParam.kt @@ -11,6 +11,7 @@ import top.fatweb.oxygen.api.param.CaptchaCodeParam * * @author FatttSnake, fatttsnake@gmail.com * @since 1.0.0 + * @see CaptchaCodeParam */ @Schema(description = "注册请求参数") data class RegisterParam( diff --git a/src/main/kotlin/top/fatweb/oxygen/api/param/permission/RetrieveParam.kt b/src/main/kotlin/top/fatweb/oxygen/api/param/permission/RetrieveParam.kt index b94a786..1b8f685 100644 --- a/src/main/kotlin/top/fatweb/oxygen/api/param/permission/RetrieveParam.kt +++ b/src/main/kotlin/top/fatweb/oxygen/api/param/permission/RetrieveParam.kt @@ -10,6 +10,7 @@ import top.fatweb.oxygen.api.param.CaptchaCodeParam * * @author FatttSnake, fatttsnake@gmail.com * @since 1.0.0 + * @see CaptchaCodeParam */ @Schema(description = "找回密码请求参数") data class RetrieveParam( diff --git a/src/main/kotlin/top/fatweb/oxygen/api/param/tool/ToolManagementGetParam.kt b/src/main/kotlin/top/fatweb/oxygen/api/param/tool/ToolManagementGetParam.kt index 8948910..0c8fc83 100644 --- a/src/main/kotlin/top/fatweb/oxygen/api/param/tool/ToolManagementGetParam.kt +++ b/src/main/kotlin/top/fatweb/oxygen/api/param/tool/ToolManagementGetParam.kt @@ -3,6 +3,13 @@ package top.fatweb.oxygen.api.param.tool import io.swagger.v3.oas.annotations.media.Schema import top.fatweb.oxygen.api.param.PageSortParam +/** + * Get tool in management parameters + * + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + * @see PageSortParam + */ data class ToolManagementGetParam( /** * Type of search diff --git a/src/main/kotlin/top/fatweb/oxygen/api/service/tool/IEditService.kt b/src/main/kotlin/top/fatweb/oxygen/api/service/tool/IEditService.kt index 31da2ef..3a92b4a 100644 --- a/src/main/kotlin/top/fatweb/oxygen/api/service/tool/IEditService.kt +++ b/src/main/kotlin/top/fatweb/oxygen/api/service/tool/IEditService.kt @@ -52,7 +52,8 @@ interface IEditService : IService { /** * Get tool by ID * - * @param + * @param id Tool ID + * @return ToolVo object * @author FatttSnake, fatttsnake@gmail.com * @since 1.0.0 */ @@ -61,14 +62,20 @@ interface IEditService : IService { /** * Create tool * + * @param toolCreateParam Create tool parameters + * @return ToolVo object * @author FatttSnake, fatttsnake@gmail.com * @since 1.0.0 + * @see ToolCreateParam + * @see ToolVo */ fun create(toolCreateParam: ToolCreateParam): ToolVo /** * Upgrade tool * + * @param toolUpgradeParam Upgrade tool parameters + * @return ToolVo object * @author FatttSnake, fatttsnake@gmail.com * @since 1.0.0 * @see ToolUpgradeParam @@ -79,30 +86,43 @@ interface IEditService : IService { /** * Update tool * + * @param toolUpdateParam Update tool parameters + * @return ToolVo object * @author FatttSnake, fatttsnake@gmail.com * @since 1.0.0 + * @see ToolUpdateParam + * @see ToolVo */ fun update(toolUpdateParam: ToolUpdateParam): ToolVo /** * Get personal tools * + * @return List of ToolVo object * @author FatttSnake, fatttsnake@gmail.com * @since 1.0.0 + * @see ToolVo */ fun get(): List /** * Get tool detail * + * @param username Username + * @param toolId Tool ID + * @param ver Version + * @return ToolVo object * @author FatttSnake, fatttsnake@gmail.com * @since 1.0.0 + * @see ToolVo */ fun detail(username: String, toolId: String, ver: String): ToolVo /** * Submit tool review * + * @param id Tool ID + * @return Result * @author FatttSnake, fatttsnake@gmail.com * @since 1.0.0 */ @@ -111,6 +131,8 @@ interface IEditService : IService { /** * Cancel tool review * + * @param id Tool ID + * @return Result * @author FatttSnake, fatttsnake@gmail.com * @since 1.0.0 */ @@ -119,6 +141,8 @@ interface IEditService : IService { /** * Delete tool * + * @param id Tool ID + * @return Result * @author FatttSnake, fatttsnake@gmail.com * @since 1.0.0 */ diff --git a/src/main/kotlin/top/fatweb/oxygen/api/service/tool/IManagementService.kt b/src/main/kotlin/top/fatweb/oxygen/api/service/tool/IManagementService.kt index 8be97b4..039ad51 100644 --- a/src/main/kotlin/top/fatweb/oxygen/api/service/tool/IManagementService.kt +++ b/src/main/kotlin/top/fatweb/oxygen/api/service/tool/IManagementService.kt @@ -16,15 +16,72 @@ import top.fatweb.oxygen.api.vo.tool.ToolVo * @see Tool */ interface IManagementService : IService { + /** + * Get tool by ID + * + * @param id Tool ID + * @return ToolVo object + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + * @see ToolVo + */ fun getOne(id: Long): ToolVo + /** + * Get tool as page + * + * @param toolManagementGetParam Get tool parameters in tool management + * @return PageVo object + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + * @see ToolManagementGetParam + * @see PageVo + * @see ToolVo + */ fun getPage(toolManagementGetParam: ToolManagementGetParam?): PageVo + /** + * Pass tool review + * + * @param id Tool ID + * @param toolManagementPassParam Pass tool review parameters in tool management + * @return ToolVo object + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + * @see ToolManagementPassParam + * @see ToolVo + */ fun pass(id: Long, toolManagementPassParam: ToolManagementPassParam): ToolVo + /** + * Reject tool review + * + * @param id Tool ID + * @return ToolVo object + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + * @see ToolVo + */ fun reject(id: Long): ToolVo + /** + * Off shelve tool + * + * @param id Tool ID + * @return ToolVo object + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + * @see ToolVo + */ fun offShelve(id: Long): ToolVo + /** + * Delete tool + * + * @param id Tool ID + * @return Result + * @author FatttSnake, fatttsnake@gmail.com + * @since 1.0.0 + */ fun delete(id: Long): Boolean } \ No newline at end of file diff --git a/src/main/kotlin/top/fatweb/oxygen/api/service/tool/impl/EditServiceImpl.kt b/src/main/kotlin/top/fatweb/oxygen/api/service/tool/impl/EditServiceImpl.kt index af4caa3..7b2eecd 100644 --- a/src/main/kotlin/top/fatweb/oxygen/api/service/tool/impl/EditServiceImpl.kt +++ b/src/main/kotlin/top/fatweb/oxygen/api/service/tool/impl/EditServiceImpl.kt @@ -43,7 +43,7 @@ class EditServiceImpl( .map(ToolTemplateConverter::toolTemplateToToolTemplateVoByList) override fun getTemplate(id: Long): ToolTemplateVo = - baseMapper.getTemplate(id)?.let(ToolTemplateConverter::toolTemplateToToolTemplateVoWithBaseDist) + baseMapper.selectTemplate(id)?.let(ToolTemplateConverter::toolTemplateToToolTemplateVoWithBaseDist) ?: throw NoRecordFoundException() override fun getCategory(): List = @@ -210,7 +210,7 @@ class EditServiceImpl( if (username == "!" && WebUtil.getLoginUserId() == null) { throw NoRecordFoundException() } - val toolList = baseMapper.detail(username, toolId, ver, WebUtil.getLoginUsername()) + val toolList = baseMapper.selectDetail(username, toolId, ver, WebUtil.getLoginUsername()) if (toolList.isNullOrEmpty()) { throw NoRecordFoundException() } diff --git a/src/main/resources/mapper/tool/EditMapper.xml b/src/main/resources/mapper/tool/EditMapper.xml index 910c7ea..591d72f 100644 --- a/src/main/resources/mapper/tool/EditMapper.xml +++ b/src/main/resources/mapper/tool/EditMapper.xml @@ -1,7 +1,7 @@ - select t_b_tool_template.id as tool_template_id, t_b_tool_template.name as tool_template_name, t_b_tool_template.base_id as tool_template_base_id, @@ -128,7 +128,7 @@ order by t_b_tool_main.id desc - select t_b_tool_main.id as tool_id, t_b_tool_main.name as tool_name, t_b_tool_main.tool_id as tool_tool_id,