239 lines
11 KiB
Markdown
239 lines
11 KiB
Markdown
# 优化包合并分析报告
|
||
|
||
## 📋 总览
|
||
|
||
| 文件 | 行数变化 | 冲突模型引用 | 安全合并? | 策略 |
|
||
|------|---------|------------|----------|------|
|
||
| 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 类存在即可。
|