jcgl/docs/02-工程结构与分层.md

02 工程结构与分层

1. 目录结构

仓库根目录：

jcgl/
├── yktgl/                  # 后端（Spring Boot / Maven）
│   ├── pom.xml
│   └── src/
│       ├── main/
│       │   ├── java/org/example/yktgl/...
│       │   └── resources/
│       │       ├── application.yml / application-*.yml
│       │       ├── mapper/**/*.xml
│       │       ├── wsdl/PbResource.wsdl
│       │       ├── db/                 # 手工升级脚本
│       │       └── static/             # 历史前端构建产物
│       └── test/java/...
├── YktVue/                 # Vue 前端
└── docs/                   # 本文档目录

后端 Java 包（org.example.yktgl）：

包	职责
jcgl	叫乘核心：入寓/离寓、叫乘执行、房间、交路匹配、补助、卡余额、统计联动
jlgl	交路维护：交路 CRUD、叫乘时刻、上传、跨公寓同步、车次查询
regist	人员资料与注册：注册查询、照片、人员增删改
recharge	现金充值：设备发起、值班端处理、余额变动、补助入账
pay	消费：设备余额查询与扣款、消费明细
MealsOrdering	食堂/餐食订单与消费
kcgl	库存/出入库/物料/成品/文件（扩展业务）
display	登录、用户、角色、权限、菜单、部门、日志
excel	各类报表导出（POI）
xxtj	信息统计：日报、进出情况、月报、补助统计
zdwh	字典/基础资料：公寓、房间、工种、节假日、餐补标准；IP→公寓解析
syndata	运安/中心数据同步、同步日志、人员同步服务
heartBeat	设备心跳、设备指令、设备信息
callingDevice / checkInDevice / roomDevice / payDevice / registDevice / vendPayDevice	各类设备的接入层（心跳 + 业务）
clean	房间保洁
jgxxgl	叫乘报警/警示信息查询
quartz	Quartz 工具、任务管理、叫乘任务 WakeUpJob
schedule	@Scheduled 补偿任务与启动恢复
websockets	各类 WebSocket 端点
common	通用返回体、验证码、工具、Session/WebSocket 配置
config	异步线程池、RestTemplate、Swagger
util	日期、字符串工具
test	测试/演示接口（生产应限制）

2. 分层约定与调用链

典型调用链：

Controller（参数/鉴权/协议编解码）
   → Service（业务编排、事务、状态机）
      → Mapper 接口（MyBatis）
         → mapper/**/*.xml（SQL）
            → KingbaseES

实际代码中的偏差：

• 部分 Controller 直接调用 Mapper（如设备心跳、字典查询）。
• 设备接入层通常只有一个 Service，同时承担协议解析与业务调用。
• JcglService 体量过大，承担了叫乘、房间、人员、补助、同步、归档等多类职责；迭代时应优先“新增小服务 + 复用其中方法”，避免继续膨胀。

请求与返回

• 统一返回 common/entity/Result 或 ResultData，包含成功标志、消息、数据。
• 设备接口多返回 ResultData；Web 接口多返回 Result。
• 部分统计接口直接返回 JSONObject（如 /synData/synPersonData）。

事务与异常

• 写操作使用 @Transactional；捕获异常后调用 TransactionAspectSupport.currentTransactionStatus().setRollbackOnly() 再返回失败。
• 叫乘任务创建、WebSocket 推送等副作用通过 afterCurrentTransactionCommits(...) 延迟到提交后，避免“事务回滚但消息已发/任务已建”。
• 大量 try/catch 将异常转成 Result.failure(message)，同时写业务日志；排查时需同时看 GY_LOGS / 同步日志 / System.out。

3. 启动流程

入口：YktglApplication

@EnableTransactionManagement
@SpringBootApplication
@EnableScheduling
public class YktglApplication extends SpringBootServletInitializer

启动关键动作：

1. Spring 容器初始化，激活 spring.profiles.active（默认 local）。
2. SessionConfig 开启 Redis HttpSession。
3. WebSocketConfig 注册 ServerEndpointExporter，扫描 @ServerEndpoint（websockets/*）。
4. ServerStartupListener 在启动时做初始化（端口/环境相关）。
5. WakeupJobRecoveryRunner 监听 ApplicationReadyEvent，从 GY_JCXX 恢复未来叫乘任务。
6. @Scheduled 任务开始运行（见 07）。

4. 配置与 Profile

• 主配置：application.yml，只保留通用项与 active: local。
• 环境配置：application-{byq,cc,dev,dl,local,pj,prod,sjt,tl}.yml，各自定义端口、数据源、Redis、公寓、AMI、串口等。
• 自定义前缀：baseConfig.*（公寓、中心地址、同步白名单、设备密码、服务器 OS）、callcontrol.*（AMI、录音、串口）。

详细字段见 08-部署与配置.md。

5. 公共组件速查

组件	位置	用途
Result / ResultData	common/entity	统一返回体
CaptchaUtil / CaptchaResult	common	登录验证码
IpUtil	common/utils	取真实客户端 IP
HttpRequest	common/utils	内部 HTTP 调用（运安人员接口等）
MD5Util / PasswordEncoder	common/utils	口令处理
MyBatisUtils	common/utils	MyBatis 辅助
SpringUtils	common/utils	静态获取 Bean
AsyncConfig	config	异步线程池（核心 10、最大 200、队列 10）
RestTemplateConfig	config	HTTP 客户端
SwaggerConfig	config	仅扫描 jlgl.controller
QuartzUtils / SchedulerManager	quartz	任务创建/取消/重建
CallDutyMatchLock	jcgl/service	交路抓取与匹配的互斥锁（DB 行锁 + 租约）
AsteriskCallUtil	jcgl/service	AMI 呼叫、会议桥、录音、挂断
JcWebsocket 等	websockets	按公寓/房间推送

6. 测试现状

src/test/java 下已有部分单元/切片测试（录音控制器、当前在寓交路 SQL、最近同步时间、人员同步等），但工程 target/ 为空，未见完整构建/测试产物。迭代前建议先补齐可重复的构建与测试基线。

7. 关键文件索引

行号为当前版本近似位置，改动后请以方法名检索。

文件	关注内容
jcgl/service/JcglService.java	叫乘/入住/离寓/房间/补助/同步/归档主逻辑（约 4192 行）
├─ 559–1010	房间列表、推荐、房态修改、入住提交、离寓提交
├─ 1320–1450	processCallDuty / processTempCallDuty 状态上报
├─ 1700–2150	远程同步、交路匹配、提醒补偿
├─ 2400–2510	ryzt 状态更新与校验
├─ 2640–2800	按开车时间与时间规则计算叫乘时刻
├─ 3065–3175	刷脸离寓
├─ 3600–3700	房间校验、时间线校验
└─ 3880–4192	停止叫乘、录音、归档
jcgl/controller/JcglController.java	/jcgl 全部 Web/设备接口入口
jcgl/service/AsteriskCallUtil.java	AMI 连接、呼叫、会议桥、TTS、录音、挂断
jcgl/service/CallDutyMatchLock.java	同步/匹配互斥锁
jcgl/service/ByxxResourceService.java	运安 WSDL 调用与快照写入
quartz/SchedulerManager.java	叫乘任务创建/取消/重建
quartz/WakeUpJob.java	单个叫乘任务执行
quartz/QuartzUtils.java	Quartz 基础设施
schedule/JcSchedule.java	漏叫提醒、超时离寓、归档
schedule/SynDataSchedule.java	运安抓取/人员同步
schedule/WakeupJobRecoveryRunner.java	启动恢复任务
mapper/jcgl/JcglMapper.xml	叫乘核心 SQL（表结构事实来源之一）
mapper/jcgl/JcglRoomMapper.xml	房间 SQL 与推荐逻辑
mapper/jcgl/LeaveEventMapper.xml	离寓事件
mapper/heartBeat/HeartBeatMapper.xml	设备、心跳、指令
mapper/recharge/RechargeMapper.xml	充值申请/余额/补助
heartBeat/service/HeartBeatService.java	指令写入与设备维护
zdwh/service/ZdwhService.java	IP→公寓、字典
websockets/JcWebsocket.java	叫乘实时推送
application.yml / application-*.yml	运行配置