jiachenlong/docs/RELEASE_v1.0.0.md

# 甲辰藏品管理系统 v1.0.0 发布说明

**发布日期**: 2026-03-16  
**版本**: v1.0.0  
**分支**: `main`  
**提交**: `initial`

---

## 🎉 初始版本

这是精简重构后的第一个正式版本，包含核心功能。

---

## 🎯 版本亮点

### 1. 统一版本管理系统 📦
**问题**: 之前版本号分散在多个文件，修改麻烦且容易遗漏  
**解决方案**: 
- 新增根目录 `VERSION` 文件集中管理版本号
- 后端启动时自动读取 VERSION 文件
- 前端构建时自动注入版本号到所有页面
- 浏览器标签页标题自动更新

**使用方法**:
```bash
# 只需修改这一处
vi VERSION
# 修改：VERSION=2.9.0

# 重新构建即可
npm run build
```

### 2. 冠字号查重功能 🔍
**功能**: 保存藏品时自动检测是否已有相同冠字号的藏品

**流程**:
1. 用户填写藏品信息（包含冠字号）
2. 点击保存 → 后端自动查重
3. 发现重复 → 弹窗提示：
   ```
   ⚠️ 发现重复冠字号！
   冠字号：J063558611
   已存在于：龙钞 (编号：0001)
   
   是否继续保存？
   ```
4. 用户选择：
   - **取消** → 终止保存
   - **确认** → 强制保存（支持重复冠字号）

**适用场景**: 
- 防止误操作重复录入
- 特殊情况下允许保存重复冠字号（如不同评级公司）

### 3. 图片重命名优化 📸
**旧格式**: `UUID.jpg` (如 `aaf56f63-548a-49f1-9b07-116a73b7dfa0.jpg`)  
**新格式**: `用户名 - 藏品编号 - 冠字号.jpg`

**示例**:
```
酷博特 -0001-J063558611.jpg
酷博特 -0002-J051811231.jpg
admin-0001.jpg  (无冠字号时)
```

**优势**:
- 文件名直观，一眼看出是谁的哪个藏品
- 便于手动查找和管理图片文件
- 自动清理特殊字符，兼容各操作系统
- 文件冲突时自动添加时间戳

---

## 🐛 Bug 修复

### 1. 用户管理 - 角色设置失效 ❌→✅
**问题**: 添加用户时选择"管理员"角色，保存后还是"普通用户"

**原因**:
- 前端调用 `/api/auth/register` 接口（硬编码 role="user"）
- 后端使用 `Query` 而非 `Form` 接收参数

**修复**:
- 新增 `POST /api/admin/users` 接口（支持 role 参数）
- 前端改为调用管理员接口
- 修复 error_handler 字段映射错误

### 2. 图片显示 - 全部显示系统 Logo ❌→✅
**问题**: 所有藏品图片都显示系统 logo，不显示实际图片

**原因**: Nginx 缺少 `/uploads` 路径代理配置

**修复**:
```nginx
location /uploads {
    proxy_pass http://127.0.0.1:3000/uploads;
    client_max_body_size 20M;
}
```

### 3. OCR 识别 - API 调用失败 ❌→✅
**问题**: OCR 识别返回 500 错误

**原因**: DashScope API 格式错误
```json
// ❌ 错误格式
{
  "model": "qwen-vl-max",
  "input": {"messages": [...]}
}

// ✅ 正确格式
{
  "model": "qwen-vl-max",
  "messages": [...],
  "max_tokens": 1000
}
```

---

## ⚙️ 技术优化

### 1. 版本号显示位置
- **统计页面** (`/stats`) - 右上角
- **藏品列表** (`/list`) - 右上角
- **添加藏品** (`/add`) - 右下角浮动
- **用户管理** (`/admin`) - 右下角浮动
- **首页** (`/`) - 底部
- **登录页** (`/login`) - 底部
- **浏览器标签页** - 标题自动更新

### 2. 藏品编码逻辑
**规则**: 本用户所有藏品中最大编码 +1

```python
def generate_code(version: str, user_id: str, db: Session) -> str:
    # 查询当前用户的所有编码
    user_codes = db.query(Collection.f01_02_code).filter(
        Collection.f01_02_code.isnot(None),
        Collection.f99_91_user_id == user_id
    ).all()
    
    # 找出最大数字编码（4 位纯数字）
    max_num = 0
    for (code,) in user_codes:
        if re.match(r'^\d{4}$', code):
            num = int(code)
            if num > max_num:
                max_num = num
    
    # 返回最大号 +1
    return str(max_num + 1).zfill(4)
```

**特点**:
- ✅ 每个用户独立编码（不与其他用户混算）
- ✅ 自动找出当前用户最大编码
- ✅ 返回最大编码 +1（4 位数字，如 0001, 0002）

### 3. 后端接口优化
- `POST /api/admin/users` - 支持 Form 参数
- `PUT /api/admin/users/{id}` - 同时支持 Query 和 JSON body
- `POST /api/collections?force=true` - 强制保存（忽略重复警告）

### 4. 日志记录增强
```python
logger.info(f"创建用户：username={username}, role={role}")
logger.warning(f"发现重复冠字号：{serial}, 已存在 ID: {id}")
logger.info(f"图片上传成功：{filename}")
```

---

## 📊 文件变更统计

**提交**: `1e42b7f`  
**变更**: 11 files changed, 206 insertions(+), 48 deletions(-)

### 修改文件列表
1. `VERSION` (新增) - 统一版本配置文件
2. `backend-fastapi/app/main.py` - 自动读取版本号
3. `backend-fastapi/app/routers/collections.py` - 查重 + 图片重命名
4. `backend-fastapi/app/routers/ocr.py` - API 格式修复
5. `backend-fastapi/app/routers/users.py` - 用户管理接口
6. `backend-fastapi/app/core/error_handler.py` - 错误映射修复
7. `zodiac-mobile/package.json` - 版本号
8. `zodiac-mobile/vite.config.js` - 自动更新 title
9. `zodiac-mobile/src/config/version.js` - 自动读取版本
10. `zodiac-mobile/src/pages/Add.jsx` - 查重弹窗
11. `zodiac-mobile/src/pages/Admin.jsx` - 版本号显示
12. `zodiac-mobile/src/pages/List.jsx` - 版本号显示
13. `zodiac-mobile/src/pages/Stats.jsx` - 版本号显示

---

## 🚀 升级指南

### 从 v2.7.x 升级到 v2.8.0

#### 1. 拉取新版本
```bash
cd /path/to/zodiac-collector
git fetch origin
git checkout v2.8.0
```

#### 2. 安装依赖
```bash
# 后端
cd backend-fastapi
pip install -r requirements.txt

# 前端
cd zodiac-mobile
pnpm install
```

#### 3. 重新构建
```bash
# 前端构建
npm run build
sudo cp -r dist/* /var/www/mobile/dist/

# 重启后端
pkill -f "uvicorn app.main:app"
nohup uvicorn app.main:app --port 3000 --host 0.0.0.0 &
```

#### 4. 验证版本
```bash
# 检查后端版本
curl http://localhost:3000/ | grep version
# {"name":"甲辰收藏系统 FastAPI 后端","version":"2.8.0",...}

# 检查前端版本
curl http://localhost:3001/ | grep title
# <title>甲辰收藏 v2.8.0</title>
```

---

## 📝 使用建议

### 1. 版本管理
- 每次发布新版本只需修改 `VERSION` 文件
- 构建前检查版本号是否正确
- 建议遵循语义化版本规范（主版本。次版本。修订版）

### 2. 冠字号查重
- 正常情况直接保存即可
- 如果确实需要保存重复冠字号，点击"确认"继续
- 建议在备注中说明重复原因

### 3. 图片管理
- 新上传的图片自动使用新命名格式
- 旧图片保持原有 UUID 格式（不影响使用）
- 建议定期整理图片文件

---

## 🐛 已知问题

暂无

---

## 📞 技术支持

- **代码仓库**: http://47.253.189.47:3000/coolbot/zodiac-collector
- **问题反馈**: 创建 Issue 或联系开发团队
- **在线系统**: http://120.26.133.10:3001/

---

## 🎉 致谢

感谢所有参与 v2.8.0 开发和测试的团队成员！

**特别感谢**:
- 产品需求提出
- Bug 报告与测试
- 代码审查与优化

---

**甲辰藏品管理系统开发团队**  
2026-03-15