xh-medical-sign-web/clinical-web

clinical-web

医签通医护端 Web 应用，面向医生、护士、科室人员和系统管理人员。

使用场景

• 电脑浏览器；
• 电子病历 iframe 嵌入；
• 护士站电脑；
• 后续可适配医院平板；
• 电脑连接外接签字板。

签字板是医护端的一种硬件签署渠道，不是独立的移动端应用。

核心职责

医生端

• 从电子病历中发起知情同意；
• 自动带入患者、就诊和医嘱信息；
• 选择文书模板；
• 确认已完成病情解释；
• 发送手机签署或打开现场签署。

护士/现场端

• 调出待签署任务；
• 协助患者使用签字板；
• 查看签署结果和异常状态。

护士可以协助操作，但不应被系统误记为病情解释人员。

管理端

• 文书模板和版本管理；
• 用户、角色和文档权限；
• 签署记录查询；
• 统计和报表；
• 设备及系统配置。

重点业务流程

电子病历中选择患者
→ 选择就诊/医嘱/项目
→ 选择或生成文书
→ 医生完成解释并发起
→ 手机、二维码或签字板签署
→ 查看状态
→ 回传电子病历

需要支持的异常

• 患者拒绝签署；
• 患者或家属无法联系；
• 实际陪同人和登记手机号不一致；
• 签署链接过期；
• 文书需要动态追加；
• 急诊抢救紧急例外；
• 签署成功但回传失败。

当前技术栈

Vue 3
TypeScript
Vite
Vue Router
Pinia
Element Plus
Axios

TanStack Vue Query、PDF 预览、报表图表、自动化测试和签字板适配器暂不接入，等真实接口和业务流程稳定后再按需要增加。

签字板调用应通过独立的 signature-adapter 或本地桥接服务封装，业务页面不直接绑定具体厂商 SDK。

非目标

• 不在前端自行判断最终签署法律效力；
• 不在医护端直接修改已经签署的正式文书；
• 不把患者完整病历发送到患者手机端。

当前状态

已完成 Vite 基础初始化、路由、Pinia、原型主题 CSS、登录页、首页、签署工作台第一版 Mock 和文档库管理页面。登录、首页统计、签署工作台的患者/就诊/模板/任务/审计、签署文件下载、短信重发、模板创建/版本工作流、用户组织查询与用户创建编辑，以及按模板维护文档权限已经接入 MEDISIGN 后端；系统设置仍保留 Mock，真实签字板/线上签名回调和打印服务仍需设备或后端能力。

当前路由结构

公开页
└─ /login                       登录页

ClinicalLayout
├─ 工作台
│  ├─ /workbench/home              首页
│  └─ /workbench/signing           签署工作台
└─ 管理
   ├─ /management/documents        文档库管理
   ├─ /management/reports          报表分析
   ├─ /management/users            用户与权限
   ├─ /management/document-permissions  文档权限
   └─ /management/settings         系统设置

布局拆分为 Menu、Header 和 Container 三个公共组件，页面内容由各自的 View 负责。

页面目录按业务域组织：auth 保留登录页；工作台页面位于 views/workbench；管理页面位于 views/management。每个具体页面目录都有 index.vue 入口和 components 目录，用于继续拆分当前页面组件。

跨页面复用的业务组件和 composable 不放在具体 View 目录中：

• components/signing/NewSigningTaskDialog.vue：新增签署任务公共弹窗，供签署工作台和文档库管理复用；
• composables/useSigningTaskForm.ts：封装患者定位、就诊选择、模板选择、签署方式、校验和任务提交状态。

API 与类型约定

API 模块与页面按业务域对应。工作台页面使用 api/workbench 下的页面文件，管理页面使用 api/management 下的直接文件：

• api/workbench/home.ts
• api/workbench/signing.ts
• api/workbench/artifacts.ts
• api/workbench/deliveries.ts
• api/management/documents.ts
• api/management/reports.ts
• api/management/users.ts
• api/management/roles.ts
• api/management/permissions.ts
• api/management/organization.ts
• api/management/document-permissions.ts
• api/management/audit.ts
• api/management/settings.ts

所有接口统一使用 utils/request.ts 导出的单例请求实例。登录接口已接入 MEDISIGN 后端：

• POST /api/v1/auth/login：账号密码登录；
• GET /api/v1/auth/captcha：获取按需启用的图形验证码；
• GET /api/v1/auth/me：查询当前用户；
• POST /api/v1/auth/logout：注销当前会话；
• 后续请求自动携带 X-Token 请求头。

签署工作台已接入的真实接口包括：

• GET /api/v1/patients、GET /api/v1/patients/{id}：患者定位；
• GET /api/v1/patients/{id}/visits、GET /api/v1/visits：就诊关联；
• GET /api/v1/templates/available-versions：可发起模板版本；
• GET /api/v1/sign-tasks、GET /api/v1/sign-tasks/{id}：任务列表和详情；
• POST /api/v1/sign-tasks、POST /api/v1/sign-tasks/{id}/prepare-send：创建任务和准备投递；
• POST /api/v1/sign-tasks/{id}/void、/resend、/reopen：作废、短信重发和重新开启；
• GET /api/v1/sign-tasks/{id}/events：操作审计事件。

已接入或封装的扩展接口包括：

• GET /api/v1/sign-artifacts/task/{taskId}、GET /api/v1/sign-artifacts/task/{taskId}/{artifactId}：签署文件索引；
• GET /api/v1/sign-artifacts/{artifactId}/download：原始 PDF、签署后 PDF、签名原图下载；
• POST /api/v1/sign-deliveries/{taskId}/sms/resend：短信重发，自动携带幂等键；
• GET/POST /api/v1/templates、GET /api/v1/templates/{id}：模板列表、详情；
• GET/POST /api/v1/templates/{id}/versions、版本工作流接口：版本查询、创建、送审、驳回、通过、发布、停用、归档；
• GET /api/v1/users、GET /api/v1/roles、GET /api/v1/campuses、GET /api/v1/departments：用户页真实查询及组织字典；
• GET/POST/PUT/DELETE /api/v1/permissions：API 权限分页查询、详情、新增、修改和停用；
• GET/POST/DELETE /api/v1/templates/{id}/permissions：按模板查询和维护文档权限；
• GET /api/v1/audit-logs：全局审计日志查询 API。

报表页在真实模式下使用 GET /api/v1/sign-tasks 聚合当前任务数据，并支持跳转任务和导出当前筛选结果；MEDISIGN 文档中暂无独立的报表统计接口。首页同样从模板、院区和签署任务接口聚合工作台概览。

API 请求和响应类型按业务域放在 api/workbench/types.ts、api/management/types.ts；页面展示和交互类型放在对应 View 目录的 types.ts；全局复用类型放在 types/common.ts。页面提交模型会在 API 边界转换为后端 DTO，不向后端发送患者快照、文档名称或明文手机号等页面字段。

开发环境默认使用 /api 作为同源接口前缀，Vite 会将 /api 转发到 https://ipad.shenynet.com，因此浏览器不会直接跨域请求后端。代理配置位于 vite.config.ts，不改写 /api/v1/... 路径。修改代理或环境变量后需要重启 Vite 开发服务。

生产环境不会使用 Vite 的开发代理，需要在 Nginx 或其他网关中配置同样的 /api 反向代理。除登录外，当前业务 API 模块默认返回 Mock 数据，设置 VITE_USE_MOCK=false 后切换已实现的真实接口。使用本地开发代理时，VITE_API_BASE_URL 应填写 /api；如果改为直连后端，则需要后端配置允许当前前端源的 CORS。

当前尚未接入的签署能力包括手写板设备桥接、线上签署页面/签名回调和打印服务。签署投递、一次性 Token 消费和真实 PNG 上传 API 已完成封装，但页面不能用 Canvas 演示数据冒充真实签名；需要接入设备适配器或患者 H5 回调后再启用。短信初次发送接口需要完整手机号，而患者查询只返回脱敏手机号，因此真实模式会要求当前操作人员确认完整投递地址；生产环境也可以改为由后端根据患者 ID 解析投递地址。默认 Mock 模式仍可用于演示完整交互，联调时设置 VITE_USE_MOCK=false。