技术栈
总览
当前技术选型围绕四个目标展开：
- 用 SQLite 支撑中小规模实验室业务，并保持可接受的检索能力。
- 用 React + Vite 提供高密度业务界面。
- 用 Redis 增强会话、限流和 SSE，同时允许降级。
- 用浏览器扩展对接外部采购平台。
后端
FastAPI
- 用途：提供 REST API、SSE、静态资源和运行时中间件。
- 落点：app/main.py
SQLModel + SQLAlchemy
- 用途：定义模型、DTO 和 SQLite 映射。
- 落点：
app/models/*.py
SQLite
- 用途：主数据库。
- 落点：app/database.py
- 关键配置：
WAL、foreign_keys=ON、复合索引、FTS5 虚拟表和触发器。
JWT + python-jose
- 用途：登录认证。
- 落点：
app/core/auth.py - 模式：浏览器使用 HttpOnly Cookie，脚本或调试工具可使用 Bearer Token。
Redis
- 用途：会话缓存、登录限流和 SSE pub/sub。
- 落点：
app/core/redis.py、app/services/sse_redis.py - 特点：具备降级能力，不可用时部分功能仍可继续。
Ruff
- 用途：后端 lint。
- 验证命令：
ruff check app/
前端
React 19
- 用途：页面和组件开发。
- 落点：
frontend/src/
TypeScript 5.9
- 用途：前端类型系统。
Vite 7
- 用途：前端构建与开发服务器。
- 落点：
frontend/
React Router DOM 7
- 用途：页面路由。
- 落点：
frontend/src/App.tsx
Zustand
- 用途：认证状态、UI 状态和 SSE 状态。
- 落点：
frontend/src/store/
TanStack Table 8 + React Virtual
- 用途：高密度列表和虚拟滚动。
- 落点：
frontend/src/components/ui/DataTable.tsx、frontend/src/hooks/useTableState.tsx
React Hook Form + Valibot
- 用途：表单状态管理与输入校验。
- 落点：
frontend/src/lib/validationSchemas.ts、frontend/src/lib/formConfigs.tsx
Tailwind CSS 4 + Radix UI
- 用途：样式系统和基础无障碍组件。
- 落点：
frontend/src/components/ui/
实时通信与外围能力
SSE
- 用途：库存、订单和仪表盘的局部更新。
- 后端：
app/api/events.py、app/services/sse_manager.py - 前端：
frontend/src/hooks/useSSE.ts、frontend/src/hooks/useListSSE.ts
浏览器扩展
- 用途：采集外部购物车并导入系统。
- 落点：
browser-extension/ - 关键桥接路径：
/cart-import、/api/cart-sync、/api/cart-sync/import
文档与部署
VitePress
- 用途：当前 wiki。
- 落点：
wiki/
Docker + Nginx
- 用途：部署后端、前端、Redis 和统一入口。
- 落点：
docker/、docker-compose.yml
技术选型之间的关系
开发时最常接触的工具链
| 场景 | 工具 |
|---|---|
| 后端 lint | ruff check app/ |
| 前端 lint | cd frontend && npm run lint |
| wiki 本地开发 | cd wiki && npm run dev |
| wiki 构建 | cd wiki && npm run build |
| 后端启动 | python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000 |
| 前端启动 | cd frontend && npm run dev |
继续看哪一页
- 想看代码目录怎么分：去 目录结构
- 想看接口怎么组织：去 API 边界与导航
- 想看后端职责：去 后端服务地图
- 想看前端基础设施：去 前端 Hooks 和 前端 Lib 工具箱
- 想看数据库实体：去 数据模型 和 字段参考