从零到上手

本页提供首次接手仓库的最短学习路径，用于建立对业务主线、代码分层、运行边界和常见改动入口的稳定认知。

第一阶段：先建立三个核心判断

先把下面三件事记牢，再开始读代码：

试剂和耗材使用不同流程。试剂订单会继续流向暂存、库存或常用货架；耗材订单在完成后结束。
Inventory 才是现货事实源。借用日志、仪表盘卡片、常用货架展示都不能替代它。
前端大量页面看似不同，实际共享同一套表格、URL 状态、SSE 和认证恢复基础设施。

如果这三件事没有先建立，后面会很容易把“订单状态”“库存状态”“前端局部 patch”混成一个概念。

第二阶段：用 30 分钟建立代码地图

按以下顺序阅读：

README.md：确认项目定位、运行方式和部署入口。
app/main.py：理解后端入口、中间件、生命周期、路由挂载和 /cart-import 重定向。
app/database.py 与 app/db_bootstrap：理解 SQLite、WAL、索引、FTS 和默认管理员初始化。
frontend/src/main.tsx 与 frontend/src/App.tsx：理解前端启动、QueryClient、路由分层和守卫。
app/models：先分清用户、试剂订单、耗材订单、库存、公告、会话、借用日志这些对象。
app/api：把对象和接口一一对上。
frontend/src/components/ui/FilterTable.tsx、frontend/src/hooks/useTableState.tsx、frontend/src/hooks/useListSSE.ts：理解列表页共性实现。

第三阶段：把业务链路走一遍

至少走通以下五条链路：

登录并刷新页面，观察登录态是否被正确恢复。
提交一条试剂订单，管理员审批，再执行到货确认。
对同一条试剂订单分别测试“直接入库”和“先暂存后补位”两条路径。
提交一条耗材订单，完成审批并标记完成。
走一遍库存借用 -> 归还链路，并观察列表是否通过 SSE 提示刷新。

若能把这五步分别对应到模型、API、页面和 SSE 事件房间，后续阅读代码时就不会只停留在文件名层面。

第四阶段：补一遍外部导入链路

这个仓库有一条容易被忽略、但很关键的外围链路：

浏览器插件 popup 抓购物车
bridge 脚本把批次桥接到 /cart-import
导入页逐条提交成标准订单

导入链路涉及以下文件：

这条链路的关键边界为“插件只负责桥接，最终仍走系统自身的订单创建规则”。

第五阶段：常见改动入口

后端入口、中间件、安全策略：app/main.py
SQLite、索引、FTS、默认管理员：app/database.py、app/db_bootstrap
试剂工作流：app/api/reagent_orders_workflow.py
耗材工作流：app/api/consumable_orders.py
库存借还与导入：app/api/inventory.py
认证与设备会话：app/core/auth.py、app/api/user_sessions.py
前端应用骨架：frontend/src/App.tsx、frontend/src/pages/Layout.tsx
列表页：frontend/src/components/ui/FilterTable.tsx、frontend/src/hooks/useTableState.tsx
状态同步：frontend/src/hooks/useSSE.ts、frontend/src/hooks/useListSSE.ts、frontend/src/store/sseStore.ts
表单和输入验证：frontend/src/components/BaseForm.tsx、frontend/src/lib/formConfigs.tsx、frontend/src/lib/validationSchemas.ts

第六阶段：第一轮实操

按以下顺序完成第一轮熟悉：

跑通本地后端与前端。
登录系统并浏览主要页面。
跟踪一遍试剂订购 -> 审批 -> 到货 -> 入库。
跟踪一遍耗材订购 -> 审批 -> 完成。
跟踪一遍库存借用 -> 归还。
跟踪浏览器插件把购物车桥接到 /cart-import 的链路。
打开两个页面标签，验证写操作后 SSE 是否让列表进入刷新或 stale 状态。

完成这些步骤后，继续阅读关键文件索引和核心导读，建立文件、职责和运行时现象之间的映射关系。

关键机制补充

useListSSE 对不影响搜索和排序语义的更新执行安全 patch；其他更新会标记 stale 并触发重拉。
public 账号在建单、导入等写入场景下受到额外限制。
/cart-import 导入页主链路逐条调用标准订单创建接口。
输入校验由前端 schema、后端 DTO 和服务端标准化共同承担。

参考代码