# mindray-backend

**Repository Path**: zhWang286/mindray-backend

## Basic Information

- **Project Name**: mindray-backend
- **Description**: 本系统为医疗设备界面信息提供集中管理平台，通过层级化数据模型（分类 → 设备 → 界面 → 控件）存储设备操作流程，支持界面截图管理和交互逻辑标注。
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-12-01
- **Last Updated**: 2026-03-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Mindray Backend

医疗设备界面管理系统后端服务，提供设备信息、界面截图、交互逻辑的结构化存储与管理。

**完整文档**: [项目 Wiki](https://gitee.com/zhWang286/mindray-backend/wikis/Home)

## 项目背景

本系统为医疗设备界面信息提供集中管理平台，通过层级化数据模型（分类 → 设备 → 界面 → 控件）存储设备操作流程，支持界面截图管理和交互逻辑标注。

### 核心功能

- **设备分类管理**: 二级分类体系（总分类/子分类）
- **设备信息维护**: 设备编码、名称、状态管理（编辑中/审核中/已发布）
- **界面管理**: 界面截图存储、入口标识、层级关系
- **控件标注**: 热区坐标、跳转逻辑、交互关系
- **对象存储**: MinIO 存储设备界面截图
- **用户权限**: JWT 认证授权（规划中）

## 技术栈

### 核心框架
Python 3.12+、FastAPI 0.110+、SQLAlchemy 2.0、Pydantic 2.x

### 基础设施
MySQL 8.2、MinIO、Alembic、structlog

### 开发工具
uv、ruff、mypy

## 项目架构

```
src/
├── core/                    # 共享基础设施层
│   ├── config.py            # 配置管理
│   ├── db.py                # 数据库连接与会话管理
│   ├── exceptions.py        # 全局异常定义
│   ├── log.py               # 日志
│   ├── security.py          # 认证授权工具
│   └── minio_client.py      # 对象存储客户端
│
├── modules/                 # 业务领域模块
│   ├── devices/             # 设备管理
│   │   ├── model.py         # ORM
│   │   ├── schema.py        # DTO
│   │   ├── service.py       # 业务逻辑层
│   │   └── router.py        # API
│   └── users/               # 用户管理领域
│
└── main.py                  # 入口
```

**设计原则**: Router → Service → Model 单向依赖，禁止跨模块直接访问数据模型。

## 快速开始

### 1. 安装依赖

```bash
# 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 克隆项目
git clone git@gitee.com:zhWang286/mindray-backend.git
cd mindray-backend

# 同步依赖
uv sync
```

### 2. 配置环境

```bash
# 复制环境变量模板
cp .env.example .env.dev

# 编辑配置（数据库、MinIO 等）
vim .env.dev
```

### 3. 初始化数据库

```bash
# 执行数据库迁移
uv run alembic upgrade head
```

### 4. 启动服务

```bash
# 开发模式（热重载）
source .venv/bin/activate
uvicorn src.main:app --reload --host 0.0.0.0 --port 8154
```

### 5. 访问服务

- API 文档: http://localhost:8154/docs
- 健康检查: http://localhost:8154/health
- 配置信息: http://localhost:8154/config

## 开发规范

```bash
# 代码格式化
uv run ruff format .

# 代码检查
uv run ruff check .

# 类型检查
uv run mypy src
```

## 文档导航

- [开发指南](docs/Development.md) - 详细开发流程与规范
- [系统架构](docs/Architecture.md) - 领域模型与技术架构
- [数据库迁移](docs/Database_Migration.md) - Alembic 迁移指南
- [API 规范](docs/API_Standards.md) - RESTful API 开发标准
- [部署指南](docs/Deployment.md) - 生产环境部署