docs: 更新 README 为 OARMS 项目文档

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-18 15:41:14 +08:00 · 2026-05-18 15:41:14 +08:00 · 1292d8769e
parent 1d1d1f52d2
commit 1292d8769e
1 changed files with 103 additions and 66 deletions
--- a/README.md
+++ b/README.md
@ -1,10 +1,6 @@
-# youfool-prj-springboot3-template
+# OARMS - 广州市户外广告监管系统后端

-基于 Spring Boot 3.x 的企业级后端项目模板。
-
-## 项目简介
-
-本模板是 youfool 框架团队提供的基础后台开发模板，集成了常用的企业级开发组件和最佳实践，帮助开发者快速搭建业务系统。
+广州市户外广告监测监管系统（Outdoor Advertising Regulation & Monitoring System）后端服务，负责广告大屏信息管理、法律法规维护、监测规则配置、录屏取证、线索转办等全链路业务。

 ## 技术栈

@ -12,18 +8,65 @@
 |------|------|------|
 | Spring Boot | 3.4.5 | 基础框架 |
 | Java | 21 | 编程语言 |
-| PostgreSQL | 42.7.9 | 主数据库 |
-| MySQL | 8.0.28 | 数据库驱动 |
-| Lombok | 1.18.42 | 简化代码 |
-| youfool-framework-springboot3 | 1.0.4 | 基础框架 |
+| DM8 (达梦) | 8.1 | 国产数据库 |
+| MyBatis-Plus | 3.5.12 | ORM 框架 |
+| Sa-Token | 1.42.0 | 权限认证 |
+| Knife4j | 4.4.0 | API 文档 |
+| Druid | 1.2.24 | 连接池 |

-## 核心特性
+## 业务模块

- **多数据源支持**：集成动态数据源，支持主从配置
- **权限认证**：集成 Sa-Token，支持灵活的权限控制
- **API 文档**：集成 Knife4j，提供在线接口文档
- **监控面板**：集成 Druid 数据库连接池监控
- **CMS 后台**：内置基础框架 CMS 后台管理系统
+系统按业务域划分为 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
+```

 ## 快速开始

@ -31,80 +74,72 @@

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

-### 运行项目
+### 编译

 ```bash
-# 编译打包
-mvn clean package
+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

-# 或指定环境运行
-java -jar target/youfool-prj-springboot3-template.jar --spring.profiles.active=dev
+# 方式二：本地开发
+mvn dependency:build-classpath -Dmdep.outputFile=classpath.txt
+java -cp "target/classes;$(cat classpath.txt)" -Dfile.encoding=UTF-8 \
+     com.chinaweal.youfool.prj.YoufoolApplication
 ```

 ### 访问地址

 | 功能 | 路径 | 账号 | 密码 |
 |------|------|------|------|
-| CMS 后台管理系统 | /cms | admin | 123456 |
 | 接口文档 | /doc.html | admin | 123456 |
 | Druid 监控 | /druid | admin | 123456 |

-> 注意：接口文档如出现乱码，请在启动时指定 JVM 参数 `-Dfile.encoding=UTF-8`
+## 数据源配置

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

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

-项目支持多环境配置，通过 `spring.profiles.active` 切换：
+开发环境配置在 `application-dev.yml`，生产环境在 `application-prod.yml`。

- `dev` - 开发环境
- `prod` - 生产环境
+> 事务注解必须使用 `@DSTransactional`，不能使用 `@Transactional`。

-### 数据源配置
+## API 概览

-当前版本使用苍米豆的 [动态数据源](https://github.com/baomidou/dynamic-datasource-spring-boot-starter)。
+所有接口路径以 `/api/` 开头，登录接口在 `/user/auth/`。

-**重要提示**：使用事务时需使用 `@DSTransactional` 代替 `@Transactional` 注解。
-
-### 端口配置
-
-默认端口为 8080，可通过环境变量 `PRJ_PORT` 修改。
-
-## 项目结构
-
-```
-youfool-prj-springboot3-template/
-├── src/
-│   ├── main/
-│   │   ├── java/com/chinaweal/youfool/prj/
-│   │   │   ├── YoufoolApplication.java       # 启动类
-│   │   │   ├── common/                        # 公共模块
-│   │   │   ├── config/                        # 配置类
-│   │   │   ├── controller/                    # 控制器
-│   │   │   ├── service/                       # 业务逻辑
-│   │   │   └── dev/                           # 开发工具（代码生成等）
-│   │   └── resources/
-│   │       ├── application.yml                # 主配置
-│   │       ├── application-dev.yml            # 开发环境配置
-│   │       ├── application-prod.yml           # 生产环境配置
-│   │       └── logback-spring.xml             # 日志配置
-└── pom.xml                                     # Maven 配置
-```
+| 模块 | 基础路径 | 核心接口 |
+|------|---------|---------|
+| 大屏管理 | /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 test
-
 # 打包（跳过测试）
 mvn clean package -DskipTests

@ -115,9 +150,11 @@ mvn checkstyle:check
 ## 注意事项

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

 ## 许可证