docs: 补齐代码规范与评审清单,记录 HTTP 边界与 Checkstyle 决策

This commit is contained in:
2026-11-20 09:36:38 +08:00
parent ec2f74bf18
commit 5310f480ce
7 changed files with 356 additions and 1 deletions
+10 -1
View File
@@ -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`。
## 关联项目
| 项目 | 路径 | 端口 | 说明 |