jcgl/docs/06-接口清单.md

06 接口清单

1. 通用约定

• 基础路径：http://host:8081/yktgl（server.servlet.context-path）。
• 返回体：
  • Result：{code/flag, message, data}（Web 接口常用）
  • ResultData：设备接口常用
  • 少数接口直接返回 JSONObject 或字符串。
• 公寓上下文：绝大多数写接口通过客户端 IP 解析 gyid；少数接口显式接收 gyid，但服务端仍会校验。
• 方法约束宽松：大量接口用 @RequestMapping，GET/POST 都可访问，部分写操作也能用 GET 触发。新增接口建议明确 @GetMapping/@PostMapping。
• 字符集：JSON 为 UTF-8；设备请求体常为单行 JSON。

2. 叫乘核心 /jcgl

方法	路径	用途
ALL	/getJcxxByRyid	按人员/记录查叫乘信息
ALL	/getEmployeeArriveInfo	按单位查人员到达信息
POST	/getJcXx	条件查询在寓/叫乘列表
POST	/resetJllx	重置交路类型
GET	/getLatestSyncTime	当前公寓最近同步时间
GET	/getSjgz	时间规则（叫乘/离寓提前量）
ALL	/getJlxxList	按车次/机车号查交路
ALL	/getRoomList	房间列表
GET	/getRoomRecommendations	入住房间推荐
ALL	/modifyRoomStatus	设置不能入住/恢复可入住
ALL	/submitAll	提交入寓登记（submit_rydj）
ALL	/updateMeal3	更新第三餐补助
ALL	/getBtje_info	按入住时间查补助金额
ALL	/getBtje_infoMeal3	第三餐补助信息
ALL	/getRyxx	按人员查资料
ALL	/getRyxxByRyId	按人员查资料（含公寓上下文）
ALL	/remakeRemainder	重算余额/补助
ALL	/modifyJcXx	修改叫乘信息并重建任务
POST	/getJcXxFromGy	从公寓端获取叫乘信息
ALL	/getZbyList	值班员列表
ALL	/getGzList	工种列表
POST	/modifyRyXx	修改人员资料
POST	/deleteRyXx	删除人员
ALL	/isHoliday	是否节假日
ALL	/getGyOptions	按单位取公寓选项
POST	/synCallDutyInfo	运安计划推送（整表快照）
POST	/processCheckInRegistration	设备入寓登记（code 1/2/3）
POST	/processCheckOutRegistration	设备离寓（code 1/2）
POST	/processCallDuty	叫乘设备状态上报（status 1–5）
POST	/processTempCallDuty	临时叫乘状态上报
ALL	/getCcJcXx	按车次聚合叫乘信息
ALL	/getCcJcXx_Ls	历史车次叫乘信息
ALL	/getCallDutyInfoByDeviceCode	叫乘屏按设备码取人员
ALL	/getTempCallDutyInfoByDeviceCode	临时叫乘屏取人员
ALL	/getSynJcXx	分页查运安快照
ALL	/getRzXx	入住信息
ALL	/getRemoteSynJcXx	远程同步（当前为桩实现，返回空成功）
ALL	/synUnMatchJcXx	触发交路匹配
POST	/syncJcXxData	手工归档 7 天前已离寓记录
ALL	/handleTempCalling	临时叫乘（人工）
ALL	/handleRoomCall2 / /handleRoomCallEnd2	房间呼叫/结束（新版）
ALL	/handleRoomCall / /handleRoomCallEnd	房间呼叫/结束（旧版）
ALL	/handleMultiRoomCall / /handleMultiRoomCallEnd	多房间呼叫/结束
ALL	/handleCheckOut	值班端办理离寓
ALL	/cancelTrainAssignment	取消交路并清理任务
ALL	/getWslRyXx	未匹配人员信息
ALL	/getRyFjXx	人员房间信息
ALL	/exchangeRoom	换房
ALL	/handleStopCalling	停止叫乘（需报警事件键）
ALL	/yatest	运安 SOAP 连通性测试
ALL	/ya/list	触发运安计划抓取
ALL	/driver/{driverId}	查询运安司机信息
GET	/getRecordingConfig	录音回放配置（RecordingController）

3. 交路 /jlgl

路径	用途
/addJlXx	新增交路
/modifyJlXx	修改交路
/getJlXxList	交路列表
/getJlXxJcsjList	交路及叫乘时刻
/delJlXx、/deleteJlXx	删除交路
/uploadJlXx	Excel 上传交路
/getMessageFromGy、/getMessageFromFcd	从公寓/发车点获取信息
/getGyXxList、/getTyXxList	公寓/停运信息
/addTySjList	新增停运时间
/confirmJlXx	交路确认
/getTrainNumberInfo	车次信息

4. 人员与注册 /regist

方法	路径	用途
POST	/registPersonInfo	设备注册协议（code 1 拍照、2 查/更新照片、3 按 ID 查、4 批量增量）
POST	/addPersonInfo	新增人员（写真 + 照片表）
ALL	/getPersonelInfo	按手机号/姓名查人员
POST	/updatePersonelInfo	修改人员并下发设备指令
ALL	/deletePersonelInfo	逻辑删除人员并清理照片

5. 充值 /recharge

路径	用途
/processCashRecharge	设备充值协议（code 1–4）
/handleRecharge	值班端处理充值
/autoRecharge	自动补助入账（对应定时器已停用）
/getAllowance	补助查询
/getRechargeInfo	充值记录
/getRechargeStatisInfo	充值统计
/getAllowanceStatis	补助统计

6. 消费 /pay

路径	用途
/processPayment	设备消费协议（code 1 查余额、2 扣款）
/getConsumDetailInfo	消费明细
/getCashConsumeStatisInfo	现金消费统计
/getAllowanceConsumeStatisInfo	补助消费统计
/getConsumeStatis	消费汇总

7. 设备接入

基础路径	接口	用途
/callingDevice	POST /heartbeat	叫乘屏心跳
/checkInDevice	POST /heartbeat	签到机心跳
/roomDevice	POST /heartbeat	房间屏心跳
/payDevice	POST /heartbeat	消费机心跳
/registDevice	POST /heartbeat	注册机心跳
/vendPayDevice	POST /heartbeat、POST /processPayment	售货机心跳/支付
/heartBeat	/getDeviceInfo、/getDeviceStatusInfo、/modifyDeviceInfo、/modifyApkVersion	管理端设备查询/维护

7.1 心跳请求字段（常见）

deviceCode、versionName、deviceType、ip、deviceUpdateState、lastUserUpdateTime、lastDeviceConfigUpdateTime、roomNumber。

7.2 心跳响应字段

devicePassword、apartmentName、serverTime、updateState、apkUrl、指令列表。

7.3 设备业务协议

场景	code/status	说明
入寓登记	code 1/2/3	查询/提交/按 ID 查询
离寓	code 1/2	查询/刷脸离寓
叫乘	status 1–5	开始/复叫/叫乘报警/离寓报警/应答
临时叫乘	status 1–5	同上，另刷新房间设备
充值	code 1–4	查余额/申请/查状态/取消
消费	code 1/2	查余额/扣款
售货机	code 1/2/3	查余额/下单/结果或退款
注册	code 1–4	拍照/查询/按 ID/批量增量
保洁	—	开始/结束保洁（/clean）

8. 管理后台

8.1 登录与权限

路径	用途
/auth/getCaptcha、/auth/captchaImage	验证码
/auth/login	登录
/auth/logon	注册/开通
/auth/logout	退出
/auth/getInfo	当前用户信息
/auth/getMenuInfo	用户菜单
/user/*	用户增删改查、改密、启停
/role/*	角色与角色权限
/permission/*	权限树与权限维护
/menu/*	菜单维护
/dept/*	部门树、公寓部门树

8.2 基础资料 /Zdwh

时间规则、公寓、房间、节假日、餐补标准的新增/修改/删除/查询；公寓与房间资料是入住与推荐的基础。

8.3 统计与导出

路径	用途
/xxtj/getBjcs	报警次数
/xxtj/getJdqk	进出情况
/xxtj/getRtjb	日报
/xxtj/getYtjb	月报
/xxtj/getDailyApartmentReport、/getDailyApartmentReportFull	公寓日报
/xxtj/getApartmentAllowanceStatis	补助统计
/excel/exportJcXxExcell	叫乘明细
/excel/exportDailyApartmentReport	日报
/excel/exportJcXxExcellOld	旧版叫乘明细
/excel/exportAllowanceExcell	补助明细
/excel/exportRechargeExcell	充值明细
/excel/exportConsumeExcell	消费明细
/excel/exportRechargeStatisExcell	充值统计
/excel/exportAllowanceStatisExcell	补助统计
/excel/exportCashConsumeStatisExcell	现金消费统计
/excel/exportAllowanceConsumeStatisExcell	补助消费统计

8.4 其他

路径	用途
/clean/startCleaning、/endCleaning、/getRoomCleanInfo	保洁
/jgxxgl/getJgXx	报警/警示查询
/Meals/*	餐食、订单、房间、餐次列表
/kcgl/*	库存/出入库/物料/成品/文件
/synData/*	运安/公寓人员、财务数据
/jwDataLog/getSynJcXxIsOffline	同步状态/是否离线
/websocket/{username}、/jcwebsocket/{username}、/jlwebsocket/{username}、/rlywebsocket/{username}、/MealsWebsocket/{username}	WebSocket 端点

9. WebSocket 消息

消息	含义
{"lx":"refresh"}	叫乘/房间/人员数据刷新
{"lx":"ry","content":...}	入寓人员信息推送值班端
{"lx":"zcxx","photoBase64":...,"deviceCode":...,"zcid":...}	注册拍照
{"lx":"xgxx","content":...,"newPhotoBase64":...}	人员资料/照片更新
{"lx":"cz"}	充值申请提醒

JcWebsocket.sendMessage(message, gyid) 会按公寓路由；gyid="all" 表示广播。

10. 接口扩展建议

1. 新接口明确 HTTP 方法，避免用 @RequestMapping 触发写操作。
2. 统一返回体，不在 Controller 里拼 JSONObject。
3. 前端传入的 gyid 只能作为提示，服务端必须重新解析/校验。
4. 设备协议新增字段时保持向后兼容：旧字段可缺省，新增字段给默认值。
5. 接口文档以本清单为基线，最终以 JcglController 等源码为准；Swagger 目前只扫描 jlgl.controller，覆盖不全。