# 优化包合并分析报告

## 📋 总览

| 文件 | 行数变化 | 冲突模型引用 | 安全合并? | 策略 |
|------|---------|------------|----------|------|
| models/user.py | 23→299 (+276) | ⚠️ **核心冲突** | ❌ | 手动合并 |
| models/workflow.py | 55→362 (+307) | ✅ 无 | ✅ | 直接覆盖 |
| services/workflow_engine.py | 359→1319 (+960) | ✅ 无 | ✅ | 直接覆盖 |
| services/query_service.py | 709→1253 (+544) | ✅ 无 | ✅ | 直接覆盖 |
| services/audit_engine.py | 234→790 (+556) | ✅ 无 | ✅ | 直接覆盖 |
| services/ticket_executor.py | 1384→1688 (+304) | ✅ 无 | ✅ | 直接覆盖 |
| api/v1/endpoints/ticket.py | 747→1029 (+282) | ⚠️ AuditLog引用 | ✅ | 直接覆盖 |
| api/v1/endpoints/query.py | 226→426 (+200) | ⚠️ AuditLog引用 | ✅ | 直接覆盖 |
| api/v1/endpoints/user.py | 116→116 (0) | ⚠️ AuditLogService | ✅ | 直接覆盖 |

---

## 🔴 冲突分析

### 冲突1：`user_groups` 表名冲突

| 维度 | 我们的版本 | 优化包版本 |
|------|-----------|-----------|
| **位置** | `models/instance_group.py` | `models/user.py` |
| **类型** | `Table()` 关联表 | `class UserGroup(Base)` ORM模型 |
| **表名** | `user_groups` | `user_groups` |
| **列** | user_id, group_id, permissions | id, name, description, group_permissions, ... |
| **用途** | User ↔ InstanceGroup 多对多关联 | 独立的用户组权限管理实体 |

**冲突本质**：两个完全不同的数据库表结构映射到同一个表名。优化包的 `UserGroup` 是一个完整的权限组系统，我们的 `user_groups` 只是一个简单的关联表。

### 冲突2：AuditLog 双重定义

| 维度 | 我们的版本 (`models/audit_log.py`) | 优化包版本 (`models/user.py`) |
|------|----------------------------------|-------------------------------|
| **表名** | `audit_logs` | `audit_logs` |
| **字段风格** | 运维审计（target_type, query_content, db_type） | 通用审计（resource_type, before_data, after_data） |
| **关系** | 无 relationship | `user = relationship("User", ...)` |

**关键发现**：优化包的 `ticket.py` 和 `query.py` 都 `from app.models.audit_log import AuditLog`（即使用的是我们的版本），而不是从 `models.user` 导入！

### 冲突3：新增模型类（无冲突但需数据库迁移）

优化包 `models/user.py` 新增了：
- `UserGroup` — 用户组模型（表名与我们的关联表冲突）
- `UserGroupMember` — 用户组成员关联表
- `AuditLog` — 审计日志（与 `models/audit_log.py` 重复定义）

---

## 📁 逐文件分析

### 1. models/user.py — ⚠️ 需手动合并

**差异概要**：
- User 模型新增了 4 个 JSON 权限字段（data_source_permissions, custom_permissions, column_permissions, permissions_updated_at）
- User 模型新增了 5 个 relationship（tickets, approvals, audit_logs, query_histories, user_groups）
- User 模型新增了 5 个方法（has_permission, has_data_source_permission, get_allowed_columns, to_dict, __repr__）
- 新增 3 个类：UserGroup, UserGroupMember, AuditLog

**冲突点**：
- `secondary="user_groups"` — 与 instance_group.py 的 Table 定义冲突
- `user_groups = relationship("UserGroup", ...)` — 引用同文件 UserGroup
- `audit_logs = relationship("AuditLog", ...)` — 引用同文件 AuditLog
- `to_dict()` 中 `self.user_groups` — 引用 UserGroup relationship

**合并策略**：
```
✅ 直接采纳：User 模型的 JSON 权限字段（4个新字段）
✅ 直接采纳：User 的便捷方法（has_permission, to_dict 等）
⚠️ 需修改：User.groups 的 secondary 保持 "user_groups"（不改，与 instance_group.py 兼容）
❌ 不采纳：User.user_groups relationship（引用冲突的 UserGroup）
❌ 不采纳：User.tickets/approvals/audit_logs/query_histories（跨模型耦合，按需添加）
❌ 不采纳：UserGroup 类（表名冲突）
❌ 不采纳：UserGroupMember 类（依赖 UserGroup）
❌ 不采纳：AuditLog 类（已在 audit_log.py 独立定义）
⚠️ to_dict() 中的 user_groups 引用需要改为 groups 或移除
```

### 2. models/workflow.py — ✅ 可安全覆盖

**差异概要**：
- WorkflowDefinition 新增 category, updated_at, created_by, flow_config, trigger_conditions 字段
- 新增 WorkflowVersion 类（版本控制）
- WorkflowStep 大幅增强（description, approver_assignment, entry_conditions, transition_conditions, field_permissions）
- TicketApproval 大幅增强（workflow_id, version_id, step_type, actual_approver_id, transfer 信息, 超时标记）
- 新增 WorkflowExecutionLog 类（执行日志）

**新增依赖**：`json`, `UniqueConstraint`, `JSON` — 标准库/SQLAlchemy

**安全评估**：无冲突模型引用，纯功能增强。✅

### 3. services/workflow_engine.py — ✅ 可安全覆盖

**差异概要**：
- 从简单引擎升级为支持条件审批、超时策略、中断恢复的完整引擎
- 新增 WorkflowStatus/ApprovalAction/TimeoutStrategy 枚举
- 新增 ConditionResult/ApproverAssignment 数据类
- 引擎核心方法大幅扩展

**import 检查**：
- `from app.models.workflow import (WorkflowDefinition, WorkflowStep, WorkflowVersion, TicketApproval, WorkflowExecutionLog)` — 全部来自 workflow.py
- `from app.models.user import User` — 只用 User 基础字段
- 无冲突模型引用

### 4. services/query_service.py — ✅ 可安全覆盖

**差异概要**：查询服务增强，支持更多数据库类型和查询优化。

**import 检查**：
- `from app.models.instance import Instance` — ✅
- `from app.schemas.query import UnifiedQueryResult` — ✅
- `from app.services.db_connector import DBConnector` — ✅
- 无冲突模型引用

### 5. services/audit_engine.py — ✅ 可安全覆盖

**差异概要**：审计引擎增强，新增枚举和条件判断。

**import 检查**：
- 无外部模型导入，仅标准库 + typing
- 无冲突模型引用

### 6. services/ticket_executor.py — ✅ 可安全覆盖

**差异概要**：工单执行器增强，支持更多 SQL 解析和执行策略。

**import 检查**：
- `from app.models.instance import Instance` — ✅
- `from app.models.ticket import Ticket` — ✅
- `from app.services.sql_analyzer import SQLAnalyzer, SQLType` — ✅
- 无冲突模型引用

### 7. api/v1/endpoints/ticket.py — ✅ 可安全覆盖

**AuditLog 使用情况**：
- `from app.models.audit_log import AuditLog` — ✅ 使用我们的独立 AuditLog
- `AuditLog.target_type`, `AuditLog.target_id`, `AuditLog.created_at` — ✅ 我们模型有这些字段
- `AuditLogService.log(target_type=..., detail=...)` — ✅ audit_log_service.py 两版完全相同

**注意**：ticket.py 使用的 AuditLog 字段（target_type, target_id, detail, db_type, status）全部存在于我们的 `models/audit_log.py`。

### 8. api/v1/endpoints/query.py — ✅ 可安全覆盖（需注意字段）

**AuditLog 使用情况**：
- `from app.models.audit_log import AuditLog` — ✅ 使用我们的独立 AuditLog
- 直接创建 `AuditLog(...)` 实例，使用字段：
  - ✅ 我们模型有：user_id, username, action, target_type, target_id, instance_name, db_type, database_name, query_content, execution_time_ms, rows_affected, result_status, detail
  - ⚠️ **`query_type`** — 我们模型没有这个字段！
  - ⚠️ **`status`** — 我们模型没有 `status`，只有 `result_status`

**需要的处理**：在我们的 `models/audit_log.py` 中新增 `query_type` 字段：
```python
query_type = Column(String(20), nullable=True)  # 新增：查询类型
```

### 9. api/v1/endpoints/user.py — ✅ 可安全覆盖

**差异**：两版完全相同（0 差异），优化包版本多了 AuditLogService 引用但代码一致。

---

## 🗂️ 推荐执行顺序

### 第一阶段：无冲突文件直接覆盖（7个文件）

```bash
# 1. models/workflow.py
# 2. services/workflow_engine.py
# 3. services/query_service.py
# 4. services/audit_engine.py
# 5. services/ticket_executor.py
# 6. api/v1/endpoints/ticket.py
# 7. api/v1/endpoints/user.py (两版相同，跳过)
```

### 第二阶段：小修复

在 `models/audit_log.py` 新增 `query_type` 字段：
```python
query_type = Column(String(20), nullable=True)  # 查询类型（SELECT/INSERT/UPDATE/DELETE等）
```

### 第三阶段：手动合并 models/user.py

**保留我们现有结构**，只合并以下安全内容：

1. **新增 User 字段**（JSON 权限相关）：
   ```python
   data_source_permissions = Column(JSON, nullable=True, default=list)
   custom_permissions = Column(JSON, nullable=True, default=dict)
   column_permissions = Column(JSON, nullable=True, default=dict)
   permissions_updated_at = Column(DateTime, nullable=True)
   ```

2. **新增 User 方法**：
   ```python
   def has_permission(self, action: str) -> bool: ...
   def has_data_source_permission(self, ...) -> bool: ...
   def get_allowed_columns(self, ...) -> list: ...
   def to_dict(self, include_sensitive=False) -> dict: ...
   ```

3. **不合并的内容**：
   - `UserGroup` 类 → 如果需要用户组功能，必须改名或用不同表名
   - `UserGroupMember` 类 → 同上
   - `AuditLog` 类 → 已有独立文件，不重复定义
   - `User.user_groups` relationship → 依赖冲突的 UserGroup
   - `User.audit_logs` relationship → 需要评估是否添加（跨模型耦合）
   - `User.tickets`/`approvals`/`query_histories` → 按需添加

4. **to_dict 方法调整**：
   - 将 `self.user_groups` 改为 `self.groups`（匹配现有 InstanceGroup 关系）

### 第四阶段：数据库迁移

新增/修改的数据库表：
- `workflow_versions` — 新增表
- `workflow_execution_logs` — 新增表
- `workflow_definitions` — 新增 category, updated_at, created_by, flow_config, trigger_conditions 字段
- `workflow_steps` — 新增多个字段
- `ticket_approvals` — 新增多个字段
- `audit_logs` — 新增 query_type 字段
- `users` — 新增 4 个 JSON 权限字段

---

## ⚠️ 风险提示

1. **UserGroup/user_groups 冲突**：如果未来需要优化包的用户组功能，需要：
   - 将优化包的 `UserGroup` 改表名为 `user_permission_groups`
   - 或将我们的关联表 `user_groups` 改名为 `user_instance_groups`
   - 同时更新所有外键和 relationship 引用

2. **AuditLog 双定义**：SQLAlchemy 的 metadata 中如果同时注册两个同名 `__tablename__` 的类会报错。只要不同时 import 就没问题。确保不 import `models/user.py` 中的 AuditLog 即可。

3. **workflow.py 的 relationship 指向 "User"**：通过字符串引用，SQLAlchemy 在运行时解析。只要所有模型在 metadata 中注册时 User 类存在即可。