jcgl/docs/09-迭代指引与风险清单.md

09 迭代指引与风险清单

1. 技术债与风险

P0：会直接影响构建/上线

项	现状	影响	建议
Spring Boot 依赖版本错配	pom.xml 在 Boot 2.6.13 父工程下显式声明 spring-boot-starter-web:3.5.4、spring-boot-starter-data-redis:3.3.1	可能拉入 Spring 6 / Jakarta 依赖，与 javax.servlet 代码不兼容，导致编译/运行失败	删除显式版本，交给父工程管理；或统一升到 Boot 3 + Jakarta（大改造）。先跑一次 mvn clean test 确认基线
明文口令与内部地址入库	各 application-*.yml 含数据库口令、AMI 口令、devicePassword、内网 IP	已推送到远端，存在泄露风险	轮换口令；改用环境变量/配置中心；生产库最小权限
无根级 .gitignore	仓库根目录没有 .gitignore，仅有 YktVue/.gitignore	易误提交构建产物、日志、数据转储	在仓库根补充 .gitignore（target、logs、*.log、node_modules、dist、本地配置）
构建/测试基线不明	target/ 为空，测试未运行，无 CI 配置	无法判断改动是否破坏现有功能	建立 CI：编译 + 单测 + 关键 SQL 校验

P1：影响正确性与可维护性

项	现状	影响	建议
JcglService 过大	约 4192 行，混合叫乘、房间、补助、交路、归档、设备指令	改动风险高、冲突多、难测试	按“叫乘执行 / 房间 / 卡务 / 交路匹配 / 归档”拆服务，先抽只读逻辑与纯函数
交路 MERGE 停用	mergeSynJcXx 因同 id 多司机被注释	快照与历史数据可能长期不一致	改为 id + ryid 唯一键后恢复，并加数据清理脚本
远程同步为桩	/jcgl/getRemoteSynJcXx 直接返回成功	调用方误以为已同步	恢复实现或明确返回“未启用”
部分定时任务停用	RechargeSchedule、JlSchedule、LogSchedule 全部注释	自动补助、交路同步、日志清理不生效	明确替代方案；若不再需要则删除代码
写接口用 @RequestMapping	大量写操作接受 GET	易被误触发、难做权限/审计	新接口强制 POST；存量逐步收敛
异常被吞	大量 catch 返回 Result.failure，仅写日志	故障定位困难、事务边界不清	统一异常处理与错误码；关键路径保留堆栈
日志不规范	System.out.println 与业务日志混用	无法集中检索/轮转	统一 SLF4J + 文件轮转；敏感信息脱敏
硬编码	公寓名“通辽南公寓/通辽南派班室”、照片路径、内网 IP、中心地址	多公寓/迁移环境需改代码	抽到配置或字典表
交路匹配只覆盖单公寓	matchCallDutyUnderLock 只处理 baseConfig.gyid 配置的公寓	一实例多公寓时，其他公寓不会自动匹配交路	明确部署形态；如需一实例多公寓，把 gyid 改为循环/列表并逐公寓加锁
房态语义不一致	selectRoomRecommendations 与前端允许 3（待清扫）、6（保洁中）；validateRoomForCheckIn 也允许 6	保洁中的房间可能被入住	确认业务规则；若不允许，收紧 SQL 与校验
备份文件/旧构建	RoomLook copy.vue、JcXx.vue.bak_mojibake、resources/static 下旧前端与 .gz	干扰阅读、增大仓库	清理或移入 legacy/

P2：体验与稳健性

项	说明
processCallDuty 空值判断顺序	`ryid.equals("")
h1.concat(...) 结果未赋值	ByxxResourceService 中拼接公寓编码无效，h1 实际未追加 housecode
syncJlXX 返回 null	/jcgl/ya/list 永远返回空数据，容易误判
personData 空数组	jsonArray.getJSONObject(0) 未判空，上游无数据时异常
时间字符串	全链路用字符串 + TO_DATE，格式/时区问题只能在运行期暴露
IP→公寓	依赖真实客户端 IP；反向代理未透传时会识别错误
设备照片/抓拍	Base64 体积大，需关注请求体大小、内存与磁盘
测试接口暴露	/test/*、/jcgl/yatest、/jcgl/driver/{id} 可访问外部系统，生产应限制

2. 改动落点速查

需求	先看	可能要改
调整叫乘/复叫/报警时间	GY_SJGZ、modifyJcXxBySynJcXx、populateJcXxByJlXx	JcglService、WakeUpJob、SchedulerManager
改叫乘提醒节点	JcglService.notifyMissedCallWarnings、selectMissedCallWarnings	JcSchedule、SQL
改叫乘语音内容	AsteriskCallUtil.makeWakeup	TTS 文案、格式化函数
改房间状态规则	getRoomStatus、validateRoomForCheckIn、modifyRoomStatus	JcglRoomMapper.xml、前端 Room.vue
改房间推荐	selectRoomRecommendations	推荐 SQL、getRoomRecommendations
新增设备类型	heartBeat、GY_SB、GY_SB_XT	新建 xxxDevice 包、心跳控制器
改设备指令	HeartBeatService.addDeviceInstructionInfo*	各业务调用点
改入住补助	getAllowanceInfo、getTrainAllowanceInfo、changeRemainder	GY_YKT_* 表、节假日规则
改充值/消费	RechargeService、PayService、VendPayDeviceService	余额与明细同事务
改交路维护	JlGlService、GYGL_JLXX	上传模板、同步接口
改运安同步	ByxxResourceService、SynDataSchedule	WSDL、字段映射、锁
改匹配规则	matchCallDutyUnderLock	工号匹配、时间重算、任务重建
改离寓/抓拍	processCheckOutRegistration、leaveSnapshot.*	GYGL_LY_EVENT、文件目录
新增报表	xxtj / excel	对应 Mapper XML
改权限/菜单	display、GL_*	登录、RBAC、菜单
改公寓识别	ZdwhService.getUniqueGyByIp	GY_SB、GY_GYZD、代理配置

3. 建议的迭代顺序

1. 建立基线：修复 pom 版本错配，确保能编译；跑通现有测试；加 CI。
2. 安全整改：口令外置与轮换；生产关闭测试接口；补根 .gitignore；清理备份文件。
3. 稳定性：统一日志与异常；关键路径加监控（叫乘任务创建数、AMI 连接、同步状态、快照积压）。
4. 结构治理：拆分 JcglService；把硬编码公寓/路径/地址配置化；收敛写接口 HTTP 方法。
5. 业务增强：恢复并测试 mergeSynJcXx、远程同步；完善多公寓参数化；补叫乘/入住/离寓的集成测试。
6. 数据治理：归档与索引优化；房间占用对账；历史数据清理。

4. 待确认问题

建议与业务/现场逐条确认，确认后回写本文档：

1. 保洁中（room_status=6）房间是否允许入住？ 当前推荐 SQL、入住校验、前端都允许，但 modifyRoomStatus 又禁止修改保洁中房间。
2. 待清扫（3）房间是否应出现在推荐列表？ 当前会出现，可能影响值班员选房效率。
3. 便乘/驻在是否完全不叫乘？ 当前 jllx=1 且跳过任务；是否符合现场？
4. 运安下发的 jcsj 是否彻底弃用？ 当前仅保留读取，最终按本地规则重算。
5. 远程同步是否还需要？ getRemoteSynJcXx 目前是桩。
6. 多公寓部署形态：一公寓一实例，还是一实例多公寓？影响 IP 映射、同步任务与锁。
7. 刷脸抓拍是否强制？ requiredForDevice=false 目前兼容旧设备，何时切为 true？
8. Oracle Profile（byq/cc/dl/pj）是否继续维护？ 若迁移 Kingbase，需要同步 SQL 兼容性。
9. 叫乘任务恢复范围：应用重启后恢复未来任务，是否也要补偿“重启期间已错过”的任务？当前只恢复未来任务，错过由提醒任务兜底。
10. 归档保留策略：GY_JCXX_HIS 保留多久？是否需要冷备/清理？

5. 文档维护约定

• 本文档以代码为准；接口、表、状态码变更时同步更新对应章节。
• 新增模块时，在 03-业务模块地图.md 增加一行，并在 06-接口清单.md 补接口。
• 新增表/字段时，在 05-数据模型.md 补字段与状态字典。
• 新增外部依赖/定时任务时，在 07-外部集成与定时任务.md 补时序与排障点。
• 每次迭代结束，把已解决的风险从本清单移除，并在提交说明中引用相关文档章节。