# bip2gscloud

**Repository Path**: esun0922/bip2gscloud

## Basic Information

- **Project Name**: bip2gscloud
- **Description**: 数据迁移
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-01
- **Last Updated**: 2026-10-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# YonBIP → 浪潮 GS Cloud 数据迁移

把用友 YonBIP 的凭证数据取出来，按浪潮 GS Cloud《集团公司数智财务建设数据集中接口规范 V2.1》
的「凭证接收接口」（`/api/jg/gl/v3.0/fiaccinterface/syncAccDocList`）格式生成 JSON 文件。

## 目前有两套实现

| | 位置 | 说明 |
| --- | --- | --- |
| **数据迁移工具（主）** | [gsyy-tool/](gsyy-tool/) | Spring Boot + Thymeleaf 网页工具，DuckDB 存配置和对照表。配置 BIP 数据源 / GS Cloud 接口、查凭证、生成浪潮 JSON。双击 `一键启动.bat` 启动（已在运行就直接开浏览器，没打过包会先打包），浏览器开 http://localhost:8088；`build.bat` 打包并跑测试 |
| Python 原型 | [tools/](tools/) | 命令行版，取数逻辑一样，排查问题时更快 |

详细说明看 [gsyy-tool/README.md](gsyy-tool/README.md)。下面是 BIP 侧数据模型的调研结论，两套实现共用。

---

## 0. 迁移范围（不止凭证）

《集团公司数智财务建设数据集中接口规范 V2.1》一共 **5 大类、53 个接口**，凭证只占 3 个。
工具里按模块登记在 [/module](http://localhost:8088/module)，已实现的能点进功能页，
没实现的进预留页，写清楚浪潮侧调哪些接口、BIP 侧读哪些表（带本库实测状态）、还差什么。

| 模块 | 状态 | 浪潮接口 | BIP 侧来源表 |
| --- | --- | --- | --- |
| **凭证** | 已实现 | `syncAccDocList` / `deleteAccDocList` / `AccDocCheckJtReceive` | `gl_voucher` `gl_detail` `gl_docfree1` `gl_deffree1` `gl_cashflowcase` |
| **报账单** | 已摸底 · 待开发 | 28 个 `/api/jg/ssp/v1.0/bq/sync*Bills` + `DataCheckBzd` | `er_bxzb` `er_busitem` `er_jkzb` `er_djlx` `er_billcontrast` `er_fieldcontrast` |
| **电子影像 / 附件** | 已摸底 · 待开发 | `synczipinfo` / `slice/upload` / `getFileHandleResult` | **`sm_pub_filesystem`**（单据↔附件关系）`bap_fs_header` `bap_fs_body` `bap_fs_module` `imag_billmapping` `imag_basefactory` |
| 基础数据 | 预留 | 8 个 `/api/jg/syncbddata/v3.0/bdsyncinterface/` | `org_orgs` `org_dept` `bd_psndoc` `bd_psnjob` `sm_user` `bd_accassitem` |
| 期初余额 | 预留 | `syncFzye` / `DataCheckNcye` | `gl_balance`（`gl_freebalance` 本库没有） |
| 数据核对 | 预留 | 9 个 `checkcount*` | — |
| 采集监控 | 预留 | `reportheartbeat` / `reporttask` | — |

接口名和路径是从规范 HTML 里按「章节标题 → 该节出现的 `/api` 路径」**成对抽出来的**，
没按英文名猜 —— 里面有反直觉的：

- 「合同应收报账单」是 `syncCtContractRecvBills`
- 「其他应收报账单」反而是 `syncHetRecvBills`

### 0.1 报账单摸底结论（本库实测）

- 表头 → 表体：`er_bxzb.pk_jkbx = er_busitem.pk_jkbx`，一对多。
  `er_bxzb` 有 **228 列**，`er_busitem` 有 **191 列**。
- `pk_jkbx` 散布在 **16 张表**里（发票关系、分摊、行程、预算占用等）。
- **手册列的表有几张本版本根本没有**：`er_hkzb`、`er_paydetail`、`er_bxverdept`、
  `arap_bxbusitem` 都不存在。`ARAP_BXBUSITEM` 是表体的**模型编码**，
  实际物理表是 `er_busitem` —— 照着手册硬套会白找半天。
- `er_djlx` 有 46 条单据类型。本库现有 **1 张报账单**，类型 `2641 差旅费报销单`，
  正好对上浪潮的 `syncTravelBills`。
- BIP 单据类型 ↔ 浪潮接口的对应关系，工具里按名称做了初步标注，**必须找集团确认**。

### 0.2 附件摸底结论（本库实测）

- 附件走 UFS 两张表：`bap_fs_header`（文件名、大小、版本、Bucket）
  → `bap_fs_body`（`storepath` 物理定位、`filetype`、加密压缩标记）。
  **文件实体不在数据库里。**
- 本库是**磁盘存储模式**，`storepath` 形如 `C:/ufs/bip/<bucket>/xxx/yyy/nnn`；
  `cryptoflag=0`、`compressflag=0`（未加密未压缩）。
- Bucket（`bap_fs_header.module`）实测有两个：`uapattachroot`（4 个，业务附件）、
  `exceltemp`（5 个，Excel 导出临时文件）。共 9 个文件。

#### 单据 ↔ 附件的关联链（2026-09-01 更正，已用真实数据逐环验证）

> **此前本节写着「`ext_tablename`/`ext_type` 全是空，关系表无从反查」——
> 观察没错（9/9 确实全空），但由此得出的「无法关联」是错的。**
> 关联根本不走 `ext_tablename`，走 `SM_PUB_FILESYSTEM` 这张表。

```
gl_voucher.pk_voucher / gl_detail.pk_detail   业务对象主键（凭证头 / 凭证分录）
er_bxzb.pk_jkbx      / er_busitem.pk_busitem  业务对象主键（报账单头 / 报账单分录）
   ↓  = LEFT(sm_pub_filesystem.filepath, 20)
sm_pub_filesystem.pk_doc                      业务附件关系表（本库 15 行）
   ↓  = bap_fs_header.path
bap_fs_header.guid                            文件元数据
   ↓  = bap_fs_body.headid
   ↓    且 version = COALESCE(fileversion, 该 headid 下的 MAX(version))
bap_fs_body.storepath                         磁盘物理路径
```

要点：

- `sm_pub_filesystem` 里 `isfolder='y'` 是目录、`isfolder='n' and isdoc='z'` 才是文件。
  本库 15 行 = 11 个目录 + 4 个文件。
- `filepath` 的结构是 `<20位业务对象主键>/<文件名>`。**前 20 位是哪一层的主键取决于
  附件挂在哪一层**，本库四种锚点都出现过：凭证头 `gl_voucher`（2 个文件）、
  报账单头 `er_bxzb`（1 个文件）、**凭证分录 `gl_detail`（2 个目录，0 个文件）**、
  以及 `logo/` 那条（见下）。
- **附件可以挂在分录上，不只挂在凭证头上（2026-09-07 更正）。** 此前本节只写了
  凭证头和报账单头。全库 5658 张单列 char 主键表扫描确认，`sm_pub_filesystem` 里
  这两个目录行的前 20 位是 **`gl_detail.pk_detail`**：

  | 目录 `filepath` | 是什么 |
  | --- | --- |
  | `10011010000000005GSJ` | `gl_detail.pk_detail`，凭证 `...GSI` 的第 1 分录 |
  | `10011010000000005GU2` | `gl_detail.pk_detail`，凭证 `10011010000000005GU0` 的第 2 分录 |

  **本库这两个分录目录是空的（0 个文件）**，所以只查凭证头的写法在这里跑起来一切正常；
  到客户真库上，只要有人往分录的附件框里传过文件就**静默全漏**——不报错、不留痕、
  包里少文件。手册 §9.7 / §9.8 / §9.10 的锚点**本来就是 `GL_DETAIL`**，§9.11 才把
  凭证头列为**另一条**要单独检查的路。所以自动关联的锚点是四支 UNION：凭证头 /
  凭证分录 / 报账单头 / 报账单分录（`er_busitem` 那一支本库无实证，属结构外推）。
- **`logo/000110100000000021CC/dongmu-logo2.png` 不是「非业务目录」（2026-09-07 更正）。**
  此前本节把它归成「非业务的 `logo/` 目录」，**不准确**：路径第 2 段
  `000110100000000021CC` 是 `org_group.pk_group`（东木集团），它是业务主键，
  **只是不在偏移 0**。四跳里它照样被 `LEFT(filepath, 20) = 'logo/000110100000000'`
  自然过滤掉（三张业务表都不命中），**不需要为它多写规则**——多写反而可能误杀。
- **`bap_fs_header.fileversion` 可为 NULL（2026-09-07 更正）**，且没有默认约束
  （有 `DEFAULT ((1))` 的是 `bap_fs_body.version`，两边不对称）。所以版本条件必须写成
  `b.version = COALESCE(h.fileversion, (SELECT MAX(b2.version) …))`；**直接写
  `b.version = h.fileversion`，只要 `fileversion IS NULL`，这条附件就会被 INNER JOIN
  整条静默丢弃**。本库 9 行 `fileversion` 全是 1，现在看不出来。
  版本条件本身只是**去重手段不是正确性条件**——下载压根不用版本号，
  `demo/mydl/.../MyDownloadServlet.java:154` 传的是 `0`。
- `bap_fs_body` 靠 `headid` 关联 `bap_fs_header.guid`，**不是靠 path**。
- 9 个文件里 4 个已挂接（全在 `uapattachroot`），5 个未挂接的是 `exceltemp` 的
  Excel 临时文件——本来就不是业务附件，未挂接是正常的。

实测已挂到凭证上的两个附件：

| 凭证 | 期间/凭证号 | 附件 |
| --- | --- | --- |
| `10011010000000005CWL` | 2024-05 / 1 | `bip2305.txt` |
| `10011010000000005GU0` | 2024-05 / 1 | `浪潮&用友GSYY数据集中工具数据库字典_HTML5(1).html` |

参考 [doc/YonBIP凭证与报账单相关表查询手册_HTML5.html](doc/YonBIP凭证与报账单相关表查询手册_HTML5.html)
第 9 章。该手册 9.7 节写的是 `GL_DETAIL.PK_DETAIL = LEFT(FILEPATH,20)`（凭证分录），
9.11 节才把凭证头列为另一条路。**本库两条都真实存在**：凭证头匹配到 2 个文件，
凭证分录匹配到 2 个目录但**目录里 0 个文件**——所以「只查凭证头」在本库跑起来不报错，
在客户真库上会静默漏。（此处曾写「分录一个都没匹配上」，2026-09-07 更正。）

这条链已在 **A-3a** 落地成代码：`BipAttachService` 的四跳 SQL（四支 UNION 锚点、
`ISNULL(dr,0)=0` 软删除、`COALESCE` 版本兜底）+ `AttachAutoLinkService` 的编排
（只对本地 SUCCESS 凭证、手工挂接优先、未命中清单），手工入口退居人工纠正。

---

## 1. 环境

| 项 | 值 |
| --- | --- |
| YonBIP 地址 | http://192.168.175.128/ |
| 数据库 | SQL Server 2016 SP2，192.168.175.128:1433 |
| 库名 / 账号 | `yonbipdb` / `sa` |
| 模型口径 | YonBIP V3 高级版（沿用 NC Cloud 总账数据模型） |

依赖：`pip install pymssql`（已安装 2.3.13）。
连接参数在 [tools/db.py](tools/db.py)，可用环境变量 `BIP_DB_HOST/PORT/USER/PWD/NAME` 覆盖。

---

## 2. 目录

```
tools/
  db.py              数据库连接
  q.py               临时执行任意 SQL（排查用）
  bip_voucher.py     凭证查询核心：Meta（元数据/档案缓存）+ VoucherQuery
  query_voucher.py   命令行入口
out/                 导出的 JSON
doc/                 参考文档
```

## 3. 用法

```bash
cd tools
```

列出账簿 / 凭证类别 / 辅助核算维度 / 凭证年度期间分布：

```bash
python query_voucher.py --list-books --list-types --list-dims --list-periods
```

自检 17 个辅助核算维度对应的档案表是否都能解析（主键列、编码列、名称列、行数、示例）：

```bash
python query_voucher.py --check-dims
```

查询凭证（控制台表格）：

```bash
python query_voucher.py --book 201-0001 --year 2024 --period 01 12
```

导出为结构化中间 JSON（后续用于生成浪潮报文）：

```bash
python query_voucher.py --book 201-0001 --year 2024 --out ../out/bip_vouchers.json
```

其它常用参数：`--vtype 01`（凭证类别）、`--num 1 2 3`、`--pk <凭证主键>`、
`--only-booked`（只取已记账）、`--exclude-void`（排除作废）、`--include-temp`（含暂存）、
`--ts-from '2024-05-01 00:00:00'`（按 `gl_voucher.ts` 增量取数）、`--limit N`、`--all`。

---

## 4. 已确认的 BIP 数据模型（在本库实测）

| 表 | 用途 | 关键点 |
| --- | --- | --- |
| `gl_voucher` | 凭证头 | `pk_prepared`=制单人、`pk_checked`=审核人、**`pk_manager`=记账人**、`pk_casher`=出纳（由 `md_property` 元数据确认，不是望文生义的"主管"）；BIP 没有"会计主管"字段 |
| `gl_detail` | 凭证分录 | `debitamount/creditamount`=原币，`localdebit/creditamount`=账簿本币，`excrate2`=账簿本币汇率，`direction` D/C |
| `gl_docfree1` | 参照型辅助核算值 | `assid` + `f1..f30`，F 列位置由 `fi_freemap.num` 决定；**空槽位写的是 `NN/A`**（4 字符），不是 `~` 也不是 `N/A` |
| `gl_deffree1` | 录入型（自定义）辅助值 | `assid` + `f1..f10` |
| `fi_freemap` | 辅助维度 → F 列映射 | 本库 `mod='00'`（总账）共 17 个维度，全部 `isdef='N'` |
| `bd_accassitem` | 辅助核算项目定义 | `classid` → `md_class.id` → 物理档案表 |
| `bd_accass` | 科目 ↔ 辅助项目 | `pk_accasoa` + `pk_entity`(=辅助项目)；`pk_coveraccasoa` 指回体系基准表的源配置行 |
| `bd_accsystem` / `bd_accchart` | 科目体系 / 科目表 | 账簿用的是**组织级科目表**，辅助核算要配在**体系基准科目表**上才会向下传导 |
| `fipub_VouchertypeRule` + `fipub_accasoasub` | 凭证类别约束 | `ruletype=3` 必有清单内科目、`4` 必无 |
| `bd_accperiod` / `bd_accperiodmonth` | 会计日历 | 本库只有 **2023、2024** 两年，各 12 期，无调整期 |
| `gl_cashflowcase` | 现金流量分配 | 按 `pk_detail` 关联 |
| `bd_accasoa` / `bd_account` | 科目 | **科目名称在 `bd_accasoa.name`**，`bd_account.name` 是 `~`；编码在 `bd_account.code` |

### 辅助核算的正确读法（重要）

本库 `gl_freevalue` 是 NCC/YonBIP 的「组合布局」
（`freevalueid` + `typevaluemd5` + `typevalue1..9`），**不能**按老 NC65 的
`checktype/checkvalue` 逐行解析。可读的辅助值在 `gl_docfree1` / `gl_deffree1`：

```
gl_detail.assid → gl_docfree1.assid → f{fi_freemap.num}
                → bd_accassitem.classid → md_class.defaulttablename / keyattribute
                → 档案表取 编码 / 名称
```

这套映射先由 `md_property` 元数据交叉验证（`gl_docfree1.f1`=部门、`f2`=人员档案、
`f7`=现金流量项目、`f10`=项目 …… 与 `fi_freemap.num` 顺序完全一致），
**2026-08-31 又用一张真实带辅助核算的凭证做了端到端实证**，见第 7 节。

两条只有真实数据才能暴露的规律：

- **`assid` 是辅助组合的哈希，不是分录主键**。同一张凭证里辅助组合完全相同的多条分录
  **共用一条 `gl_docfree1`**（实测：6602 和 1001 都是「部门=运输总办 + 人员=集团人力」，
  共用同一个 `assid`）。所以按 `assid` 关联时要预期一对多。
- **空槽位的哨兵是 `NN/A`**。`gl_docfree1` 里没填的 F 列不是 `~` 也不是 `N/A`，
  而是 4 个字符的 `NN/A`。漏掉它会把空槽当成档案主键去查，凭空造出假的辅助行 ——
  这个 bug 就是这次实测抓到的，Java 和 Python 两边都已修。

本库当前的 17 个维度（`--check-dims` 输出）：

| # | 维度 | 存放位置 | 档案表 |
| --- | --- | --- | --- |
| 1 | 部门 | `gl_docfree1.f1` | `org_dept` |
| 2 | 人员档案 | `f2` | `bd_psndoc` |
| 3 | 地区分类 | `f3` | `bd_areacl` |
| 4 | 客商 | `f4` | `bd_cust_supplier` |
| 5 | 内部客商 | `f5` | `bd_cust_supplier` |
| 6 | 物料基本信息 | `f6` | `bd_material_v` |
| 7 | 现金流量项目 | `f7` | `bd_cashflow` |
| 8 | 收支项目 | `f8` | `bd_inoutbusiclass` |
| 9 | 资金计划项目 | `f9` | `bd_fundplan` |
| 10 | 项目 | `f10` | `bd_project` |
| 11 | 银行账户 | `f11` | `bd_bankaccsub` |
| 12 | 成本中心 | `f12` | `resa_costcenter` |
| 13 | 客户档案 | `f13` | `bd_customer` |
| 14 | 供应商档案 | `f14` | `bd_supplier` |
| 15 | 银行类别 | `f15` | `bd_banktype` |
| 16 | 物料基本分类 | `f16` | `bd_marbasclass` |
| 17 | 资产类别 | `f17` | `fa_category` |

档案表、主键列、编码列、名称列全部是**动态解析**的（`md_class` / `md_property` + 主键约束兜底），
所以客户自定义的辅助核算维度也能自动识别，不需要改代码。

### 造测试数据时踩过的四个坑

要在 BIP 里手工做一张带辅助核算的凭证，下面四条都会拦人，按顺序解决：

**① 辅助核算要配在「科目体系」上，不是「会计科目-全局」**

「会计科目-全局」编辑的是 `0001 基准科目表`，它和账簿实际用的科目表是**两套独立的
`bd_account`**（`pk_originalaccount` 各自指向自己，互不继承），在那儿配了不生效。

本库的挂接关系：

```
科目体系 0001 基准科目体系      → 科目表 0001 基准科目表         (全局)
科目体系 0008 政府会计科目体系  → 科目表 0008 政府会计基准科目表  (全局)
科目体系 2021 2021基准科目体系  → 科目表 2021 2021基准科目表     (全局)
                              → 科目表 1000 东木集团科目表     (东木集团) ← 六个账簿都用它
```

正确做法是在 **`2021 2021基准科目体系`** 上配，BIP 会自动往下级科目表生成对应的
`bd_accass` 行，并用 `pk_coveraccasoa` 指回源行。

**② 凭证类别有「必有/必无科目」约束**（`fipub_VouchertypeRule` + `fipub_accasoasub`）

| 规则 | ruletype | 绑定凭证类别 | 科目清单 |
| --- | --- | --- | --- |
| 现金 | **3 = 必有** | 01 记账凭证（记） | 1001 库存现金、1002 银行存款、1012 其他货币资金 |
| 非现金 | **4 = 必无** | 10 转账凭证（转） | 同上 |

记账凭证**必须**引用现金类科目，转账凭证**不能**引用。不含现金科目的测试凭证要用**转账凭证**。

**③ 碰现金类科目就必须做现金流量分析，而本库做不了**

`bd_account.cashtype`：1001=1、1002=2（现金类），1122/2202/6602=0。只要凭证引用现金类科目，
NCC 就要求把现金发生额全额分配到现金流量项目，否则报「现金流量本币金额分析错误」。

但本库 55 条现金流量项目全部 `pk_org = 东木集团`，而**适用范围表 `bd_cashflowuse` 是 0 行** ——
从来没分配下发到任何成员组织。所以在成员单位账簿里制单，主表项参照框搜不到任何项目，
这条路走不通。**结论：测试凭证一律避开 1001/1002/1012。**

**④ 会计日历只有 2023、2024**

`bd_accperiodmonth` 只有这两年共 24 期，`gl_initbuild.builtyear` 六个账簿都是 2023，
`gl_closeaccbook` 0 行（没有任何期间结账）。所以**可制单区间 = 2023-01 ~ 2024-12**，
填 2026 或 2014 都会报「与 xxxx 对应的会计期间不存在」。

---

## 5. 与浪潮 GS Cloud 凭证接收接口的字段映射

接口：`POST http://ip:port/api/jg/gl/v3.0/fiaccinterface/syncAccDocList`
（一个批次必须是**一个账套、一个会计年度**的数据；`SRCDOCID` 全局唯一）

### 顶层

| GS 字段 | BIP 来源 |
| --- | --- |
| `YEAR` | `gl_voucher.year` |
| `ACCORGID` | 集团下发的核算组织 ID —— 需要 BIP 组织 ↔ 集团组织对照表 |
| `LEDGERID` | 集团下发的账簿 ID —— 需要 `pk_accountingbook` ↔ 集团账簿对照表 |

### `ACCDOCLIST`（凭证头）

| GS 字段 | BIP 来源 | 说明 |
| --- | --- | --- |
| `SRCDOCID` | `pk_voucher` | 成员单位凭证 ID |
| `ACCPERIODCODE` | `period` | 两位 |
| `ACCDOCTYPE` | `bd_vouchertype.code` 映射 | 常量表待集团提供 |
| `ACCDOCDATE` | `prepareddate` | 转 `yyyyMMdd` |
| `NUMBEROFATTCH` | `attachment` | |
| `MAKERID` / `MAKERNAME` | `pk_prepared` → `sm_user` | ID 需换成集团返回的用户 ID |
| `SECRETLEVEL` | 固定 `PUBLIC` | BIP 无密级字段 |
| `EXTERNALDOC` | `bd_vouchertype.shortname` + `num` | 如 `记0001` |
| `AUDITORID` / `AUDITORNAME` | `pk_checked` | |
| `BOOKERID` / `BOOKERNAME` | `pk_manager`（记账人） | |
| `CASHIERID` / `CASHIERNAME` | `pk_casher` | |
| `ACCMANAGERID` / `ACCMANAGERNAME` | **BIP 无对应字段**，留空 | 非必填 |
| `ISAUDIT` | `pk_checked`/`checkeddate` 非空 → 是/否 | |
| `ISBOOK` | `tallydate` 非空 → 是/否 | |
| `ISVOID` | `discardflag='Y'` → 1，否则 0 | |
| `BATCHINDEX` | 批内顺序号 | |

### `ENTRYLIST`（分录）

| GS 字段 | BIP 来源 |
| --- | --- |
| `SRCDOCID` / `SRCACCENTRYID` | `pk_voucher` / `pk_detail` |
| `ACCENTRYCODE` | `detailindex` 左补 0 至 5 位 |
| `ACCTITLECODE` | `accountcode`（可能要走科目对照） |
| `ACCTITLEID` | 集团下发的科目 ID —— 需科目对照表 |
| `ABSTRACT` | `gl_detail.explanation` |
| `AMOUNT`（本币） | `localdebitamount` / `localcreditamount` |
| `FOREIGNCURRENCY`（原币） | `debitamount` / `creditamount` |
| `LENDINGDIRECTION` | `direction`：`D`→`1`，`C`→`2` |
| `CURRENCYID` | 集团下发的币种 ID（由 `bd_currtype.code` 映射） |
| `EXCHANGERATE` | `excrate2`（账簿本币汇率） |
| `SETTLEMENT` / `SETTLEMENTNUMBER` | `checkstyle`（结算方式） / `verifyno`、`checkno` |
| `BIZDATE` | `verifydate` 或 `checkdate` → `yyyyMMdd` |
| `BATCHINDEX` | 分录顺序号 |

### `ASSISTANCELIST`（辅助）

| GS 字段 | BIP 来源 |
| --- | --- |
| `ACCASSCODE` | 辅助顺序号，左补 0 至 5 位 |
| `DEPTID` | `gl_docfree1.f1` 部门 → 集团核算部门 ID |
| `ACCEMPLOYEEID` | `f2` 人员档案 → 集团核算人员 ID |
| `RELATEDORGID` | 客商 / 客户 / 供应商（`f4`/`f13`/`f14`）→ 集团往来单位 ID |
| `SPECATEID01..99` | 其余辅助维度 → 集团核算项目 ID |
| `RELATEDORGLYID/CODE/NAME/USCC` | 本地往来单位主键、编码、名称、社会信用代码 |
| `BANKACCOUNTLYID/CODE/NAME` | `f11` 银行账户（`bd_bankaccsub`） |
| `BANKLYID/CODE/NAME` | 金融机构 / `f15` 银行类别 |
| `QUANTITY` / `UNITPRICE` | `debitquantity`/`creditquantity` / `price` |
| `AMOUNT` / `FOREIGNCURRENCY` / `EXCHANGERATE` / `FOREIGNCURRENCYID` | 同分录 |

`RELATEDORGLY*` / `BANKACCOUNTLY*` / `BANKLY*` 这三组「本地系统档案」字段
**不需要配对照表**，工具直接从 BIP 档案带出主键/编码/名称（已实测，见第 7.1 节）。
只有对应的集团 ID（`RELATEDORGID` 等）才需要对照。

`DEPTID` / `ACCEMPLOYEEID` / `RELATEDORGID` / `SPECATEIDnn` 由「辅助核算对照表」两级决定：
维度级行（档案主键留空）决定该维度落到哪个字段，档案级行（档案主键有值）给出集团档案 ID。
部门→`DEPTID`、人员→`ACCEMPLOYEEID`、客商/客户/供应商→`RELATEDORGID` 有内置缺省，
其余维度必须显式配 `SPECATEIDnn`，否则进未映射清单。

查询结果里每条分录都带了 `account_aux_config`（该科目在 `bd_accass` 中配置了哪些辅助维度），
用于满足接口规范里「每个分录的辅助项需按科目的核算关系赋值」这条要求。

---

## 6. 还需要确认的事项（推送前必须闭环）

1. **集团下发 ID 的来源**：`ACCORGID`、`LEDGERID`、`ACCTITLEID`、`CURRENCYID`、
   `MAKERID/AUDITORID/BOOKERID/CASHIERID`、`DEPTID`、`ACCEMPLOYEEID`、`RELATEDORGID`、
   `SPECATEIDxx` 都是"集团下发/集团返回"的 ID，需要一张对照表。
   集团现有的「浪潮&用友 GSYY 数据集中工具」里对应的是 `YY_ORG_ORGS`（账套账簿对照）、
   `GS_SUBJECT_COMPARISON`（科目对照）、`FREEMAP`（辅助核算对照，含浪潮两位辅助编码 `GSCODE`）。
   需要确认本项目是复用这套对照表，还是另建。
2. **`ACCDOCTYPE` 凭证类型编号常量表**（规范里写的是"常量，后续提供"）。
3. **`SPECATEID01..99` 与 BIP 辅助维度的对应关系**（哪个维度落到哪个序号）。
4. **现金流量**：GS 凭证接口没有独立的现金流量字段。BIP 里现金流量既可能作为辅助维度 `f7`，
   也可能存在 `gl_cashflowcase`，需确认是否作为核算项目传、传哪个序号。
   注：本演示环境 `gl_cashflowcase` 为 0 行、`bd_cashflowuse` 也为 0 行（项目未分配到成员组织），
   这条链路在这里无法产生数据，等接真实环境再验。
5. **推送范围**：只推已记账凭证还是含未审核；作废凭证是否推（`ISVOID`）；暂存凭证默认已排除。

---

## 7. 验证记录

### 7.1 辅助核算全链路端到端实证（2026-08-31，已通过）

在 BIP 界面上手工配置科目辅助核算 + 制单，把 `gl_docfree1` 那条链路完整验了一遍。

**配置**（配在 `2021 2021基准科目体系` 上，自动传导到科目表 `1000`）：

| 科目 | 辅助项 |
| --- | --- |
| 6602 管理费用 | 部门(0001)、人员档案(0002) |
| 1122 应收账款 | 客户档案(0017) |
| 1001 库存现金 | 部门(0001)、人员档案(0002) |

**测试凭证**：账簿 `600-0001 东木运输-基准账簿`，2024-05，**转账凭证 转1**，摘要「买东西测试」

```
行1  借 6602 管理费用 100  【部门=6001 运输总办, 人员=10006 集团人力】
行2  贷 1122 应收账款 100  【客户档案=DFCX0001 东方晨旭】
```

**落库结果**：

```
行1 assid=…GSA → gl_docfree1.f1 =100110100000000025DU (部门 6001 运输总办)
                 gl_docfree1.f2 =10011010000000002P44 (人员 10006 集团人力)
                 gl_docfree1.f13=NN/A                 (空槽哨兵)
行2 assid=…GSL → gl_docfree1.f13=10011010000000005GSD (客户 DFCX0001 东方晨旭)
                 f1/f2 = NN/A
```

**生成的浪潮报文** `ASSISTANCELIST`（对照表填全后未映射项 = 0）：

| 分录 | 落位字段 | 值来源 |
| --- | --- | --- |
| 6602 | `DEPTID` | 部门 6001 运输总办 → 集团部门 ID |
| 6602 | `ACCEMPLOYEEID` | 人员 10006 集团人力 → 集团人员 ID |
| 1122 | `RELATEDORGID` | 客户 DFCX0001 东方晨旭 → 集团往来单位 ID |
| 1122 | `RELATEDORGLYID/CODE/NAME` | **本地往来单位三件套自动带出，不需要配对照** |

`ENTRYLIST` 方向也对：6602 借 → `LENDINGDIRECTION=1`，1122 贷 → `2`。

**这一轮确认的结论**：

1. `fi_freemap.num` → F 列映射正确：部门=`f1`、人员=`f2`、客户档案=`f13`
2. `assid` 是辅助组合哈希，相同组合的分录共用一条 `gl_docfree1`
3. 科目体系配置经 `pk_coveraccasoa` 自动向下级科目表传导
4. 档案动态解析在三张不同档案表上均成功（`org_dept` / `bd_psndoc` / `bd_customer`）
5. 未映射检测能精确报出缺哪个档案的集团 ID
6. **抓到并修复一个真 bug**：空槽哨兵 `NN/A` 未被归一，会造出假辅助行

### 7.2 当前环境的数据量

- `gl_voucher` 3 张：`100-0001` 记1、`201-0001` 记1（各 2 条无辅助分录）、
  `600-0001` 转1（2 条带辅助分录）
- `gl_detail` 6 条，`gl_docfree1` 2 条辅助组合
- `bd_accass` 9 行（0001 基准 3 行 + 2021 基准 3 行 + 科目表 1000 传导来的 3 行）
- `gl_deffree1` / `gl_freevalue` / `gl_cashflowcase` 仍为 0 行

### 7.3 还没有真实数据覆盖的部分

- **录入型（自定义）辅助核算** `gl_deffree1`：本库 17 个维度全是参照型（`isdef='N'`），
  没有录入型维度，这条分支只有代码路径、没有数据验证
- **现金流量** `gl_cashflowcase`：受第 4 节「坑③」限制，本环境无法产生数据
- **多币种 / 数量金额辅助**：只验过 CNY、汇率 1、数量 0