# TSP智能助手部署与更新指南

## 📋 目录
- [部署策略](#部署策略)
- [版本控制](#版本控制)
- [更新方式](#更新方式)
- [环境管理](#环境管理)
- [备份与回滚](#备份与回滚)
- [监控与通知](#监控与通知)
- [最佳实践](#最佳实践)

## 🚀 部署策略

### 1. 多环境部署架构

```
开发环境 (Development)
    ↓ 测试通过
测试环境 (Staging)  
    ↓ 验证通过
生产环境 (Production)
```

### 2. 环境配置

| 环境 | 路径 | 服务名 | 自动重启 | 用途 |
|------|------|--------|----------|------|
| development | `./dev_deploy` | 无 | 否 | 本地开发 |
| staging | `/opt/tsp_assistant_staging` | `tsp_assistant_staging` | 是 | 功能测试 |
| production | `/opt/tsp_assistant` | `tsp_assistant` | 是 | 生产服务 |

## 🔄 版本控制

### 版本号规则
- **主版本号 (Major)**: 重大功能变更，可能不兼容
- **次版本号 (Minor)**: 新功能添加，向后兼容
- **修订号 (Patch)**: 错误修复，向后兼容

### 版本管理命令

```bash
# 查看当前版本
python version.py version

# 增加版本号
python version.py increment --type patch    # 1.2.0 -> 1.2.1
python version.py increment --type minor    # 1.2.0 -> 1.3.0
python version.py increment --type major    # 1.2.0 -> 2.0.0

# 添加变更日志
python version.py changelog --message "修复系统性能趋势图表显示问题"

# 创建Git标签
python version.py tag --message "Release v1.2.0"
```

## 🔧 更新方式

### 1. 热更新 (Hot Update)
**适用场景**: 前端文件、配置文件、非核心Python文件
**优点**: 无需重启服务，用户体验好
**缺点**: 有限制，不能更新核心逻辑

```bash
# 热更新
python scripts/update_manager.py hot-update --source ./new_version --environment production
```

**支持热更新的文件**:
- `src/web/static/js/dashboard.js`
- `src/web/static/css/style.css`
- `src/web/templates/dashboard.html`
- `src/web/app.py` (部分)
- 配置文件

### 2. 完整更新 (Full Update)
**适用场景**: 核心逻辑变更、数据库结构变更、依赖更新
**优点**: 完整更新，确保一致性
**缺点**: 需要重启服务

```bash
# 完整更新
python scripts/update_manager.py full-update --source ./new_version --environment production
```

### 3. 自动更新 (Auto Update)
**智能选择**: 优先尝试热更新，失败则进行完整更新

```bash
# 自动更新
python scripts/update_manager.py auto-update --source ./new_version --environment production
```

## 🌍 环境管理

### 部署到不同环境

```bash
# 开发环境
python scripts/update_manager.py auto-update --source ./new_version --environment development

# 测试环境
python scripts/update_manager.py auto-update --source ./new_version --environment staging

# 生产环境
python scripts/update_manager.py auto-update --source ./new_version --environment production
```

### 环境检查

```bash
# 检查更新可用性
python scripts/update_manager.py check --source ./new_version --environment production
```

## 💾 备份与回滚

### 自动备份
- 每次更新前自动创建备份
- 备份包含应用文件和数据库
- 备份信息记录在 `backup_info.json`

### 手动备份

```bash
# 创建备份
python scripts/update_manager.py create-backup --environment production
```

### 回滚操作

```bash
# 列出所有备份
python scripts/update_manager.py list-backups

# 回滚到指定备份
python scripts/update_manager.py rollback --backup tsp_assistant_backup_20250916_163000 --environment production
```

### 备份信息
每个备份包含：
- 应用文件完整副本
- 数据库文件
- 版本信息
- Git提交哈希
- 备份时间戳

## 📊 监控与通知

### 健康检查
- 更新后自动执行健康检查
- 检查服务是否正常启动
- 验证API接口可用性

### 通知机制
- 更新成功/失败通知
- 回滚操作通知
- 系统状态监控

## 🎯 最佳实践

### 1. 更新流程

```bash
# 1. 开发完成，提交代码
git add .
git commit -m "feat: 添加新功能"
git push

# 2. 更新版本号
python version.py increment --type minor
python version.py changelog --message "添加新功能"

# 3. 创建发布标签
python version.py tag --message "Release v1.4.0"

# 4. 部署到测试环境
python scripts/update_manager.py auto-update --source . --environment staging

# 5. 测试验证通过后，部署到生产环境
python scripts/update_manager.py auto-update --source . --environment production
```

### 1.1. 飞书集成部署前准备

```bash
# 1. 配置飞书应用
# - 在飞书开放平台创建企业自建应用
# - 获取app_id和app_secret
# - 配置应用权限（读取多维表格）

# 2. 更新配置文件
# 编辑 config/integrations_config.json
{
  "feishu": {
    "app_id": "your-app-id",
    "app_secret": "your-app-secret", 
    "app_token": "your-app-token",
    "table_id": "your-table-id",
    "status": "active"
  }
}

# 3. 初始化数据库（包含新字段）
python init_database.py

# 4. 测试飞书连接
# 访问主仪表板的"飞书同步"标签页
# 点击"测试连接"验证配置
```

### 2. 安全更新

```bash
# 生产环境更新前先备份
python scripts/update_manager.py create-backup --environment production

# 使用自动更新（包含回滚机制）
python scripts/update_manager.py auto-update --source ./new_version --environment production
```

### 3. 紧急回滚

```bash
# 快速回滚到最新备份
python scripts/update_manager.py rollback --backup $(python scripts/update_manager.py list-backups | head -1 | cut -d' ' -f2) --environment production
```

### 4. 版本管理最佳实践

- **开发阶段**: 使用patch版本号
- **功能完成**: 使用minor版本号
- **重大变更**: 使用major版本号
- **每次发布**: 创建Git标签
- **重要更新**: 记录详细变更日志

## 🛠️ 工具集成

### CI/CD 集成

```yaml
# GitHub Actions 示例
name: Deploy TSP Assistant
on:
  push:
    tags: ['v*']
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Deploy to Staging
        run: |
          python scripts/update_manager.py auto-update --source . --environment staging
      - name: Run Tests
        run: |
          # 运行自动化测试
      - name: Deploy to Production
        if: success()
        run: |
          python scripts/update_manager.py auto-update --source . --environment production
```

### Docker 集成

```dockerfile
# Dockerfile 示例
FROM python:3.9-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
EXPOSE 5000
CMD ["python", "start_dashboard.py"]
```

## 🚨 故障处理

### 常见问题

1. **更新失败**
   - 检查依赖是否正确安装
   - 验证数据库迁移是否成功
   - 查看服务日志

2. **回滚失败**
   - 确认备份文件完整性
   - 检查文件权限
   - 验证服务配置

3. **健康检查失败**
   - 检查服务是否正常启动
   - 验证端口是否被占用
   - 查看应用日志

4. **飞书集成问题**
   - 检查飞书应用权限配置
   - 验证app_token和table_id是否正确
   - 确认网络连接和API访问权限
   - 查看飞书同步日志

5. **数据库字段迁移失败**
   - 检查数据库连接状态
   - 验证字段映射配置
   - 确认数据库权限
   - 查看数据库初始化日志

### 紧急处理

```bash
# 停止服务
sudo systemctl stop tsp_assistant

# 手动回滚
sudo rm -rf /opt/tsp_assistant
sudo cp -r ./backups/tsp_assistant_backup_20250916_163000/app /opt/tsp_assistant
sudo chown -R www-data:www-data /opt/tsp_assistant
sudo systemctl start tsp_assistant
```

## 📝 更新记录

### v1.4.0 (2025-09-19)
- ✅ 飞书集成功能：支持飞书多维表格数据同步
- ✅ 页面功能合并：飞书同步页面合并到主仪表板
- ✅ 数据库架构优化：扩展工单表字段，支持飞书数据
- ✅ 代码重构优化：大文件拆分，降低运行风险
- ✅ 字段映射完善：智能映射飞书字段到本地数据库
- ✅ 数据库初始化改进：集成字段迁移到初始化流程

### v1.3.0 (2025-09-17)
- ✅ 数据库架构优化：MySQL主数据库+SQLite备份系统
- ✅ 工单详情API修复：解决数据库会话管理问题
- ✅ 备份管理系统：自动备份MySQL数据到SQLite
- ✅ 数据库状态监控：实时监控MySQL和SQLite状态
- ✅ 备份管理API：支持数据备份和恢复操作

### v1.2.0 (2025-09-16)
- ✅ 系统设置扩展：API管理、模型参数配置、端口管理
- ✅ 真实数据分析：修复性能趋势图表显示
- ✅ 工单AI建议功能
- ✅ 知识库搜索优化
- ✅ Agent管理改进

### v1.1.0 (2025-09-16)
- ✅ 工单AI建议功能
- ✅ 知识库搜索优化
- ✅ Agent管理改进

### v1.0.0 (2024-01-01)
- ✅ 初始版本发布

---

**注意**: 生产环境更新前请务必在测试环境验证，并确保有可用的备份。