# jksb-data-sync

**Repository Path**: wangxiang-technology/jksb-data-sync

## Basic Information

- **Project Name**: jksb-data-sync
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-27
- **Last Updated**: 2026-06-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 海垦大数据接口数据同步服务 — 技术方案规划

## 1. 项目概述

### 1.1 项目名称

**jksb-data-sync**（海垦大数据接口数据同步服务）

### 1.2 项目背景

为解决海垦集团大数据平台与其他厂商系统对接问题（对方仅提供接口方式），从源系统定时拉取、清洗、入库、补数、日志追溯，并提供权限控制、接口调用、任务调度、监控告警能力，建设本独立调度服务。

### 1.3 建设目标

- 独立部署、解耦核心业务系统
- 定时自动同步 + 手动触发补数
- 统一权限认证（Sa-Token）
- 分布式任务调度（XXL-Job）
- 完整日志、可追溯、可重跑
- 高可用、易运维、可扩展

## 2. 技术栈选型

### 2.1 核心框架

| 组件 | 版本 | 说明 |
|------|------|------|
| Spring Boot | 3.5.14 | 启动、依赖管理 |
| XXL-Job | 3.4.0 | 分布式任务调度中心 + 执行器 |
| Sa-Token | 1.45.0 | 权限认证、登录、路由拦截、Token 管理 |
| MyBatis-Plus | 3.5.16 | ORM、分页 |
| Spring HTTP Interface | 6.x | 远程接口调用（@PostExchange） |
| Redis | 6+ | Sa-Token 存储、分布式锁、缓存 |
| PostgreSQL | 15+ | 业务数据、任务日志 |

### 2.2 版本约束

```xml
Spring Boot: 3.5.14
XXL-Job: 3.4.0
Sa-Token: 1.45.0
MyBatis-Plus: 3.5.16
```

## 3. 系统架构设计

### 3.1 整体架构图

```
┌─────────────────┐     ┌─────────────────────────────┐
│  XXL-Job Admin  │────▶│    jksb-data-sync           │
│  （调度中心）      │     │    （执行器 / 主服务）         │
└─────────────────┘     └──────────┬──────────────────┘
                                    │
         ┌──────────────┬──────────┴──────────┬──────────────┐
         │              │                    │              │
    ┌────▼────┐    ┌────▼────┐          ┌────▼────┐    ┌────▼────┐
    │ Sa-Token│    │ HTTP Interface│          │PostgreSQL│    │  Redis  │
    │ 权限控制 │    │ 接口调用 │          │ 业务数据 │    │ 缓存/锁 │
    └─────────┘    └─────────┘          └─────────┘    └─────────┘
```

### 3.2 部署模式

| 组件 | 部署方式 |
|------|---------|
| XXL-Job Admin | 独立部署（单实例或集群） |
| jksb-data-sync | 独立部署（可多实例集群） |
| Redis | 独立部署（支持集群） |
| PostgreSQL | 独立部署 |

## 4. 功能模块设计

### 4.1 模块划分（包结构）

```
com.jksb.data.sync
├── config/
│   ├── SaTokenConfig.java                  # Sa-Token 配置
│   ├── XxlJobConfig.java                   # XXL-Job 执行器配置
│   ├── NcHttpClientConfig.java                  # HTTP Interface 客户端配置
│   └── WebConfig.java                      # CORS、拦截器注册
├── nccw/
│   ├── job/
│   │   ├── NccwIufoReportOrgSyncJob.java         # 财务系统-报表组织信息表 同步任务
│   │   ├── NccwIufoDataZcfzbSyncJob.java          # 财务系统-资产负债表 同步任务
│   │   ├── NccwIufoDataLrbSyncJob.java                # 财务系统-利润表 同步任务
│   │   └── NccwIufoDataXjllbSyncJob.java              # 财务系统-现金流量表 同步任务
│   ├── feign/
│   │   ├── NccwAuthClient.java               # Token获取接口
│   │   └── NccwDataClient.java               # 数据查询接口
│   ├── service/
│   │   ├── INccwIufoReportOrgService.java            # 报表组织接口
│   │   ├── INccwIufoDataZcfzbService.java         # 资产负债表接口
│   │   ├── INccwIufoDataLrbService.java               # 利润表接口
│   │   ├── INccwIufoDataXjllbService.java             # 现金流量表接口
│   │   └── impl/
│   │       ├── NccwIufoReportOrgServiceImpl.java      # 报表组织实现
│   │       ├── NccwIufoDataZcfzbServiceImpl.java   # 资产负债表实现
│   │       ├── NccwIufoDataLrbServiceImpl.java         # 利润表实现
│   │       └── NccwIufoDataXjllbServiceImpl.java       # 现金流量表实现
│   ├── entity/
│   │   ├── NccwIufoReportOrg.java                    # 报表组织实体
│   │   ├── NccwIufoDataZcfzb.java                 # 资产负债表实体
│   │   ├── NccwIufoDataLrb.java                       # 利润表实体
│   │   └── NccwIufoDataXjllb.java                     # 现金流量表实体
│   ├── mapper/
│   │   ├── NccwIufoReportOrgMapper.java
│   │   ├── NccwIufoDataZcfzbMapper.java
│   │   ├── NccwIufoDataLrbMapper.java
│   │   └── NccwIufoDataXjllbMapper.java
├── sys/                                      # 系统管理
│   ├── controller/
│   │   ├── SysAuthController.java            # 登录/登出
│   │   └── SysJobLogController.java          # 任务日志查询
│   ├── service/
│   │   ├── ISysAuthService.java              # 认证接口
│   │   ├── ISysJobLogService.java            # 日志接口
│   │   └── impl/
│   │       ├── SysAuthServiceImpl.java
│   │       └── SysJobLogServiceImpl.java
│   ├── entity/
│   │   ├── SysJobLog.java                    # 任务执行日志
│   │   └── SysUser.java                      # 用户表
│   └── mapper/
│       ├── SysJobLogMapper.java
│       └── SysUserMapper.java
├── common/
│   ├── Result.java                         # 统一返回结果
│   ├── PageResult.java                     # 分页结果
│   ├── BusinessException.java              # 业务异常
│   └── Constants.java                      # 常量
└── util/
    ├── TokenUtil.java                      # Token 工具
    ├── DateUtil.java                       # 日期工具
    └── RetryUtil.java                      # 重试工具
```

> **nccw 说明**：nccw 代表数据源/系统标识（用友 NC 财务系统），后续对接其他系统时按同样模式在 `nccw/` 同层扩展，如 `ncrl/`、`fwxt/`。

### 4.2 核心功能

#### 4.2.1 权限认证模块（Sa-Token）

- 登录 / 登出
- 接口路由拦截（除登录、XXL-Job 执行器接口外，全部需登录）
- 角色 / 权限校验（如：admin 角色才能执行补数）
- Token 存储到 Redis，支持分布式
- 放行 XXL-Job 执行器接口（`/xxl-job/**` 无需登录）

#### 4.2.2 定时任务调度模块（XXL-Job）

**4 个核心任务：**

| 任务名称 | JobHandler | CRON | 动态参数 |
|---------|-----------|------|---------|
| 组织同步 | NccwIufoReportOrgSyncJob | 0 0 2 * * ? | `{dataPeriod: "202601"}` |
| 资产负债表同步 | NccwIufoDataZcfzbSyncJob | 0 30 2 * * ? | `{date:"2026-01", orgCode:""}` |
| 利润表同步 | NccwIufoDataLrbSyncJob | 0 0 3 * * ? | `{date:"2026-01", orgCode:""}` |
| 现金流量表同步 | NccwIufoDataXjllbSyncJob | 0 30 3 * * ? | `{date:"2026-01", orgCode:""}` |

**任务特性：**

- 支持 CRON 配置（如每日凌晨 2 点）
- 支持手动触发、**动态传参**（指定日期 / 组织补数）
- 支持失败重试、超时控制
- 执行日志入库，可追溯、可重跑

#### 4.2.3 远程接口调用模块（HTTP Interface）

**对接海垦NC财务源系统 5 个接口：**

| 接口 | URL | 说明 |
|------|-----|------|
| Token获取 | POST `/uapws/rest/user/login` | 获取调用凭证 |
| 报表组织查询 | POST `/uapws/rest/query/reportOrg` | 按期间查组织体系 |
| 资产负债表 | POST `/uapws/rest/query/balanceSheet` | 按期间+组织查 |
| 利润表 | POST `/uapws/rest/query/income` | 按期间+组织查 |
| 现金流量表 | POST `/uapws/rest/query/cashFlow` | 按期间+组织查（文档路径待确认） |

**设计要点：**

- 统一请求头（uap_token, uap_usercode, uap_dataSource）
- 超时配置：connectTimeout=5s, readTimeout=30s（在 NcHttpClientConfig 中配置）
- 重试配置：RetryUtil 重试工具
- 响应结果统一解析、异常处理

#### 4.2.4 数据处理模块

| 步骤 | 说明 |
|------|------|
| 数据拉取 | HTTP Interface 调用源接口 |
| 数据清洗 | 字段映射、格式转换、空值处理、异常过滤 |
| 数据入库 | 批量插入/更新、事务控制、唯一性校验 |
| 数据补数 | 按日期、组织重跑任务，覆盖或追加 |

#### 4.2.5 日志与监控模块

- **任务执行日志**：任务 ID、名称、参数、状态、耗时、结果、异常堆栈
- **操作日志**：用户、操作、IP、时间、参数
- **接口调用日志**：请求/响应、耗时、状态
- 日志入库，支持按条件查询、导出

## 5. 数据库设计（核心表）
核心数据库表结构对应的放在sql根目录下的nccw、sys

## 6. 核心接口设计

### 6.1 权限接口

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/auth/login` | 登录（返回 Sa-Token） |
| POST | `/auth/logout` | 登出 |
| GET | `/auth/info` | 获取当前用户信息 |


### 6.2 任务日志接口

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/job/log` | 查询 XXL-Job 执行日志（分页+条件） |

## 7. 核心业务流程

### 7.1 同步流程

```
JobHandler.execute(params)
  │
  ├─ 1. 解析参数（期间、组织编码）
  ├─ 2. TokenService.getToken()        ← Redis缓存Token
  ├─ 3. 获取组织列表（若有则按组织迭代）
  ├─ 4. 调用 HTTP Interface 拉取报表数据
  ├─ 5. 清洗数据（字段映射/空值处理）
  ├─ 6. 分批写入（事务控制）
  ├─ 7. 记录 hk_job_log（状态/耗时/错误）
  └─ 8. 返回执行结果给 XXL-Job Admin
```

**补数能力说明：**

- XXL-Job Admin 控制台手动触发任务，通过"动态参数"传入 JSON
- 参数支持：日期范围 `{startPeriod, endPeriod}`、组织编码、报表类型
- 自动按期间正向迭代，确保数据一致性
- 单次补数上限 24 个月，防止误操作

## 8. 配置说明

### 8.1 application.yml 主要配置块

```yaml
server:
  port: 8088

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/hk_report
    username: postgres
    password: postgres
    driver-class-name: org.postgresql.Driver
  redis:
    host: localhost
    port: 6379
    database: 0

sa-token:
  token-name: token
  timeout: 86400
  redis-timeout: 2592000
  is-log: true

xxl:
  job:
    admin:
      addresses: http://localhost:8081/xxl-job-admin
    executor:
      appname: jksb-data-sync 
      port: 9999
      logpath: /data/xxl-job/logs
      logretentiondays: 30
app:
  api:
    base-url: http://ip:port
    paths:
      login: /uapws/rest/user/loginx
      report-org: /uapws/rest/query/reportOrg
      balance-sheet: /uapws/rest/query/balanceSheet
      income: /uapws/rest/query/income
      cash-flow: /uapws/rest/query/cashFlow
  auth:
    usercode: yy13
    password: 123qwe
  job:
    retry:
      max-attempts: 3
    backfill:
      max-periods: 24
```

## 9. 安全设计

| 安全措施 | 说明 |
|---------|------|
| Sa-Token 权限控制 | 所有接口（除登录、XXL-Job）必须登录 |
| 密码加密 | BCrypt 加密存储 |
| 接口防重放 | 请求时间戳 + 签名校验 |
| SQL 防注入 | MyBatis-Plus 参数化查询 |
| 异常处理 | 统一异常返回，不暴露敏感信息 |
| 路由放行 | XXL-Job 执行器接口 `/xxl-job/**` 自动放行 |

## 10. 部署与运维

### 10.1 Docker Compose 部署

项目采用 Docker Compose 编排所有服务，一键启动。

#### docker-compose.yml

#### Dockerfile

```dockerfile

```

#### 启动命令

```bash
# 构建并启动所有服务
docker-compose up -d --build

# 查看日志
docker-compose logs -f jksb-data-sync

# 单独重启同步服务
docker-compose restart jksb-data-sync

# 停止所有服务
docker-compose down
```

#### 目录结构

```
docker-compose.yml
Dockerfile
```

### 10.2 监控

| 手段 | 说明 |
|------|------|
| 日志 | Logback，按天分割，保留 30 天 |
| 健康检查 | Spring Boot Actuator `/actuator/health` |
| 任务监控 | XXL-Job Admin 控制台 |
| 业务监控 | `hk_job_log` 任务执行记录表 |

## 11. 交付物

| 交付物 | 说明 |
|--------|------|
| 完整源码 | Controller / Service / Job / Client / Entity / Mapper / Config |
| 数据库建表 SQL | 5 张核心表 DDL |
| 配置模板 | application.yml / application-dev.yml / application-prod.yml |
| 部署说明文档 | XXL-Job Admin 部署 + 执行器注册 + 任务配置 |

## 12. 附录：接口文档对照

接口规范详见 `海垦三大报表及报表组织数据查询接口调用-1.1.docx`。

### Token 获取

```
POST /uapws/rest/user/login
Body: {"usercode":"yy13", "pwd":"123qwe"}
Response: {uap_usercode, uap_dataSource, uap_token}
```

### 报表组织查询

```
POST /uapws/rest/query/reportOrg
Header: uap_token, uap_usercode, uap_dataSource
Body: {"date": "2026-01"}
Response: {code, message, data: {records: [{org_code, org_name, ...}]}}
```

### 三大报表查询

```
POST /uapws/rest/query/balanceSheet   (资产负债表)
POST /uapws/rest/query/income          (利润表)
POST /uapws/rest/query/cashFlow        (现金流量表，文档路径待确认)
Header: uap_token, uap_usercode, uap_dataSource
Body: {"date": "2026-01", "orgcode": ""}
Response: {code, message, data: {records: [{org_code, Y011104VT01: 0, ...}]}}
```