# Excel数据导入指南

## 1. 概述

本指南说明如何将 `docs/example.xls` 中的工程项目数据导入到数据库中。

## 2. 准备工作

### 2.1 安装依赖

```bash
pip install mysql-connector-python xlrd
```

### 2.2 配置数据库

编辑 `backend/config/.env` 文件，配置数据库连接信息：

```env
DB_HOST=localhost
DB_USER=root
DB_PASSWORD=rootpassword
DB_NAME=project_manager
DB_CHARSET=utf8mb4
```

### 2.3 初始化数据库

```bash
cd backend/config
mysql -u root -p < init-database.sql
```

## 3. 导入数据

### 3.1 方法一：使用Python脚本（推荐）

```bash
cd backend/config
python3 import-excel-data.py
```

**注意事项**:
- 确保 `docs/example.xls` 文件存在
- 确保数据库连接正常
- 确保管理员用户已创建

### 3.2 方法二：手动导入

1. 将Excel转换为CSV
2. 使用MySQL导入工具
3. 手动执行SQL INSERT语句

## 4. 数据映射

### 4.1 Excel工作表映射

| Excel工作表 | 对应的工程类别 |
|-----------|---------------|
| 1-1基建 | 基建工程 |
| 1-2业扩 | 业扩工程 |
| 1-3客户 | 客户工程 |
| 1-4营销 | 营销工程 |
| 2检修、技改、应急抢修项目 | 检修工程 |

### 4.2 字段映射关系

详见 `docs/database-design.md` 第4章。

## 5. 数据验证

### 5.1 检查导入数量

```sql
SELECT COUNT(*) FROM projects;
```

### 5.2 按工程类别统计

```sql
SELECT engineering_type, COUNT(*) as count 
FROM projects 
GROUP BY engineering_type;
```

### 5.3 检查关键字段

```sql
-- 检查合同编号为空的项目
SELECT * FROM projects WHERE project_no IS NULL OR project_no = '';

-- 检查项目名称为空的项目
SELECT * FROM projects WHERE name IS NULL OR name = '';

-- 检查金额字段异常的项目
SELECT * FROM projects WHERE contract_amount < 0;
```

## 6. 常见问题

### 6.1 日期格式错误

**问题**: Excel中的日期格式无法识别

**解决**:
- 检查Excel中的日期格式是否正确
- 特殊值如"未到期"、"未开工"会被设置为NULL

### 6.2 数字格式错误

**问题**: 数字字段包含非数字字符

**解决**:
- 使用 `parse_number_value()` 函数自动处理
- 空值会被设置为NULL

### 6.3 重复数据

**问题**: 合同编号重复

**解决**:
- 检查Excel中是否有重复的合同编号
- 使用 `INSERT IGNORE` 或 `ON DUPLICATE KEY UPDATE`

### 6.4 字符编码问题

**问题**: 中文字符乱码

**解决**:
- 确保数据库使用 utf8mb4 字符集
- 确保Python脚本使用正确的编码

## 7. 更新数据

### 7.1 完全重新导入

```bash
# 清空现有数据
mysql -u root -p project_manager -e "TRUNCATE TABLE projects;"

# 重新导入
cd backend/config
python3 import-excel-data.py
```

### 7.2 增量导入

修改Python脚本，只导入新增的项目：

```python
# 检查项目是否已存在
cursor.execute("SELECT id FROM projects WHERE project_no = %s", (project_no,))
if cursor.fetchone():
    continue  # 跳过已存在的项目
```

## 8. 自动化部署

### 8.1 创建部署脚本

`scripts/deploy.sh`:

```bash
#!/bin/bash

echo "开始部署..."

# 1. 停止服务
echo "停止服务..."
systemctl stop project-manager-backend

# 2. 备份数据库
echo "备份数据库..."
mysqldump -u root -p project_manager > backup_$(date +%Y%m%d_%H%M%S).sql

# 3. 初始化数据库
echo "初始化数据库..."
mysql -u root -p < backend/config/init-database.sql

# 4. 导入Excel数据
echo "导入Excel数据..."
cd backend/config
python3 import-excel-data.py

# 5. 启动服务
echo "启动服务..."
systemctl start project-manager-backend

echo "部署完成！"
```

### 8.2 添加定时任务

```bash
# 每天凌晨2点自动导入数据
crontab -e

# 添加以下行
0 2 * * * /path/to/scripts/deploy.sh >> /var/log/project-manager/deploy.log 2>&1
```

## 9. 监控和日志

### 9.1 导入日志

```bash
# 查看导入日志
tail -f /var/log/project-manager/import.log
```

### 9.2 数据完整性检查

创建定时任务检查数据完整性：

```sql
-- 检查缺失字段
SELECT 
    COUNT(*) as missing_contract_no
FROM projects 
WHERE project_no IS NULL OR project_no = '';
```

## 10. 性能优化

### 10.1 批量插入

使用批量插入提高性能：

```python
# 一次插入100条记录
cursor.executemany(sql, params_list)
```

### 10.2 禁用索引

导入数据时临时禁用索引：

```sql
ALTER TABLE projects DISABLE KEYS;
-- 导入数据
ALTER TABLE projects ENABLE KEYS;
```

## 11. 安全注意事项

### 11.1 数据库权限

不要使用root用户导入数据，创建专用用户：

```sql
CREATE USER 'import_user'@'localhost' IDENTIFIED BY 'secure_password';
GRANT INSERT, SELECT ON project_manager.* TO 'import_user'@'localhost';
```

### 11.2 SQL注入防护

使用参数化查询，避免SQL注入。

### 11.3 敏感信息保护

不要将密码硬编码在脚本中，使用环境变量或配置文件。

---

**文档维护**: 本文档由后端程序员维护
**更新时间**: 2026-01-25