# com-luck-imp

**Repository Path**: lwhou/com-luck-imp

## Basic Information

- **Project Name**: com-luck-imp
- **Description**: 主要对Excel、CSV和JSON等数据进行导入，同时对导入的数据进行验证。
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: develop
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-10-24
- **Last Updated**: 2026-02-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# com-luck-imp - 通用数据导入平台

## 介绍
`com-luck-imp` 是一个强大的通用数据导入与验证平台，旨在解决复杂的数据集成问题。它支持从多种文件格式（Excel, CSV, JSON）解析数据，经过灵活的验证和清洗规则后，将数据导入到各种关系型数据库或通过 API 推送至下游系统。

平台特别针对国产化环境进行了适配，支持 **人大金仓 (KingbaseES)** 等国产数据库，并提供了精细的 Schema 配置支持。

## 核心功能

### 1. 多源数据解析
- **Excel**: 支持 `.xlsx`, `.xls` 格式，自动识别表头。
- **CSV**: 支持多种编码（UTF-8, GBK 等），自动处理分隔符。
- **JSON**: 支持复杂嵌套结构的 JSON 数据解析。

### 2. 广泛的数据库支持
- **主流数据库**: MySQL, PostgreSQL, SQLite, Oracle, SQL Server。
- **国产数据库**: **人大金仓 (KingbaseES)** (完整支持非 public Schema 配置)。
- **Schema 支持**: 针对 PostgreSQL 和 Kingbase，支持配置特定的 Schema（模式），解决多租户或特定业务场景的数据隔离问题。

### 3. 强大的验证与转换引擎
- **基础验证**: 必填校验、数据类型校验、长度校验、正则校验。
- **数据转换**: 
  - 动态默认值（UUID, 当前时间, 序列号占位符）。
  - 字符串处理（大小写转换, 空格清理）。
- **动态字典映射**: 
  - **数据库字典**: 根据源数据查询数据库表获取目标值（支持多条件过滤、Schema 指定）。
  - **API 字典**: 调用外部 API 获取映射关系。

## 对接文档

- [用户使用手册.md](file:///d:/work/source/python-project/com-luck-imp/doc/%E7%94%A8%E6%88%B7%E4%BD%BF%E7%94%A8%E6%89%8B%E5%86%8C.md)
- [离线Linux部署手册.md](file:///d:/work/source/python-project/com-luck-imp/doc/%E7%A6%BB%E7%BA%BFLinux%E9%83%A8%E7%BD%B2%E6%89%8B%E5%86%8C.md)

### 4. 灵活的导入策略
- **写入模式**: 支持仅插入、仅更新、插入或更新（Upsert）、删除后插入。
- **事务管理**: 支持整批提交或逐行提交，确保数据一致性。
- **错误处理**: 详细的行级错误报告，支持导出错误数据以便修正后重试。

### 5. 任务管理与监控
- **异步执行**: 后台执行耗时导入任务，不阻塞前端操作。
- **进度追踪**: 实时查看导入进度、成功/失败行数。
- **日志审计**: 完整的操作日志和系统日志。

## 架构设计

### 1. 系统架构
平台采用经典的分层架构设计，主要包含以下层次：
- **表现层 (Presentation Layer)**: 基于 Flask 的 Web UI 和 RESTful API，提供用户交互和外部集成能力。
- **业务逻辑层 (Business Layer)**: 包含核心的导入服务、模板管理、数据验证、任务调度等逻辑。
- **数据访问层 (Data Access Layer)**: 封装了对元数据存储（SQLite）和目标数据源（MySQL, PostgreSQL, Oracle, KingbaseES 等）的访问操作。
- **核心引擎 (Core Engines)**:
  - **解析引擎**: 负责多格式文件的读取与标准化（Pandas/OpenPyXL）。
  - **验证引擎**: 基于配置规则对数据进行清洗和校验。
  - **执行引擎**: 负责将处理后的数据写入目标系统。

### 2. 核心模块
- **luck.imp (导入核心模块)**:
  - `controller`: 处理 HTTP 请求。
  - `service`: 协调解析、验证和导入流程。
  - `parsers`: 实现 Excel, CSV, JSON 的具体解析逻辑。
  - `validators`: 实现数据类型、正则、字典映射等验证逻辑。
  - `engines`: 实现 Database 和 API 的数据写入逻辑。
- **luck.sys (系统模块)**:
  - 负责用户认证 (Auth)、权限管理和系统级配置。
- **luck.util (工具模块)**:
  - 提供数据库连接池、日志、加密、通用工具类。

### 3. 数据处理流程
1.  **上传**: 用户上传文件，系统存储至临时区。
2.  **解析**: 解析引擎根据模板配置（表头行、数据行）读取文件内容。
3.  **验证**: 逐行执行验证规则（必填、类型、字典转换），生成验证报告。
4.  **转换**: 执行数据转换（默认值填充、格式化）。
5.  **执行**: 执行引擎根据策略（Insert/Update/Upsert）将数据写入目标库。
6.  **反馈**: 实时更新任务状态，生成最终的成功/失败统计。

### 4. 架构图

```mermaid
graph TD
    Client[用户/客户端] -->|HTTP/HTTPS| Web[Web 界面 / API]
    
    subgraph "LuckImp 应用服务"
        direction TB
        
        Layer_Web[表现层]
        Layer_Service[业务逻辑层]
        Layer_Core[核心引擎层]
        Layer_Data[数据访问层]
        
        Web --> Layer_Web
        
        Layer_Web -->|路由分发| Layer_Service
        
        subgraph "Layer_Service (业务逻辑)"
            Svc_Auth[认证服务]
            Svc_Task[任务调度服务]
            Svc_Imp[导入流程服务]
            Svc_Tpl[模板管理服务]
        end
        
        subgraph "Layer_Core (核心引擎)"
            Engine_Parse[解析引擎 (Pandas/Excel)]
            Engine_Validate[验证/转换引擎]
            Engine_Exec[执行/写入引擎]
        end
        
        Svc_Imp --> Engine_Parse
        Engine_Parse --> Engine_Validate
        Engine_Validate --> Engine_Exec
        
        subgraph "Layer_Data (数据访问)"
            DAO_Meta[元数据 DAO]
            DAO_Source[数据源 DAO]
        end
        
        Layer_Service --> Layer_Data
        Engine_Exec --> Layer_Data
    end
    
    subgraph "外部系统 & 存储"
        DB_Meta[(SQLite 元数据库)]
        DB_Target[(目标数据库\nMySQL/PG/Oracle/Kingbase)]
        API_Target[第三方 API]
        FileSystem[文件存储]
    end
    
    DAO_Meta --> DB_Meta
    DAO_Source --> DB_Target
    Engine_Exec --> API_Target
    Engine_Parse --> FileSystem
```

### 5. 技术栈详情
- **后端框架**: Python Flask
- **数据处理**: Pandas, NumPy, OpenPyXL
- **任务调度**: APScheduler
- **数据库驱动**: 
  - `psycopg2-binary` (PostgreSQL / Kingbase)
  - `PyMySQL` (MySQL)
  - `oracledb` (Oracle)
  - `pyodbc` (SQL Server)
  - `jaydebeapi` + `ojdbc*.jar` (Oracle JDBC Fallback)
- **前端技术**: Bootstrap 4, jQuery, DataTables
- **部署方式**: Docker, Windows Service, Executable (PyInstaller)

## 安装教程

### 1. 环境准备
确保已安装 Python 3.8+ 环境。

### 2. 安装依赖
```bash
pip install -r requirements.txt
```
*注意：对于 Oracle 或 SQL Server，可能需要安装额外的系统级驱动库。*

### 3. Oracle 数据库特别说明 (12c+ 支持)
本服务优先使用 `python-oracledb` (Thin 模式) 连接 Oracle。
如果遇到 **DPY-3015** 错误（旧密码验证器不兼容），服务会自动降级尝试使用 **JDBC** 连接。

**启用 JDBC 支持步骤：**
1. 确保服务器已安装 Java 运行时 (JRE/JDK 8+)。
2. 将 Oracle JDBC 驱动包 (如 `ojdbc8.jar`) 放入项目根目录下的 `drivers` 文件夹中。
   - 也可以通过环境变量 `ORACLE_JDBC_JAR` 指定 jar 包绝对路径。
3. 在数据源配置中，填写 `JDBC URL` (例如 `jdbc:oracle:thin:@//host:port/service`)。

### 4. 初始化配置
- 检查 `luck/config/LuckConfig.json` (如果存在) 进行基础配置。
- 默认使用 SQLite 作为系统元数据存储 (`luck/config/Luck.db`)，无需额外部署数据库即可启动。

### 4. 启动服务
**Windows:**
双击 `start.bat` 或在命令行运行：
```bash
python start.py
```

**Linux/Mac:**
```bash
python start.py
```

启动后默认访问地址：
- `http://localhost:5011`（端口来自 `luck/config/LuckConfig.json` 的 server_port）

## 使用说明

1.  **配置数据源**: 在"数据源管理"中添加目标数据库连接。如果是 Kingbase/PostgreSQL，请注意填写正确的 Schema。
2.  **创建模板**: 在"模板管理"中定义导入规则，设置源字段与目标字段的映射关系。
3.  **上传文件**: 在"文件管理"或导入入口上传待导入的数据文件。
4.  **执行导入**: 选择模板和文件，发起导入任务。
5.  **查看结果**: 在"任务历史"中查看导入结果和错误报告。

## 参与贡献

1.  Fork 本仓库
2.  新建 Feat_xxx 分支
3.  提交代码
4.  新建 Pull Request