gz-oarms/README.md

# OARMS - 广州市户外广告监管系统后端

广州市户外广告监测监管系统（Outdoor Advertising Regulation & Monitoring System）后端服务，负责广告大屏信息管理、法律法规维护、监测规则配置、录屏取证、线索转办等全链路业务。

## 技术栈

| 组件 | 版本 | 说明 |
|------|------|------|
| Spring Boot | 3.4.5 | 基础框架 |
| Java | 21 | 编程语言 |
| DM8 (达梦) | 8.1 | 国产数据库 |
| MyBatis-Plus | 3.5.12 | ORM 框架 |
| Sa-Token | 1.42.0 | 权限认证 |
| Knife4j | 4.4.0 | API 文档 |
| Druid | 1.2.24 | 连接池 |

## 业务模块

系统按业务域划分为 5 大域、10 个模块：

| 域 | 模块 | 数据表 | 说明 |
|----|------|--------|------|
| BS 基础 | BS-1 大屏管理 | bs_screen, bs_screen_history | 户外广告大屏基础信息维护 |
| LB 法律 | LB-1 法律法规 | lb_law_clause | 广告相关法律法规条款管理 |
| MR 监测 | MR-1 监测规则 | mr_monitoring_rule, mr_rule_law_clause_rel, mr_rule_operation_history | 广告内容监测规则配置 |
| AM 监控 | AM-1 录屏设置 | am_recording_config | 大屏录屏参数配置 |
| AM 监控 | AM-2 随机录屏 | am_recording_task, am_alert_notification | 录屏任务调度与告警 |
| AM 监控 | AM-3 广告画面监控 | am_monitor_record | 广告画面抓拍与识别记录 |
| CW 取证 | CW-1 固化取证 | cw_evidence_record, cw_evidence_status_history | 违法广告取证固化 |
| CW 取证 | CW-2 规则关联 | cw_evidence_rule_relation | 取证与监测规则关联 |
| CW 取证 | CW-3 线索生成 | cw_monitoring_clue, cw_clue_generation_log | 违法线索自动/手动生成 |
| CW 取证 | CW-4 线索转办 | cw_clue_transfer_record, cw_transfer_operation_log | 线索转办与处置跟踪 |

## 项目结构

```
gz-oarms/
├── docs/
│   └── db/sql/                          # DDL 建表语句 + 初始数据
├── src/main/java/com/chinaweal/youfool/prj/
│   ├── YoufoolApplication.java          # 启动类
│   ├── common/                          # 常量、工具类
│   ├── config/                          # Spring 配置
│   ├── controller/                      # 登录等通用接口
│   ├── service/                         # 通用服务（用户等）
│   └── modules/
│       ├── screen/                      # BS-1 大屏管理
│       │   ├── controller/
│       │   ├── entity/                  # Entity / Query / Req / VO
│       │   ├── mapper/
│       │   └── service/
│       ├── law/                         # LB-1 法律法规
│       ├── rule/                        # MR-1 监测规则
│       ├── monitor/
│       │   ├── config/                  # AM-1 录屏设置
│       │   ├── task/                    # AM-2 随机录屏
│       │   └── record/                  # AM-3 广告画面监控
│       └── evidence/
│           ├── record/                  # CW-1 固化取证
│           ├── relation/                # CW-2 规则关联
│           ├── clue/                    # CW-3 线索生成
│           └── transfer/                # CW-4 线索转办
├── src/main/resources/
│   ├── application.yml                  # 主配置
│   ├── application-dev.yml              # 开发环境数据源
│   ├── application-prod.yml             # 生产环境数据源
│   └── logback-spring.xml              # 日志配置
└── pom.xml
```

## 快速开始

### 环境要求

- JDK 21+
- Maven 3.6+
- DM8 数据库（已部署，17 张表已初始化）

### 编译

```bash
mvn clean compile
```

### 运行

由于 `spring-boot-maven-plugin` 配置了 `ZIP` layout 分离依赖，`mvn spring-boot:run` 无法直接使用。需通过以下方式启动：

```bash
# 方式一：打包后运行（生产部署）
mvn clean package -DskipTests
java -jar target/youfool-prj-springboot3-template.jar

# 方式二：本地开发
mvn dependency:build-classpath -Dmdep.outputFile=classpath.txt
java -cp "target/classes;$(cat classpath.txt)" -Dfile.encoding=UTF-8 \
     com.chinaweal.youfool.prj.YoufoolApplication
```

### 访问地址

| 功能 | 路径 | 账号 | 密码 |
|------|------|------|------|
| 接口文档 | /doc.html | admin | 123456 |
| Druid 监控 | /druid | admin | 123456 |

## 数据源配置

项目使用动态数据源（dynamic-datasource），配置两个数据源：

| 数据源 | Schema | 用途 |
|--------|--------|------|
| master | OARMS | 业务数据（大屏、法规、规则、取证等） |
| youfool | YOUFOOL | 框架日志（restLog） |

开发环境配置在 `application-dev.yml`，生产环境在 `application-prod.yml`。

> 事务注解必须使用 `@DSTransactional`，不能使用 `@Transactional`。

## API 概览

所有接口路径以 `/api/` 开头，登录接口在 `/user/auth/`。

| 模块 | 基础路径 | 核心接口 |
|------|---------|---------|
| 大屏管理 | /api/screen | query, detail, save, update, remove, toggle-status, check-code, check-address, export, import, import-template, histories |
| 法律法规 | /api/law-clause | query, detail, save, update, remove, repeal, check-clause-number, effective |
| 监测规则 | /api/monitoring-rules | query, detail, save, update, remove, toggle-status, check-name, enabled, scope-types, status-options, export |
| 录屏设置 | /api/recording-config | query, detail, save, update, remove, toggle-status, configurable-screens |
| 录屏任务 | /api/recording-task | query, detail, save |
| 广告监控 | /api/monitor-record | query, detail, save |
| 固化取证 | /api/evidence-record | query, detail, save, download, play |
| 规则关联 | /api/evidence-rule-relation | query-by-evidence, relate |
| 线索生成 | /api/monitoring-clue | query, detail, save, clue-preview, status-summary |
| 线索转办 | /api/clue-transfer | query, detail, save, targets/districts, targets/departments, targets/persons, disposal-feedback |

## 常用命令

```bash
# 编译
mvn clean compile

# 打包（跳过测试）
mvn clean package -DskipTests

# 代码风格检查
mvn checkstyle:check
```

## 注意事项

1. 本项目使用 JDK 21 编译，请确保本地 JDK 版本匹配
2. 数据库为达梦 DM8，DDL 语法与 MySQL/PostgreSQL 有差异，详见 `docs/db/sql/`
3. 动态数据源事务必须使用 `@DSTransactional` 注解
4. `mvn spring-boot:run` 因 ZIP layout 配置无法直接启动，请使用上述替代方式
5. CW-4 部门/人员数据当前为模拟数据，需对接组织架构系统
6. CW-1 文件下载/播放路径为占位实现，需对接文件存储系统

## 许可证

Copyright © chinaweal.com.cn