其他常见改动

新增定时任务

  1. 在业务模块的 task/ 包写 handler，方法上加 @XxlJob("xxxSyncTask")，参数通过 XxlJobHelper.getJobParam() 读取，复杂参数用 dto 里的任务参数载体承载（如渠道报表的 ChannelReportJobParam）。
  2. 任务内部自己做幂等与断点，调度中心重试会产生重复触发；耗时任务把执行结果与关键指标写进 XxlJobHelper.log / 同步日志表，便于排查。
  3. 执行器由 asone-server-system/.../configuration/XxlJobExecutorConfiguration.java 按 xxl.job.executor.enabled 条件装配，本地 application-local.yml 关闭注册，线上地址在 application.yml 的 xxl.job.admin.addresses（走 asone-net 容器名直连）。
  4. 到 XXL-JOB 调度中心（https://xxl-job-admin.asone.club/）在 asone-server 执行器分组下新建任务，指定 JobHandler、CRON 与参数；执行器 access-token 必须与调度中心分组注册 Token 完全一致，3.x 起为空会注册失败。
  5. 调度中心本身的行为问题只输出结论与规避方式，不改 xxl-job/xxl-job/ 上游源码。

新增数据导出

图 1 · 导出任务状态流转（system_export_task.status）
  1. 在业务模块 export/ 实现 com.qianxunclub.asone.export.ExportTaskHandler<P>，exportType() 返回全局唯一的导出类型编码。
  2. 由 asone-server-system/.../task/ExportTaskScheduler 统一调度，任务记录落 system_export_task，不要在页面里做同步大文件导出。
  3. 前端提交导出任务后通过全局 Model src/models/exportTask 轮询进度并下载，文案补 src/locales/{zh-CN,en-US}。
  4. Excel 处理统一用已有的 Fesod Sheet，不另引 POI 封装库。

接入新渠道

图 2 · 渠道出站调用的限频位置
  1. 在 asone-module-channel-report/config 新增渠道配置类（@ConfigurationProperties，如 IdgShReportProperties），配置项写入模块 application-channel-report.yml 的 *-report.*。
  2. 出站调用走渠道共用的 RestClient，出站限频在其拦截器里按 host 保证相邻两次请求间隔不少于 channel-api.request-interval-millis（默认 3000ms，application-channel-report.yml 现配 2000ms，0 表示关闭）；新增渠道自动继承，不要在业务代码里另加 sleep。
  3. 同步逻辑放 service/，handler 放 task/，报表实体继承模块内既有基类，Mapper 复用泛型基接口（ChannelReportSummaryMapper<T> / ChannelReportBatchMapper<T>）。
  4. 渠道接口说明文档放 asone-server/asone-module-channel-report/docs/<渠道>渠道API接口文档.md，与代码同批提交。
  5. 表结构变化写入全量 DDL，见数据库。

新增权限点与菜单

项位置
后端权限字符串接口方法 @PreAuthorize("hasAuthority('xxx:read' / 'xxx:manage')")
前端权限常量asone-front/src/constants/permissions.ts
菜单资源后台「系统管理 → 菜单管理」新增 system_resource，path 与前端路由完全一致
授权域system_resource.role_scope：BUSINESS 可分配普通角色，SYSTEM 仅系统 / 超级管理员；只在顶级菜单设置，子级继承
会话限制写接口叠加 @authenticationType.isSession(authentication)，API Key 场景例外

菜单与授权域是数据驱动，改动只影响库表，但新增顶级菜单或调整 role_scope 语义属于结构性变更，需要同时更新架构与新增业务域页面。

新增国际化文案

  • 后端：写入所在模块 src/main/resources/i18n/messages-xxx*.properties（默认中文、_en_US 英文），新 bundle 需追加到 application.yml 的 spring.messages.basename；语言由请求头 X-Locale 决定。
  • 前端：src/locales/zh-CN 与 src/locales/en-US 同步补齐，pnpm i18n-check 校验缺失项。

新增业务错误码

在 asone-server-system/.../constants/ResponseCodeEnum 增加枚举项（配 ResponseHandler），业务侧抛 configuration/BizException；不要在 Controller 里自定义返回结构，统一响应体由 GlobalResponseBodyAdvice 产出。

新增配置项

  • 模块级配置放该模块的 application-<模块后缀>.yml + 对应 *Properties 类，配置类走 spring-boot-configuration-processor 生成元数据。
  • 全局运行参数放 asone-server-boot/src/main/resources/application.yml。
  • 密钥、连接串等环境相关值一律通过环境变量或部署平台外部配置注入，不进仓库。
  • 新增配置项属于开发者文档同步范围，见文档同步规则。