# 实现方案 - 2026-04-29-21-51-19

## 对应需求
- 需求分析文档: `需求分析-2026-04-29-21-51-19.md`

## 方案概述
在 RTX 4090 + Ubuntu 22.04 环境下，将纯前端 React 应用改造为全栈语义分割系统。本次为**骨架搭建 + 核心能力落地**，优先保证各模块可独立运行并互联互通。

## 整体架构

```
┌─────────────────────────────────────────────────────────────────┐
│                        前端层 (React 19)                         │
│  Zustand (状态)  +  Axios (HTTP)  +  WebSocket (实时进度)        │
│  Konva (Canvas)  +  TailwindCSS (样式)                           │
└────────────────────────────┬────────────────────────────────────┘
                             │ HTTP / WebSocket
┌────────────────────────────▼────────────────────────────────────┐
│                    后端层 (FastAPI + Python)                     │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐               │
│  │ 项目/模板 API │ │ 媒体解析 API │ │ AI 推理 API  │               │
│  └──────┬──────┘ └──────┬──────┘ └──────┬──────┘               │
│         └─────────────────┼─────────────────┘                   │
│                           │ SQLAlchemy                          │
│  ┌────────────────────────▼────────────────────────┐           │
│  │           PostgreSQL (关系数据)                  │           │
│  └─────────────────────────────────────────────────┘           │
│                           │                                    │
│  ┌────────────────────────▼────────────────────────┐           │
│  │           MinIO (对象存储: 视频/帧/Mask)         │           │
│  └─────────────────────────────────────────────────┘           │
│                           │                                    │
│  ┌────────────────────────▼────────────────────────┐           │
│  │           Redis (缓存 + 任务队列)                │           │
│  └─────────────────────────────────────────────────┘           │
│                           │                                    │
│  ┌────────────────────────▼────────────────────────┐           │
│  │           SAM 3 (GPU 推理节点)                   │           │
│  └─────────────────────────────────────────────────┘           │
└─────────────────────────────────────────────────────────────────┘
```

## 修改/新增文件清单

### A. 基础设施层

#### A1. 系统服务安装
- **操作**: `sudo apt install postgresql postgresql-contrib redis-server ffmpeg`
- **操作**: 下载并启动 MinIO 二进制
- **说明**: 配置 PostgreSQL 数据库/用户，Redis 默认端口，MinIO 端口 9000/9001

#### A2. Conda 环境
- **操作**: `conda create -n seg_server python=3.11`
- **操作**: 安装 PyTorch 2.5+ CUDA 13.x、FastAPI、SQLAlchemy、psycopg2-binary、redis-py、minio、uvicorn、python-multipart、celery、opencv-python、pillow、scikit-image、pydicom、numpy

### B. 后端层 (新增 backend/ 目录)

#### B1. `backend/main.py`
- **类型**: 新增
- **内容**: FastAPI 入口，CORS 配置， lifespan 管理（启动/关闭数据库、Redis、MinIO 连接）

#### B2. `backend/config.py`
- **类型**: 新增
- **内容**: 环境变量配置（DB_URL、REDIS_URL、MINIO_ENDPOINT、SAM_MODEL_PATH 等）

#### B3. `backend/database.py`
- **类型**: 新增
- **内容**: SQLAlchemy engine + session + Base，PostgreSQL 连接

#### B4. `backend/models.py`
- **类型**: 新增
- **内容**: 数据库 ORM 模型：Project、Frame、Annotation、Template、Mask

#### B5. `backend/schemas.py`
- **类型**: 新增
- **内容**: Pydantic 数据校验模型

#### B6. `backend/minio_client.py`
- **类型**: 新增
- **内容**: MinIO 客户端封装（上传、下载、预签名 URL）

#### B7. `backend/redis_client.py`
- **类型**: 新增
- **内容**: Redis 客户端封装

#### B8. `backend/routers/projects.py`
- **类型**: 新增
- **内容**: 项目 CRUD API

#### B9. `backend/routers/templates.py`
- **类型**: 新增
- **内容**: 本体模板 API

#### B10. `backend/routers/media.py`
- **类型**: 新增
- **内容**: 视频/图片/DCM 上传 API，FFmpeg 拆帧任务触发

#### B11. `backend/routers/ai.py`
- **类型**: 新增
- **内容**: SAM 3 推理 API（point/box/semantic），Mask 生成与存储

#### B12. `backend/routers/export.py`
- **类型**: 新增
- **内容**: 标注数据导出（COCO JSON、PNG Mask）

#### B13. `backend/services/sam3_engine.py`
- **类型**: 新增
- **内容**: SAM 3 模型加载、推理封装、GPU 内存管理

#### B14. `backend/services/frame_parser.py`
- **类型**: 新增
- **内容**: FFmpeg 视频拆帧、DCM 影像逐帧提取、帧上传 MinIO

#### B15. `backend/services/task_queue.py`
- **类型**: 新增
- **内容**: Celery + Redis 异步任务队列封装

#### B16. `backend/requirements.txt`
- **类型**: 新增
- **内容**: Python 依赖清单

### C. 前端层 (修改现有 src/)

#### C1. `src/store/index.ts` (新增)
- **内容**: Zustand 全局 Store（project、workspace、annotations、ui 状态）

#### C2. `src/lib/api.ts` (新增)
- **内容**: Axios 实例封装，baseURL 指向 FastAPI

#### C3. `src/lib/websocket.ts` (新增)
- **内容**: WebSocket 客户端，接收解析进度

#### C4. `src/App.tsx` (修改)
- **内容**: 移除 Login 硬编码，接入真实登录 API；Provider 包裹

#### C5. `src/components/ProjectLibrary.tsx` (修改)
- **内容**: 从后端 API 加载项目列表，支持创建/删除

#### C6. `src/components/TemplateRegistry.tsx` (修改)
- **内容**: 从后端 API 加载本体字典，支持动态增删

#### C7. `src/components/CanvasArea.tsx` (修改)
- **内容**: 点击画布捕获坐标，发送至后端 AI 接口，接收并渲染 Mask Path

#### C8. `src/components/AISegmentation.tsx` (修改)
- **内容**: 对接后端 SAM 3 推理接口，显示推理状态

#### C9. `src/components/Dashboard.tsx` (修改)
- **内容**: 显示真实解析队列进度（WebSocket）

### D. 部署与运维

#### D1. `start_services.sh` (新增)
- **内容**: 一键启动 PostgreSQL、Redis、MinIO、FastAPI 的脚本

#### D2. `backend/download_sam3.py` (新增)
- **内容**: SAM 3 模型权重自动下载脚本

## 新增依赖

### Python (conda 环境)
```
fastapi uvicorn[standard] python-multipart
sqlalchemy psycopg2-binary alembic
redis celery
minio
opencv-python pillow scikit-image pydicom numpy
```

### 前端 (npm)
```
zustand axios
```

## 兼容性分析
- Express `server.ts` 将被保留但不再作为默认启动方式，FastAPI 成为主后端
- 前端路由逻辑不变，仅数据获取方式从内存/mock 改为 HTTP API
- 回滚策略: 回退到 `npm start` 仍可运行旧版 Express 前端

## 预估工作量
- 基础设施: 20 分钟
- 后端骨架: 40 分钟
- 前端改造: 30 分钟
- SAM 3 部署: 20 分钟
- 联调验证: 20 分钟