# 血细胞智能识别分析系统

**Repository Path**: elfbobo_admin_admin/blood-cell-analyzer

## Basic Information

- **Project Name**: 血细胞智能识别分析系统
- **Description**: 本系统是面向专业化验场景的临床辅助诊断平台。采用“本地边缘计算 + 云端大模型”协同架构：前端基于 Electron、React 与 TypeScript 构建高性能交互界面；后端通过 FastAPI 部署 YOLO (ONNX) 模型实现毫秒级细胞检测与计数；针对复杂病理，集成云端多模态大模型生成辅助分析报告。系统旨在为医疗工作者提供专业、高效、智能的数字化化验工具。
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-04-22
- **Last Updated**: 2026-04-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 血细胞智能识别分析系统

血细胞智能识别分析系统是一个面向检验场景的桌面应用与后端服务一体化项目，当前阶段提供：

- Electron + React + TypeScript 的桌面端骨架与联调页面
- FastAPI 后端（含认证、健康检查、检测/crop stub 接口）
- MySQL + SQLAlchemy 数据层
- Celery + Redis 异步任务链路（`enqueue-detect`）
- OpenAPI 契约作为前后端协作单一事实来源（SSOT）

## API 契约（团队 SSOT）

- 人类可读说明：[`docs/api/README.md`](docs/api/README.md)
- OpenAPI 规范：[`docs/api/openapi.yaml`](docs/api/openapi.yaml)
- 约定说明：[`docs/api/conventions.md`](docs/api/conventions.md)

> 联调与 Mock 以 `docs/api/openapi.yaml` 为准。运行时 `openapi.json` 仅用于对照检查。

## 技术栈

- 桌面端：Electron、React 18、TypeScript、Vite
- 后端：FastAPI、Pydantic、SQLAlchemy
- 认证：JWT（`/api/auth/register`、`/api/auth/login`、`/api/auth/me`）
- 异步任务：Celery、Redis
- 数据库：MySQL 8
- 测试与质量：Pytest、Ruff

## 项目结构

```text
blood-cell-analyzer/
├─ backend/                # FastAPI + SQLAlchemy + Celery
├─ desktop/                # Electron + React 桌面端
├─ docs/
│  ├─ api/                 # OpenAPI 契约与接口约定
│  └─ plan/                # 需求/计划文档
├─ docker/
│  └─ mysql-init/          # MySQL 初始化脚本
├─ scripts/                # Windows PowerShell 启动脚本
├─ docker-compose.yml
└─ README.md
```

## 环境要求

- Windows 10/11（已提供 PowerShell 启动脚本）
- Python 3.10+
- Node.js 18+
- MySQL 8（本地模式）
- Redis 7（本地模式）
- Docker Desktop（可选，推荐用于快速联调）

## 快速开始

### 方式一：推荐（Docker 一键联调）

在仓库根目录执行：

```powershell
docker compose up --build
```

默认会启动：

- `mysql`（3306）
- `redis`（6379）
- `backend`（8000）
- `worker`（Celery）

接口文档与健康检查：

- [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs)
- [http://127.0.0.1:8000/api/health](http://127.0.0.1:8000/api/health)

### 方式二：本地开发（不使用 Docker）

#### 1) 启动后端 API

```powershell
.\scripts\start-backend.ps1 -UseDocker false -BindHost 127.0.0.1 -Port 8000
```

脚本会自动：

- 创建 `backend/.venv`
- 安装 `backend/requirements.txt`
- 启动 `uvicorn app.main:app --reload`

#### 2) 启动 Celery Worker

```powershell
.\scripts\start-worker.ps1 -UseDocker false -Pool solo -LogLevel info
```

> Windows 开发环境建议 `-Pool solo`，可避免 prefork 在部分环境下的权限问题。

#### 3) 启动桌面端（Electron + Vite）

首次安装依赖：

```powershell
cd .\desktop
npm install
```

然后回到仓库根目录执行：

```powershell
.\scripts\start-desktop.ps1 -ApiBaseUrl http://127.0.0.1:8000
```

## 环境变量

后端默认从 `backend/.env` 读取配置，可基于示例文件初始化：

```powershell
copy .\backend\.env.example .\backend\.env
```

关键配置项：

- `API_HOST` / `API_PORT`
- `DATABASE_URL`
- `CELERY_BROKER_URL` / `CELERY_RESULT_BACKEND`
- `JWT_SECRET_KEY` / `JWT_ALGORITHM` / `JWT_EXPIRE_MINUTES`

## 当前已实现的核心接口

- 健康检查：`GET /api/health`
- 检测（stub）：`POST /api/detect`
- 细胞裁剪（stub）：`POST /api/crop-cells`
- 模型信息：`GET /api/model/info`
- 异步任务入队：`POST /api/tasks/enqueue-detect`
- 认证注册/登录/用户信息：
  - `POST /api/auth/register`
  - `POST /api/auth/login`
  - `GET /api/auth/me`

## 测试与代码质量

在 `backend/` 下执行：

```powershell
.\.venv\Scripts\python -m pytest
.\.venv\Scripts\python -m ruff check app tests
```

现有测试覆盖健康检查与检测接口契约（stub 场景）。

## 常见问题

- 数据库连接失败：确认 MySQL 已启动，且 `DATABASE_URL` 中数据库与账号已创建
- Worker 无法入队：确认 Redis 已启动，并检查 `CELERY_BROKER_URL`
- 桌面端白屏：确认 Vite 已在 `5173` 启动，且后端地址与 `-ApiBaseUrl` 一致

## 参与贡献

1. Fork 本仓库
2. 新建功能分支（如 `feat/xxx`）
3. 提交代码并补充必要测试
4. 发起 Pull Request

---

英文说明见：[`README.en.md`](README.en.md)