53 lines
4.5 KiB
Markdown
53 lines
4.5 KiB
Markdown
# ICC 客户信息同步（org_base）Spec
|
||
|
||
## Why
|
||
客户档案目前依赖手工维护，鑫潼 ICC 平台已存在基础组织（org_base）客户主数据。需按 ICC 平台接口文档，通过定时任务从 ICC 拉取 org_base 组织数据，按字段映射对 customer 客户表执行新增/变更，实现客户主数据自动化同步。
|
||
|
||
## What Changes
|
||
- **新增** `customer` 表 `icc_code` 字段（ICC 客户编码，唯一索引），作为 ICC 同步的幂等匹配键；同步修改实体、迁移脚本与 db_seed.sql（幂等一致）
|
||
- **新增** ICC OAuth2 密码模式鉴权客户端：获取公钥 → RSA(ECB/PKCS1) 加密密码 → `extend/token` 换取 access_token（2h 有效，进程内缓存过期自动续签）
|
||
- **新增** `IccCustomerSyncService`：从 `.env` 读取 ICC 配置，分页全量拉取 `organization/page`（`maxRangeId=0`，过滤 `orgType=org_base`），按字段映射对 customer 幂等 upsert（已存在记录先比较映射字段，不一致才变更），写 `icc_sync_log`
|
||
- **新增** 定时任务：注册 `icc_customer_sync.task` 到任务注册表与 `sys_job`（默认每 10 分钟，可配置）
|
||
- **安全**：全部 SQL 走 Sequelize 参数绑定；接口凭据经 `.env` 读取，不硬编码到代码；ICC 拉取失败仅记录 `icc_sync_log` 错误日志，不抛业务错误
|
||
|
||
## Impact
|
||
- Affected specs: ICC 数据同步（含现有 icc_line_sync 模式）、客户管理（customer 主数据）
|
||
- Affected code:
|
||
- server/src/entity/customer.entity.ts（新增 iccCode）
|
||
- server/src/task/icc_customer_mapper.ts（新增：字段映射集中配置）
|
||
- server/src/service/icc_customer_sync.service.ts（新增：OAuth2 鉴权 + 拉取 + upsert + 日志）
|
||
- server/src/task/icc_customer_sync.task.ts（新增：定时任务定义）
|
||
- server/src/task/job_registry.ts、server/src/service/job_scheduler.service.ts（注册任务与运行时）
|
||
- server/.env（新增 ICC 凭据配置项）
|
||
- database/migrations/（新增迁移文件）、database/db_seed.sql（customer 表结构与 sys_job 种子）
|
||
|
||
## ADDED Requirements
|
||
|
||
### Requirement: ICC 客户信息同步（org_base 定时任务）
|
||
系统 SHALL 通过定时任务从 ICC 平台同步 org_base 客户信息到 customer 表：OAuth2 鉴权获取 access_token → 分页全量拉取组织数据（maxRangeId=0，pageSize≤1000，循环至末页）→ 过滤 `orgType=org_base` → 按字段映射（`orgCode→iccCode`、`orgName→customerName`、`province→province`、`city→city`、`county→district`）幂等 upsert，并写 `icc_sync_log`（sync_type=`customer`）。
|
||
|
||
#### Scenario: 定时同步成功
|
||
- **WHEN** 定时任务触发（默认 `*/10 * * * *`，可配置）
|
||
- **THEN** 拉取 ICC org_base 组织并新增/变更对应 customer 记录；新增客户自动生成 `customer_no`（沿用 KH+YYYYMMDD+序号规则）；已存在客户（按 `icc_code` 匹配）先比较 customer_name/province/city/district 四个映射字段与现有值，仅当任一字段不一致时才执行更新，一致则跳过，其余手工字段（status/salesman_id/联系方式等）保持不变；`icc_sync_log` 写入成功记录
|
||
|
||
#### Scenario: 重复执行幂等
|
||
- **WHEN** 同一 orgCode 连续两次同步均存在且 ICC 数据未变化
|
||
- **THEN** 第二次执行按 icc_code 命中已有记录，比较后字段一致不执行 update，不产生重复客户、不产生无意义变更
|
||
|
||
#### Scenario: 全量分页拉取
|
||
- **WHEN** 组织数据超过一页
|
||
- **THEN** 按 pageNum 递增循环请求直至 currentPage==totalPage，全部合并后统一 upsert
|
||
|
||
#### Scenario: ICC 鉴权失败 / 接口异常
|
||
- **WHEN** 公钥获取失败、token 换取失败或组织接口返回非 0 code / HTTP 非 2xx
|
||
- **THEN** 同步失败仅写 `icc_sync_log`（status=0、error_message），业务不抛错；access_token 过期时自动重新走 OAuth2 鉴权
|
||
|
||
### Requirement: customer 表 icc_code 字段
|
||
系统 SHALL 在 customer 表新增 `icc_code` 字段（字符串，可空，唯一索引）用于承载 ICC 客户编码；已有客户在首次同步时按 orgCode 匹配后回填该字段；该字段不参与客户档案页面手工编辑逻辑（同步来源字段）。
|
||
|
||
### Requirement: ICC 凭据环境配置
|
||
系统 SHALL 通过 `.env` 读取 ICC 平台连接配置：`ICC_BASE_URL`（host）、`ICC_VERSION`、`ICC_CLIENT_ID`、`ICC_CLIENT_SECRET`、`ICC_USERNAME`、`ICC_PASSWORD`；业务代码不出现明文凭据。
|
||
|
||
## MODIFIED Requirements
|
||
（无既有功能被修改；现有 icc_line_sync 任务保持原行为不变）
|