文档中心凭证三件套
Python SDK 中与「凭证」相关的两类核心元素为：凭证模型（JournalModel / AsyncJournalModel，组件类型 JM）与 单据 / 凭证模板（JournalTemplate / AsyncJournalTemplate，组件类型 JT）。二者分别对应 deepfos.api.journal_model 与 deepfos.api.journal_template。
在线文档入口：
源码模块：
-
deepfos.element.journal：JournalModel -
deepfos.element.journal_template：JournalTemplate、QueryBuilder、FullPostingParameter等
一、凭证模型 JournalModel
用于按 头表 + 行表 维护凭证数据（保存、更新、校验、删除、查询、过账等），底层表结构来自模型配置。
1. 初始化
from deepfos.element.journal import JournalModel
jm = JournalModel(
element_name='MY_JM',
path='/Application/02_Journal/MY_JM'
)
2. 常用属性
|
属性 |
说明 |
|---|---|
|
|
|
|
|
头表物理表名 |
|
|
|
|
|
当前库字段引用符，拼 SQL 时使用 |
3. 新增保存：save(head_df, line_df, ...)
头表必须包含 _type（凭证类型代码）及与行表关联的 journal_id（默认关联字段名可通过 relation_field 修改）。行表需包含关联字段及业务列。
import pandas as pd
head_df = pd.DataFrame([
{"_type": "type_01", "journal_id": "J001", "year": "2024", "entity": "E01"},
])
line_df = pd.DataFrame([
{"journal_id": "J001", "line_no": "1", "account": "1001", "debit": "100"},
])
jm.save(head_df, line_df, sync=True)
sync=False 时走异步保存接口（快速返回，适合大批量）。可通过 enable_* 一系列开关控制校验与默认值行为。
4. 更新：update(head_df, line_df, ...)
支持头行编辑及行的增删，通过 header_operate、line_operate 控制 EDIT / ADD / DELETE / DELETE_ADD 等组合。
5. 查询：query(where=..., head_column=..., line_column=..., sort_config=...)
where 可为 journal.table 上的 pypika 条件或已生成的 SQL 片段字符串。返回 (head_df, line_df) 两个 DataFrame。
t = jm.table
where = (t.year == '2024') & (t.entity == 'E01')
h, l = jm.query(where=where, head_column=['journal_id', 'year'], line_column=['line_no', 'account'])
6. 校验与删除
-
check(where)：标准校验，成功时会更新头表校验状态字段（见平台行为说明）。 -
delete(where)：按条件删除头行（条件以头表为主）。
7. 过账与取消过账
jm.posting(where)
jm.cancel_post(where)
where 写法与 query 一致。
二、单据模板 JournalTemplate
用于 日记账 / 单据模板 场景：批量写入头体数据、按复杂条件批量查询、以及按维度组合触发过账或取消过账。
1. 初始化
from deepfos.element.journal_template import JournalTemplate
jt = JournalTemplate('Journal_elimadj', path='/demo/journal')
2. 元数据与关联元素
|
属性 |
说明 |
|---|---|
|
|
模板全量定义（头体尾、审批、过账等） |
|
|
头表、体表字段编码列表 |
|
|
过账参数维度配置 |
|
|
关联审批流、角色方案元素（未配置时访问会报错） |
|
|
审批记录表、关账表对应的 DataTable 封装 |
3. 批量保存：batch_save(main, body, columns=None, chunksize=1000)
头表、体表为两个 DataFrame，通过 相同索引 或 columns 参数指定关联列 对齐多行体数据。
main = main_df.set_index(['year', 'entity'], drop=False)
body = body_df.set_index(['year', 'entity'], drop=False)
jt.batch_save(main, body)
4. 批量查询：new_query() + batch_query / batch_query_raw
使用 jt.table 得到字段代理，链式构造筛选与排序，再交给 batch_query。
t = jt.table
q = jt.new_query().where([
t.account.eq('1001001'),
t.period.gt('2'),
]).order_by([t.period.desc()])
df = jt.batch_query(q, show_detail=False)
5. 条件删除：delete(where)
where 为头表字段到取值列表的字典，或等价结构的 DataFrame。
6. 过账：get_posting / cancel_posting
传入 POV 维度字典，或使用 FullPostingParameter 在多套过账参数类别下分别指定维度筛选。
jt.get_posting({"year": "2024", "period": "12", "entity": "E01"})
使用说明
-
凭证模型侧重「凭证类型 + 头行表」一致性及与凭证组件规则引擎的校验；模板侧重「日记账单据」头体结构与过账维度映射。
-
条件表达式写法与数据表组件一致时，可参考 数据表 Python SDK 中的 SQL / pypika 习惯。
-
异步场景请使用
AsyncJournalModel、AsyncJournalTemplate，并对 IO 方法使用await。
注意事项
-
凭证模型 头表
_type必须与模型中配置的凭证类型代码一致，否则保存前会在 SDK 侧校验失败。 -
save与update：新增与修改路径不同，误用可能导致主键或行操作语义不符合预期。 -
模板过账：维度键需落在
posting_params定义的固定维度内；多类别参数时需使用FullPostingParameter。 -
清单页默认查询等若不走上述元素类，请以服务端 OpenAPI 与 HTTP 凭证三件套 为准。
回到顶部
咨询热线
400-821-9199
