# 甲辰藏品管理系统 - 完整错误码文档

**版本**: v2.7.3  
**更新时间**: 2026-03-14

---

## 📖 错误码格式

```
E + 模块 (2 位) + 序号 (3 位)
```

例如：`E00011` = 认证模块 (01) + 第 11 号错误

---

## 🔢 完整错误码列表

### 00-09: 通用错误

| 错误码 | 含义 | HTTP 状态 | 常见原因 | 解决方案 |
|--------|------|----------|----------|----------|
| E00000 | 未知错误 | 0 | 未定义的错误 | 检查日志 |
| E00001 | 网络连接失败 | 0 | 网络不通、服务未启动 | 检查网络和后端服务 |
| E00002 | 服务器响应超时 | 0 | 请求超时 | 重试或检查服务器负载 |
| E00003 | 服务器内部错误 | 500 | 代码异常、数据库错误 | 查看后端日志 |

### 10-19: 认证错误

| 错误码 | 含义 | HTTP 状态 | 常见原因 | 解决方案 |
|--------|------|----------|----------|----------|
| E00010 | 未登录或登录已过期 | 401 | Token 失效 | 重新登录 |
| E00011 | 用户名或密码错误 | 401 | 密码错误、用户名不存在 | 检查账号密码 |
| E00012 | 验证码错误 | 400 | 验证码输入错误 | 重新输入或刷新验证码 |
| E00013 | 账号已被禁用 | 403 | 账号被封禁 | 联系管理员 |
| E00014 | 无权访问此资源 | 403 | 权限不足 | 申请权限或用管理员账号 |
| E00015 | 令牌无效或已过期 | 401 | Token 过期 | 重新登录 |

### 20-29: 登录注册

| 错误码 | 含义 | HTTP 状态 | 常见原因 | 解决方案 |
|--------|------|----------|----------|----------|
| E00020 | 请输入用户名和密码 | 400 | 空表单 | 填写完整信息 |
| E00021 | 用户名至少 3 个字符 | 400 | 用户名太短 | 使用更长的用户名 |
| E00022 | 密码至少 6 个字符 | 400 | 密码太短 | 使用更长的密码 |
| E00023 | 用户名已存在 | 400 | 重复注册 | 更换用户名 |
| E00024 | 邮箱已被注册 | 400 | 邮箱重复 | 更换邮箱或找回密码 |
| E00025 | 邮箱格式不正确 | 400 | 邮箱格式错误 | 检查邮箱格式 |
| E00026 | 手机号格式不正确 | 400 | 手机号格式错误 | 检查手机号格式 |

### 30-39: 藏品管理

| 错误码 | 含义 | HTTP 状态 | 常见原因 | 解决方案 |
|--------|------|----------|----------|----------|
| E00030 | 藏品名称不能为空 | 400 | 名称为空 | 填写名称 |
| E00031 | 藏品名称至少 2 个字符 | 400 | 名称太短 | 使用更长的名称 |
| E00032 | 藏品分类不能为空 | 400 | 分类为空 | 选择分类 |
| E00033 | 藏品不存在 | 404 | ID 错误、已删除 | 检查藏品 ID |
| E00034 | 禁止重复：此冠字号已存在 | 400 | 重复编号 | 使用不同编号 |
| E00035 | 成本价格必须>=0 | 400 | 负数价格 | 输入正数 |
| E00036 | 目标价格必须>=0 | 400 | 负数价格 | 输入正数 |
| E00037 | 发行年份必须是 4 位数字 | 400 | 年份格式错误 | 如：2024 |
| E00038 | 图片格式不正确 | 400 | 不支持的图片格式 | 使用 JPG/PNG |
| E00039 | 图片大小不能超过 10MB | 400 | 图片太大 | 压缩图片 |

### 40-49: OCR 识别

| 错误码 | 含义 | HTTP 状态 | 常见原因 | 解决方案 |
|--------|------|----------|----------|----------|
| E00040 | 请选择图片文件 | 400 | 未选择图片 | 上传图片 |
| E00041 | 图片尺寸太小，无法识别 | 400 | 图片分辨率太低 | 使用更清晰的图片 |
| E00042 | OCR 识别失败，请重试 | 500 | 识别服务异常 | 重试或更换图片 |
| E00043 | OCR 服务暂时不可用 | 503 | 服务宕机 | 稍后重试 |
| E00044 | 无法识别图片内容 | 400 | 图片内容不清晰 | 更换清晰的图片 |

### 50-59: 用户管理（仅管理员）

| 错误码 | 含义 | HTTP 状态 | 常见原因 | 解决方案 |
|--------|------|----------|----------|----------|
| E00050 | 仅管理员可访问 | 403 | 权限不足 | 使用管理员账号 |
| E00051 | 用户不存在 | 404 | 用户 ID 错误 | 检查用户 ID |
| E00052 | 不能删除自己 | 400 | 删除当前用户 | 删除其他用户 |
| E00053 | 不能修改自己的角色 | 403 | 权限限制 | 让其他管理员修改 |

### 60-69: 文件上传

| 错误码 | 含义 | HTTP 状态 | 常见原因 | 解决方案 |
|--------|------|----------|----------|----------|
| E00060 | 文件太大 | 400 | 超过大小限制 | 压缩文件 |
| E00061 | 不支持的文件格式 | 400 | 格式不支持 | 使用支持的格式 |
| E00062 | 上传失败 | 500 | 服务器错误 | 重试或联系管理员 |

---

## 🔍 特殊错误：E00000 + JSON 解析错误

### 错误信息示例
```
⚠️ E00000: Unexpected token '<', "<html> <h"... is not valid JSON
```

### 原因分析
这个错误说明**前端期望 JSON 响应，但实际收到的是 HTML**。常见原因：

1. **后端服务未启动** - Nginx 返回 502/503 错误页面（HTML）
2. **API 地址配置错误** - 请求了错误的 URL，返回 404 页面（HTML）
3. **网络代理问题** - 防火墙/代理服务器返回拦截页面（HTML）
4. **浏览器缓存** - 缓存了旧的错误页面

### 解决方案

#### 方案 1: 检查后端服务
```bash
# 检查后端是否运行
ps aux | grep uvicorn

# 如果没有，启动后端
cd /home/admin/.openclaw/workspace/zodiac-collector/backend-fastapi
uvicorn app.main:app --port 3000 --host 0.0.0.0
```

#### 方案 2: 检查 Nginx 配置
```bash
# 检查 Nginx 状态
systemctl status nginx

# 检查 Nginx 配置
nginx -t
```

#### 方案 3: 清除浏览器缓存
1. 按 `F12` 打开开发者工具
2. 右键点击刷新按钮
3. 选择"**清空缓存并硬性重新加载**"

#### 方案 4: 检查 API 地址
打开浏览器开发者工具 → Network 标签，查看登录请求的 URL：
- 应该是：`http://120.26.133.10:3001/api/auth/login`
- 如果是其他地址，说明配置有误

---

## 🛠️ 调试技巧

### 1. 查看浏览器控制台
按 `F12` 打开开发者工具，查看：
- **Console** - JavaScript 错误
- **Network** - API 请求详情

### 2. 查看后端日志
```bash
tail -f /tmp/zodiac-backend.log
```

### 3. 查看 Nginx 日志
```bash
tail -f /var/log/nginx/access.log
tail -f /var/log/nginx/error.log
```

### 4. 测试 API
```bash
# 测试登录接口
curl -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=admin&password=admin123"

# 测试藏品列表
curl http://localhost:3000/api/collections \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

## 📞 快速诊断流程

```
登录失败
    ↓
1. 打开浏览器 F12 → Network 标签
    ↓
2. 查看登录请求的状态码
    ↓
    ├── 0 或 (failed) → 网络问题/服务未启动 → 检查后端服务
    ├── 401 → 密码错误 → 检查账号密码
    ├── 404 → API 地址错误 → 检查 Nginx 配置
    ├── 500 → 服务器错误 → 查看后端日志
    └── 502/503 → Nginx 无法连接后端 → 重启后端服务
```

---

**文档维护**: 系统自动更新  
**最后更新**: 2026-03-14 10:30
