# 1、接口介绍
在财务项目开发过程或者第三方系统对接时会有需要查询科目余额的或者核算维度余额的场景，为此提供了此余额接口供使用，可以按照科目或者核算维度的角度查询**单组织某个期间**余额数据。余额接口调用通过以下微服务方式调用。
```java
String result = DispatchServiceHelper.invokeBizService("fi", "gl", "BalanceService", "getBalance", param.toString());
```
# 2、使用说明
将微服务需要的参数封装成一个类，在使用时只需要够构造微服务对应的参数类，然后设置后对应的参数，调用就可以返回余额数据。下面会对使用的参数类以及先关的一些关键点进行介绍。
## 2.1、微服务参数类构造
调用余额表接口需要先构造对应的参数类，然后序列化传递给微服务接口使用。接口参数类如下：
```java
public class BalanceQueryParam {
//查询字段
private List<String> selectors = new ArrayList<String>();
//核算组织（必录）
private long orgId;
//科目表（必录）
private long accountTableId;
//账簿类型（必录）
private long bookTypeId;
//期间（必录）
private long periodId;
//币别（不设置则查所有币别）
private long currencyId;
//科目：<核算维度：值>
private Map<Long, List<Map<String, Long>>> accountAssgrp = new HashMap<>();
//分组汇总字段
private List<String> groupBys = new ArrayList<String>();
//是否扣减损益类金额
private boolean isSubstractPL = false;
//指定科目查询
private boolean isSpecialAccount = true;
public void addSelector(String selector) {
selectors.add(selector);
}
public void addGroupBy(String groupBy) {
groupBys.add(groupBy);
}
/**
* 以下省略getter和 setter方法
*/
}
```
## 2.2、参数类字段说明
| 字段 | 说明 | 备注 |
| ------------ | ------------ | ------------ |
| selectors | **余额表金额字段** 字段标识对应gl_balance元数据 | 必录，**只传金额字段** |
| orgId | 核算组织 | 必录 |
| bookTypeId | 账簿类型 | 必录 |
| accountTableId | 查询科目表 | 非必录 |
| periodId | 查询期间 | 必录 |
| currencyId | 币别 | 非必录，不录则查所有币别，综合本位币是所有币别的本位币汇总 |
| accountAssgrp | 科目维度Map参数，下文详细展开 | 科目非必录； 如需查所有科目则不传科目，只能查核算维度组合ID，无法按指定维度汇总查询 |
| groupBys | 汇总字段，**余额表非金额字段** 字段标识对应gl_balance元数据 | 必录，**非金额字段，除了金额字段的其他字段**； 查period期间字段则只查询当期有发生的数据，当期无发生不返回 |
| isSubstractPL | 是否扣减结转损益发生 | 默认为false |
|isSpecialAccount| true:只返回传参科目余额; false:返回传参科目上下级科目 | 默认为true； 注：查所有科目时，改为false |
accountAssgrp 科目数据传递在此详细说明下：
key是科目对应版本的ID，value是一个List<Map<String, Long>>，对应多个维度信息，Map中key是核算维度的flexfield,value是对应的核算维度基础资料值ID。**flexfield对应核算维度bd_asstacttype(表名t_bas_flex_property系统库)的fflexfield的值，是该维度的唯一标识。**
## 2.3、查找对应版本可用科目数据
科目基础资料是存在版本化的情况的，也就是一个编码会对应到多条数据，微服务接口需要传对应版本的科目id，如果不是前端界面已经传了对应版本的科目id过来，而是自己通过编码去查库的话，需要根据期间找到对应版本的科目记录。查询方式如下：
```java
//假设查询科目1001对应的id 期间period：2021年5期
long orgId = 100000L;
long acctTableId = 1L;
Date enddate = period.getDate("enddate");
//当前组织可用的科目
QFilter forgId = BaseDataServiceHelper.getBaseDataFilter("bd_accountview", orgId);
//科目表过滤
QFilter faccttableId = new QFilter("accounttable", QCP.equals, acctTableId);
//科目编码
QFilter facct = new QFilter("number", QCP.equals, "1001");
//科目生效日期过滤
QFilter fdate = new QFilter("startdate", QCP.less_equals, enddate)
.and(new QFilter("enddate", QCP.large_equals, enddate));
QueryServiceHelper.queryDataSet("", "bd_accountview", "id", new QFilter[]{forgId, faccttableId, facct, fdate}, null);
```
## 2.4、余额表gl_balance字段说明
| 字段 | 说明 | 备注 |
| ------------ | ------------ | ------------ |
| org | 核算组织 | |
| booktype | 账簿类型 | |
| period | 期间 | 有凭证发生的期间，如果无凭证发生的期间则不会记录余额 |
| endperiod | 结束期间 | 该维度下一个发生期间，无下一期则该值为99999999999L，表示最大期间 |
| accounttable | 科目表 | |
| account | 科目 | |
| currency | 币别 | |
| assgrp | 核算维度 | 多维度的唯一组合ID，例如：客户A供应商b；如需按指定维度汇总，则不能查该字段；查科目所有维度则需二开解析维度组合ID |
| measureunit | 计量单位 | |
| beginfor | 期初原币金额 | |
| beginlocal | 期初本位币金额 | |
| beginqty | 期初数量 | |
| debitfor | 本期借方原币金额 | |
| debitlocal | 本期借方本位币金额 | |
| creditfor | 本期贷方原币金额 | |
| creditlocal | 本期贷方本位币金额 | |
| debitqty | 本期借方数量 | |
| creditqty | 本期贷方数量 | |
| yeardebitfor | 本年借方原币金额 | |
| yeardebitlocal | 本年借方本位币金额 | |
| yearcreditfor | 本年贷方原币金额 | |
| yearcreditlocal | 本年贷方本位币金额 | |
| yeardebitqty | 本年借方数量 | |
| yearcreditqty | 本年贷方数量 | |
| endfor | 期末原币金额 | |
| endlocal | 期末本位币金额 | |
| endqty | 期末数量 | |
| count | 凭证分录数 | 用于记录对应余额的汇总凭证发生数 |
| comassist1 | 公共维度1 | 对应科目表的公共维度1，不启用公共维度则不需要关心 |
| comassist2 | 公共维度2 | 对应科目表的公共维度2，不启用公共维度则不需要关心 |
**延伸字段说明**：
科目余额方向字段：account.dc dc，方向值：借方dc=1，贷方dc=-1
注：接口所有余额数据都是按余额方向展示, 如endlocal=-100，dc=1, 表示借方期末余额-100；如需正数显示，方向和余额皆需乘以-1，则是贷方期末余额100
**需二开字段说明**：
**本期发生额** = (本期借方-本期贷方)*余额方向；
**本年累计发生额** = (本年借方-本年贷方)*余额方向；
**年初余额** = 期末余额-本年累计发生额；
注意以上字段都需区分本位币(后缀local)和原币字段(后缀for)，比如本位币的本期发生额=(debitlocal-creditlocal)*余额方向；
# 3、使用示例
## 示例1
查询2001科目下客户(f0001)维度的人民币发生金额，类似在核算维度余额表查询2001科目，维度选了客户进行查询。
```java
public static void test1(){
BalanceQueryParam param = new BalanceQueryParam();
param.setOrgId(51L);
param.setBookTypeId(237528347981256704L);
param.setCurrencyId(1);
param.setAccountTableId(1L);
param.setPeriodId(120210050L);
//设置查询字段(金额字段)
param.addSelector("creditlocal");
param.addSelector("debitlocal");
param.addSelector("endfor");
//设置汇总字段(非金额字段)，按客户f001和科目汇总；f0001 : 核算维度flexfield字段值，表示科目2001按客户维度汇总；
param.addGroupBy("f0001");
param.addGroupBy("account");
List<Map<String, Long>> list = new ArrayList<>();
Map<String,Long> flex = new HashMap<>();
flex.put("f0001", null);
list.add(flex);
//查询期间
DynamicObject period = BusinessDataServiceHelper.loadSingleFromCache(120210050L, "bd_period");
//根据期间和编码查找对应版本的科目id
long acctId = getAcctId(period, "1002");
param.setAccountAssgrp(acctId, list);
String result = DispatchServiceHelper.invokeBizService("fi", "gl", "BalanceService", "getBalance", param.toString());
}
/**
* 查找对应组织当前期间可用版本科目id
*/
private long getAcctId(DynamicObject period, String number){
long orgId = 51L;
long acctTableId = 1L;
Date enddate = period.getDate("enddate");
/**
* 查科目必要前置条件，查对应期间版本的科目ID
*/
//当前组织可用的科目
QFilter forgId = BaseDataServiceHelper.getBaseDataFilter("bd_accountview", orgId);
//科目表过滤
QFilter faccttableId = new QFilter("accounttable", QCP.equals, acctTableId);
//日期过滤
QFilter fdate = new QFilter("startdate", QCP.less_equals, enddate)
.and(new QFilter("enddate", QCP.large_equals, enddate));
/**
* 自定义查科目条件，按所需条件查科目
*/
//科目编码
QFilter facct = new QFilter("number", QCP.equals, number);
DynamicObject acct = QueryServiceHelper.queryOne( "bd_accountview", "id",
new QFilter[]{forgId, faccttableId, facct, fdate});
return acct.getLong("id");
}
```
##
