docs: 补充 Controller 职责与参数校验规范\n\n- 在开发规范中新增 8.4 Controller 与请求参数校验规范\n- 明确 Controller 只负责数据接收/校验、调用业务Service和封装返回结果\n- 建议使用 @Valid/@Validated + @NotBlank/@NotNull 等注解做必填校验\n- 提供登录接口参数校验示例和全局异常处理示例

doc/资金服务平台 FundPlatform 架构设计文档.md

@@ -3419,6 +3419,70 @@ fund-sys/
    - 业务服务层使用 `com.fundplatform.sys.service` / `com.fundplatform.sys.domain` 等包名，与数据访问层在物理结构上清晰分离；
    - Controller 只依赖业务服务层，不直接依赖 `ServiceImpl` 或 Mapper。
 
+### 8.4 Controller 与请求参数校验规范
+
+1. **Controller 职责**
+   - 仅负责：
+     - 接收请求数据（包含 Header、Path、Query、Body）；
+     - 调用**业务服务层**（`XxxService` / `XxxDomainService`）；
+     - 对业务层返回结果进行封装和格式转换（如封装为统一 `Result<T>`）；
+   - 明确禁止在 Controller 中编写业务规则、事务控制、跨聚合业务编排等复杂逻辑；
+   - Controller 不直接依赖 MyBatis 的 `ServiceImpl` / Mapper，只依赖业务服务接口。
+
+2. **请求参数校验（Bean Validation）**
+   - 强制启用 Spring Validation，对外暴露的接口必须进行参数校验：
+     - 使用 `@Valid` 或 `@Validated` 标注方法参数或类；
+     - 对必填字段使用 `@NotBlank`（字符串）、`@NotNull`（对象）、`@NotEmpty`（集合/数组）等注解；
+     - 对数值范围使用 `@Min`、`@Max`、`@Positive`、`@PositiveOrZero` 等注解；
+     - 对字符串长度使用 `@Size`；
+   - 推荐在 DTO 层（如 `LoginRequestDTO`、`CustomerCreateDTO`）上声明校验规则，而不是在 Entity 上；
+   - 统一使用全局异常处理（如 `@RestControllerAdvice`）拦截 `MethodArgumentNotValidException` / `ConstraintViolationException`，返回统一错误结构。
+
+3. **示例：登录接口参数校验**
+
+```java
+@Data
+public class LoginRequestDTO {
+
+    @NotBlank(message = "用户名不能为空")
+    private String username;
+
+    @NotBlank(message = "密码不能为空")
+    private String password;
+}
+
+@RestController
+@RequestMapping("/api/v1/auth")
+@RequiredArgsConstructor
+public class AuthController {
+
+    private final AuthService authService;
+
+    @PostMapping("/login")
+    public Result<LoginVO> login(@Valid @RequestBody LoginRequestDTO request) {
+        LoginVO vo = authService.login(request);
+        return Result.success(vo);
+    }
+}
+```
+
+4. **示例：全局参数校验异常处理**
+
+```java
+@RestControllerAdvice
+public class GlobalExceptionHandler {
+
+    @ExceptionHandler(MethodArgumentNotValidException.class)
+    public Result<Void> handleValidationException(MethodArgumentNotValidException ex) {
+        String message = ex.getBindingResult().getFieldErrors().stream()
+                .findFirst()
+                .map(FieldError::getDefaultMessage)
+                .orElse("请求参数不合法");
+        return Result.error(400, message);
+    }
+}
+```
+
 ---
 
 ## 九、附录