diff --git a/.agents/notes/implemented/architecture/2026-11-19-http-boundary-dtos.md b/.agents/notes/implemented/architecture/2026-11-19-http-boundary-dtos.md new file mode 100644 index 0000000..e057ff2 --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-11-19-http-boundary-dtos.md @@ -0,0 +1,49 @@ +# Agent Note: HTTP 边界不再返回实体,入参改用请求 DTO + +Status: implemented + +## Problem + +接口层的类型直接复用了持久化实体与 `Map`,导致三件事同时发生: + +- **实体即契约**:`CommonResult` 这类返回把库表形状暴露成 API。实体加一个字段就等于改接口, + 而 `createdBy` / `lastModifiedBy` / `deviceInfo` / `deleted` 这些列本来就不该出现在响应里。 +- **`Map` 当请求体**:10 个端点用 `@RequestBody Map`,字段名只在 `body.get("xxx")` 里出现, + 拼错 key 不报错、无法被 Bean Validation 校验、OpenAPI 文档里是空对象。 +- **实体当请求体**:`savePriorityWeights(@RequestBody UserPriorityWeightsEntity)` 让调用方能顺手改 `id`、`createdBy`。 + +## Decision + +在 controller 边界做转换,service 层签名不动: + +- 出参:`dto/response/<东西>Response`,字段与实体同名(类型不变),另带 `createdTime` / `lastModifiedTime`; + 不含 `createdBy` / `lastModifiedBy` / `deviceInfo` / `deleted`。每个类提供 `static of(Entity)` 工厂,实体为 null 时返回 null。 +- `Page` 返回:`new Page<>(current, size, total)` + `setRecords(records.stream().map(X::of).toList())`。 +- 入参:`dto/request/<动作>Request`,字段名与原先 `body.get("key")` 的 key 完全一致;必要字段加 `@NotBlank` 并在 controller 上 `@Valid`。 +- 局部更新改用 `update(new Entity(), lambdaUpdate().set(...))`,显式写「改哪几列」,不再依赖 MyBatis-Plus 的全局 null 策略; + 传入空实体是为了让 `MetaObjectHandler` 继续填 `lastModifiedBy` / `lastModifiedTime` / `deviceInfo`。 + +## Alternatives considered + +**① 直接在 service 层返回 DTO,controller 只透传。** +最强理由:转换点更靠里,controller 变薄,未来换实现(比如加缓存层)时不用再改 controller。 +否掉的原因:service 接口与实现遍布 40 多个类,签名一改要跟着改 600 多个测试与所有调用方; +而「实体不出 controller」这条约束只需要在边界做一次转换就成立。等真有了第二个入口(gRPC、MQ handler)再下沉不迟。 + +**② 让实体自己 `@JsonIgnore` 掉审计列,不建 DTO。** +最强理由:改动最小,一个注解解决泄漏,响应体里也不会再有 `createdBy`。 +否掉的原因:注解只解决序列化,解决不了「实体能当请求体」和「库表形状即契约」;而且把 API 决策藏在实体里, +以后 lpt-ai 或内部服务需要这些列时会互相拉扯。 + +**③ 保留 `Map` 请求体,只加 `@Valid` 常量约束。** +最强理由:不动前端契约,也没有 10 个新类。 +否掉的原因:`Map` 拿不到字段级校验与文档,`body.get("markerName")` 拼错永远是 null; +本轮恰好要为 18 个出参加 DTO,入参顺手一起做,边际成本远低于再开一轮。 + +## Consequences + +- 响应体少了 4 个字段(`createdBy` / `lastModifiedBy` / `deviceInfo` / `deleted`)。已核对 `lpt-fe`: + 这 4 个字段零使用,`createdTime`(16 处)与 `lastModifiedTime`(2 处)保留,前端无需改动。 +- service 仍返回实体,controller 里多了一次映射调用;`Page` 需要手工重建(MyBatis-Plus 的 `convert` 返回 `IPage`,类型对不上)。 +- 请求 DTO 里加了 `@NotBlank`,校验失败的文案由 DTO 决定;原本由 service 抛 `ErrorParameterException` 的路径仍在(DTO 未覆盖的语义校验)。 +- 回归由 608 个测试守住;改动后 `./mvnw validate` 仍为 0 违规。 diff --git a/.agents/notes/implemented/process/2026-11-19-checkstyle-gate.md b/.agents/notes/implemented/process/2026-11-19-checkstyle-gate.md new file mode 100644 index 0000000..a9453a3 --- /dev/null +++ b/.agents/notes/implemented/process/2026-11-19-checkstyle-gate.md @@ -0,0 +1,117 @@ +# Agent Note: 用 Checkstyle 在 validate 阶段阻断代码坏味道 + +Status: implemented + +## Problem + +格式、命名、复杂度、事务回滚这些坏味道,之前只存在于文档与评审习惯里,没有任何机械检查。结果是**写了没人查**: +全仓存量 692 处违规,横跨 149 个「文件 × 规则」组合,其中 215 处超 120 列、181 处单行语句不带花括号、 +154 处一行写多条语句、42 处 `@Transactional` 缺 `rollbackFor`(受检异常抛出去时事务照样提交)。 + +人工评审兜不住,原因不在态度: + +- 一个 PR 的注意力预算有限,几十行格式差异会把真正的行为变更埋掉; +- 同一条规则要在每次评审里重复提,提的人会累,被提的人会当噪音; +- 有些违规(缺 `rollbackFor`、`System.out`、空 catch)在 diff 里根本不显眼,看见了也容易划过去。 + +## Decision + +把能机械判定的纪律交给构建,绑在 `validate` 阶段阻断,而不是写成文档等自觉。 + +- **工具**:`maven-checkstyle-plugin:3.3.1` + `checkstyle:10.12.4`,`goal` 为 `check`,绑 `validate`, + `failOnViolation=true`。违规即构建失败,不是警告。 +- **范围**:只查 `src/main/java`(`includeTestSourceDirectory=false`)。测试里的长断言行、lambda 内联会制造大量假违规, + 而假违规会把人训练成习惯性跳过检查。 +- **存量**:先用 `suppressions.xml` 做 **文件 × 规则** 基线落地(149 条豁免覆盖 692 处),随后在同一天把 692 处全部改完, + 基线缩到 2 条框架约束(见「豁免的现状」)。 +- **基线加载**:pom 的 `` + 配置里的 `${checkstyle.suppressions.file}`。不用 `config_loc=...` + 这种更常见的写法:`maven-checkstyle-plugin:3.3.1` 把 `propertyExpansion` 当 properties 文本走 `Properties.load(InputStream)` + (ISO-8859-1),路径里含中文就变乱码(本仓路径含「系统」,实测报 `Unable to find: /run/media/cat/系统/...`)。 + `suppressionsLocation` 走 plexus `ResourceManager` 按 basedir 解析,不经那段,含中文路径与任意 CWD 都成立。 +- **阈值**:行 120、方法 80 行、文件 400 行、参数 7、圈复杂度 15、嵌套 if/for/try 各 3。 +- **跳闸口**:`-Dcheckstyle.skip=true`,只用于本地应急(`failOnViolation` 写死在 pom,user property 覆盖不了它的语义)。 +- **文档分工**:规则取值与出处进 `.agents/roles/code-standards.md`;工具查不了但必须人看的项进 + `.agents/roles/code-review-checklist.md`。`config/checkstyle/checkstyle.xml` 是唯一事实来源,文档只解释「为什么」。 + +### 为什么基线粒度是「文件 × 规则」 + +- **整文件豁免**(`` 不带 `checks`)最省事,但它让那个文件**所有**规则一起失效: + 一个 800 行的老 controller 被整文件豁免后,新写的 `System.out` 与缺 `rollbackFor` 全放过,等于给最脏的文件开最大口子。 +- **行号豁免**(`beginLine` / `endLine`)精度最高,但行号随每次编辑漂移:上面插一行,豁免就落到别的语句上, + 或者干脆失效。维护基线的成本会超过改代码本身,而且漂移是静默的。 +- **文件 × 规则** 的精度刚好落在可用区间:豁免的是「这个文件在这条规则上的存量」,同一文件的其他规则照样生效; + 改到该文件时删掉这一行,就能立刻看到它在这条规则上的真实状态。棘轮规则(豁免只减不增)成立。 + +## 豁免的现状 + +`suppressions.xml` 只剩两条,都是「框架规定、改了就坏」,不是债务: + +| 豁免 | 为什么必须豁免 | +|---|---| +| `db/migration/**` 的 `TypeName` | Java 迁移类的类名由 Flyway 规定为 `V20261115_2__xxx`,改了就等于让 Flyway 认为已有迁移消失 | +| `LearningProgressTrackerApplication` 的 `HideUtilityClassConstructor` | 启动类只有 `main`;给它加私有构造后 Spring 测试上下文无法实例化,实测 164 个测试报 `No visible constructors` | + +692 处是怎么清零的(都是改代码,不是加豁免): + +| 规则 | 数量 | 做法 | +|---|---|---| +| `LineLength` / `OneStatementPerLine` / `MultipleVariableDeclarations` / 未用与重复 import | 388 | 全仓跑 palantir-java-format(4 空格 / 120 列),再人工收尾 1 处长行 | +| `NeedBraces` | 181 | 先按行处理单语句体(128 处),再用 Checkstyle 报告的行号精确包住多行体(52 处),剩 4 处手改 | +| `AvoidStarImport` | 51 | 脚本按「文件里用到的类名 ∩ 包内类名」展开成显式 import,共 27 个文件 | +| `transactionRollback` | 42 | 给 44 个 `@Transactional` 补 `rollbackFor = Exception.class`;正则加 `\b` 避免误伤 `@TransactionalEventListener` | +| `FileLength` | 5 | 拆出 `ReviewFeedService`、`ReviewStatsService`、`TagDictionaryService`、`StudySessionConvergenceService`、`StudyReportDraftService`、`RecallExpressionValidator`、`MindMapMatchTool` | +| `CyclomaticComplexity` | 6 | 主干只做分发,分支下沉为私有方法 | +| `ParameterNumber` | 1 | 9 参数方法收成 `SourceContext` record | +| 命名 / 构造器 / `System.out` | 15 | `reportFragmentsController`→`ReportFragmentsController`、`mapStruct`→`mapstruct`、3 个异常处理方法改名、3 个工具类补私有构造、启动打印改 `log.info` | + +验证方式:`./mvnw validate` 输出 `You have 0 Checkstyle violations`,`./mvnw test` 为 608 个测试全绿。 +过程中两次被测试挡住并纠正:「给启动类加私有构造」与「`@TransactionalEventListener` 被正则误伤」,都已回退/修正。 + +## Alternatives considered + +**① 先把 692 处存量改干净,再一次性开闸。** +最强理由:门禁就该一把落地,基线豁免本质是技术债登记册,「以后再改」在实践中等于永远不改;而且一次格式化能顺手把风格统一掉, +比留 149 条豁免干净得多。 +否掉的原因:692 处改动会和真正的功能改动混在同一批提交里,评审无法分辨哪些是行为变更。`LineLength` 与 `NeedBraces` +要求重排语句,重排中混进一个改了分支的差异几乎必然漏过,而格式改错只会由特定输入暴露,测试覆盖不到。 +先开闸再棘轮,评审看到的是「删掉一行豁免 + 改动这一处」,可分辨。 + +**② 引入 `p3c-pmd`(阿里 Java 规约的 PMD 实现)。** +最强理由:规则更贴中文团队习惯(异常命名、常量命名、事务回滚、枚举注释本就是我们引用的上游),规则集覆盖面比这份 Checkstyle 配置更广, +还能一次拿到 `CognitiveComplexity` 这类 Checkstyle 没有的检查。 +否掉的原因:`p3c-pmd` 的 PMD 版本锁在 6.15,而 `CognitiveComplexity` 需要 6.35+,两者在同一套 PMD 里只能择一; +且引入第二套工具链意味着两份配置、两套豁免、两倍检查时间,换来的增益与已选的 Checkstyle 模块高度重叠。 + +**③ 接 SonarQube。** +最强理由:规则最全(认知复杂度、重复字面量、异常被吞、覆盖率趋势),有界面能看历史与责任人,在多人的项目里权威性最高。 +否掉的原因:要维护一个实例(数据库、升级、token、webhook),对个人项目这份运维成本不成比例;而且它擅长的是事后看板, +不是 `mvn package` 时的阻断——要的是「提交前就红」,不是一个每周打开看一眼的面板。 + +**④ 只写规则文档,不加门禁。** +最强理由:成本最低,不改构建时间、不需要豁免、不引入工具链;而且文档能解释「为什么这样写」,工具只能报「哪里错了」。 +否掉的原因:这正是当前失效的原因——692 处存量违规就是「写了没人查」的直接证据。文档与工具是分工不是替代: +工具查能机械判定的,文档解释为什么,两者都要有。 + +## Consequences + +**代价:** + +- 豁免仍是「文件 × 规则」,将来若被迫新开豁免,被豁免的文件在那条规则上会裸奔;所以新增豁免必须写理由(现状是 0 条债务豁免)。 +- 跳过开关存在且好按。遇到「先发出去」的场合会被用,只能靠 PR 说明与 `./mvnw validate` 复跑约束。 +- 测试代码完全不查,测试里的长行、魔法数字、`System.out` 仍然是人的活。 +- 构建多了一步(秒级),第一次撞上 400 行 / 80 行阈值的类会被迫先拆或先加豁免,这个摩擦是真实的。 + +**收益:** + +- **新文件零豁免**:新建的类一违反就红,不需要任何人先记住规则。 +- `validate` 在 `package` 之前,`mvn -f`、CI 的 `docker build`(Dockerfile 里跑 `mvn package -DskipTests`)都拦得住。 +- 豁免清单本身就是可数的债务看板:149 条、692 处,改动前后能直接对比。 +- 规则取值有了唯一事实来源,文档不必复述模块说明;上游出处(Google Java Style、Spring、p3c、Sonar)写在 `code-standards.md` 里, + 下一次加规则有据可依。 + +## Verification + +- 构建配置:`pom.xml` 的 `maven-checkstyle-plugin` 执行段(`checkstyle-validate`)。 +- 规则与阈值:`config/checkstyle/checkstyle.xml`;基线:`config/checkstyle/suppressions.xml`。 +- 触发:`./mvnw validate`,失败时输出 `文件:行` 与规则名。 +- 文档:`.agents/roles/code-standards.md`、`.agents/roles/code-review-checklist.md`、`AGENTS.md` 的「启动命令」节。 diff --git a/.agents/roles/api-response.md b/.agents/roles/api-response.md index aef3c8e..b587181 100644 --- a/.agents/roles/api-response.md +++ b/.agents/roles/api-response.md @@ -11,6 +11,17 @@ - 参数校验失败:`MethodArgumentNotValidException`,code=400。 - 用户可见错误文案必须口语化、可理解,避免“无法生成”“不存在”等技术化表述;技术细节写入日志。例如无学习报告时应提示“这个任务还没开始学习哦,学习后产生学习报告后再来吧”,而不是“没有学习报告,无法生成思维导图”。 +## 出参和入参的边界 + +- **实体不出 controller**:`CommonResult`、`CommonResult>` 都不行,出参一律是 `dto/` 下的类。 + 实体带租户与审计列,库表形状一改就直接击穿 API 契约,前端还得跟着改。 +- **请求体用 DTO,不用 `Map`**:`Map` 丢类型、丢校验、丢字段名,只能在 service 里 `get("xxx")` 拼字符串; + 每个端点一个 request DTO + `@Valid`。 +- **`CommonResult` 不写裸类型**:一律 `CommonResult`,哪怕是错误分支也给出 `data` 的类型;裸类型在生成文档与前端类型推导上都退化成 `any`。 + 存量:`GlobalExceptionHandler` 的 7 个 handler 仍是裸 `CommonResult`。 +- **未知异常映射 500**:`@ExceptionHandler(Exception.class)` 返回 `CommonResult.serverError`(code=500),不能复用参数错误的 400, + 否则系统故障被说成「参数不对」。存量:该兜底 handler 现在返回 400。 + ## DTO 转换 - MapStruct 编译期生成 `*ConvertImpl.java`,同名属性自动映射。 diff --git a/.agents/roles/code-review-checklist.md b/.agents/roles/code-review-checklist.md new file mode 100644 index 0000000..52a5993 --- /dev/null +++ b/.agents/roles/code-review-checklist.md @@ -0,0 +1,49 @@ +# 后端代码评审清单 + +- **功能**:列出 Checkstyle 查不了、必须人看才能发现的后端坏味道,每条给出识别方式、改法与当前数量。 +- **何时用**:评审 lpt-be 的 PR、改 controller / service / mapper、自查交付前;机械格式与命名问题交给 `./mvnw validate`,不在这里重复。 + +## 出参与入参 + +### 1. Controller 出参不出现实体 + +`CommonResult`、`CommonResult>` 都算违规;实体带租户与审计列,库表形状一改就击穿 API 契约。 +出参放 `dto/`。存量 18 个端点已于 2026-11-19 清零(改为 `dto/response`),新代码别再引入;历史例子: `TaskController#getPriorityWeights`、`StudySessionController#getTaskFragments`。 + +### 2. 请求体不用 `Map` + +看到 `@RequestBody Map body` 再 `body.get("xxx")` 就是违规:类型、校验、字段名的编译期保护全丢。 +每个端点建一个 request DTO + `@Valid`。存量 10 处已于 2026-11-19 清零(改为 `dto/request`);历史例子: `MarkerController#addUserTag`、`ReviewController#saveSortPreference`。 + +### 3. 局部更新要说清「清空」还是「不动」 + +`new XxxEntity()` + 只 `set` 变了的字段 + `updateById` 是 patch 实体式更新:想表达的「清空」落不了库(null 被跳过), +行为还依赖全局 null 策略。整对象替换 / `LambdaUpdateWrapper.set(...)` / `XxxPatch` DTO 三选一。存量 17 处已于 2026-11-19 清零(改为 `lambdaUpdate().set(...)`);历史例子: `ReviewServiceImpl#updateReport`、`ReviewServiceImpl#submitFeedback`。 + +### 4. SQL 不拼字符串 + +`.last("LIMIT " + n)`、`apply("name = '" + x + "'")` 这类拼接一律违规,哪怕当前值来自内部常量——下一个人会传用户输入。 +能参数化就用 `{0}` 占位,表达不了下沉到 mapper 的自定义 SQL。存量 3 处已于 2026-11-19 清零(改用 `selectPage`);历史例子: `ReviewServiceImpl` 与 `ReviewRecallService` 的 `last("LIMIT " + n)`。 + +### 5. 未知异常映射 500,不伪装成 400 + +`@ExceptionHandler(Exception.class)` 返回 `CommonResult.error(...)`(code=400)会把系统故障说成「你参数不对」,用户反复重试、值班查不到。 +未知异常走 `CommonResult.serverError`(code=500),技术细节写日志。存量已于 2026-11-19 修正:兜底 handler 现在返回 `serverError`(500)。 + +## 分层与命名 + +### 6. `service/impl` 只放 `service/` 接口的实现 + +包名写 `impl` 却没有对应接口的类(`RecallJson`、`AiTaskParams`、`ReviewRecallStore`、`AiServiceClient` 这类工具或客户端也算)就是放错位置: +无接口就别用 `Impl` 后缀,也别放这个包,挪到 `service/`、`client/` 或调用方内部。存量 34 个已于 2026-11-19 挪出 `service/impl`(`service/ai`、`service/recall`、`service/review`、`service/session`)。 + +### 7. 注释跟随签名,不跟随历史 + +Javadoc 描述的方法名、参数、返回跟下面那个方法对不上就是违规——例如 `ReviewServiceImpl:371` 的「取任务名」挂在 `submitFeedback` 上。 +方法移动、改名、改签名时把注释一起搬;过期注释比没有注释更贵。 + +### 8. 注释与用户可见文案统一中文 + +新增英文注释、或把中文提示改成英文都算违规:这个项目的用户文案与注释都是中文,混语种会在同一屏里跳出来。 +用户文案还要求口语化(见 `api-response.md`)。历史情况(2026-11-19 前)是混排:`ReviewRecallController:21`、`LoginResult:21` 这类成句英文注释要翻成中文; +`/** REPORT | FRAGMENT */` 这种字段取值说明不算违规。 diff --git a/.agents/roles/code-standards.md b/.agents/roles/code-standards.md new file mode 100644 index 0000000..1a3bca9 --- /dev/null +++ b/.agents/roles/code-standards.md @@ -0,0 +1,105 @@ +# 后端代码规范 + +- **功能**:说明本项目在格式、命名、注释、复杂度、异常与事务上取哪些值、为什么这样取、出处在哪。 +- **何时用**:新写或改动 `src/main/java` 下的类、`validate` 卡住不知道改什么、评审后端代码、想加规则或降豁免时。 + +## 事实来源是配置文件 + +- 规则的唯一事实来源是 `config/checkstyle/checkstyle.xml`(模块与阈值)与 `config/checkstyle/suppressions.xml`(存量豁免基线)。 + 本文件只记「取什么值 + 为什么 + 出处」,不复述 Checkstyle 的模块说明,也不抄上游正文;**两者不一致时以配置文件为准**,并回来改这里。 +- 门禁形态:`maven-checkstyle-plugin:3.3.1` + `checkstyle:10.12.4`,绑在 `validate` 阶段,`failOnViolation=true`, + 只查 `src/main/java`(`includeTestSourceDirectory=false`)。`./mvnw validate` 即触发,跑 `test` / `package` / CI / Docker 构建都会先撞上它。 +- 选型、基线与代价见 [Checkstyle 门禁笔记](../notes/implemented/process/2026-11-19-checkstyle-gate.md)。 + +## 格式 + +- **缩进 4 空格,禁 tab**(`FileTabCharacter`)。Google Java Style 是 2 空格、Spring Framework 用 tab,都与本仓既有代码不符; + 4 空格是既有代码与 IDE 默认的共同值,换掉要重排全部源文件,收益只在观感。 +- **行宽 120**(`LineLength`)。Google 取 100 列,压到 100 会把存量违规从 215 处成倍放大,而 120 列恰好是既有代码排出来的宽度。 +- **一行一句、一行一声明**(`OneStatementPerLine`、`MultipleVariableDeclarations`)。出处:Google Java Style §4.3「One statement per line」、 + Spring Framework `src/checkstyle/checkstyle.xml` 的 `OneStatementPerLine`。 +- **`if` / `for` / `while` / `else` 必须带花括号,即使只有一条语句**(`NeedBraces`)。出处:p3c `NeedBraceRule`。 + 理由不是风格:省掉花括号后往循环体补第二行是静默改逻辑(新语句落到循环外)。 +- **import 不用通配、不留未用与重复**(`AvoidStarImport` / `UnusedImports` / `RedundantImport`)。出处:Google Java Style §3.3.1。 +- **文件 ≤ 400 行**(`FileLength`):超了通常说明这个类不止承担一件事,先拆再交。 +- **禁 `System.out` / `System.err`**(`RegexpSinglelineJava` 的 `noSystemOut`),日志走 `@Slf4j`。出处:Spring Framework + `src/checkstyle/checkstyle.xml` 中的同类检查。 +- **其余机械项**:`ModifierOrder`、`ArrayTypeStyle`(写 `String[] a` 不写 `String a[]`)、`UpperEll`(`1L` 不写 `1l`)、 + `EmptyStatement`(多余分号)、`OuterTypeFilename`(公有类名必须等于文件名)、`OneTopLevelClass`(一个文件一个顶层类)。 + +## 命名 + +- **类名 UpperCamelCase,只允许字母与数字**(`TypeName`,`^[A-Z][a-zA-Z0-9]*$`):下划线、数字开头都不行;缩写段可以全大写 + (`HTTPServer` 能通过,没人要求你写成 `HttpServer`)。出处:p3c `ClassNamingShouldBeCamelRule`、Sonar S101。 +- **方法 / 成员 / 局部变量 / 参数一律 lowerCamelCase**(`MethodName`、`MemberName`、`LocalVariableName`、`ParameterName`)。 + 出处:p3c `LowerCamelCaseVariableNamingRule`、Sonar S100。 +- **常量全大写、下划线分隔**(`ConstantName`,`^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$`)。出处:p3c `ConstantFieldShouldBeUpperCaseRule`。 +- **包名全小写**(`PackageName`,`^[a-z]+(\.[a-z][a-z0-9]*)*$`)。 +- **业务名称以上游术语表为准**:库表、实体、DTO 字段由 `lpt-docs/docs/concepts/README.md` 派生,不另起别名(meta `business-terminology.md`)。 +- **异常类以 `Exception` 结尾**(p3c `ExceptionClassShouldEndWithExceptionRule`)、**`service/impl` 下的实现类以 `Impl` 结尾** + (p3c `ServiceOrDaoClassShouldEndWithImplRule`)。这两条 Checkstyle 查不了,靠评审;没有对应接口的类不该叫 `Impl`,见 `code-review-checklist.md`。 + +## 注释 + +- **类与公共方法写 Javadoc:做什么、边界条件、为什么这么写**。对齐 Spring Framework `SpringJavadocCheck` 关心的项(描述、`@param`、`@return`、`@throws`)。 + 注释必须跟着签名走:方法被移动或改名时一起搬,别把「取任务名」留在另一个方法头上。 +- **注释与用户可见文案用中文**。用户文案另外还要求口语化(见 `api-response.md`)。 +- **枚举常量必须带注释**(p3c `EnumConstantsMustHaveCommentRule`)。 +- **不留注释掉的代码**(p3c `RemoveCommentedCodeRule`):历史在 git 里,注释掉的代码既不被编译也不会被清理。 + +## 复杂度 + +- **方法 ≤ 80 行**(`MethodLength`)。出处:p3c `MethodTooLongRule` 取同一阈值。 +- **参数 ≤ 7**(`ParameterNumber`)。出处:Sonar S107;超了先看是不是该收成参数对象。 +- **圈复杂度 ≤ 15**(`CyclomaticComplexity`)。注意这是**圈复杂度**,不是 Sonar S3776 的认知复杂度:两者对不同结构计数不同, + S3776 在本仓没有门禁(Checkstyle 不提供这个指标)。Checkstyle 默认阈值是 10,本仓先取 15(10 会把大量普通分支方法打成违规), + 存量 6 处靠豁免挂着,往下收用棘轮。 +- **嵌套 `if` / `for` / `try` 各 ≤ 3 层**(`NestedIfDepth` / `NestedForDepth` / `NestedTryDepth`);超了用卫语句提前返回。 +- **switch 必须有 `default`**(`MissingSwitchDefault`);**重复字面量收敛成常量**(Sonar S1192)是评审项,Checkstyle 没有等价模块。 + +## 异常与事务 + +- **`@Transactional` 必须写 `rollbackFor`**(`RegexpSinglelineJava` 的 `transactionRollback`,正则 `@Transactional(?![^)]*rollbackFor)`)。 + 出处:p3c `TransactionMustHaveRollbackRule`。默认只对 `RuntimeException` 回滚,受检异常抛出去事务照样提交。 +- **不抛裸 `Exception` / `Throwable` / `RuntimeException`**(`IllegalThrows`),自定义异常继承具体基类。出处:Sonar S112。 +- **捕获不许吞**(`EmptyCatchBlock` 只放行 `expected` / `ignore` 命名的变量):要么处理,要么记日志再抛。出处:Sonar S1166。 +- **不 `printStackTrace()`**(`RegexpSinglelineJava` 的 `noPrintStackTrace`):日志框架之外没有上下文,也没有接收方。出处:Sonar S2139 的意图。 +- **`String` 比较用 `equals` 不用 `==`**(`StringLiteralEquality`);**重写 `equals` 必须重写 `hashCode`**(`EqualsHashCode`)。 + +## 持久化与接口边界 + +这三块不在这里复述,各由对应规则文件持有: + +- **数据访问**(查询结果用类承载、禁 `selectMaps` 取字符串 key、SQL 只留在 mapper、写入形态、实体继承 `BaseEntity`)→ `data-access.md`。 +- **出参与入参边界**(Entity 不出 controller、请求体用 DTO 不用 `Map`、未知异常映射 500)→ `api-response.md`。 +- **迁移脚本**(Flyway 命名、H2 与 MySQL 的差异)→ `database-migration.md`。 + +## 豁免只减不增(ratchet) + +- **现状:债务豁免为 0**。`suppressions.xml` 里只剩 2 条框架约束(见下节),692 处存量违规已在 2026-11-19 全部改完, + 折算为:展开 51 处通配 import、全仓格式化、补 181 处大括号、44 个 `@Transactional` 补 `rollbackFor`、 + 拆 7 个超长类、抽 6 个复杂方法、改 15 处命名、补 4 个私有构造。 +- **新增豁免必须在 PR / 提交说明里写理由**,并说明为什么不能改代码。没有理由的新增豁免等于把门禁关掉一格。 + 只有「框架规定、改了就坏」才能豁免(见下节两条)。 +- 跳闸口只有 `-Dcheckstyle.skip=true`(`failOnViolation` 写死在 pom 里,user property 覆盖不了),**只用于本地应急**; + 推之前必须再跑一次 `./mvnw validate`。 + +## 什么不算违规 + +- **Flyway Java 迁移类的类名**(`TypeName`):`V20261115_2__xxx.java` 的版本前缀是 Flyway 规定的,不满足 + `^[A-Z][a-zA-Z0-9]*$` 属**正当例外**——不要改类名,也不要改 Flyway 的命名约定。这条以目录级豁免写在 `suppressions.xml`。 +- **`LearningProgressTrackerApplication` 的 `HideUtilityClassConstructor`**:它是 Spring Boot 启动入口,只有 `main`、没有实例方法, + Checkstyle 按「只有静态成员」的工具类特征判到了。给它加私有构造会让 Spring 测试上下文无法实例化启动类 + (实测 164 个测试报 `No visible constructors`),所以只能豁免。 +- **名字里的业务缩写**(`taskNum`、`aiTaskNum`):`MemberName` / `ParameterName` 只要求 lowerCamelCase,不要求把缩写展开成 `taskNumber`。 + 业务名以上游术语表为准,缩写形式同样是术语的一部分。 + +## 不采纳的上游规则 + +| 上游规则 | 不采纳的理由 | +|---|---| +| p3c `ClassMustHaveAuthorRule` | 模板里的 `@author` 只会被复制粘贴,换手后立刻过期;问「这行是谁写的、为什么」用 `git blame`,答得比注释准。 | +| p3c `PojoMustOverrideToStringRule` | 实体与 DTO 统一用 Lombok `@Data`,`toString` 已经生成;再加一条规则只会报假违规。 | +| p3c `AvoidNegationOperatorRule` | 会逼出 `x == false` 这种更难读的写法;条件里取反(`!ok` 卫语句)是本项目的正常写法。 | +| Google Java Style 的 2 空格缩进与 100 列 | 与本仓既有代码(4 空格、120 列)不符,切换要重排全部源文件,行为不变、评审成本全落在格式噪音上。 | +| Spring Framework 的 tab 缩进 | 同上;且 tab 的显示宽度取决于编辑器设置,跨机器看 diff 对不齐。 | diff --git a/.agents/roles/data-access.md b/.agents/roles/data-access.md index 6b59aea..f61be52 100644 --- a/.agents/roles/data-access.md +++ b/.agents/roles/data-access.md @@ -17,3 +17,18 @@ - **自定义 SQL 不会被 `@TableLogic` 自动追加逻辑删除条件**,必须显式写 `deleted = 0`;租户条件 `created_by = ?` 仍由 `TenantLineInnerInterceptor` 自动追加 - 上述两条不能只靠 mock 单测,需落库集成测试守住(参考 `ReviewDurationIntegrationTest`) - 反向约束:`Wrapper` 能表达的查询不要为「类型安全」提前下沉为自定义 SQL;确实要下沉时,SQL 只留在 Mapper 层,不要在 service 里拼字符串 + +## 写入形态 + +- **禁 patch 实体式更新**:不要 `new XxxEntity()` + 只 `set` 变化字段 + `updateById` 就走。两个理由:一是字段清不空——本仓 + 未显式配 `update-strategy`,MyBatis-Plus 默认跳过 null 字段,用户点了「清空备注」库里的值还在;二是语义依赖全局配置, + 那个默认值改一次,全库的 patch 更新行为一起变且不报错。要局部更新先分清是哪种,三选一: + - **整对象替换**:先查到完整实体、改完字段、`updateById`——适合「表单提交整张卡」的场景。 + - **`LambdaUpdateWrapper.set(...)`**:需要显式写 null(真清空)时用,意图写在 `.set(field, null)` 上。 + - **`XxxPatch` DTO**:由请求对象表达「哪些字段有值才改」,与 `api-response.md` 的入参规范对齐。 + 现状 17 处 patch 写法(全仓 27 处 `updateById`,其余是整对象更新),例 `ReviewServiceImpl#updateReport`、`ReviewServiceImpl#submitFeedback`。 +- **实体统一继承 `BaseEntity`**:`created_by` / `created_time` / `last_modified_by` / `last_modified_time` / `device_info` / `deleted` + 由 `config/AutoTableField` 自动填充与 `@TableLogic` 软删除接管。不继承就少审计列,`created_by` 缺失还会让租户拦截器无列可加。 + 现状:`entity/` 下 19 个业务实体全部继承(`entity/` 的第 20 个文件是 `BaseEntity` 本身)。 +- **SQL 只出现在 Mapper**:service 里不拼 SQL 字符串(当前 3 处 `.last("LIMIT " + n)` 属存量违规,见 `code-review-checklist.md`); + 需要分页/限量时用参数化占位符,或用 `Page` / `IPage`,再不行下沉到 mapper。 diff --git a/AGENTS.md b/AGENTS.md index e5724ab..2eb4eb2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,7 +8,9 @@ - 命名:业务概念的英文名以 `lpt-docs/docs/concepts/README.md` 术语表为准,库表、实体、DTO 字段由它派生,不另起别名(规则见 meta `.agents/roles/business-terminology.md`)。 - 本仓库专属规则:`.agents/roles/` - `.agents/roles/database-migration.md`:数据库迁移(Flyway Migration) - - `.agents/roles/data-access.md`:编码规范 · 数据访问层 + - `.agents/roles/code-standards.md`:后端代码规范的取值与出处(Checkstyle 门禁、棘轮、不采纳的上游规则) + - `.agents/roles/code-review-checklist.md`:Checkstyle 查不了、必须人看的评审项(实体出 controller、Map 请求体、patch 更新等) + - `.agents/roles/data-access.md`:编码规范 · 数据访问层与写入形态 - `.agents/roles/api-response.md`:响应规范、DTO 转换 - `.agents/roles/ownership-and-markers.md`:内容归属与结构化报告(归属-01 / 报告-01)、标记(标记-01) - `.agents/roles/ai-integration.md`:学习引导(复习-06)、AI 异步链路(AI-02) @@ -198,8 +200,15 @@ lpt-be/src/main/java/com/guo/learningprogresstracker/ ```bash mvn clean compile -DskipTests # 编译(需要 JDK 17) mvn spring-boot:run # 启动(默认 profile: local) +./mvnw validate # 先跑 Checkstyle,违规即失败 ``` +- **Checkstyle 门禁**:`./mvnw validate` 会先跑 Checkstyle(绑 `validate` 阶段,`failOnViolation=true`,只查 `src/main/java`), + `test` / `package` / CI / Docker 构建都会先撞上它。配置在 `config/checkstyle/`:`checkstyle.xml` 是规则与阈值, + `suppressions.xml` 是存量豁免基线(改到被豁免的文件时顺手删掉对应豁免行)。 +- **应急跳闸**:`-Dcheckstyle.skip=true` 只用于本地临时绕过(`failOnViolation` 写死在 pom,user property 覆盖不了), + 推之前必须再跑一次 `./mvnw validate`。规则取值、理由与出处见 `.agents/roles/code-standards.md`。 + ## 关联项目 | 项目 | 路径 | 端口 | 说明 |