# LearningAnalytics 数据库修复指南

## 问题描述

在提交评分时出现两类错误：

### 错误1: IP 地址类型不匹配
```
psycopg2.errors.DatatypeMismatch: column "ip_address" is of type inet but expression is of type character varying
```
**原因**：`ip_address` 字段类型为 `INET`，但应用传递字符串 `'127.0.0.1'`。

### 错误2: 分数值溢出
```
psycopg2.errors.NumericValueOutOfRange: numeric field overflow
DETAIL: A field with precision 5, scale 4 must round to an absolute value less than 10^1.
```
**原因**：`partial_score` 字段类型为 `NUMERIC(5,4)`，只能存储 -9.9999 到 9.9999，但实际分数可能达到 7-10 分。

## 解决方案

1. 修改 `ip_address` 字段类型为 `VARCHAR(64)`
2. 修改 `partial_score` 字段类型为 `NUMERIC(6,2)`

## 使用方法

### 方法一：使用自动修复脚本（推荐）

```bash
cd /Volumes/T9/code/math/apis/FilamentAdmin/scripts
bash fix_learning_analytics_db.sh
```

脚本会自动：
1. 检测数据库容器
2. 执行 SQL 修复命令
3. 验证修复结果

### 方法二：手动执行 SQL

1. **连接数据库**：
   ```bash
   docker exec -it learning_analytics_postgres psql -U rag_user -d learning_analytics
   ```

2. **执行修复**：
   ```sql
   -- 修改 ip_address 字段类型
   ALTER TABLE student_attempts
   ALTER COLUMN ip_address TYPE VARCHAR(64);

   -- 修改 partial_score 字段类型
   ALTER TABLE student_attempts
   ALTER COLUMN partial_score TYPE NUMERIC(6,2);
   ```

3. **验证**：
   ```sql
   \d student_attempts | grep -E "ip_address|partial_score"
   ```

## 文件说明

- `fix_learning_analytics_db.sh` - 自动修复脚本
- `../database/migrations/2025_12_02_fix_learning_analytics_ip_address_type.sql` - SQL 脚本
- `README_DB_FIX.md` - 本说明文档

## 验证成功

执行成功后，应看到：
```
✓ 修复完成!
  - ip_address: INET → VARCHAR(64)
  - partial_score: NUMERIC(5,4) → NUMERIC(6,2)
```

## 字段类型说明

### ip_address
- **原类型**: `INET` (网络地址类型)
- **新类型**: `VARCHAR(64)` (字符串类型)
- **用途**: 存储客户端 IP 地址
- **优点**: 避免类型转换问题，兼容性更好

### partial_score
- **原类型**: `NUMERIC(5,4)` (1位整数 + 4位小数 = -9.9999 到 9.9999)
- **新类型**: `NUMERIC(6,2)` (4位整数 + 2位小数 = -9999.99 到 9999.99)
- **用途**: 存储题目得分，支持 0-100 分的常规考试分数
- **优点**: 足够的整数位存储满分 100 分，保留 2 位小数

## 注意事项

- 这些修改不影响数据完整性
- 修复后需要重启 LearningAnalytics 服务：`docker-compose restart learning-analytics`
- 确保 FilamentAdmin 和 LearningAnalytics 服务都已重启

## 测试

修复完成后，访问 http://fa.test/admin/upload-exam-paper 测试评分提交功能。应该能够正常为选择题、填空题、解答题评分并提交。