hzdyjs/学籍号刷新/学生学籍号刷新脚本设计说明.md

# 学生学籍号刷新脚本设计说明

## 📋 文档说明

**版本**: v1.0.0
**制定时间**: 2025-12-26
**适用范围**: 学生学籍号自动刷新业务
**重要性**: ⚠️ **核心数据处理脚本** - 自动刷新学生学籍号信息

---

## 🎯 设计目标

### 1. 业务需求

- **自动刷新学籍号**: 自动为学生生成学籍号（'G' + 身份证号）
- **数据完整性**: 确保所有学生的ext_field2字段都有正确的学籍号
- **批量处理**: 支持大量数据的批量处理
- **监控守护**: 持续监控并处理新的学生数据

### 2. 技术要求

- **数据安全性**: 遵循项目数据库设计规范
- **性能优化**: 合理的批量处理策略，支持高效更新
- **扩展性**: 支持一次性处理和持续监控两种模式
- **容错性**: 完善的错误处理和重试机制

---

## 🗄️ 脚本架构

### 文件结构

```
学籍号刷新/
├── data.conf              # 开发环境配置
├── data.conf.prod         # 生产环境配置
├── process_student_id_card_refresh.sh  # 主处理脚本
└── 学生学籍号刷新脚本设计说明.md     # 设计文档
```

### 脚本模式

#### 1. 一次性处理模式
```bash
./process_student_id_card_refresh.sh once
```
- 一次性刷新所有符合条件的学籍号
- 适合初始化或手动触发处理

#### 2. 持续监控模式（默认）
```bash
./process_student_id_card_refresh.sh
```
- 每10分钟检查一次需要刷新的记录
- 持续运行的守护进程模式

---

## 🔄 处理逻辑

### 刷新规则

**学籍号生成规则**: `ext_field2 = 'G' + id_card`

### 处理条件

```sql
WHERE (ext_field2 IS NULL OR ext_field2 = '')
  AND id_card IS NOT NULL
  AND id_card != ''
  AND deleted = 0
```

### 更新语句

```sql
UPDATE xg_student_msg SET
    ext_field2 = CONCAT('G', id_card),
    update_by = 1,
    update_time = NOW()
WHERE (ext_field2 IS NULL OR ext_field2 = '')
  AND id_card IS NOT NULL
  AND id_card != ''
  AND deleted = 0;
```

---

## ⚙️ 配置说明

### data.conf 配置参数

```bash
# Database configuration
DB_HOST="47.99.164.66"          # 数据库主机
DB_PORT="3306"                  # 数据库端口
DB_NAME="hzdyjs_xg"            # 数据库名
DB_USER="root"                 # 数据库用户
DB_PASS="nsyOfyOyoFCr%Brj-k_5PqbW"      # 数据库密码

# Script configuration
LOG_DIR="${SCRIPT_DIR}/student_id_card_refresh"  # 日志目录
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"  # 脚本目录
LOCK_FILE="${SCRIPT_DIR}/script.lock"  # 锁定文件

# Processing configuration
BATCH_SIZE=500                 # 批次处理大小
MAX_RETRY=3                    # 最大重试次数
RETRY_DELAY=5                  # 重试间隔（秒）
CYCLE_INTERVAL=600             # 循环间隔（秒，默认10分钟）
```

---

## 🔧 使用方法

### 1. 准备工作

```bash
# 进入脚本目录
cd 学籍号刷新

# 给脚本添加执行权限
chmod +x process_student_id_card_refresh.sh
```

### 2. 一次性处理模式

```bash
# 执行一次性刷新
./process_student_id_card_refresh.sh once
```

### 3. 持续监控模式

```bash
# 使用快速启动脚本（推荐）
./run_refresh.sh bg

# 或直接后台运行
nohup ./process_student_id_card_refresh.sh > /dev/null 2>&1 &
```

### 4. 停止脚本

```bash
# 查找进程
ps aux | grep process_student_id_card_refresh

# 终止进程
kill -9 <PID>
```

---

## 📊 日志和监控

### 日志文件

日志文件保存在 `student_id_card_refresh/` 目录下：
- 文件命名: `process_student_id_card_refresh_YYYYMMDD_HHMMSS.log`
- 包含详细的处理过程和错误信息

### 日志内容

```
[2025-12-26 14:30:15] [INFO] 启动学生学籍号刷新处理脚本
[2025-12-26 14:30:15] [INFO] 处理类型: ID_CARD_REFRESH(学籍号刷新)
[2025-12-26 14:30:15] [INFO] 数据库连接成功
[2025-12-26 14:30:15] [INFO] 发现 1250 条需要刷新的学籍号记录，开始处理...
[2025-12-26 14:30:20] [INFO] 批次处理完成 - 找到记录: 500, 失败: 0
```

### 监控要点

1. **处理进度**: 定期检查日志中的处理进度
2. **错误统计**: 关注失败的记录数和错误原因
3. **性能监控**: 监控数据库负载和脚本运行状态

---

## 🔒 安全考虑

### 数据安全

1. **多租户隔离**: 通过deleted字段和业务逻辑隔离
2. **事务安全**: 每次更新都有明确的条件限制
3. **备份机制**: 更新前建议备份相关数据
4. **权限控制**: 脚本需要数据库写入权限

### 运行安全

1. **单实例运行**: 通过锁定文件防止多实例同时运行
2. **错误处理**: 完善的错误捕获和日志记录
3. **资源控制**: 合理的批次大小和处理间隔

---

## 🚀 性能优化

### 批量处理策略

- **批次大小**: 500条/批，避免单次处理过多数据
- **处理间隔**: 10分钟，与学生换班级脚本保持一致
- **并发控制**: 单进程运行，避免数据库压力

### 数据库优化

```sql
-- 建议添加的索引（如果性能需要）
ALTER TABLE xg_student_msg ADD INDEX idx_ext_field2_deleted (ext_field2, deleted);
ALTER TABLE xg_student_msg ADD INDEX idx_id_card_deleted (id_card, deleted);
```

---

## 📞 维护说明

### 定期维护任务

1. **日志清理**: 定期清理历史日志文件
2. **配置检查**: 检查配置文件是否正确
3. **数据库监控**: 监控脚本对数据库的影响
4. **性能调优**: 根据实际情况调整批次大小和间隔

### 故障处理

#### 常见问题

1. **数据库连接失败**
   - 检查网络连接和数据库状态
   - 验证配置文件中的数据库参数

2. **权限不足**
   - 检查数据库用户的权限
   - 确认用户有UPDATE权限

3. **磁盘空间不足**
   - 清理日志文件
   - 检查磁盘空间使用情况

#### 应急处理

```bash
# 强制停止脚本
pkill -f process_student_id_card_refresh

# 清理锁定文件
rm -f process_student_id_card_refresh.lock

# 手动执行SQL验证
mysql -h host -u user -p database -e "UPDATE语句"
```

---

## 📈 统计分析

### 处理统计

```sql
-- 查看学籍号刷新情况
SELECT
    COUNT(*) as total_students,
    SUM(CASE WHEN ext_field2 LIKE 'G%' THEN 1 ELSE 0 END) as with_id_card,
    SUM(CASE WHEN ext_field2 IS NULL OR ext_field2 = '' THEN 1 ELSE 0 END) as need_refresh
FROM xg_student_msg
WHERE deleted = 0;
```

### 效果验证

```sql
-- 验证学籍号格式是否正确
SELECT
    student_no,
    student_name,
    id_card,
    ext_field2,
    CONCAT('G', id_card) as expected_id_card
FROM xg_student_msg
WHERE ext_field2 LIKE 'G%'
  AND CONCAT('G', id_card) != ext_field2
  AND deleted = 0;
```

---

## ⚠️ 重要提醒

1. **数据备份**: 执行脚本前务必备份数据库
2. **测试验证**: 先在测试环境验证脚本功能
3. **监控运行**: 持续监控脚本运行状态和日志
4. **权限控制**: 确保脚本运行账号有适当权限
5. **文档同步**: 脚本变更必须同步更新本文档

---

## 🔗 相关文档

- **数据库设计**: `docs/设计文档/database/mysql-database-standard.md`
- **项目规范**: `.cursor/cursorrules-backend.md`
- **API文档**: `docs/开发文档/API/用户认证登录API.md`

---

### 🔧 版本历史

#### v1.0.2 (2025-12-26) - 易用性增强版
- ✅ **后台执行**: 新增`run_refresh.sh bg`模式，支持后台守护进程
- ✅ **用户友好**: 提供PID显示、状态检查和停止命令提示
- ✅ **使用简化**: 一键启动后台监控，无需手动nohup

#### v1.0.1 (2025-12-26) - 性能优化版
- ✅ **逻辑简化**: 移除不必要的预查询统计，直接执行UPDATE语句
- ✅ **效率提升**: 使用`SELECT ROW_COUNT()`获取受影响行数，一次查询完成所有操作
- ✅ **代码精简**: 减少数据库查询次数，降低系统开销
- ✅ **监控优化**: 监控模式也使用简化的处理逻辑

#### v1.0.0 (2025-12-26) - 初始版本
- ✅ 基础学籍号刷新功能
- ✅ 批量处理和监控模式
- ✅ 完善的日志和错误处理

---

**最后更新**: 2025-12-26
**当前版本**: v1.0.2
**维护人员**: AI Assistant
**联系方式**: 项目技术团队