opsxsql/merge-analysis-report.md

优化包合并分析报告

📋 总览

文件	行数变化	冲突模型引用	安全合并?	策略
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 字段：

query_type = Column(String(20), nullable=True)  # 新增：查询类型

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

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

---

🗂️ 推荐执行顺序

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

# 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 字段：

query_type = Column(String(20), nullable=True)  # 查询类型（SELECT/INSERT/UPDATE/DELETE等）

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

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

1. 新增 User 字段（JSON 权限相关）：

   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 方法：

   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 类存在即可。