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文件包含工程研究中心数组，每个工程研究中心包含：

{
  "中心名称": "工程研究中心名称",
  "中心编号": "工程研究中心编号", 
  "年度数据": [
    {
      "归属年份": "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. 准备工作

确保以下条件满足：

• 后端服务已停止运行
• 数据库文件 backend/data/app.db 存在
• Python环境已激活 (conda activate fast-dashboard-env)
• JSON数据文件 src/assets/实验室.json 已更新

2. 环境准备

在命令行中执行：

# 激活conda环境
conda activate fast-dashboard-env

# 进入后端目录
cd backend

3. 执行数据导入

运行导入脚本：

python import_lab_data_full.py

4. 导入过程说明

脚本会执行以下操作：

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

5. 输出信息解读

脚本运行时会显示：

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

6. 验证导入结果

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

1. 启动后端服务：

   uvicorn main:app --reload
   

2. 访问API接口：

   GET http://localhost:8000/labs/
   

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

常见问题及解决方案

1. JSON格式错误

问题: JSON文件中包含Python的None值，导致解析失败 解决方案:

python fix_json_format.py

2. 年份字段类型错误

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

python fix_year_data_types.py

3. 检查特定工程研究中心数据

用途: 当某个工程研究中心出现问题时，可以单独检查其数据格式 使用方法:

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. 数量检查：

   SELECT COUNT(*) FROM labs;
   

2. 年度数据检查：

   SELECT name, current_year, json_length(annual_data) as year_count 
   FROM labs 
   WHERE annual_data IS NOT NULL;
   

3. 统计数据检查：

   SELECT name, valid_patents, doctoral_students, total_funding 
   FROM labs 
   ORDER BY total_funding DESC;
   

数据更新策略

完全重新导入

如果数据变化很大，建议：

1. 备份现有数据库
2. 清空labs表
3. 重新导入所有数据

增量更新

如果只是部分数据更新：

1. 脚本会自动检测已存在的工程研究中心
2. 根据中心编号或名称匹配
3. 更新现有记录的数据

数据备份

在大规模更新前，建议备份：

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