Files
zyt/artifacts/doctor-web-migration/backend-research.md
T
2026-10-22 11:02:57 +08:00

12 KiB
Raw Blame History

医生网页面诊迁移:后端只读调查

调查日期:2026-10-20。确认截止时刻:北京时间 2026-10-24 00:00:00(10 月 23 日结束后),即 UTC 2026-10-23 16:00:00,Unix 秒 1792771200。应按 now >= cutoff 判定到期,不能在 10 月 23 日零点提前禁用。

本文只调查现有实现并给出建议;未改业务代码,未读取 .env、数据库内容、令牌或密钥。已有脏文件保留。

结论

本次最小准确业务范围是:到期后,仅禁止医生从网页获取新的通话签名及发起新的通话。建议统一策略作用于 tcm.diagnosis/getCallSignature 和 tcm.diagnosis/startCall;医助、管理员、医生桌面工作站保持原权限。列表、历史病历、处方和通话收尾接口不需要随迁移公告一起禁用。

最关键的兼容问题:医生 Python 桌面应用和网页当前均用 terminal=1 登录,不能直接以 terminal == PC 区分它们。若本次以明确的工作站 User-Agent 识别新桌面,并兼容旧 python-httpx/...,这是常规客户端迁移识别方案,不是不可伪造的客户端认证;浏览器 Origin、Sec-Fetch-* 等信号应优先判为网页。长期更稳妥的办法是独立医生工作站终端与会话,但会涉及已安装客户端和旧令牌的迁移,本次不必扩大。

现有公告机制

  • server/app/adminapi/controller/notice/NoticeController.php:settingLists()、detail()、set() 是“通知设置”的管理接口。
  • server/app/adminapi/logic/notice/NoticeLogic.php:36:detail() 从 NoticeSetting 取 system_notice/sms_notice/oa_notice/mnp_notice;system_notice 是场景通知模板(标题、内容、启用状态)。set() 更新现有模板配置,未提供接诊台或问诊列表的全局公告发布/读取接口。
  • server/app/common/enum/notice/NoticeEnum.php:目前主要为登录/绑定/换绑/找回密码验证码场景,不是医生客户端迁移公告。
  • server/app/adminapi/logic/ConfigLogic.php:51 / controller/ConfigController.php:40:getConfig() 是免登录基础配置,目前只有网站名称、logo、版权、版本等,无系统公告字段。

因此,两页面共用一个迁移公告组件/配置即可,不建议把一次客户端迁移伪装成现有验证码通知场景。若需要服务端统一时间和文案,可新增小的只读政策响应或向基础配置附加公开政策;服务端执行拦截时仍必须独立使用服务器时间。

医生身份与角色

证据 当前语义
server/app/adminapi/logic/firstvisit/MyPatientLogic.php:22 DOCTOR_ROLE_ID = 1,ASSISTANT_ROLE_ID = 2,团队角色 [3,7,8],root 优先放行
server/app/adminapi/logic/tcm/DiagnosisLogic.php:3118 getDoctors() 联表 admin_role,role_id=1 获取医生
同文件 getAssistants() role_id=2 获取医助
server/app/common/cache/AdminTokenCache.php:89 缓存含 admin_id/root/role_id/terminal,role_id 是数组
server/app/adminapi/logic/auth/AdminLogic.php:319 myself 返回 user.role_ids 整数数组,适合前端公告受众与禁用状态使用

后端判定应该使用可信的登录身份,角色值先转整数,不能用前端提交的角色、姓名或“有接诊菜单”代替医生身份。需先排除 root=1。单纯拥有医助/团队角色且没有角色 1 的账号应放行;多角色 [1,2] 或 [1,3] 需要明确定义医生身份优先级,至少加入回归用例,避免依赖角色数组第一项。按“含角色 1 的非 root 为医生”最接近现有医生列表语义;如业务要对同时拥有管理角色的医生豁免,需显式列出豁免角色,不能猜测。

终端认证与桌面兼容

文件/方法 证据
admin/src/config/index.ts:2 网页 terminal: 1
admin/src/api/user.ts:5 login() /login/account 带 terminal: config.terminal;企微网页登录亦如此
app/src/doctor_workstation/services/repository.py:842 login() 医生 Python 桌面明确发送 {"account": ..., "password": ..., "terminal": 1}
app/src/doctor_workstation/services/api_client.py:477 _headers() 自定义头目前仅 Accept、version、Content-Type、token;没有专用医生工作站身份头或 User-Agent
server/app/common/enum/AdminTerminalEnum.php:26 PC=1、MOBILE=2、WECOM_RPA=7、WECOM_RPA_MOBILE=9;8 被 AI 浏览器占用
server/app/adminapi/validate/LoginValidate.php:34 账号登录只接受 1/2/7/9
server/app/adminapi/service/AdminTokenService.php:41 setToken() 按 (admin_id, terminal) 找/复用会话,故终端 1 不只是枚举冲突,也会共用会话维度
server/app/common/cache/AdminTokenCache.php:98 terminal 从持久化 AdminSession 进入请求身份

7/9 不是医生工作站终端。 server/app/adminapi/controller/DesktopController.php 的 session() 是企微客服软件换取客服身份的接口,只允许 wecomRpaTerminals();不能为医生工作站借用 7 或9,否则会扩大客服后台身份的可换取范围。

推荐的即时方案:给医生桌面设置 ZytDoctorWorkstation/<version> User-Agent;服务器在浏览器信号不存在时识别这个明确前缀,并按部署范围兼容旧 python-httpx/<version>。旧桌面兼容策略应写测试并在研究/变更说明中如实表述其可信边界。不要仅接受任意请求提交的 desktop=1 即放行。

若以后分离医生工作站终端,应增加新的未占用枚举、登录验证、Python 登录参数,保留既有账号和权限逻辑;旧终端 1 的持久化 token 不会自动变成新终端,升级后应清理/重新登录或安全换取新会话。LoginController::workWechatLogin() 当前直接收 terminal,未使用 LoginValidate,有新终端方案时也应统一处理其允许值。

面诊/问诊调用入口

接口/方法 当前行为与建议
DiagnosisController::getCallSignature()(334)→ DiagnosisLogic::getCallSignature()(908) 校验诊单/患者身份、行级范围,生成 doctor_<adminId> 的 TRTC/IM 签名,签名有效 86400 秒。应作为主要迁移拦截入口,在签名生成/IM账号导入前拒绝到期的医生网页请求。
DiagnosisController::startCall()(350)→ DiagnosisLogic::startCall()(1520) 校验患者、数据范围、挂号音视频策略后创建进行中通话记录。应加相同拦截,覆盖已缓存签名后重新开始的请求。不能把它等同于腾讯SDK本身的鉴权。
doctor.appointment/reception / AppointmentLogic::reception()(645) 接诊台聚合详情,已有挂号/数据范围检查;属于查看数据,建议保留。
tcm.diagnosis/lists/detail/readonlyDetail/trackingWindow 列表/历史病例查看,医助与管理员也使用,建议保留。
doctor.appointment/complete / AppointmentLogic::complete()(583) 标记完成、通知医助、可能系统代开空处方;不是开始通话,建议不在本次一起禁用。
tcm.prescription/add/edit/audit/void/delete 处方动作有独立鉴权/别名策略,本次“网页到期无法面诊”不应自动扩大到开方、审核或药师工作。
tcm.diagnosis/edit、doctor.appointment/addDoctorNote 病例、诊疗笔记写入,和通话迁移不是同一权限,建议保持现状。
bindCallRoom/endCall/startCloudRecording/uploadCallRecording/attachLocalCallRecording/startCallTranscription/upsertCallTranscriptSegments/finishCallTranscription 当前通话房间绑定、结束、录音/文字落盘流程。建议保留原权限,避免跨截止时刻进行中的通话丢失记录;尤其不能一刀切封 tcm.diagnosis/*。
tcm.diagnosis/watchCall 医助只拉流旁观,getAssistantWatchRoomParams() 另校验指派医助,保留。
tcm.diagnosis/getDoctorSignature(631) / getPatientSignature(649) 历史测试签名入口;admin/src/views/test/patient-call.vue:308 用前者。不是当前常规医生面诊链路。需要记录为边界:如果本次要求阻止所有可用签名获取途径,应对医生网页同样限制这两个入口;医助仍需兼容,不能全局删除。

网页主链路证据:admin/src/views/patient/reception/index.vue:439 的 handleCall() 先调 getCallSignature(),再打开 chat-dialog;挂号页 admin/src/views/tcm/appointment/list.vue、list_h5.vue 也发同一签名请求。问诊聊天组件 admin/src/components/chat-dialog/index.vue 会再次取签名并创建通话记录。

必须处理的旧页面边界

  • 由于签名有效24小时,截止前已拿到签名并已登录腾讯IM/TRTC的网页,不会因服务器后续拒绝签名自动退出。
  • admin/src/components/chat-dialog/index.vue:769 的 ensureCallRecordStarted() 捕获 startCall() 失败后只 console.warn,因此“拒绝落库”本身未必阻止腾讯SDK呼叫。
  • 为覆盖真实使用场景,前端需要在通话按钮/呼叫前钩子再次判定到期,并在页面保持打开期间跨越截止时刻时更新状态;后端两入口作为常规请求的最终防线。只隐藏接诊台按钮不足以覆盖挂号页、H5或已经打开的聊天弹窗。
  • 若要求对持有旧签名的非标准客户端也强制断开,需要腾讯侧会话/签名吊销或更强设备认证策略,不属于仅新增公告的最小变更范围。

放置策略与响应

现有链路为 server/app/adminapi/config/route.php:Init → Login → Auth → CheckDemo。LoginMiddleware 验证 token 并设置 request.adminInfo/adminId,AuthMiddleware 存在 root 放行与未注册路由绕过。

统一迁移策略适合在登录身份已加载后按两个精确控制器/动作调用,或放在两个控制器方法开始处调用同一个 helper;不要依赖新权限菜单存在才触发,也不要在登录时整账号封禁。政策判断应顺序处理:精确面诊入口 → 截止时刻 → root/医生角色 → 桌面识别 → 返回迁移提示。

失败响应可沿用 JsonService::fail() 的 code=0 业务失败,附稳定的迁移标识/截止数据方便页面呈现;不要用 code=-1,否则前端会当登录过期退出并丢失工作上下文。不要复用企微绑定 code=10。

日期建议使用带时区的不可变时间对象(Asia/Shanghai 或明确 +08:00),或固定 epoch;server/config/app.php 当前默认时区虽为 Asia/Shanghai,但不应依赖宿主机器时区解析这个业务截止。

验证方式

本次已执行既有只读契约测试(均只 require autoload、反射源码或调用纯策略,未启动业务服务):

cd D:\web\zyt\server
php tests/CallSignatureIdentityContractTest.php
php tests/DiagnosisWorkspaceRowAuthorizationTest.php
php tests/AdminDesktopAuthContractTest.php

结果全部通过:Call signature identity contract: OK、Diagnosis workspace row authorization: OK、OK。

实施后应加一组无数据库政策测试,注入当前时间并覆盖:

  1. 截止前1秒、截止当秒、截止后1秒,且进程默认时区换为UTC仍一致。
  2. 网页医生 root=0, role_id=[1], terminal=1 在两入口被拒绝;医助 [2]、管理员 root、无医生角色的团队账号保留。
  3. 新工作站UA和旧Python桌面UA按兼容策略放行;带Origin/Sec-Fetch的浏览器即使声称桌面UA也不意外放行;正常浏览器、空UA/未知UA在到期后作为网页处理。
  4. 多角色数组、字符串数字角色、空身份的明确语义。
  5. 只读列表/病例/处方、结束通话、录音上传、医助旁观等非拦截路由仍通过策略。
  6. 前端在截止前打开并持有签名,跨到截止后不能从聊天栏或音视频工具栏发起新呼叫;进行中通话的结束和录音上传仍完成。

测试环境可用时间注入,不要修改生产系统时间或依赖测试机当前日期。未进行真实患者呼叫、真实开方或任何生产写操作。