关键文件索引

本页不是简单列文件名，而是说明“遇到某类问题时，优先看哪几个文件，为什么先看它们”。

启动与运行边界

app/main.py：FastAPI 实例、生命周期、中间件、安全头、SSE 上下文、/cart-import 重定向和所有路由挂载都在这里收口。
app/database.py：SQLite 引擎、WAL、外键、性能索引、FTS、schema consistency check 和默认管理员初始化都从这里进入。
frontend/src/main.tsx：前端启动时机、QueryClient、cache version bootstrap 和真正挂载 App 的入口。
frontend/src/App.tsx：前端路由树、认证守卫、懒加载页面和全局 Provider 的装配点。

认证、会话与访问边界

app/core/auth.py：CurrentUser、管理员检查、token 会话校验和 Cookie/Bearer 兼容逻辑的核心。
app/api/user_sessions.py：设备会话管理的 API 入口。
frontend/src/store/useStore.ts：bootstrapAuth()、logout()、authStatus 状态机和本地持久化策略。
frontend/src/api/client.ts：Axios 拦截器、401/403 收敛、X-SSE-Client-Id 注入和设备标识传递。
frontend/src/pages/Layout.tsx：前端导航项的权限过滤、账户入口、主题切换和退出确认。

核心业务链

app/api/reagent_orders.py：试剂订单列表、查询和基础 CRUD。
app/api/reagent_orders_workflow.py：试剂审批、到货、入库、仪表盘卡片和删除权限的核心工作流。
app/api/consumable_orders.py：耗材列表、搜索、审批、完成、导出和删除权限。
app/api/inventory.py：库存列表、借用、归还、Excel 导入、手工入库、导出等主入口。
app/api/common_shelf.py：常用货架分组、位置建议、补瓶、减瓶和删除。
app/services/internal_code.py：库存瓶级唯一编码生成器，排查入库冲突时优先看这里。
app/services/pinyin_utils.py：名称、分类、品牌、位置的拼音与首字母预计算逻辑。

数据模型与检索基线

app/models：User、UserSession、ReagentOrder、ConsumableOrder、Inventory、CommonShelf、Announcement 等数据对象定义。
app/models/inventory.py：库存事实源、借用日志和手工入库 DTO。
app/models/reagent_order.py：试剂状态枚举、订购原因和规格拆分后的字段。
app/models/consumable_order.py：耗材状态枚举和搜索相关字段。
app/services/api_utils.py：列表页短 TTL 缓存，是排查“数据改了但第一页还是旧的”时必须看的文件。

实时同步与缓存一致性

app/api/events.py：SSE 建连入口、房间白名单、会话周期复检。
app/services/sse_manager.py：本地 fan-out、Redis 跨进程广播、慢客户端断开、auth.invalid 消息构造。
app/services/sse_redis.py：Redis 发布订阅封装。
frontend/src/hooks/useSSE.ts：EventSource 连接、重连、序号断档处理和 auth invalid 事件收敛。
frontend/src/hooks/useListSSE.ts：列表级 patch / stale 策略。
frontend/src/store/sseStore.ts：客户端 SSE 运行时状态、lastSeqByRoom 和 staleRooms。

前端页面基础设施

frontend/src/components/ui/FilterTable.tsx：列表页工具栏、搜索、筛选和表格容器总入口。
frontend/src/hooks/useTableState.tsx：分页、搜索、防抖、模糊搜索、列宽和展开状态。
frontend/src/hooks/useTableUrlState.ts：URL 查询参数与表格状态同步。
frontend/src/components/BaseForm.tsx：统一表单渲染外壳。
frontend/src/lib/validationSchemas.ts：前端表单校验和 API 错误归一化。
frontend/src/hooks/useTheme.ts：主题初始化与切换逻辑。

购物车导入与扩展桥接

browser-extension/manifest.json：扩展权限、content script 注入范围和 popup 入口。
browser-extension/background/service-worker.js：目标购物车标签页解析、后台消息路由、详情页抓取辅助。
browser-extension/popup/popup.js：抓取、详情补齐、类型判断、批次保存和跳转系统页面。
browser-extension/content/import-bridge.js：把扩展批次复制到页面 localStorage 并发出 IMPORT_BATCH_READY 消息。
frontend/src/pages/CartImport.tsx：购物车导入 UI 布局。
frontend/src/pages/cartimport/cartImportControllers.ts：批次加载、草稿持久化、CAS 预警和逐条提交逻辑。

部署与运行环境

docker-compose.yml：redis、backend、frontend 三服务编排。
docker/backend/Dockerfile：后端镜像构建方式。
docker/frontend/Dockerfile：前端静态资源镜像构建方式。
docker/nginx/default.conf：统一代理 /api、/static 和前端路由回退。

按问题反查文件

登录态异常：先看 auth.py、useStore.ts、api/client.ts
到货或入库异常：先看 reagent_orders_workflow.py、inventory.py、internal_code.py
耗材列表搜索异常：先看 consumable_orders.py、database.py
页面数据旧但刷新正常：先看 api_utils.py、events.py、useListSSE.ts
扩展导入失败：先看 popup.js、import-bridge.js、cartImportControllers.ts
线上容器访问异常：先看 docker-compose.yml、default.conf、main.py

参考代码