save code

backend/docs/excel-import-guide.md

@@ -0,0 +1,266 @@
+# 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