临床标本库自动化端到端交付
# 临床标本库自动化：端到端交付实践
一套连接既有业务系统、三类自动化设备与物理样本操作的内网业务系统。项目从现场需求、业务建模推进到前后端、数据、上下游适配、验证、交付与知识沉淀。
- 项目窗口：2026-07-21—2026-08-24
- 投入方式：约一个月内兼职推进，约投入一半个人可用时间
- 交付形态：Vue 3 + FastAPI + SQLite，Windows 内网解压运行
- 工作方式：AI 扩大实现和复核带宽，人负责业务判断、风险授权与现场核对
# 项目背景
临床标本入库会同时改变三类事实：既有业务系统中的记录、本地系统中的样本与物理管码关系、自动化设备中的真实位置。现场人员还需要执行取放、扫码、核对和异常处理。
核心工作不是单独做一个页面或接口，而是把这些状态组织成一条能够执行、恢复、追溯和交接的闭环。个人责任范围覆盖：
现场观察 → 需求与流程建模 → 交互设计 → 前端 / 后端 / 数据 → 上下游适配 → Mock 与契约 → 自动回归 → 现场联调 → Windows 交付 → Wiki / changelog / 操作指南
# 系统边界
既有业务系统
│ 授权会话 + HTTP 接口
▼
本地业务系统（Vue / FastAPI / SQLite）
├─ 喷码：任务、审批与导出
├─ 整板扫描：消息队列单次问答
└─ 自动化冰箱：消息队列长任务事件
│
▼
试管 / 冻存盒 / 物理位置 / 现场人员操作
2
3
4
5
6
7
8
9
10
开发过程中，上下游经常无法同时就绪，因此使用 Mock、真实报文样本和分层验收持续推进。离线回归只能证明本地逻辑和契约，不能替代真实设备或完整组合流程的现场验收。
# 三层事实与职责
# 既有业务系统：上游身份与业务数据
上游提供项目、样本状态与历史流水。适配层保留原始载荷并归一字段，使后续流程接收统一契约。上游没有提供的事实保持未知，不根据相邻数据补齐。
# 本地系统：绑定与过程事实
本地系统负责样本实例与物理管码绑定、业务动作、逐管任务快照、设备事件、操作日志和回传记录。出现错绑、歧义或无法安全关联的事件时，流程进入核对，不覆盖已经形成的物理事实。
# 自动化设备：物理执行事实
设备掌握真实执行状态和位置。本地系统只有在接收到合法成功终态及可解析的实际结果后，才投影当前库存。计划位置代表意图，不代表设备已经完成操作。
# 代表性设计
# 设备长任务与断线恢复
自动化冰箱任务可能持续 10—30 分钟。流程不使用浏览器状态或固定业务超时推断失败，而是等待设备终态。稳定触发键覆盖重复终态、页面刷新、并发请求和进程重启，避免重复下发。
# 失败可见与受控恢复
设备显示空位但实际下发被拒绝时，系统保留原任务、原位置和设备原因。现场人员可以在同一业务分区内选择另一个合法位置重新下发；新位置仍需新的设备成功终态确认。
# 多个上游入口归一
不同查询入口覆盖的样本状态不同。系统先通过适配层归一为同一份样本契约，后续喷码、扫描、绑定、设备任务和回传不按数据来源复制业务逻辑。
# AI Coding 如何参与
AI 用于检索 Wiki、代码、日志和现场记录，恢复项目上下文；展开实体、状态、接口和异常方案；覆盖前后端、测试、工具与文档细节；执行批量回归、静态审计和差异检查。
人负责判断证据可信度，决定业务边界与优先级，控制变更粒度，授权真实写操作，并核对设备与实物。AI 提升的是从问题到修正再到证据沉淀的周转速度，不替代现场事实和风险判断。
# 证据矩阵
| 结果 | 当前证据 | 边界 |
|---|---|---|
| 扫码器四个接口、95 管真实回包、发现六个协议漏写字段 | 现场实测 | 只证明扫码器链路 |
| 自动化冰箱长任务、设备终态与实际位置处理 | 现场记录 + 当前实现 | 最新组合流程需要按版本逐项复验 |
| 后端 1051 passed，7 skipped | 2026-08-24 离线快照 | 不代替外部系统或设备验收 |
| 前端 92 passed，Vite 生产构建成功 | 2026-08-24 离线快照 | 不代表物理执行成功 |
| 五条只读数据库副本业务旅程 | 2026-08-22 离线快照 | 是历史快照，不代表持续线上状态 |
| 喷码任务、审批、导出和适配代码 | 已实现 | 现场设备连接与最终字段协议仍待验收 |
# 当前边界
现有证据可以证明项目责任范围、系统复杂度、部分现场协议结果和离线质量保护。长期服务等级、固定人效倍数、投资回报、现场节省时间和错误率变化均缺少对照数据，不做数字推断。
本页不使用现场图片，不公开机构名称、个人数据、账号凭证、内部网络信息或本地数据库。