# 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
```

## 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_` |

### 分层结构

每个模块遵循 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/` 开头

### 数据源

两个数据源，通过 dynamic-datasource 切换：
- `master`（primary）→ OARMS schema，业务数据
- `youfool` → YOUFOOL schema，框架日志（restLog）

### 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`

## Development Guide

详细开发指南见 `docs/backend-module-dev-guide.md`，包含 Entity/Controller/Service/Mapper/Query 模板代码和 DM8 类型映射表。