账密登录接口

huimv-employment/fe-api/src/main/java/com/huimv/employment/controller/mp/AgentController.java

@@ -34,7 +34,9 @@ public class AgentController {
     }
 
     @PostMapping("/messages")
-    @Operation(summary = "发送消息并获取 AI 回复")
+    @Operation(summary = "发送消息并获取 AI 回复",
+            description = "向智能体发送用户消息，返回 AI 回复文本及会话 ID。"
+                    + "conversationId 不传时服务端自动生成，后续多轮对话传入同一 ID 以保持上下文。")
     public R<AgentMessageResponse> sendMessage(@Validated @RequestBody AgentMessageRequest request) {
         LoginUser loginUser = LoginUserHolder.require();
         AgentMessageResponse response = agentChatService.chat(

huimv-employment/fe-api/src/main/java/com/huimv/employment/controller/mp/AiProxyController.java

@@ -37,13 +37,16 @@ public class AiProxyController {
     }
 
     @GetMapping("/models")
-    @Operation(summary = "获取可用模型列表（OpenAI 兼容）")
+    @Operation(summary = "获取可用模型列表", description = "OpenAI 兼容 GET /v1/models，透传上游 KB 服务响应。")
     public ResponseEntity<byte[]> models() {
         return kbOpenAiProxyService.listModels();
     }
 
     @PostMapping(value = "/chat/completions", consumes = MediaType.APPLICATION_JSON_VALUE)
-    @Operation(summary = "对话补全（OpenAI 兼容，支持 SSE 流式）")
+    @Operation(summary = "对话补全（OpenAI 兼容）",
+            description = "请求/响应体与 OpenAI Chat Completions 规范一致，透传上游 KB 服务。"
+                    + "请求体示例：{\"model\":\"gpt-4\",\"messages\":[{\"role\":\"user\",\"content\":\"你好\"}],\"stream\":false}"
+                    + "；stream=true 时返回 text/event-stream SSE 流式响应。")
     public void chatCompletions(HttpServletRequest request, HttpServletResponse response) throws IOException {
         byte[] body = StreamUtils.copyToByteArray(request.getInputStream());
         if (kbOpenAiProxyService.isStreamRequest(body)) {

huimv-employment/fe-api/src/main/java/com/huimv/employment/controller/mp/AuthController.java

@@ -27,10 +27,14 @@ import org.springframework.web.bind.annotation.RestController;
 
 /**
  * 小程序端认证：短信 / 微信 / 可选账密（登录后设置）。
+ * <p>
+ * 登录成功后返回 JWT，后续请求 Header 携带 {@code Authorization: Bearer <token>}。
+ * 账密相关密码字段须先调用 {@code GET /password/public-key} 获取 RSA 公钥，前端加密后再提交。
+ * </p>
  */
 @RestController
 @RequestMapping("/api/v1/mp/auth")
-@Tag(name = "认证", description = "登录与账密管理，除 set/status 外均为匿名访问")
+@Tag(name = "认证", description = "短信/微信/账密登录与密码管理。除 password/set、password/status 外均为匿名访问")
 public class AuthController {
 
     private final AuthService authService;
@@ -42,37 +46,51 @@ public class AuthController {
     }
 
     @PostMapping("/sms/send")
-    @Operation(summary = "发送登录验证码")
+    @Operation(summary = "发送登录验证码",
+            description = "向指定手机号发送 6 位登录验证码，同一号码 60 秒内不可重复发送。"
+                    + "Mock 模式（fe.sms.mock-enabled=true）下不实际发短信，验证码固定为 123456。"
+                    + "须携带 userType，决定登录后的小程序端身份（enterprise / worker）。")
     public R<SmsSendResponse> sendSmsCode(@Validated @RequestBody SmsSendRequest request) {
         return R.ok(authService.sendLoginCode(request));
     }
 
     @PostMapping("/sms/login")
-    @Operation(summary = "短信验证码登录")
+    @Operation(summary = "短信验证码登录",
+            description = "校验验证码后登录或自动注册，返回 JWT 及用户基本信息。"
+                    + "登录成功后建议调用 GET /api/v1/mp/getInfo 查询登记状态。")
     public R<LoginResponse> loginBySms(@Validated @RequestBody SmsLoginRequest request) {
         return R.ok(authService.loginBySms(request));
     }
 
     @PostMapping("/wechat/login")
-    @Operation(summary = "微信小程序 code 登录")
+    @Operation(summary = "微信小程序 code 登录",
+            description = "使用 wx.login 获取的 code 换取 openid 并登录。"
+                    + "Mock 模式（fe.wechat.miniapp.mock-enabled=true）下 code 可为任意非空字符串。"
+                    + "短信用户与微信用户一期未做账号合并，openid 与手机号分别建号。")
     public R<LoginResponse> loginByWechat(@Validated @RequestBody WechatLoginRequest request) {
         return R.ok(authService.loginByWechat(request));
     }
 
     @GetMapping("/password/public-key")
-    @Operation(summary = "获取 RSA 公钥（前端加密密码）")
+    @Operation(summary = "获取 RSA 公钥",
+            description = "返回 PEM 格式 RSA 公钥，前端用于加密密码后再调用 login/set/reset 接口。"
+                    + "明文密码不在网络传输，服务端解密后 BCrypt 入库。")
     public R<PasswordPublicKeyResponse> passwordPublicKey() {
         return R.ok(passwordAuthService.getPublicKey());
     }
 
     @PostMapping("/password/login")
-    @Operation(summary = "用户名/手机号 + 密码登录")
+    @Operation(summary = "用户名/手机号 + 密码登录",
+            description = "account 支持用户名或手机号；encryptedPassword 为 RSA 加密后的 Base64 字符串。"
+                    + "连续密码错误 5 次将锁定账号 30 分钟。")
     public R<LoginResponse> loginByPassword(@Validated @RequestBody PasswordLoginRequest request) {
         return R.ok(passwordAuthService.loginByPassword(request));
     }
 
     @PostMapping("/password/set")
-    @Operation(summary = "设置或修改登录密码（需 JWT）")
+    @Operation(summary = "设置或修改登录密码",
+            description = "需 JWT 鉴权。首次设密须传 username（全局唯一）及 encryptedPassword、encryptedConfirmPassword。"
+                    + "已设密用户改密须额外传 encryptedOldPassword。所有密码字段均为 RSA 加密 Base64。")
     @SecurityRequirement(name = "Authorization")
     public R<Void> setPassword(@Validated @RequestBody PasswordSetRequest request) {
         LoginUser loginUser = LoginUserHolder.require();
@@ -81,14 +99,17 @@ public class AuthController {
     }
 
     @PostMapping("/password/reset")
-    @Operation(summary = "短信验证码重置密码")
+    @Operation(summary = "短信验证码重置密码",
+            description = "忘记密码场景：先调用 POST /sms/send 获取验证码，再提交手机号、验证码及新密码（RSA 加密）。"
+                    + "手机号须为已注册账号。")
     public R<Void> resetPassword(@Validated @RequestBody PasswordResetRequest request) {
         passwordAuthService.resetPassword(request);
         return R.ok();
     }
 
     @GetMapping("/password/status")
-    @Operation(summary = "查询是否已设置登录密码")
+    @Operation(summary = "查询是否已设置登录密码",
+            description = "需 JWT 鉴权。返回 passwordSet 及 usernameMask（已设密时）。")
     @SecurityRequirement(name = "Authorization")
     public R<PasswordStatusResponse> passwordStatus() {
         LoginUser loginUser = LoginUserHolder.require();

huimv-employment/fe-common/pom.xml

@@ -18,5 +18,9 @@
             <groupId>org.springframework.security</groupId>
             <artifactId>spring-security-crypto</artifactId>
         </dependency>
+        <dependency>
+            <groupId>io.swagger.core.v3</groupId>
+            <artifactId>swagger-annotations</artifactId>
+        </dependency>
     </dependencies>
 </project>

huimv-employment/fe-common/src/main/java/com/huimv/employment/common/web/R.java

@@ -1,30 +1,24 @@
 package com.huimv.employment.common.web;
 
+import io.swagger.v3.oas.annotations.media.Schema;
+
 import java.io.Serializable;
 
 /**
  * 统一 API 响应体，与技术方案 §6.1 约定一致。
- * <p>
- * 响应格式：{@code {"code": 200, "msg": "success", "data": { ... }}}
- * </p>
- * <ul>
- *   <li>{@code code=200} — 成功</li>
- *   <li>{@code code≠200} — 失败，msg 为错误提示</li>
- * </ul>
- *
- * @param <T> data 字段的类型
  */
+@Schema(description = "统一响应体")
 public class R<T> implements Serializable {
 
     private static final long serialVersionUID = 1L;
 
-    /** 业务状态码，200 表示成功 */
+    @Schema(description = "业务状态码，200 表示成功", example = "200")
     private int code;
 
-    /** 提示信息，成功时为 "success"，失败时为具体错误描述 */
+    @Schema(description = "提示信息", example = "success")
     private String msg;
 
-    /** 业务数据载荷，失败时通常为 null */
+    @Schema(description = "业务数据")
     private T data;
 
     public R() {

huimv-employment/fe-service/pom.xml

@@ -48,5 +48,9 @@
             <groupId>com.github.binarywang</groupId>
             <artifactId>weixin-java-miniapp</artifactId>
         </dependency>
+        <dependency>
+            <groupId>io.swagger.core.v3</groupId>
+            <artifactId>swagger-annotations</artifactId>
+        </dependency>
     </dependencies>
 </project>

huimv-employment/fe-service/src/main/java/com/huimv/employment/service/agent/dto/AgentMessageRequest.java

@@ -1,18 +1,19 @@
 package com.huimv.employment.service.agent.dto;
 
+import io.swagger.v3.oas.annotations.media.Schema;
+
 import javax.validation.constraints.NotBlank;
 
-/**
- * 小程序智能体对话请求。
- */
+@Schema(description = "智能体对话请求")
 public class AgentMessageRequest {
 
-    /** 企业 ID（可选，预留多企业场景） */
+    @Schema(description = "企业 ID（可选，预留多企业场景）", example = "1")
     private Long enterpriseId;
 
-    /** 会话 ID，不传则自动生成 */
+    @Schema(description = "会话 ID，不传则自动生成", example = "conv-abc123")
     private String conversationId;
 
+    @Schema(description = "用户消息内容", example = "帮我起草一份临时工用工协议", requiredMode = Schema.RequiredMode.REQUIRED)
     @NotBlank(message = "消息内容不能为空")
     private String message;
 

huimv-employment/fe-service/src/main/java/com/huimv/employment/service/agent/dto/AgentMessageResponse.java

@@ -1,20 +1,20 @@
 package com.huimv.employment.service.agent.dto;
 
-/**
- * 小程序智能体对话响应。
- */
+import io.swagger.v3.oas.annotations.media.Schema;
+
+@Schema(description = "智能体对话响应")
 public class AgentMessageResponse {
 
-    /** AI 回复文本 */
+    @Schema(description = "AI 回复文本", example = "好的，请提供用工岗位、工时和薪资等信息。")
     private String reply;
 
-    /** 会话 ID */
+    @Schema(description = "会话 ID", example = "conv-abc123")
     private String conversationId;
 
-    /** 下一步动作（如 show_employment_draft），一期可为空 */
+    @Schema(description = "下一步动作（如 show_employment_draft），一期可为空")
     private String nextAction;
 
-    /** 关联草稿 ID，一期可为空 */
+    @Schema(description = "关联草稿 ID，一期可为空")
     private String draftId;
 
     public String getReply() {

huimv-employment/fe-service/src/main/java/com/huimv/employment/service/auth/PasswordAuthService.java

@@ -3,20 +3,10 @@ package com.huimv.employment.service.auth;
 import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
 import com.huimv.employment.common.exception.BizException;
 import com.huimv.employment.common.exception.ErrorCode;
-import com.huimv.employment.common.util.AesUtils;
-import com.huimv.employment.common.util.MobileUtils;
-import com.huimv.employment.common.util.PasswordPolicyUtils;
-import com.huimv.employment.common.util.PasswordUtils;
-import com.huimv.employment.common.util.RsaUtils;
-import com.huimv.employment.common.util.UsernameUtils;
+import com.huimv.employment.common.util.*;
 import com.huimv.employment.dao.entity.FeUser;
 import com.huimv.employment.dao.mapper.FeUserMapper;
-import com.huimv.employment.service.auth.dto.LoginResponse;
-import com.huimv.employment.service.auth.dto.PasswordLoginRequest;
-import com.huimv.employment.service.auth.dto.PasswordPublicKeyResponse;
-import com.huimv.employment.service.auth.dto.PasswordResetRequest;
-import com.huimv.employment.service.auth.dto.PasswordSetRequest;
-import com.huimv.employment.service.auth.dto.PasswordStatusResponse;
+import com.huimv.employment.service.auth.dto.*;
 import com.huimv.employment.service.config.SecurityProperties;
 import com.huimv.employment.service.sms.SmsCodeService;
 import org.springframework.stereotype.Service;

huimv-employment/fe-service/src/main/java/com/huimv/employment/service/auth/dto/LoginResponse.java

@@ -1,33 +1,32 @@
 package com.huimv.employment.service.auth.dto;
 
+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
  * 登录成功响应体。
- * <p>
- * 客户端拿到 {@link #token} 后，后续请求在 Header 携带：
- * {@code Authorization: Bearer <token>}
- * </p>
  */
+@Schema(description = "登录成功响应")
 public class LoginResponse {
 
-    /** JWT 访问令牌 */
+    @Schema(description = "JWT 访问令牌，后续请求 Header 携带 Authorization: Bearer <token>", example = "eyJhbGciOiJIUzI1NiIs...")
     private String token;
 
-    /** Token 有效时长（秒），默认 7200（2 小时） */
+    @Schema(description = "Token 有效时长（秒）", example = "7200")
     private long expiresIn;
 
-    /** 用户 ID，对应 fe_user.id */
+    @Schema(description = "用户 ID", example = "1001")
     private Long userId;
 
-    /** 用户类型：enterprise / worker */
+    @Schema(description = "用户类型：enterprise / worker", example = "enterprise")
     private String userType;
 
-    /** 脱敏手机号，如 138****8000 */
+    @Schema(description = "脱敏手机号", example = "138****8000")
     private String mobileMask;
 
-    /** 用户昵称，可空 */
+    @Schema(description = "用户昵称，可空", example = "张三")
     private String nickname;
 
-    /** 是否已设置登录密码 */
+    @Schema(description = "是否已设置登录密码", example = "false")
     private boolean passwordSet;
 
     public String getToken() {

huimv-employment/fe-service/src/main/java/com/huimv/employment/service/auth/dto/MpUserInfoResponse.java

@@ -1,21 +1,26 @@
 package com.huimv.employment.service.auth.dto;
 
+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
  * 小程序当前用户信息，含登记状态及企业/临时工详情。
  */
+@Schema(description = "小程序用户信息（含登记状态）")
 public class MpUserInfoResponse {
 
-    /** 用户类型：enterprise / worker */
+    @Schema(description = "用户类型：enterprise / worker", example = "enterprise")
     private String userType;
 
-    /** 是否已完成登记 */
+    @Schema(description = "是否已完成档案登记", example = "false")
     private boolean registered;
 
-    /** 登录账号手机号脱敏 */
+    @Schema(description = "登录账号手机号脱敏", example = "138****8000")
     private String mobileMask;
 
+    @Schema(description = "企业登记信息（userType=enterprise 且已登记时有值）")
     private EnterpriseInfo enterprise;
 
+    @Schema(description = "临时工登记信息（userType=worker 且已登记时有值）")
     private WorkerInfo worker;
 
     public String getUserType() {
@@ -59,24 +64,34 @@ public class MpUserInfoResponse {
     }
 
     /** 企业登记信息 */
+    @Schema(description = "企业登记详情")
     public static class EnterpriseInfo {
 
+        @Schema(description = "企业 ID", example = "1")
         private Long enterpriseId;
 
+        @Schema(description = "企业编号")
         private String enterpriseCode;
 
+        @Schema(description = "企业名称")
         private String name;
 
+        @Schema(description = "统一社会信用代码")
         private String creditCode;
 
+        @Schema(description = "法人姓名")
         private String legalPerson;
 
+        @Schema(description = "注册地址")
         private String registeredAddress;
 
+        @Schema(description = "联系人姓名")
         private String contactName;
 
+        @Schema(description = "联系人手机号脱敏")
         private String contactMobileMask;
 
+        @Schema(description = "认证状态")
         private String authStatus;
 
         public Long getEnterpriseId() {
@@ -153,24 +168,34 @@ public class MpUserInfoResponse {
     }
 
     /** 临时工登记信息 */
+    @Schema(description = "临时工登记详情")
     public static class WorkerInfo {
 
+        @Schema(description = "临时工 ID", example = "1")
         private Long workerId;
 
+        @Schema(description = "临时工编号")
         private String workerNo;
 
+        @Schema(description = "真实姓名")
         private String realName;
 
+        @Schema(description = "手机号脱敏")
         private String mobileMask;
 
+        @Schema(description = "身份证号脱敏")
         private String idCardNoMask;
 
+        @Schema(description = "银行卡号脱敏")
         private String bankAccountMask;
 
+        @Schema(description = "开户银行")
         private String bankName;
 
+        @Schema(description = "开户支行")
         private String bankBranch;
 
+        @Schema(description = "实名认证状态")
         private String verifyStatus;
 
         public Long getWorkerId() {

huimv-employment/fe-service/src/main/java/com/huimv/employment/service/auth/dto/PasswordLoginRequest.java

@@ -1,14 +1,17 @@
 package com.huimv.employment.service.auth.dto;
 
+import io.swagger.v3.oas.annotations.media.Schema;
+
 import javax.validation.constraints.NotBlank;
 
-/** {@code POST /api/v1/mp/auth/password/login} */
+@Schema(description = "账密登录请求")
 public class PasswordLoginRequest {
 
+    @Schema(description = "登录账号，支持用户名或手机号", example = "zhangsan", requiredMode = Schema.RequiredMode.REQUIRED)
     @NotBlank(message = "账号不能为空")
     private String account;
 
-    /** 前端 RSA 加密后的密码（Base64） */
+    @Schema(description = "RSA 公钥加密后的密码（Base64），须先调用 GET /auth/password/public-key 获取公钥", requiredMode = Schema.RequiredMode.REQUIRED)
     @NotBlank(message = "密码不能为空")
     private String encryptedPassword;
 

huimv-employment/fe-service/src/main/java/com/huimv/employment/service/auth/dto/PasswordPublicKeyResponse.java

@@ -1,8 +1,11 @@
 package com.huimv.employment.service.auth.dto;
 
-/** RSA 公钥响应 */
+import io.swagger.v3.oas.annotations.media.Schema;
+
+@Schema(description = "RSA 公钥响应")
 public class PasswordPublicKeyResponse {
 
+    @Schema(description = "PEM 格式 RSA 公钥，前端用于加密密码后再提交", example = "-----BEGIN PUBLIC KEY-----\\nMIIBIjANBg...")
     private String publicKey;
 
     public PasswordPublicKeyResponse() {

huimv-employment/fe-service/src/main/java/com/huimv/employment/service/auth/dto/PasswordResetRequest.java

@@ -1,21 +1,27 @@
 package com.huimv.employment.service.auth.dto;
 
+import io.swagger.v3.oas.annotations.media.Schema;
+
 import javax.validation.constraints.NotBlank;
 import javax.validation.constraints.Pattern;
 
-/** {@code POST /api/v1/mp/auth/password/reset} */
+@Schema(description = "短信验证码重置密码请求")
 public class PasswordResetRequest {
 
+    @Schema(description = "已注册手机号", example = "13800138000", requiredMode = Schema.RequiredMode.REQUIRED)
     @NotBlank(message = "手机号不能为空")
     @Pattern(regexp = "^1[3-9]\\d{9}$", message = "手机号格式不正确")
     private String mobile;
 
+    @Schema(description = "短信验证码", example = "123456", requiredMode = Schema.RequiredMode.REQUIRED)
     @NotBlank(message = "验证码不能为空")
     private String code;
 
+    @Schema(description = "新密码（RSA 加密 Base64）", requiredMode = Schema.RequiredMode.REQUIRED)
     @NotBlank(message = "密码不能为空")
     private String encryptedPassword;
 
+    @Schema(description = "确认新密码（RSA 加密 Base64）", requiredMode = Schema.RequiredMode.REQUIRED)
     @NotBlank(message = "确认密码不能为空")
     private String encryptedConfirmPassword;
 

huimv-employment/fe-service/src/main/java/com/huimv/employment/service/auth/dto/PasswordSetRequest.java

@@ -1,20 +1,24 @@
 package com.huimv.employment.service.auth.dto;
 
+import io.swagger.v3.oas.annotations.media.Schema;
+
 import javax.validation.constraints.NotBlank;
 
-/** {@code POST /api/v1/mp/auth/password/set} */
+@Schema(description = "设置或修改登录密码请求（需 JWT）")
 public class PasswordSetRequest {
 
-    /** 首次设密必填；改密时可不传 */
+    @Schema(description = "登录用户名，首次设密必填；改密时可不传", example = "zhangsan")
     private String username;
 
+    @Schema(description = "新密码（RSA 加密 Base64）", requiredMode = Schema.RequiredMode.REQUIRED)
     @NotBlank(message = "密码不能为空")
     private String encryptedPassword;
 
+    @Schema(description = "确认新密码（RSA 加密 Base64），须与新密码明文一致", requiredMode = Schema.RequiredMode.REQUIRED)
     @NotBlank(message = "确认密码不能为空")
     private String encryptedConfirmPassword;
 
-    /** 改密时必填（RSA 加密） */
+    @Schema(description = "旧密码（RSA 加密 Base64），已设密用户改密时必填")
     private String encryptedOldPassword;
 
     public String getUsername() {

huimv-employment/fe-service/src/main/java/com/huimv/employment/service/auth/dto/PasswordStatusResponse.java

@@ -1,10 +1,14 @@
 package com.huimv.employment.service.auth.dto;
 
-/** 账密设置状态 */
+import io.swagger.v3.oas.annotations.media.Schema;
+
+@Schema(description = "账密设置状态")
 public class PasswordStatusResponse {
 
+    @Schema(description = "是否已设置登录密码", example = "true")
     private boolean passwordSet;
 
+    @Schema(description = "用户名脱敏，未设密时为 null", example = "zha***")
     private String usernameMask;
 
     public boolean isPasswordSet() {

huimv-employment/fe-service/src/main/java/com/huimv/employment/service/auth/dto/SmsLoginRequest.java

@@ -1,24 +1,26 @@
 package com.huimv.employment.service.auth.dto;
 
+import io.swagger.v3.oas.annotations.media.Schema;
+
 import javax.validation.constraints.NotBlank;
 import javax.validation.constraints.Pattern;
 
 /**
  * 短信验证码登录请求体。
- * <p>对应接口：{@code POST /api/v1/mp/auth/sms/login}</p>
  */
+@Schema(description = "短信验证码登录请求")
 public class SmsLoginRequest {
 
-    /** 手机号，须与发送验证码时一致 */
+    @Schema(description = "手机号，须与发送验证码时一致", example = "13800138000", requiredMode = Schema.RequiredMode.REQUIRED)
     @NotBlank(message = "手机号不能为空")
     @Pattern(regexp = "^1[3-9]\\d{9}$", message = "手机号格式不正确")
     private String mobile;
 
-    /** 短信验证码，Mock 模式下固定为 123456 */
+    @Schema(description = "短信验证码；Mock 模式下固定为 123456", example = "123456", requiredMode = Schema.RequiredMode.REQUIRED)
     @NotBlank(message = "验证码不能为空")
     private String code;
 
-    /** 用户类型：enterprise（企业主）或 worker（临时工） */
+    @Schema(description = "用户类型：enterprise 或 worker", example = "enterprise", requiredMode = Schema.RequiredMode.REQUIRED)
     @NotBlank(message = "用户类型不能为空")
     @Pattern(regexp = "^(enterprise|worker)$", message = "用户类型只能是 enterprise 或 worker")
     private String userType;

huimv-employment/fe-service/src/main/java/com/huimv/employment/service/auth/dto/SmsSendRequest.java

@@ -1,23 +1,22 @@
 package com.huimv.employment.service.auth.dto;
 
+import io.swagger.v3.oas.annotations.media.Schema;
+
 import javax.validation.constraints.NotBlank;
 import javax.validation.constraints.Pattern;
 
 /**
  * 发送登录验证码请求体。
- * <p>对应接口：{@code POST /api/v1/mp/auth/sms/send}</p>
  */
+@Schema(description = "发送登录验证码请求")
 public class SmsSendRequest {
 
-    /** 手机号，11 位中国大陆号码 */
+    @Schema(description = "手机号，11 位中国大陆号码", example = "13800138000", requiredMode = Schema.RequiredMode.REQUIRED)
     @NotBlank(message = "手机号不能为空")
     @Pattern(regexp = "^1[3-9]\\d{9}$", message = "手机号格式不正确")
     private String mobile;
 
-    /**
-     * 用户类型，决定登录后的小程序端身份与菜单权限。
-     * enterprise=企业主；worker=临时工。
-     */
+    @Schema(description = "用户类型：enterprise=企业主，worker=临时工", example = "enterprise", requiredMode = Schema.RequiredMode.REQUIRED)
     @NotBlank(message = "用户类型不能为空")
     @Pattern(regexp = "^(enterprise|worker)$", message = "用户类型只能是 enterprise 或 worker")
     private String userType;

huimv-employment/fe-service/src/main/java/com/huimv/employment/service/auth/dto/SmsSendResponse.java

@@ -1,18 +1,17 @@
 package com.huimv.employment.service.auth.dto;
 
+import io.swagger.v3.oas.annotations.media.Schema;
+
 /**
  * 发送验证码成功响应体。
- * <p>告知前端当前是否 Mock 模式及验证码有效期，便于 UI 展示相应提示。</p>
  */
+@Schema(description = "发送验证码响应")
 public class SmsSendResponse {
 
-    /**
-     * 是否 Mock 模式。
-     * true 时前端可提示「测试环境，验证码为 123456」。
-     */
+    @Schema(description = "是否 Mock 模式；true 时前端可提示「测试环境，验证码为 123456」", example = "true")
     private boolean mockEnabled;
 
-    /** 验证码有效时长（秒），默认 300 */
+    @Schema(description = "验证码有效时长（秒）", example = "300")
     private int expireSeconds;
 
     public SmsSendResponse() {

huimv-employment/fe-service/src/main/java/com/huimv/employment/service/auth/dto/WechatLoginRequest.java

@@ -1,14 +1,18 @@
 package com.huimv.employment.service.auth.dto;
 
+import io.swagger.v3.oas.annotations.media.Schema;
+
 import javax.validation.constraints.NotBlank;
 import javax.validation.constraints.Pattern;
 
-/** {@code POST /api/v1/mp/auth/wechat/login} */
+@Schema(description = "微信小程序登录请求")
 public class WechatLoginRequest {
 
+    @Schema(description = "wx.login 返回的临时 code", example = "081abcXYZ", requiredMode = Schema.RequiredMode.REQUIRED)
     @NotBlank(message = "微信 code 不能为空")
     private String code;
 
+    @Schema(description = "用户类型：enterprise 或 worker", example = "worker", requiredMode = Schema.RequiredMode.REQUIRED)
     @NotBlank(message = "用户类型不能为空")
     @Pattern(regexp = "^(enterprise|worker)$", message = "用户类型只能是 enterprise 或 worker")
     private String userType;

huimv-employment/pom.xml

@@ -38,6 +38,7 @@
         <redisson.version>3.23.5</redisson.version>
         <wxjava.version>4.6.0</wxjava.version>
         <aliyun-dysmsapi.version>4.1.1</aliyun-dysmsapi.version>
+        <swagger-annotations.version>2.2.22</swagger-annotations.version>
     </properties>
 
     <dependencyManagement>
@@ -107,6 +108,11 @@
                 <artifactId>dysmsapi20170525</artifactId>
                 <version>${aliyun-dysmsapi.version}</version>
             </dependency>
+            <dependency>
+                <groupId>io.swagger.core.v3</groupId>
+                <artifactId>swagger-annotations</artifactId>
+                <version>${swagger-annotations.version}</version>
+            </dependency>
         </dependencies>
     </dependencyManagement>
 </project>