v1.0定版

README_STARTUP.md

@@ -0,0 +1,319 @@
+# 🚀 启动指南
+
+## 快速开始
+
+### 方式一：本地开发 (推荐)
+
+**前置条件：**
+- Python 3.9+ 
+- Node.js 18+
+- PostgreSQL 14+ (需要单独启动)
+
+**Windows PowerShell:**
+```powershell
+.\start.ps1
+```
+
+**Windows CMD:**
+```cmd
+start.bat
+```
+
+**Mac/Linux:**
+```bash
+chmod +x start.sh
+./start.sh
+```
+
+然后选择选项 `1` 进行本地开发。
+
+**访问地址：**
+- 前端: http://localhost:5173
+- 后端: http://localhost:8000
+- API文档: http://localhost:8000/docs
+
+---
+
+### 方式二：Docker Compose (完全隔离)
+
+**前置条件：**
+- Docker Desktop (包含 Docker Compose)
+
+**启动：**
+```powershell
+.\start-docker.ps1
+```
+
+或直接使用 docker-compose:
+```bash
+docker-compose up --build
+```
+
+**访问地址：**
+- 前端: http://localhost:3000
+- 后端: http://localhost:8000
+- API文档: http://localhost:8000/docs
+- 数据库: localhost:5432 (用户: pharma / 密码: pharma123)
+
+---
+
+## 详细说明
+
+### 方式一：本地开发
+
+#### Windows
+
+1. **启动脚本：**
+   - PowerShell: `.\start.ps1`
+   - CMD: `start.bat`
+
+2. **脚本会自动：**
+   - 检查 Python 和 Node.js
+   - 创建虚拟环境 (如需要)
+   - 安装依赖包
+   - 在新窗口启动后端和前端
+
+3. **手动启动（可选）：**
+
+   **后端：**
+   ```powershell
+   cd backend
+   python -m venv venv
+   .\venv\Scripts\Activate.ps1
+   pip install -r requirements.txt
+   uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
+   ```
+
+   **前端（新终端）：**
+   ```powershell
+   cd frontend
+   npm install
+   npm run dev
+   ```
+
+4. **PostgreSQL 配置：**
+   - 确保 PostgreSQL 已启动
+   - 默认连接: `postgresql://pharma:pharma123@localhost/pharma_news`
+   - 如需修改，编辑 `.env` 文件
+
+#### Mac/Linux
+
+```bash
+# 给脚本执行权限
+chmod +x start.sh
+
+# 运行脚本
+./start.sh
+```
+
+---
+
+### 方式二：Docker Compose
+
+#### 基本命令
+
+```bash
+# 启动所有服务（首次需要构建）
+docker-compose up
+
+# 重新构建并启动
+docker-compose up --build
+
+# 在后台运行
+docker-compose up -d
+
+# 查看日志
+docker-compose logs -f
+
+# 查看特定服务日志
+docker-compose logs -f backend
+docker-compose logs -f frontend
+
+# 停止服务
+docker-compose down
+
+# 完全清理（包括数据）
+docker-compose down -v
+```
+
+#### 常见问题
+
+**问：如何修改端口？**
+
+编辑 `docker-compose.yml`:
+```yaml
+ports:
+  - "8080:8000"  # 后端: 外部:内部
+  - "3001:80"    # 前端: 外部:内部
+```
+
+**问：如何在容器内执行命令？**
+
+```bash
+# 后端
+docker-compose exec backend python -m alembic upgrade head
+
+# 前端
+docker-compose exec frontend npm run build
+```
+
+**问：如何清理 Docker 数据？**
+
+```bash
+# 停止并删除所有容器和卷
+docker-compose down -v
+
+# 重新启动会创建新的数据库
+docker-compose up --build
+```
+
+---
+
+## 环境变量配置
+
+### 后端 (.env)
+
+```env
+# PostgreSQL
+DATABASE_URL=postgresql://pharma:pharma123@localhost:5432/pharma_news
+
+# LLM 服务
+LLM_API_KEY=your_api_key
+LLM_MODEL=gpt-4
+
+# 其他配置
+LOG_LEVEL=INFO
+```
+
+### 前端 (.env.local)
+
+```env
+VITE_API_BASE_URL=http://localhost:8000/api
+```
+
+---
+
+## 故障排除
+
+### 后端无法启动
+
+```bash
+# 1. 检查端口是否被占用
+netstat -ano | findstr :8000  # Windows
+lsof -i :8000                  # Mac/Linux
+
+# 2. 检查 Python 和依赖
+python --version
+pip list | grep fastapi
+
+# 3. 检查数据库连接
+# 确保 PostgreSQL 已启动，用户名和密码正确
+```
+
+### 前端无法启动
+
+```bash
+# 1. 清理依赖
+rm -rf node_modules package-lock.json
+npm install
+
+# 2. 检查 Node 版本
+node --version
+npm --version
+
+# 3. 清理 Vite 缓存
+rm -rf dist .vite
+```
+
+### Docker 容器无法启动
+
+```bash
+# 查看详细错误日志
+docker-compose logs
+
+# 重建镜像
+docker-compose build --no-cache
+
+# 清理所有容器和镜像
+docker system prune -a
+```
+
+---
+
+## 开发建议
+
+### 热重载
+
+- **后端**: Uvicorn 自动热重载 (修改文件后自动重启)
+- **前端**: Vite 自动热重载 (修改代码后自动更新浏览器)
+
+### 调试
+
+**后端：**
+```python
+# 在代码中添加断点
+import pdb; pdb.set_trace()
+
+# 或使用 IDE 的调试功能
+```
+
+**前端：**
+- 使用浏览器 DevTools (F12)
+- VS Code Debugger (需要配置 launch.json)
+
+### 性能监测
+
+```bash
+# 后端性能
+docker-compose stats backend
+
+# 前端性能
+npm run build  # 检查构建体积
+```
+
+---
+
+## 生产部署
+
+### 使用 Docker
+
+```bash
+# 构建生产镜像
+docker-compose -f docker-compose.yml -f docker-compose.prod.yml build
+
+# 启动生产环境
+docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d
+```
+
+### 本地生产预览
+
+```bash
+# 后端
+uvicorn app.main:app --host 0.0.0.0 --port 8000
+
+# 前端
+npm run build
+npm run preview
+```
+
+---
+
+## 脚本文件说明
+
+| 文件 | 说明 | 环境 |
+|------|------|------|
+| `start.ps1` | 本地开发启动脚本 | Windows PowerShell |
+| `start.bat` | 本地开发启动脚本 | Windows CMD |
+| `start.sh` | 本地开发启动脚本 | Mac/Linux |
+| `start-docker.ps1` | Docker Compose 启动脚本 | Windows PowerShell |
+
+---
+
+## 更多帮助
+
+- FastAPI 文档: https://fastapi.tiangolo.com/
+- Vue.js 文档: https://vuejs.org/
+- Vite 文档: https://vitejs.dev/
+- PostgreSQL 文档: https://www.postgresql.org/docs/
+- Docker 文档: https://docs.docker.com/
+