功能细节优化

backend/CHECKLIST.md

@@ -0,0 +1,237 @@
+# 启动前检查清单
+
+在首次启动或遇到问题时，请按此清单逐项检查。
+
+## ✅ 环境检查
+
+### 系统服务
+```bash
+# PostgreSQL 是否运行
+sudo service postgresql status
+sudo service postgresql start  # 如果未运行
+
+# Redis 是否运行
+redis-cli ping  # 应返回 PONG
+sudo service redis-server start  # 如果未运行
+```
+
+### Python 环境
+```bash
+# 虚拟环境是否激活
+which python  # 应显示 .venv/bin/python
+source .venv/bin/activate  # 如果未激活
+
+# 依赖是否安装完整
+pip list | grep redis
+pip list | grep jose
+pip list | grep passlib
+```
+
+## ✅ 配置检查
+
+### .env 文件
+```bash
+# 检查必要配置项
+cat .env | grep PG_PASSWORD
+cat .env | grep SECRET_KEY
+cat .env | grep REDIS_HOST
+
+# 如果缺少配置
+cp .env.example .env  # 如果 .env 不存在
+nano .env  # 编辑配置
+```
+
+### 必须配置的项
+- [ ] `PG_PASSWORD` - PostgreSQL 密码
+- [ ] `SECRET_KEY` - JWT 密钥（生产环境必须修改）
+- [ ] `REDIS_HOST` - Redis 地址（默认 localhost）
+
+## ✅ 数据库检查
+
+```bash
+# 检查数据库是否创建
+psql -U postgres -c "\l" | grep stock_cs
+
+# 检查用户表是否存在
+psql -U postgres -d stock_cs -c "\dt" | grep users
+
+# 如果数据库或表不存在
+python cli.py init
+```
+
+## ✅ 权限检查
+
+```bash
+# 测试数据库连接
+psql -U postgres -d stock_cs -c "SELECT 1;"
+
+# 测试 Redis 连接
+redis-cli ping
+
+# 如果提示权限错误
+sudo -u postgres psql -c "ALTER USER postgres PASSWORD 'your_password';"
+```
+
+## ✅ 启动服务
+
+```bash
+# 完整启动流程
+sudo service postgresql start
+sudo service redis-server start
+cd backend
+source .venv/bin/activate
+python main.py
+```
+
+### 启动成功标志
+
+看到以下日志表示启动成功：
+```
+✓ Redis 已连接: localhost:6379
+✓ 管理员账号已存在: admin
+[startup] db + scheduler + auth ready
+INFO:     Uvicorn running on http://0.0.0.0:8000
+```
+
+## ✅ 功能测试
+
+```bash
+# 1. 健康检查
+curl http://localhost:8000/api/health
+# 应返回: {"ok":true,"akshare":true,"redis":true,"auth":true}
+
+# 2. 登录测试
+curl -X POST http://localhost:8000/api/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"username":"admin","password":"admin123"}'
+# 应返回 Token
+
+# 3. 运行完整测试
+python test_core_features.py
+```
+
+## 🔧 常见问题排查
+
+### 问题 1: Redis 连接失败
+```
+✗ Redis 连接失败，缓存已禁用
+```
+**解决**:
+```bash
+sudo service redis-server start
+redis-cli ping
+```
+
+### 问题 2: 数据库连接失败
+```
+connection refused
+```
+**解决**:
+```bash
+sudo service postgresql start
+psql -U postgres -c "SELECT 1;"
+```
+
+### 问题 3: 密码认证失败
+```
+password authentication failed
+```
+**解决**:
+```bash
+sudo -u postgres psql -c "ALTER USER postgres PASSWORD 'your_password';"
+# 然后在 .env 中设置相同的密码
+```
+
+### 问题 4: 模块未找到
+```
+ModuleNotFoundError: No module named 'redis'
+```
+**解决**:
+```bash
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+### 问题 5: 401 Unauthorized
+```
+{"detail":"未认证，请先登录"}
+```
+**解决**:
+```bash
+# 先登录获取 Token
+curl -X POST http://localhost:8000/api/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"username":"admin","password":"admin123"}'
+
+# 使用 Token 访问
+curl -X GET http://localhost:8000/api/admin/status \
+  -H "Authorization: Bearer <返回的token>"
+```
+
+### 问题 6: 用户表不存在
+```
+relation "users" does not exist
+```
+**解决**:
+```bash
+python cli.py init
+```
+
+## 📝 首次部署完整流程
+
+```bash
+# 1. 系统依赖
+sudo apt update
+sudo apt install -y postgresql redis-server
+
+# 2. 启动服务
+sudo service postgresql start
+sudo service redis-server start
+
+# 3. 配置数据库密码
+sudo -u postgres psql -c "ALTER USER postgres PASSWORD 'your_password';"
+
+# 4. Python 环境
+cd backend
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+
+# 5. 配置环境变量
+cp .env.example .env
+nano .env  # 编辑 PG_PASSWORD, SECRET_KEY 等
+
+# 6. 初始化数据库
+python cli.py init
+
+# 7. 启动服务
+python main.py
+
+# 8. 测试
+python test_core_features.py
+```
+
+## 🚀 一键启动脚本（WSL）
+
+创建 `start.sh`:
+```bash
+#!/bin/bash
+sudo service postgresql start
+sudo service redis-server start
+cd /mnt/e/project/stock_cs_v1/backend  # 修改为实际路径
+source .venv/bin/activate
+python main.py
+```
+
+使用:
+```bash
+chmod +x start.sh
+./start.sh
+```
+
+## 📞 获取帮助
+
+如果以上方法都无法解决问题:
+1. 查看详细文档: `backend/UPGRADE_GUIDE.md`
+2. 查看配置说明: `backend/ENV_CONFIG.md`
+3. 查看实现总结: `三大核心功能实现总结.md`