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

64 lines
4.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 医生网页面诊迁移:后端与桌面客户端独立验证
验证日期:2026-10-20。只读审查与本地契约测试;未修改业务代码,未读取 `.env`,未调用真实业务接口,未处理其他现有脏改动。
## 结果
**指定检查全部通过,未发现本次后端与桌面请求变更的阻塞性问题。** 截止时刻、医生受众、精确通话入口和新旧桌面请求兼容性均与迁移要求一致。
| 检查 | 结果 |
| --- | --- |
| `php tests/DoctorWebConsultationPolicyTest.php` | 通过,62 条断言 |
| `DoctorWebConsultationPolicy.php` 语法 | 通过 |
| `DoctorWebConsultationMiddleware.php` 语法 | 通过 |
| `config/route.php` 语法 | 通过 |
| `logic/auth/AdminLogic.php` 语法 | 通过 |
| `tests/DoctorWebConsultationPolicyTest.php` 语法 | 通过 |
| `php tests/CallSignatureIdentityContractTest.php` | 通过 |
| `php tests/CallRecordLifecycleIdentityContractTest.php` | 通过 |
| `php tests/AppointmentCallPolicyTest.php` | 通过,34 条内存模型断言,不访问数据库 |
| `php tests/AdminDesktopAuthContractTest.php` | 通过 |
| `app/.venv-runtime/Scripts/python.exe -m pytest tests/test_api_client.py -q` | 通过,16 项测试 |
| HTTPX 原生默认头 / 新 ApiClient MockTransport 请求 | 通过,实际观测旧 UA `python-httpx/0.28.1` 和新 UA `ZytDoctorWorkstation/1.4.8`,两者均不附浏览器 Origin/Referer/Sec-Fetch 头 |
首次使用全局 `python` 运行时因该解释器未安装 pytest 失败;随后使用项目现有 `.venv-runtime` 成功完成指定测试,没有安装或更新依赖。PHP 使用本机 `D:/phpstudy_pro/Extensions/php/php8.2.9nts/php.exe`。
## 实现审查
### 日期
`server/app/adminapi/service/DoctorWebConsultationPolicy.php` 的 `CUTOFF_AT` 明确为 `2026-10-24T00:00:00+08:00`,即北京时间 10 月 23 日结束后。`DateTimeImmutable` 带明确偏移量,不依赖宿主机时区。`now < cutoff` 放行,截止当秒起执行限制。政策测试在 UTC 默认时区覆盖截止前一秒、截止当秒和后一秒。
`publicPolicy()` 返回相同 `cutoff_at` 和秒级 `server_time`,`AdminLogic` 将其附在 `myself` 的 `user.web_consultation_policy`;未给前端另造不同截止时刻。
### 受众与路由范围
策略只对可信登录身份中 **非 root 且角色数组包含医生角色 1** 的请求生效,角色先转换为整数。医助 `[2]`、无医生角色的管理团队 `[3,7,8]` 和 root 保持原有权限。多角色 `[2,1]` 仍按医生处理,与已写明的政策一致。
限定控制器 `tcm.diagnosis` 和四个动作:
- `getCallSignature`
- `startCall`
- `getDoctorSignature`
- `getPatientSignature`
后两个是此前调查发现的历史测试签名入口,限制它们避免常规签名入口停用后仍可从旧测试页取新签名。没有扩大到处方、病历编辑、预约完成、历史查看、医助旁观或通话收尾。
`DoctorWebConsultationMiddleware` 注册在 Login/Auth 之后,拿已验证身份执行检查;后续业务方法在策略拒绝时不会运行。失败沿用 `code=0`,带 `reason=doctor_web_consultation_expired` 和截止信息,不会触发登录过期流程。root 豁免在独立策略里再次明确,因此原 AuthMiddleware 的 root 提前放行不会破坏本次语义。
### 桌面兼容
没有错误地把 `terminal=1` 统一视为网页。`ApiClient._headers()` 增加 `ZytDoctorWorkstation/<__version__>`,当前源码版本 `1.4.8` 能匹配后端完整 UA 格式。API 客户端测试确认真正发出的请求带该 UA。
政策同时识别旧 HTTPX 默认 UA。额外用 `httpx.MockTransport` 捕获本地请求确认:未改旧模式的 HTTPX 客户端实际发 `python-httpx/0.28.1`,新 ApiClient 发 `ZytDoctorWorkstation/1.4.8`;均无浏览器信号。没有更改医生桌面登录终端、token头、API版本头或现有重试语义。
`Origin/Referer/Sec-Fetch-*` 优先于 UA;即使浏览器误带原生 UA 也会受限。空 UA、未知 UA、带额外前后缀的 UA 不会意外得到桌面豁免。策略测试覆盖这些情况。
## 已知边界
1. UA 是产品客户端兼容识别,**不是不可伪造的客户端认证**。能自行构造请求并持有有效医生 token 的调用方仍可仿造原生 UA。这是已选即时迁移方案的边界,不应宣传为设备级安全认证。
2. 后端拦截不会撤销截止前已签发且尚未过期的腾讯签名。已打开页面跨过截止时间后的呼叫应由本次前端呼叫前守卫处理;本次独立验证按分工不覆盖浏览器界面。真实腾讯呼叫、线上部署与已安装旧版程序没有进行端到端验证。
3. 受控测试证明拒绝路径不进入业务回调、旧原生请求允许继续,并保留 `endCall/bind/录音上传/文字落盘` 等收尾路由;这不替代部署环境中反向代理对请求头的实际行为验证。
以上边界没有扩大本次变更范围,也没有导致所运行测试失败。