generated from youfool-project/youfool-prj-springboot3-template
178 lines
7.5 KiB
Markdown
178 lines
7.5 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## Build & Run
|
||
|
||
```bash
|
||
# 编译（开发阶段跳过 checkstyle）
|
||
mvn compile -Dcheckstyle.skip=true
|
||
|
||
# 完整编译（含 checkstyle）
|
||
mvn compile
|
||
|
||
# 打包（默认跳过测试）
|
||
mvn clean package
|
||
|
||
# 本地运行（因 ZIP layout 无法用 spring-boot:run）
|
||
mvn dependency:build-classpath -Dmdep.outputFile=classpath.txt
|
||
java -cp "target/classes;$(cat classpath.txt)" -Dfile.encoding=UTF-8 com.chinaweal.youfool.prj.YoufoolApplication
|
||
```
|
||
|
||
- 默认端口 `8081`（环境变量 `PRJ_PORT` 可覆盖）
|
||
- Context Path 可通过环境变量 `PRJ_CONTEXT_PATH` 设置
|
||
- 环境切换：`spring.profiles.active` 设为 `dev` 或 `prod`，对应 `application-dev.yml` / `application-prod.yml`
|
||
- API 文档：`/doc.html`（Knife4j），Druid 监控：`/druid`，账号 admin/123456
|
||
- 公司私有仓库：`-Pcompany-nexus` profile
|
||
|
||
## Architecture
|
||
|
||
OARMS — 广州市户外广告监管系统后端，Spring Boot 3.4.5 + JDK 21 + 达梦 DM8 数据库。
|
||
|
||
### 业务域与模块
|
||
|
||
5 大业务域、10 个模块，按域组织在 `modules/` 下：
|
||
|
||
| 域 | 模块 | 包路径 | 表前缀 |
|
||
|----|------|--------|--------|
|
||
| BS 基础 | 大屏管理 | `modules/screen` | `bs_` |
|
||
| LB 法律 | 法律法规 | `modules/law` | `lb_` |
|
||
| MR 监测 | 监测规则 | `modules/rule` | `mr_` |
|
||
| AM 监控 | 录屏设置/任务/画面监控 | `modules/monitor/{config,task,record}` | `am_` |
|
||
| CW 取证 | 固化取证/规则关联/线索生成/线索转办 | `modules/evidence/{record,relation,clue,transfer}` | `cw_` |
|
||
|
||
核心实体依赖链：`SCREEN(BS-1)` → `AM-1/2/3`、`CW-1`；`MONITORING_RULE(MR-1)` → `CW-2`、`CW-3`；`EVIDENCE_RECORD(CW-1)` → `CW-2/3/4`
|
||
|
||
### 分层结构
|
||
|
||
每个模块遵循 Controller → Service → Mapper 三层，实体包内分 `query/`、`req/`、`vo/`：
|
||
|
||
```
|
||
modules/{module}/
|
||
├── entity/ # Entity + query/ + req/ + vo/
|
||
├── mapper/ # extends BaseMapper<Entity>
|
||
├── service/ # I{Entity}Service + impl/
|
||
└── controller/
|
||
```
|
||
|
||
### 关键约定
|
||
|
||
- **事务**：必须用 `@DSTransactional`，不能用 `@Transactional`（动态数据源要求）
|
||
- **数据源**：`@DS("master")` + `@TableName(schema = "OARMS", value = "表名")`
|
||
- **Entity**：继承 `SuperEntity`（含 createBy/createTime/createName/updateBy/updateTime/updateName，不含 id）
|
||
- **DI**：`@AllArgsConstructor` + `private final`
|
||
- **返回值**：`RestResult.ok(data)` / `RestResult.ok()`
|
||
- **日志**：`log.info("[OK] 操作描述: key={}", value)`
|
||
- **Mapper 扫描**：`com.chinaweal.youfool.prj.**.mapper`，新模块放此包下自动注册
|
||
- **API 路径**：所有接口以 `/api/` 开头
|
||
- **对象映射**：新模块推荐 `BeanUtils.copyProperties`，而非 MapStruct
|
||
- **删除接口**：用 `Map<String, String>` 接收 id
|
||
- **选项接口**：返回 `List<Map<String, Object>>`（label + value），value 保持自然类型（Integer 状态码 / String ID）
|
||
|
||
### 数据源
|
||
|
||
两个数据源，通过 dynamic-datasource 切换：
|
||
- `master`（primary）→ OARMS schema，业务数据
|
||
- `youfool` → YOUFOOL schema，框架日志（restLog）
|
||
|
||
连接配置在 `application-dev.yml` / `application-prod.yml`，不提交敏感信息到主配置。
|
||
|
||
### MyBatis 配置
|
||
|
||
- 配置文件：`mybatis/mybatis-config.xml`
|
||
- 开启 `mapUnderscoreToCamelCase`，DB 列名自动转驼峰映射 Java 字段
|
||
- 分页插件：`MybatisPlusInterceptor` + `PaginationInnerInterceptor`
|
||
- XML mapper 路径：`classpath*:mybatis/mapper/**/*.xml`（当前模块未使用 XML，均为注解方式）
|
||
|
||
### DM8 数据库要点
|
||
|
||
- DDL/COMMENT/INDEX 中表名列名必须大写，INSERT 中列名可用小写
|
||
- 日期字段：`@JsonFormat(pattern = DateUtil.DATE_DEFAULT_FORMAT, timezone = "GMT+8")`
|
||
- 日期时间字段：`@JsonFormat(pattern = DateUtil.DATETIME_DEFAULT_FORMAT, timezone = "GMT+8")`
|
||
- DDL 文件放在 `docs/db/sql/`，命名 `V{版本号}__{模块描述}_{ddl|init_data}.sql`
|
||
- DM8 精度上限 38，`DECIMAL` 超过会报错，经纬度用 `DECIMAL(10,6)`
|
||
- CLOB 字段存 JSON 数组时，Entity 返回 String，前端需 `JSON.parse()`
|
||
- DDL 执行使用 Python + JayDeBeApi 连接 DM8（详见 `docs/backend-module-dev-guide.md` B2 节）
|
||
|
||
### Checkstyle 要点
|
||
|
||
配置文件 `checkstyle-v1.0.xml`，开发阶段可用 `-Dcheckstyle.skip=true` 跳过。关键规则：
|
||
- 行宽 200 字符，文件最大 2000 行，方法最大 300 行
|
||
- 类名/方法名/成员变量：驼峰，最长 30 字符；参数名：最长 19 字符
|
||
- 静态常量：全大写下划线，最长 50 字符
|
||
- 非法访问成员：只能 `private`（`static final` 除外）
|
||
- 方法参数上限 7 个
|
||
- switch 必须有 default，字符串比较必须用 `equals()`
|
||
|
||
### Swagger 分组
|
||
|
||
`application.yml` 中配置 `springdoc.group-configs`，**当前仅配置了"基础框架"和"登录相关"两个分组**。新增模块需添加分组：
|
||
|
||
```yaml
|
||
- group: '新模块名'
|
||
paths-to-match: '/**'
|
||
packages-to-scan: com.chinaweal.youfool.prj.modules.新模块包名.controller
|
||
```
|
||
|
||
### 认证白名单
|
||
|
||
Sa-Token 拦截器在 `SpringMvcConfig`，白名单路径免登录：`/user/auth/**`、`/test/**`、`/doc.html**`、`/swagger*`、`/cms/**`、`/network/ping`
|
||
|
||
## PRD 文档路径
|
||
|
||
需求文档在 `gz-oarms-web/docs/prd-llm/` 目录下，按业务域组织：
|
||
|
||
```
|
||
gz-oarms-web/docs/prd-llm/
|
||
├── BS-大屏基础库域/BS-1_大屏基础信息管理/ # s1需求分析 s2实体定义 s4-api设计 s4-编码任务
|
||
├── LB-法律法规库域/LB-1_法律法规管理/
|
||
├── MR-监测规则库域/MR-1_监测规则管理/
|
||
├── AM-广告监控域/AM-{1,2,3}_*/
|
||
├── CW-内容预警域/CW-{1,2,3,4}_*/
|
||
└── DM-全局数据模型/全局实体字典.md # 核心实体跨域引用
|
||
```
|
||
|
||
## Development Guide
|
||
|
||
详细开发指南见 `docs/backend-module-dev-guide.md`，包含：
|
||
- A. 运行环境（技术栈、数据源、Maven 配置）
|
||
- B. 工具（编译命令、Python + JayDeBeApi 数据库执行工具、SQL 版本号分配）
|
||
- C. 记忆（Entity/Controller/Service/Mapper/Query 模板代码、DM8 类型映射、初始数据约定）
|
||
- D. 评估（编译验证、数据库验证、模块完成检查清单）
|
||
- E. 边界（数据库/代码/编译禁忌）
|
||
- F. Harness Engineering（全流程、模块开发进度总表、核心实体跨域依赖、待开发任务建议顺序）
|
||
|
||
前后端联调指南见 `docs/前后端联调指南.md`，包含 10 个模块的接口清单、DTO 字段、数据库表映射及高频错误模式。
|
||
|
||
## Coding Guidelines (Karpathy)
|
||
|
||
编码行为准则，偏向谨慎而非速度。简单任务可灵活判断。
|
||
|
||
### 1. 先思考再编码
|
||
|
||
- 不要假设。不确定时先问。
|
||
- 存在多种理解时，列出选项而非静默选择。
|
||
- 有更简单的方案时说出来。必要时反驳。
|
||
- 不清楚就停，指出困惑点。
|
||
|
||
### 2. 简洁优先
|
||
|
||
- 只实现被要求的功能，不加额外特性。
|
||
- 单次使用的代码不做抽象。
|
||
- 没有要求的"灵活性"或"可配置性"不加。
|
||
- 不可能发生的场景不加错误处理。
|
||
- 200 行能缩减到 50 行就重写。
|
||
|
||
### 3. 精准修改
|
||
|
||
- 只改必须改的。不"改善"相邻代码、注释或格式。
|
||
- 能用的代码不重构。匹配已有风格。
|
||
- 发现无关死代码时提及但不删除。
|
||
- 自己的改动产生的废弃 import/变量/函数要清理。
|
||
|
||
### 4. 目标驱动
|
||
|
||
- 将任务转化为可验证的目标。
|
||
- 多步骤任务先列出简短计划和验证点。
|
||
- 成功标准要明确，避免模糊目标（如"让它能用"）。
|