292 lines
7.0 KiB
Markdown
292 lines
7.0 KiB
Markdown
# 甲辰藏品管理系统 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
|