# mjava-jinlun

金伦项目的 Spring Boot 集成服务，用于在氚云/云枢、金蝶云星空和 Teambition 之间同步业务数据。项目主要承担表单回调接口、金蝶单据创建/更新、云枢表单回写、定时同步和客户对账查询。

## 技术栈

- Java 8
- Spring Boot 2.2.0.RELEASE
- Maven
- MyBatis / MyBatis-Plus
- MySQL Connector 8.0.32
- 金蝶云星空 WebAPI SDK
- 云枢 OpenAPI
- Teambition OpenAPI

## 项目结构

```text
src/main/java/com/malk/jinlun
├── JinlunApplication.java        # 应用入口，启用定时任务
├── config                        # 金蝶、云枢配置映射
├── controller                    # 对外 HTTP 接口
├── entity                        # 金蝶请求模型与通用入参模型
├── mapper                        # MyBatis Mapper
├── schedule                      # 定时同步任务
└── service                       # 业务服务、云枢客户端与实现

src/main/resources
├── mapper/JinlunMapper.xml       # 客户对账 SQL
└── logback-spring.xml            # 日志配置
```

## 核心功能

### 表单触发接口

这些接口通常由云枢/氚云表单动作调用，请求体通过 `objectId` 定位表单实例，再按业务规则读取表单字段、组装金蝶单据、提交审核并回写结果。

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| `GET` | `/test` | 连通性测试 |
| `POST` | `/addCustomer` | 根据云枢客户流程 `ZLKHLC` 创建金蝶客户 `BD_Customer` |
| `POST` | `/updateCustomer` | 根据云枢客户档案 `KHDA` 更新金蝶客户销售员 |
| `POST` | `/addCustomerContact` | 根据云枢联系人 `JL002` 创建金蝶联系人 `BD_CommonContact`，并回写联系人编码 |
| `POST` | `/addSaleOrder` | 根据云枢销售订单 `XSDD` 创建金蝶销售订单 `SAL_SaleOrder`，并回写订单编号 |
| `POST` | `/createTbProject` | 根据云枢重要样品打样申请 `ZYYPDYSQ` 创建 Teambition 项目，并回写项目 ID |
| `POST` | `/queryFromData` | 按 `schemaCode`、`propertyCode`、`propertyValue` 查询单条云枢表单数据 |

示例请求：

```json
{
  "objectId": "云枢表单实例ID"
}
```

`/queryFromData` 请求示例：

```json
{
  "schemaCode": "KHDA",
  "propertyCode": "ShortText1758195840127",
  "propertyValue": "客户编码"
}
```

### 客户对账查询

| 方法 | 路径 | 参数 | 说明 |
| --- | --- | --- | --- |
| `GET` | `/getCustomerDzmx` | `startDate`、`endDate`、`customerName` | 查询客户回款对账明细 |
| `GET` | `/getCustomerWqqk` | `startDate`、`customerName` | 查询客户往期欠款 |

SQL 位于 `src/main/resources/mapper/JinlunMapper.xml`，当前查询涉及销售出库单、收款单和暂估应收等云枢业务表。

### 定时同步任务

`JinlunTask` 由配置项 `enable.scheduling` 控制是否启用。开启后每天 00:00 起按分钟顺序执行以下任务：

| 时间 | 方法 | 金蝶 FormId | 云枢 schemaCode | 说明 |
| --- | --- | --- | --- | --- |
| 00:00 | `syncMaterial` | `BD_MATERIAL` | `WL` | 同步物料 |
| 00:01 | `syncSaleOut` | `SAL_OUTSTOCK` | `XSCKD` | 同步销售出库单 |
| 00:02 | `syncReceipt` | `AR_RECEIVEBILL` | `SKD` | 同步收款单 |
| 00:03 | `syncReceivable` | `AR_receivable` | `YSD` | 同步应收单 |
| 00:04 | `syncSaleReturn` | `SAL_RETURNSTOCK` | `XSTHD` | 同步销售退货单 |
| 00:05 | `syncXingneng` | `Sl_xingneng` | `XN` | 同步性能基础资料 |
| 00:06 | `syncSaleOrder` | `SAL_SaleOrder` | `XSDD_JDTB` | 同步销售订单进度 |
| 00:07 | `syncReceiptVerification` | `AR_MatchRecord` | `YSSKHXJL` | 同步应收收款核销记录 |

定时同步采用“先按关键字段查云枢，再更新或新增”的模式，避免重复创建。

## 配置项

项目通过 `@ConfigurationProperties` 读取配置。请在本地或部署环境中提供以下配置，不要把真实密钥、Token、Cookie 或生产连接串提交到仓库。

```yaml
cloudpivot:
  grant-type: xxx
  client-id: xxx
  client-secret: xxx
  redirect-uri: xxx
  operator-user-id: xxx

kingdee:
  XKDApiAcctID: xxx
  XKDApiUserName: xxx
  XKDApiAppID: xxx
  XKDApiAppSec: xxx
  XKDApiServerUrl: xxx

enable:
  scheduling: true
```

项目还依赖公共包中的 Teambition 配置 `TBConf`，实际配置键以 `com.malk.server.teambition` 所在基础包为准。

## 构建与运行

在项目根目录执行：

```bash
mvn clean package
```

构建产物名由 `pom.xml` 指定为：

```text
target/jinlun.jar
```

本地运行：

```bash
java -jar target/jinlun.jar
```

如需指定环境：

```bash
java -jar target/jinlun.jar --spring.profiles.active=dev
```

`pom.xml` 中当前配置了 `<skipTests>true</skipTests>`，默认 Maven 构建会跳过测试。若要执行测试，可临时覆盖：

```bash
mvn test -DskipTests=false
```

## 外部依赖

运行前需要确认以下依赖可用：

- `com.malk:base:1.1-SNAPSHOT` 已安装到本地 Maven 仓库或可从私服下载。
- `com.example:k3cloud:8.0.6` 已安装到本地 Maven 仓库或可从私服下载。
- `com.example:gson:2.8.0` 已安装到本地 Maven 仓库或可从私服下载。
- 应用可访问金蝶云星空 WebAPI、云枢 OpenAPI、Teambition OpenAPI 和业务数据库。

## 开发约束

- 表单字段编码、表单编码、金蝶 FormId 和云枢 schemaCode 必须以平台实际配置为准，不要臆造或随意替换。
- 涉及第三方凭证时，只通过配置注入，不在代码、README、测试数据或日志中硬编码。
- 新增云枢表单调用时，优先复用 `CpClient` 的 `getCpBo`、`getCpBoList`、`createCpBo`、`updateCpBo`。
- 新增金蝶单据调用时，沿用现有 `Save`、`Submit`、`Audit`、`UnAudit`、`View` 请求模型和 `isTrue` 校验方式。
- 对云枢子表字段保持行结构，避免把多行子表压平成不可追溯的字符串。
- 定时任务修改后，至少验证一次目标金蝶 FormId、云枢 schemaCode、关键查询字段和更新/新增分支。
- 接口失败时保留外部接口返回的错误信息，避免吞掉金蝶或云枢的诊断内容。

## 主要代码入口

- `JinlunController`：HTTP 接口入口。
- `JinlunServiceImpl`：表单触发业务、金蝶单据创建/更新、Teambition 项目创建。
- `JinlunTaskServiceImpl`：金蝶到云枢的定时同步逻辑。
- `CpClientImpl`：云枢 OpenAPI 封装。
- `JinlunMapper.xml`：客户对账 SQL。