7.5 KiB

Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build & Run

# 编译（开发阶段跳过 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，当前仅配置了"基础框架"和"登录相关"两个分组。新增模块需添加分组：

- 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. 目标驱动

将任务转化为可验证的目标。
多步骤任务先列出简短计划和验证点。
成功标准要明确，避免模糊目标（如"让它能用"）。

7.5 KiB Raw Blame History Unescape Escape