关键文件索引

本页按问题类型整理优先阅读文件，并说明文件排序依据。

启动与运行边界

• app/main.py：FastAPI 实例、生命周期、中间件、安全头、SSE 上下文、/cart-import 重定向和所有路由挂载都在这里收口。
• app/database.py：SQLite 引擎、WAL、外键和初始化编排入口。
• app/db_bootstrap：schema 补齐、结构绑定回填、性能索引、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/reagent_brands.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/api/chem.py 与 app/services/structure_index.py：结构缓存、PubChem 解析和子结构检索入口。
• app/api/procedure_inventory_search.py 与 app/services/procedure_inventory_search.py：实验步骤提取、CAS 解析、候选确认和库存匹配的编排入口。
• app/services/llm_usage_logger.py 与 app/models/llm_usage_log.py：LLM 调用用量元数据的写入逻辑与数据模型。

数据模型与检索基线

• 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/search_completions.py、app/search_completion_db.py、app/services/search_completion_entity_index.py 与 app/services/search_completion_ranker.py：搜索补全建议的 API、SQLite 表、实体索引和排序入口。

实时同步与缓存一致性

• 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/useInlineSearchCompletion.ts：列表搜索补全建议的前端请求、缓存和反馈 Hook。
• frontend/src/hooks/useTableState.tsx：分页、搜索、防抖、模糊搜索、列宽和展开状态。
• frontend/src/hooks/useTableUrlState.ts：URL 查询参数与表格状态同步。
• frontend/src/components/BaseForm.tsx：统一表单渲染外壳。
• frontend/src/lib/validationSchemas.ts：前端表单校验和 API 错误归一化。
• frontend/src/lib/reagentBrandOptions.ts：试剂品牌选项的查询配置和转换。
• frontend/src/lib/staticAssets.ts：RDKit 和本地字体的版本化资源路径。
• frontend/src/hooks/useTheme.ts：主题初始化与切换逻辑。
• frontend/src/components/ProcedureInventorySearchButton.tsx 与 frontend/src/components/ProcedureInventoryAnalysisPanel.tsx：库存页的实验步骤输入、解析确认与结果展示。
• frontend/src/lib/storage/procedureInventorySearchStorage.ts：用户绑定的临时结果与 10 分钟有效期管理。

购物车导入与浏览器插件桥接

• browser-extension/build-config.mjs：根据插件 env 生成 manifest 和运行配置。
• 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 预警和逐条提交逻辑。

CLI、Agent skill、MCP 与企业微信入口

• lsm_cli：本地命令行客户端，所有命令输出 JSON，并通过后端 API 工作。
• Agent skill：复用 python -m lsm_cli 或安装后的 lsm 命令，不直接访问数据库或后端内部模块。
• lsm_mcp/http_app.py：MCP Streamable HTTP 入口。
• lsm_mcp/cli_runner.py：MCP 到 CLI 子进程的执行边界，会注入仓库根目录到 PYTHONPATH。
• robot/wecom_aibot：企业微信智能机器人实现。
• robot/wechat_kf：微信客服入口。

部署与运行环境

• docker-compose.yml：redis、backend、frontend 三服务编排。
• docker/backend/Dockerfile：后端镜像构建方式。
• docker/frontend/Dockerfile：前端静态资源镜像构建方式。
• docker/nginx/default.conf：统一代理 /api、/static 和前端路由回退。
• scripts/release_version.py 与 scripts/bump-version.ps1：统一设置并校验应用版本。

按问题反查文件

• 登录态异常：先看 auth.py、useStore.ts、api/client.ts
• 到货或入库异常：先看 reagent_orders_workflow.py、inventory.py、internal_code.py
• 品牌选项异常：先看 reagent_brands.py、reagent_brand_service.py、reagentBrandOptions.ts
• 耗材列表搜索异常：先看 consumable_orders.py、sqlite_fts.py、sqlite_indexes.py
• 搜索建议异常：先看 search_completions.py、search_completion_entity_index.py、search_completion_ranker.py、useInlineSearchCompletion.ts
• 结构检索异常：先看 chem.py、structure_cache_workflow.py、structure_index.py
• 实验步骤查库存异常：先看 procedure_inventory_search.py、procedure_llm_extractor.py、procedure_pubchem_name.py、ProcedureInventoryAnalysisPanel.tsx
• 页面数据旧但刷新正常：先看 api_utils.py、events.py、useListSSE.ts
• 浏览器插件导入失败：先看 popup.js、import-bridge.js、cartImportControllers.ts
• 线上容器访问异常：先看 docker-compose.yml、default.conf、main.py
• 发布标签版本不一致：先看 release_version.py、bump-version.ps1 和各应用版本文件

参考代码

• app/api/common_shelf.py
• app/api/consumable_orders.py
• app/api/events.py
• app/api/inventory.py
• app/api/procedure_inventory_search.py
• app/api/reagent_brands.py
• app/api/reagent_orders.py
• app/api/reagent_orders_workflow.py
• app/api/user_sessions.py
• app/core/auth.py
• app/database.py
• app/db_bootstrap
• app/api/chem.py
• app/main.py
• app/services/api_utils.py
• app/api/search_completions.py
• app/search_completion_db.py
• app/services/search_completion_entity_index.py
• app/services/search_completion_ranker.py
• app/services/internal_code.py
• app/services/pinyin_utils.py
• app/services/procedure_inventory_search.py
• app/services/sse_manager.py
• browser-extension/background/service-worker.js
• browser-extension/content/import-bridge.js
• browser-extension/build-config.mjs
• browser-extension/popup/popup.js
• docker-compose.yml
• docker/nginx/default.conf
• frontend/src/api/client.ts
• frontend/src/App.tsx
• frontend/src/components/BaseForm.tsx
• frontend/src/components/ui/FilterTable.tsx
• frontend/src/hooks/useListSSE.ts
• frontend/src/hooks/useInlineSearchCompletion.ts
• frontend/src/hooks/useTableState.tsx
• frontend/src/hooks/useTableUrlState.ts
• frontend/src/lib/reagentBrandOptions.ts
• frontend/src/lib/staticAssets.ts
• frontend/src/pages/cartimport/cartImportControllers.ts
• frontend/src/store/sseStore.ts