201 lines
12 KiB
Markdown
201 lines
12 KiB
Markdown
# clinical-web
|
|
|
|
医签通医护端 Web 应用，面向医生、护士、科室人员和系统管理人员。
|
|
|
|
## 使用场景
|
|
|
|
- 电脑浏览器；
|
|
- 电子病历 iframe 嵌入；
|
|
- 护士站电脑；
|
|
- 后续可适配医院平板；
|
|
- 电脑连接外接签字板。
|
|
|
|
签字板是医护端的一种硬件签署渠道，不是独立的移动端应用。
|
|
|
|
## 核心职责
|
|
|
|
### 医生端
|
|
|
|
- 从电子病历中发起知情同意；
|
|
- 自动带入患者、就诊和医嘱信息；
|
|
- 选择文书模板；
|
|
- 确认已完成病情解释；
|
|
- 发送手机签署或打开现场签署。
|
|
|
|
### 护士/现场端
|
|
|
|
- 调出待签署任务；
|
|
- 协助患者使用签字板；
|
|
- 查看签署结果和异常状态。
|
|
|
|
护士可以协助操作，但不应被系统误记为病情解释人员。
|
|
|
|
### 管理端
|
|
|
|
- 文书模板和版本管理；
|
|
- 用户、角色和文档权限；
|
|
- 签署记录查询；
|
|
- 统计和报表；
|
|
- 设备及系统配置。
|
|
|
|
## 重点业务流程
|
|
|
|
```text
|
|
电子病历中选择患者
|
|
→ 选择就诊/医嘱/项目
|
|
→ 选择或生成文书
|
|
→ 医生完成解释并发起
|
|
→ 手机、二维码或签字板签署
|
|
→ 查看状态
|
|
→ 回传电子病历
|
|
```
|
|
|
|
## 需要支持的异常
|
|
|
|
- 患者拒绝签署；
|
|
- 患者或家属无法联系；
|
|
- 实际陪同人和登记手机号不一致；
|
|
- 签署链接过期；
|
|
- 文书需要动态追加；
|
|
- 急诊抢救紧急例外；
|
|
- 签署成功但回传失败。
|
|
|
|
## 当前技术栈
|
|
|
|
```text
|
|
Vue 3
|
|
TypeScript
|
|
Vite
|
|
Vue Router
|
|
Pinia
|
|
Element Plus
|
|
Axios
|
|
```
|
|
|
|
TanStack Vue Query、PDF 预览、报表图表、自动化测试和签字板适配器暂不接入，等真实接口和业务流程稳定后再按需要增加。
|
|
|
|
签字板调用应通过独立的 `signature-adapter` 或本地桥接服务封装，业务页面不直接绑定具体厂商 SDK。
|
|
|
|
## 非目标
|
|
|
|
- 不在前端自行判断最终签署法律效力；
|
|
- 不在医护端直接修改已经签署的正式文书；
|
|
- 不把患者完整病历发送到患者手机端。
|
|
|
|
## 当前状态
|
|
|
|
已完成 Vite 基础初始化、路由、Pinia、原型主题 CSS、登录页、首页、签署工作台第一版 Mock 和文档库管理页面。登录、首页统计、签署工作台的患者/就诊/模板/任务/审计、签署文件下载、短信重发、模板创建/版本工作流、用户组织查询与用户创建编辑，以及按模板维护文档权限已经接入 MEDISIGN 后端；系统设置仍保留 Mock，真实签字板/线上签名回调和打印服务仍需设备或后端能力。
|
|
|
|
自测与演示：开启 `VITE_MOCK_DOCUMENTS` / `VITE_MOCK_SIGNING`（两者缺省即为开启）时，文档库和签署任务的演示数据会镜像到 localStorage（见 `utils/mock-storage.ts`），刷新页面后仍可继续，不必每次重建文书、重发签署；文档库页头的「重置演示数据」可清空这些本地数据回到初始状态。持久化只针对演示数据，不涉及登录态与真实患者信息。
|
|
|
|
## 当前路由结构
|
|
|
|
```text
|
|
公开页
|
|
└─ /login 登录页
|
|
|
|
ClinicalLayout
|
|
├─ 工作台
|
|
│ ├─ /workbench/home 首页总览
|
|
│ ├─ /workbench/signing 签署工作台
|
|
│ ├─ /management/documents 文档库管理
|
|
│ └─ /management/reports 报表分析
|
|
└─ 管理
|
|
├─ /management/users 用户与权限
|
|
├─ /management/document-permissions 文档权限
|
|
└─ /management/settings 系统设置
|
|
```
|
|
|
|
菜单分组按原型呈现，与路由 path 前缀不完全对应：文档库管理和报表分析归入侧边栏「工作台」分栏，但路径仍保留在 `/management` 下。
|
|
|
|
布局拆分为 `Menu`、`Header` 和 `Container` 三个公共组件，页面内容由各自的 View 负责；侧边栏与顶栏共用 `components/layout/AppIcon.vue` 提供图标。
|
|
|
|
页面目录按业务域组织：`auth` 保留登录页；工作台页面位于 `views/workbench`；管理页面位于 `views/management`。每个具体页面目录都有 `index.vue` 入口和 `components` 目录，用于继续拆分当前页面组件。
|
|
|
|
跨页面复用的业务组件和 composable 不放在具体 View 目录中：
|
|
|
|
- `components/signing/NewSigningTaskDialog.vue`：新增签署任务公共弹窗，供签署工作台和文档库管理复用；
|
|
- `composables/useSigningTaskForm.ts`：封装患者定位、就诊选择、模板选择、签署方式、校验和任务提交状态；
|
|
- `utils/signing-document.ts`：把文书定稿 HTML 变换为签署态 HTML 的渲染管线（占位符填充、签名域、勾选与行内选项识别），签署工作台的任务详情和文档库「签署预览」共用同一份实现。
|
|
|
|
## 文书编写约定
|
|
|
|
科室在文档库的 Word 编辑器中维护文书，签署时需要交互化的内容按下面的写法即可，系统在签署和「签署预览」时自动转换：
|
|
|
|
- 占位符：`｛患者姓名｝`、`｛性别｝`、`｛年龄｝`、`｛就诊号｝`、`｛签署日期｝`、`｛患者签名｝` 等，由签署任务的患者与就诊快照填充；
|
|
- 勾选表：做成表格，第一行表头写「勾选」，另设一列写「项目」作为勾选条目名，签署时「勾选」列每个单元格变成复选框；
|
|
- 行内选项：正文里直接写方框符号，如 `□否 □是`、`□同意 □不同意`。同一段落或同一单元格内出现两个及以上方框时按二选一（互斥单选）处理，只有一个方框时保持独立复选框语义。
|
|
|
|
编辑器弹窗顶部提供「插入勾选框」「二选一」按钮，光标停在表格单元格内时插入内容会落进该单元格，不需要科室自己找符号面板。导入（.docx / 粘贴）阶段只做格式转换，不做勾选识别；识别统一在签署渲染时进行。
|
|
|
|
识别规则集中在 `utils/signing-document.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 /api/v1/users/{id}/roles`、`PUT /api/v1/users/{id}/roles`、`PUT /api/v1/users/{id}/management`：用户角色读取和用户资料/角色聚合保存；
|
|
- `POST /api/v1/users/{id}/password/reset`、`POST /api/v1/users/import/preview`、`POST /api/v1/users/import/commit`、`GET /api/v1/users/import/jobs/{jobId}`：管理员重置密码和用户导入流程；
|
|
- `GET /api/v1/roles/summary`、`GET/PUT /api/v1/roles/{roleId}/permissions`：角色人数统计和角色 API 权限分配；
|
|
- `GET/POST/PUT/DELETE /api/v1/permissions`：API 权限分页查询、详情、新增、修改和停用；
|
|
- `GET /api/v1/templates/permission-config`：按权限配置范围分页查询模板；
|
|
- `GET /api/v1/templates/permissions/matrix`、`POST /api/v1/templates/permissions/batch`：跨模板权限矩阵查询和批量新增/撤销；
|
|
- `GET/POST/DELETE /api/v1/templates/{id}/permissions`：单模板权限兼容接口，其中前端使用 GET 补充用户继承预览；
|
|
- `GET /api/v1/audit-logs`：全局审计日志查询 API。
|
|
|
|
用户与权限页面的接口核验结果、当前缺口和后端接口建议见 [`docs/users-permissions-api.md`](./docs/users-permissions-api.md)。
|
|
|
|
文档权限页面的新接口契约、继承规则、批量保存行为和联调验收标准见 [`docs/document-permissions-api.md`](./docs/document-permissions-api.md)。
|
|
|
|
报表页真实模式已接入签署报表的 options、overview、tasks 和异步 export-jobs 接口，支持权限范围内的动态筛选、服务端分页、趋势/科室聚合和完整结果导出；Mock 模式仍可用于演示。接口矩阵、时间口径和联调验收见 [reports-api.md](./docs/reports-api.md)，后端联调要求见 [reports-backend-requirements.md](./docs/reports-backend-requirements.md)。首页真实模式已接入 workbench overview。
|
|
|
|
首页真实模式已接入 GET /api/v1/workbench/overview；接口口径、字段映射和验收标准见 [docs/workbench-home-api.md](./docs/workbench-home-api.md)。
|
|
|
|
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` 反向代理。Mock 开关按业务模块（对齐菜单）拆分，缺省只有文档库和签署工作台使用演示数据，其余模块直接调用真实后端；各开关的环境变量名与缺省值见 `src/utils/mock-flags.ts`，需要临时切换时在本地 `.env.*.local` 里覆盖即可。使用本地开发代理时，`VITE_API_BASE_URL` 应填写 `/api`；如果改为直连后端，则需要后端配置允许当前前端源的 CORS。
|
|
|
|
当前尚未接入的签署能力包括手写板设备桥接、线上签署页面/签名回调和打印服务。签署投递、一次性 Token 消费和真实 PNG 上传 API 已完成封装，但页面不能用 Canvas 演示数据冒充真实签名；需要接入设备适配器或患者 H5 回调后再启用。短信初次发送接口需要完整手机号，而患者查询只返回脱敏手机号，因此真实模式会要求当前操作人员确认完整投递地址；生产环境也可以改为由后端根据患者 ID 解析投递地址。签署工作台缺省即使用演示数据（`VITE_MOCK_SIGNING`），需要走真实投递时把它设为 `false`。
|