buffer_platform/AUTH_GUIDE.md

# 用户权限系统使用指南

## 📋 系统概述

期货智析系统现已集成完整的用户权限管理系统，所有页面需要进行登录才能访问。系统支持两种用户角色：

- **管理员 (admin)**: 可以访问品种分析界面和系统管理界面
- **普通用户 (user)**: 只能访问品种分析界面

## 🔐 默认账户

系统首次启动时会自动创建默认管理员账户：

| 字段 | 值 |
|------|------|
| **用户名** | `lxy_root` |
| **密码** | `admin123` |
| **角色** | 管理员 (admin) |
| **邮箱** | `admin@system.local` |

⚠️ **重要**: 首次登录后请立即修改默认密码！

## 🚀 使用流程

### 1. 访问系统

打开浏览器访问：`http://localhost:9600`

系统会自动重定向到登录页面。

### 2. 登录

1. 输入用户名和密码
2. 点击"登录"按钮
3. 系统验证成功后会根据用户角色进行跳转

### 3. 角色跳转逻辑

#### 普通用户
- 登录后直接进入 **品种分析** 界面
- 访问地址：`http://localhost:9600/futures-analysis`

#### 管理员用户
- 登录后进入 **角色选择** 页面
- 可选择进入：
  - **品种分析** - 智能期货分析工具
  - **系统管理** - 后台管理配置界面

### 4. 退出登录

在任意页面点击"退出登录"按钮，或在角色选择页面点击退出。

## 📁 文件结构

```
app/
├── user_models.py          # 用户数据库模型
├── auth_service.py         # 认证服务（密码加密、会话管理）
├── api/
│   └── auth.py            # 认证API路由
├── static/
│   ├── login.html         # 登录页面
│   └── role_select.html   # 角色选择页面
└── main.py                # 主入口（已集成认证）
```

## 🔧 API接口

### 1. 用户登录

**POST** `/api/v1/auth/login`

**请求体:**
```json
{
  "username": "lxy_root",
  "password": "admin123"
}
```

**响应:**
```json
{
  "success": true,
  "token": "jr1xNX4egsLRStvVYLnkJj8uruB902VwCG4z3Wuy6dc",
  "user": {
    "id": 1,
    "username": "lxy_root",
    "role": "admin",
    "email": "admin@system.local"
  },
  "message": "登录成功"
}
```

### 2. 验证令牌

**GET** `/api/v1/auth/verify`

**请求头:**
```
Authorization: Bearer <token>
```

**响应:**
```json
{
  "success": true,
  "user": {
    "id": 1,
    "username": "lxy_root",
    "role": "admin",
    "email": "admin@system.local",
    "last_login": "2026-05-24T15:30:00"
  }
}
```

### 3. 获取当前用户信息

**GET** `/api/v1/auth/me`

**请求头:**
```
Authorization: Bearer <token>
```

### 4. 用户登出

**POST** `/api/v1/auth/logout`

**请求头:**
```
Authorization: Bearer <token>
```

## 🗄️ 数据库表

系统创建了两个新表：

### 1. users 表 - 用户信息

| 字段 | 类型 | 说明 |
|------|------|------|
| id | INTEGER | 主键 |
| username | VARCHAR(50) | 用户名（唯一） |
| password_hash | VARCHAR(255) | 密码哈希 |
| email | VARCHAR(100) | 邮箱 |
| role | VARCHAR(20) | 角色 (admin/user) |
| is_active | BOOLEAN | 是否启用 |
| created_at | DATETIME | 创建时间 |
| last_login | DATETIME | 最后登录时间 |

### 2. sessions 表 - 会话管理

| 字段 | 类型 | 说明 |
|------|------|------|
| id | INTEGER | 主键 |
| user_id | INTEGER | 用户ID |
| token | VARCHAR(255) | 会话令牌（唯一） |
| created_at | DATETIME | 创建时间 |
| expires_at | DATETIME | 过期时间 |
| is_valid | BOOLEAN | 是否有效 |

## 🔒 安全特性

1. **密码加密**: 使用 SHA-256 + 随机盐值加密存储
2. **会话管理**: 使用安全令牌，24小时自动过期
3. **权限控制**: 基于角色的访问控制 (RBAC)
4. **自动清理**: 过期会话自动标记为无效

## 👥 用户管理

### 创建新用户

可以通过Python脚本或直接操作数据库创建用户：

```python
from app.database import SessionLocal
from app import auth_service

db = SessionLocal()
try:
    auth_service.create_user(
        db=db,
        username='new_user',
        password='secure_password',
        email='user@example.com',
        role='user'  # 或 'admin'
    )
finally:
    db.close()
```

### 修改用户角色

```python
from app.database import SessionLocal
from app.user_models import User

db = SessionLocal()
try:
    user = db.query(User).filter(User.username == 'username').first()
    user.role = 'admin'  # 或 'user'
    db.commit()
finally:
    db.close()
```

### 禁用用户

```python
user.is_active = False
db.commit()
```

## 🎯 页面访问控制

| 页面 | 需要登录 | 需要角色 |
|------|---------|---------|
| `/login` | ❌ | ❌ |
| `/futures-analysis` | ✅ | 任意 |
| `/role-select` | ✅ | admin |
| `/ui` | ✅ | admin |
| `/ai-config` | ✅ | 任意 |
| `/api/v1/*` | 部分接口 | 视接口而定 |

## 🐛 故障排查

### 1. 登录后无法访问页面

- 检查浏览器控制台是否有错误
- 确认localStorage中保存了auth_token
- 尝试清除浏览器缓存后重新登录

### 2. 令牌过期

- 会话令牌24小时过期
- 过期后需要重新登录
- 可在代码中修改 `expires_hours` 参数

### 3. 忘记管理员密码

可以通过数据库重置：

```python
from app.database import SessionLocal
from app import auth_service

db = SessionLocal()
try:
    from app.user_models import User
    admin = db.query(User).filter(User.username == 'lxy_root').first()
    admin.password_hash = auth_service.hash_password('new_password')
    db.commit()
    print("密码已重置")
finally:
    db.close()
```

## 📝 最佳实践

1. ✅ 首次登录后修改默认密码
2. ✅ 定期清理过期会话
3. ✅ 为不同用户分配最小权限原则
4. ✅ 定期检查用户登录日志
5. ✅ 备份用户数据库表

## 🔗 相关文档

- [部署指南](./DEPLOY.md)
- [系统架构](./DESIGN.md)
- [API文档](http://localhost:9600/docs)