新增接口

步骤与落位

步骤	位置
Controller 方法	对应业务模块的 `controller/`
入参 / 出参	`model/request`、`model/response`
业务逻辑	`service/`（事务边界在这里，不在 Controller）
数据访问	`mapper/`，复杂 SQL 的 XML 放 `src/main/resources/mapper/`
权限点	方法上 `@PreAuthorize("hasAuthority('xxx:read')")`，同步到前端 `src/constants/permissions.ts`
操作日志	写操作加 `@OperationLog`
接口文档	`@Tag`、`@Operation`、`@ApiResponse`
国际化文案	模块 `i18n/messages-xxx*.properties`
前端调用	`src/services/asone-server/<域>/<controller>.ts` 新增导出函数

Controller 模板

@Tag(name = "渠道日报表", description = "渠道日报表查询接口")
@Validated
@RestController
@AllArgsConstructor
@RequestMapping("/api/channel-daily-report")
public class ChannelDailyReportController {

    private final ChannelDailyReportService channelDailyReportService;

    @GetMapping("/page")
    @PreAuthorize("hasAuthority('channelReport:read')")
    @Operation(summary = "分页查询渠道日报表")
    public IPage<ChannelDailyReportResponse> page(@Valid ChannelDailyReportPageRequest request) {
        return channelDailyReportService.page(request);
    }

    @PostMapping("/sync")
    @PreAuthorize("hasAuthority('channelReport:manage') and @authenticationType.isSession(authentication)")
    @OperationLog(summaryTemplate = "同步渠道日报表：#{#request.channelCode}")
    @Operation(summary = "触发渠道日报表同步")
    public SyncResult sync(@Valid @RequestBody ChannelDailyReportSyncRequest request) {
        return channelDailyReportService.sync(request);
    }
}

约定要点：

图 1 · 接口方法的三层声明

路径统一 /api 前缀，与前端代理和 OpenResty 转发规则一致。
注入用构造器注入（@AllArgsConstructor 或 @RequiredArgsConstructor + private final），不在字段上打 @Autowired。
读接口用 xxx:read；写接口用 xxx:manage 并叠加 @authenticationType.isSession(authentication)，把写操作限制在真人会话；需要被 API Key 调用的接口额外加 @ApiKeyAllowed。
参数校验用 jakarta.validation（@Valid、@Min 等），消息 key 走 i18n，形如 {validation.sys.id_min}。
出参两种写法都能工作：直接返回业务对象由 GlobalResponseBodyAdvice 自动包成 { success, code, message, data }，显式返回 Result.success(...) 会被原样透传；新接口优先返回业务对象。/v3/api-docs、/swagger-ui、/actuator、SSE、StreamingResponseBody 一律透传不包装。
业务失败抛 BizException，错误码在 ResponseCodeEnum；不要自己 try/catch 拼错误响应，GlobalExceptionHandler 已按异常类型分派。
分页返回 IPage / Page，禁止手写 limit 拼 SQL。

免鉴权与限流

新增登录前可访问的接口（如公开回调、验证码），把路径加入 asone-server-system/src/main/resources/application-system.yml 的 security.permit-all-paths，不要靠注解绕过。
需要排除限流统计的路径，配置到 RateLimitProperties.excludePaths（拦截器在 WebMvcConfiguration 注册）。

验证

cd asone-server && mvn -q -DskipTests -pl asone-server-boot -am compile

# 启动后确认接口进入 OpenAPI
curl -sS http://localhost:8001/v3/api-docs/asone-server | grep -o '/api/channel-daily-report/page'

# 未带令牌应 401
curl -sS -o /dev/null -w "%{http_code}\n" http://localhost:8001/api/channel-daily-report/page

前端接口层可在后端起好后执行 pnpm openapi（读取 http://localhost:8001/v3/api-docs/asone-server）重新生成，再收敛类型。