# AI近视防控系统 - 开发指南

## 项目概述

AI近视防控系统是一套用于监测、分析和预防青少年近视发展的智能平台。通过眼动追踪、视力检测算法和智能训练内容，帮助学校和家庭及时发现并干预近视发展。

## 技术栈

- **后端**: Go 1.21+
- **Web框架**: Gin
- **数据库**: MySQL 8.0
- **缓存**: Redis 7.x
- **文档**: Swagger
- **容器化**: Docker
- **编排**: Kubernetes

## 项目结构

```
ai-myopia-prevention/
├── api/                 # API定义和处理器
│   ├── handlers/        # 请求处理器
│   ├── services/        # 业务服务
│   ├── router/          # 路由定义
│   └── middleware/      # 中间件
├── db/                  # 数据库相关
│   ├── models/          # 数据模型
│   ├── migrations/      # 迁移脚本
│   └── seeders/         # 数据填充
├── internal/            # 内部业务逻辑
│   ├── config/          # 配置管理
│   ├── utils/           # 工具函数
│   └── constants/       # 常量定义
├── cmd/                 # 主程序入口
├── docs/                # 文档
├── tests/               # 测试代码
├── scripts/             # 脚本文件
├── deploy/              # 部署配置
├── static/              # 静态文件
├── uploads/             # 上传文件
├── go.mod
├── go.sum
├── Makefile
├── Dockerfile
├── .env.example
├── README.md
└── DEVELOPMENT.md
```

## 开发环境搭建

### 1. 环境要求

- Go 1.21+
- MySQL 8.0+
- Redis 7.0+
- Docker
- Git

### 2. 项目初始化

```bash
# 克隆项目
git clone <repository-url>
cd ai-myopia-prevention

# 安装依赖
go mod tidy

# 复制环境配置文件
cp .env.example .env
# 编辑 .env 文件，配置数据库连接等信息
```

### 3. 数据库配置

创建数据库并执行初始化脚本：

```bash
# 创建数据库
mysql -u root -p -e "CREATE DATABASE IF NOT EXISTS myopia_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

# 执行初始化脚本
mysql -u root -p myopia_db < scripts/init_db.sql
```

### 4. 启动开发服务器

```bash
# 使用Makefile启动
make run

# 或直接运行
go run cmd/main.go

# 服务器将启动在 http://localhost:8080
```

## API文档

API文档可通过以下方式访问：

- 在线文档: http://localhost:8080/swagger/index.html
- 详细API文档: docs/api_documentation.md

## 代码规范

### 1. Go代码规范

- 使用 `gofmt` 格式化代码
- 遵循Go语言命名约定
- 为导出的函数和类型编写文档注释

### 2. Git提交规范

- 使用语义化提交信息
- 遵循约定式提交规范

## 测试

### 单元测试

```bash
# 运行所有测试
make test

# 运行特定包的测试
go test -v ./api/handlers/...

# 查看测试覆盖率
make coverage
```

## 部署

### 1. Docker部署

```bash
# 构建Docker镜像
make docker-build

# 运行Docker容器
make docker-run
```

### 2. Kubernetes部署

```bash
# 应用部署配置
kubectl apply -f deploy/deployment.yaml
```

## 架构说明

### 微服务架构

系统采用微服务架构，主要包括以下服务：

1. **用户服务** - 用户认证和权限管理
2. **检测服务** - 视力检测和数据收集
3. **预警服务** - 预警规则和通知
4. **训练服务** - 训练内容和任务管理
5. **报表服务** - 数据报表和分析
6. **设备服务** - 设备管理和通信
7. **AI服务** - AI算法推理

### 数据库设计

- 使用GORM进行数据库操作
- 遵循数据库设计规范
- 实现数据完整性约束

## 安全考虑

- 使用JWT进行身份验证
- 实现API速率限制
- 输入数据验证和清理
- SQL注入防护

## 性能优化

- 数据库查询优化
- 缓存策略
- 连接池配置
- 静态资源压缩

## 监控和日志

- 结构化日志记录
- 性能监控指标
- 错误追踪

## 贡献指南

1. Fork项目
2. 创建功能分支
3. 提交更改
4. 发起Pull Request

## 常见问题

### 数据库连接问题

确保数据库服务正在运行，并且连接参数正确配置。

### 端口冲突

如果端口8080已被占用，可在.env文件中修改SERVER_PORT。

---

*启明计划 - 让每个孩子都拥有明亮的未来*