提交与代码质量
提交前检查
| 范围 | 命令 |
|---|---|
| 后端 | cd asone-server && mvn -q -DskipTests clean compile |
| 后端废弃 API 告警 | cd asone-server && mvn -q -DskipTests -Dmaven.compiler.showDeprecation=true compile |
后端 record 自查 | grep -rnE '(^|\s)record\s+[A-Za-z_]' --include='*.java' asone-server/*/src |
| 前端 | cd asone-front && pnpm lint |
| 前端依赖过期 | cd asone-front && pnpm outdated |
Husky + lint-staged 在提交时自动执行 Biome，commitlint 校验提交信息格式；钩子失败要修根因，不跳过钩子（不用 --no-verify）。
提交信息格式
遵循 Conventional Commits，subject 使用中文：
<type>(<scope>): <subject>
<body>
- header 不超过 72 字符，结尾不加句号；header 与 body 之间空一行，body 每行不超过 100 字符。
- 生成前先
git log --oneline -20与git diff --staged，按实际改动写，不臆造。
type
| type | 用途 |
|---|---|
feat | 新增功能、新增能力 |
fix | 修复缺陷、修正错误行为 |
refactor | 重构，不改变外部行为 |
docs | 文档、注释、DDL 说明、API 文档 |
style | 样式与格式调整，不影响逻辑 |
build | 依赖版本、pom / package.json、构建配置 |
ci | 流水线、部署脚本、flow.yaml |
chore | 杂项，如 husky、工程初始化 |
perf | 性能优化 |
config | 运行参数调整，如超时时间、开关默认值 |
按改动意图选 type：新增渠道报表同步用 feat，修报表数据错误用 fix，只调结构用 refactor。
scope
小写 kebab-case，取模块或功能域，省略不影响理解时可省略。
- 后端按 Maven 模块：
channel-report、advertisement、iaa、system、server - 前端按功能域：
export、api-key、operation-log、rate-limit、locales、workbench - 其他：
docs、api、security、auth、frontend
禁止大驼峰（ChannelReport）、类名（ExportTaskController）或带空格的 scope（login page）。
subject
- 动词开头：新增 / 修复 / 优化 / 移除 / 重构 / 统一 / 调整 / 拆分 / 精简 / 升级 / 接入 / 配置 / 支持 / 实现 / 完成 / 引入 / 替换
- 说清做了什么、能定位到具体功能点，不写「修改代码」「更新文件」这类空话
- 多个动作用「并」连接，最多两项；同类并列对象用顿号
- 涉及具体标识符、配置项、字段名时保留原文；中英文之间不加空格
body
- 改配置值、升依赖、删文件这类简单改动可以不写
- 涉及行为变更、性能影响、根因排查、新增配置项时必须写
- 写「为什么改」和「影响范围」，不复述逐行 diff；推荐结构：现状 / 问题 → 做法 → 影响或注意事项
- 用连贯段落，不用 emoji，不堆砌文件清单
示例
fix(channel-report): 渠道接口出站按主机限频，避免触发调用频繁报错
渠道侧普遍有调用频率限制，而前端日报、国家、单元、明细四个维度是独立按钮，
各自通过 CompletableFuture.runAsync 提交到线程池并发调用同一渠道主机；分页
while 循环与逐日循环内部也无任何间隔，导致渠道返回调用频繁错误。
将限频下沉到所有渠道共用的 RestClient 拦截器，按 host 维度保证相邻两次请求
开始时间至少间隔 channel-api.request-interval-millis，一处生效覆盖全部渠道、
分页循环、逐日循环与重试，不同渠道主机之间互不阻塞。
build: 将公共依赖统一提升至父pom的dependencyManagement
反例：
update code # 无信息量
feat(ChannelReport): Add throttle. # scope 大驼峰、英文、带句号
fix: 修复问题 # 没说清修的是什么
其他约束
- 禁止任何 AI 署名、
Co-authored-by、Generated with等 trailer。 - 禁止在提交信息中出现密钥、token、私钥等敏感信息。
- 一次提交只做一类事：格式化、重命名与功能修改不混在同一次提交；无关改动拆分。
- 优先创建新提交，不用
--amend改已存在的提交。 - 只提交与当前任务相关的文件，不使用
git add -A把.env、凭据类文件带进去。
范围边界
xxl-job/xxl-job/ 是 git submodule 引入的上游官方源码，一律不修改、不纳入检索与审查范围。仍在范围内的是：xxl-job/deploy/（我们的 Dockerfile 与 application.properties）、flow.yaml 中构建部署调度中心的环节、asone-server/**/task/*.java 执行器侧代码，以及父 POM 对 xxl-job-core 的依赖版本。
上游或调度中心有缺陷时，只输出结论与建议（现象、定位为第三方问题、在我们 task 代码或调度中心配置侧的规避方式、或建议升级 xxl-job.version / 向上游提 issue），不自行改 vendored 源码。