dashboard/backend/LAB_DATA_UPDATE_GUIDE.md

# 工程研究中心数据更新指南

## 概述

本文档详细说明如何将 `src/assets/实验室.json` 中的工程研究中心数据导入到数据库中。当有新的工程研究中心数据或者数据需要更新时，请按照本指南进行操作。

## 文件说明

### 主要文件
- **数据源文件**: `src/assets/实验室.json` - 包含所有工程研究中心的多年度数据
- **导入脚本**: `backend/import_lab_data_full.py` - 完整的数据导入脚本
- **JSON修复脚本**: `backend/fix_json_format.py` - 修复JSON格式问题
- **数据类型修复脚本**: `backend/fix_year_data_types.py` - 修复年份字段类型问题
- **数据检查脚本**: `backend/check_specific_lab.py` - 检查特定工程研究中心数据
- **数据库模型**: `backend/models.py` - 定义Lab表结构
- **本文档**: `backend/LAB_DATA_UPDATE_GUIDE.md` - 操作指南

### 数据结构
JSON文件包含工程研究中心数组，每个工程研究中心包含：
```json
{
  "中心名称": "工程研究中心名称",
  "中心编号": "工程研究中心编号", 
  "年度数据": [
    {
      "归属年份": "2024",
      "所属学校": "学校名称",
      "主管部门": "部门名称",
      ... // 详细的年度数据
    }
  ]
}
```

## 数据库字段映射

### 基本信息字段
| JSON字段 | 数据库字段 | 类型 | 说明 |
|---------|-----------|------|------|
| 中心名称 | name | String | 工程研究中心名称 |
| 中心编号 | center_number | String | 工程研究中心编号 |
| 所属学校 | school | String | 所属学校 |
| 主管部门 | department | String | 主管部门 |
| 所属领域 | field | String | 所属领域 |
| 归属年份 | current_year | String | 当前评估年份 |

### 详细信息字段
| JSON字段 | 数据库字段 | 类型 | 说明 |
|---------|-----------|------|------|
| 技术攻关与创新情况 | innovation_situation | Text | 技术创新描述 |
| 1.总体情况 | overall_situation | Text | 总体情况描述 |
| 2.工程化案例 | engineering_cases | Text | 工程化案例 |
| 3.行业服务情况 | industry_service | Text | 行业服务情况 |
| 1.学科发展支撑情况 | discipline_support | Text | 学科发展支撑 |
| 2.人才培养情况 | talent_cultivation | Text | 人才培养情况 |
| 3.研究队伍建设情况 | team_building | Text | 队伍建设情况 |

### 统计数据字段
| JSON字段 | 数据库字段 | 类型 | 说明 |
|---------|-----------|------|------|
| 国家级科技奖励一等奖(项) | national_awards_first | Integer | 国家一等奖数量 |
| 国家级科技奖励二等奖(项) | national_awards_second | Integer | 国家二等奖数量 |
| 省、部级科技奖励一等奖(项) | provincial_awards_first | Integer | 省部一等奖数量 |
| 省、部级科技奖励二等奖(项) | provincial_awards_second | Integer | 省部二等奖数量 |
| 有效专利(项) | valid_patents | Integer | 有效专利数量 |
| 在读博士生 | doctoral_students | Integer | 博士生数量 |
| 在读硕士生 | master_students | Integer | 硕士生数量 |
| 固定人员(人) | fixed_personnel | Integer | 固定人员数量 |
| 流动人员(人) | mobile_personnel | Integer | 流动人员数量 |
| 当年项目到账总经费(万元) | total_funding | Float | 总经费 |

### 特殊字段
| 字段 | 说明 |
|-----|------|
| annual_data | JSON格式存储所有年度数据，包含多年完整信息 |
| id | 自动生成的UUID，作为主键 |
| idcode | 使用中心编号作为显示ID |

## 操作步骤

### 1. 准备工作

确保以下条件满足：
- [x] 后端服务已停止运行
- [x] 数据库文件 `backend/data/app.db` 存在
- [x] Python环境已激活 (`conda activate fast-dashboard-env`)
- [x] JSON数据文件 `src/assets/实验室.json` 已更新

### 2. 环境准备

在命令行中执行：
```powershell
# 激活conda环境
conda activate fast-dashboard-env

# 进入后端目录
cd backend
```

### 3. 执行数据导入

运行导入脚本：
```powershell
python import_lab_data_full.py
```

### 4. 导入过程说明

脚本会执行以下操作：

1. **数据验证**：检查JSON文件是否存在
2. **数据读取**：解析JSON文件内容
3. **数据处理**：
   - 遍历每个工程研究中心
   - 检查是否已存在（根据中心编号或名称）
   - 如果存在则更新，否则创建新记录
   - 处理多年度数据，提取最新年份作为当前数据
   - 安全转换数据类型（整数、浮点数、字符串）
4. **数据库操作**：
   - 添加新记录或更新现有记录
   - 提交事务
   - 显示统计信息

### 5. 输出信息解读

脚本运行时会显示：
- 📖 正在读取数据文件
- ✅ 成功读取数据，共 X 个工程研究中心
- 🔄 正在处理工程研究中心: XXX (编号: XXX)
- ➕ 创建新工程研究中心 / 📝 工程研究中心已存在，更新数据
- ✅ 年度数据: X 年, 最新年份: XXXX
- 💾 正在保存到数据库
- 📊 统计信息

### 6. 验证导入结果

导入完成后，可以通过以下方式验证：

1. **启动后端服务**：
   ```powershell
   uvicorn main:app --reload
   ```

2. **访问API接口**：
   ```
   GET http://localhost:8000/labs/
   ```

3. **查看前端页面**：
   打开前端应用，查看工程研究中心列表和详情页

## 常见问题及解决方案

### 1. JSON格式错误
**问题**: JSON文件中包含Python的`None`值，导致解析失败
**解决方案**: 
```bash
python fix_json_format.py
```

### 2. 年份字段类型错误
**问题**: 前端报错 `TypeError: b.year.localeCompare is not a function`
**原因**: 年度数据中的`归属年份`字段是数字类型，前端期望字符串类型
**解决方案**:
```bash
python fix_year_data_types.py
```

### 3. 检查特定工程研究中心数据
**用途**: 当某个工程研究中心出现问题时，可以单独检查其数据格式
**使用方法**:
```bash
python check_specific_lab.py
```
修改脚本中的工程研究中心名称来检查不同工程研究中心。

## 故障排除

### 常见错误及解决方案

#### 1. 文件不存在错误
```
❌ 错误：找不到数据文件
```
**解决方案**：确认 `src/assets/实验室.json` 文件存在且路径正确

#### 2. 数据库连接错误
```
❌ 数据库操作失败
```
**解决方案**：
- 确认数据库文件 `backend/data/app.db` 存在
- 确认没有其他进程占用数据库
- 确认有足够的磁盘空间

#### 3. JSON格式错误
```
❌ 导入失败: JSON decode error
```
**解决方案**：
- 使用JSON验证工具检查文件格式
- 确认文件编码为UTF-8
- 检查是否有多余的逗号或括号

#### 4. 数据类型转换错误
```
❌ 处理工程研究中心 XXX 时出错
```
**解决方案**：
- 检查JSON中数值字段是否包含非数字字符
- 脚本有safe_int和safe_float函数来处理大部分类型错误
- 如果持续出错，可以手动检查该工程研究中心的数据

### 数据一致性检查

导入后建议进行以下检查：

1. **数量检查**：
   ```sql
   SELECT COUNT(*) FROM labs;
   ```

2. **年度数据检查**：
   ```sql
   SELECT name, current_year, json_length(annual_data) as year_count 
   FROM labs 
   WHERE annual_data IS NOT NULL;
   ```

3. **统计数据检查**：
   ```sql
   SELECT name, valid_patents, doctoral_students, total_funding 
   FROM labs 
   ORDER BY total_funding DESC;
   ```

## 数据更新策略

### 完全重新导入
如果数据变化很大，建议：
1. 备份现有数据库
2. 清空labs表
3. 重新导入所有数据

### 增量更新
如果只是部分数据更新：
1. 脚本会自动检测已存在的工程研究中心
2. 根据中心编号或名称匹配
3. 更新现有记录的数据

### 数据备份
在大规模更新前，建议备份：
```powershell
copy backend\data\app.db backend\data\app_backup_$(Get-Date -Format "yyyyMMdd_HHmmss").db
```

## 性能优化

### 大量数据处理
如果数据量很大（>100个工程研究中心）：
1. 考虑分批处理
2. 添加进度条显示
3. 使用批量插入操作

### 内存优化
- 避免一次性加载所有数据到内存
- 使用流式处理方式
- 及时释放不需要的对象

## 维护建议

### 定期任务
1. **每月检查**：验证数据一致性
2. **每季度备份**：完整备份数据库
3. **每年更新**：根据新的数据字段要求更新脚本

### 版本控制
- 对导入脚本进行版本控制
- 记录每次数据更新的变更日志
- 保留历史数据备份

## 联系信息

如有问题或需要技术支持，请联系：
- 开发团队：AI助手
- 文档更新：每次数据模型变更时同步更新

---

**最后更新时间**：2024年度
**文档版本**：v1.0
**适用环境**：Windows + Python + FastAPI + SQLite