gz-oarms/CLAUDE.md

# 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 字段、数据库表映射及高频错误模式。