已知限制#

本文说明本服务的适用环境、写入分级、业务覆盖范围和已知限制。路由与字段见 接口参考，配置项见 配置参考，U8 自身的行为见 U8 行为说明。

1. 适用环境#

• 只在 U8+ V18.0 上开发和测试。其他版本的业务组件方法、参数和行为可能不同：先运行 u8co-bridge.exe --check-signatures（配置参考「命令行」）核对运行时类型库签名，再在测试账套上复核。签名自检只能发现方法名、参数个数和按引用方式的差异，发现不了行为变化；没有类型库的 .NET 组件只确认已注册。
• 桥是 32 位进程，必须运行在安装了同版本 U8、能创建 U8 业务 COM 组件的 Windows 主机上。
• 服务以 LocalSystem 运行，没有桌面。U8 组件若弹出交互对话框，工作线程会卡住，3 分钟后由看门狗让进程退出，再由服务管理器拉起。
• 一个桥只对应一个 U8 应用服务器（u8Server）。
• 生产订单审核需要 U8 生产制造服务（U8MPool）在运行，否则返回 503 u8_unavailable。U8 的部分服务在某些管理操作（例如重设数据库 sa 口令）之后可能停止。
• 缺省情况下桥使用 U8 登录给出的数据库连接（与 U8 客户端相同）。换成权限较低的专用登录（sql.json）时，U8 组件内部的跨库访问可能失败。
• U8 许可按工作站计点：同一台机器对同一个子系统不论登录多少次都只占 1 点，但这 1 点要与其他工作站竞争。某子系统的点数被占满时，U8 登录返回「加密点数已饱和」，桥按 licenseRetries 等待 3 秒、8 秒重试（连同登录本身总共不超过 20 秒），仍失败返回 503 u8_license_full，只能等其他用户退出或加购点数。许可采样回落到 UA_TaskLog 时 license_detail.used 会少算，near 只作提示，实际饱和以 full 为准；采样方式和 license_source 见 U8 行为说明「许可点数（加密点数）」。

2. 写入分级#

写入按风险分为两级。分级是桥上的硬性限制，写入策略（配置参考「写入策略」）在其上再做按账套、单据类型、操作的放行；二者是「与」的关系。

第一级：常规写入#

由 U8 业务组件、U8 凭证导入或 EAI 完成的写入（保存、审核、关闭、生单、核销、制单等），以及日常操作中复现 U8 界面执行的受控 SQL（凭证作废、签字、删除，取消核销、取消制单，单个档案的修改等）。对 allowedAccounts 中的账套开放（只读账套除外），再按写入策略放行。

以下写入属于第一级，开放正式账套前须特别确认：

• 采购手工结算（vouchers/create 的 purchase_settle）：复现 U8 手工结算界面执行的 SQL，已在测试账套上与 U8 自己做出的结算单逐项比对；限制见第 4 节「采购」。
• 货位调整单（position_adjust）的新增、审核、弃审、删除：经 U8 库存组件。
• 到货单的关闭、打开（vouchers/close 的 arrival）：经 U8 采购组件。

写入策略中对某账套使用通配（"type": "*" 或 "ops": ["*"]）时，以上写入随之放行，开通前逐项确认。

第二级：复现写入#

U8 没有可无界面调用的组件、由桥复现 U8 界面执行的 SQL 完成的写入，以及改动跨模块的期初、记账、结账状态的写入：

库存期初结存单的新增走 U8 官方 EAI 导入、审核和删除走库存组件，但改动的是跨模块的期初数据，因此归第二级；读取不受限制。

开放条件。 第二级写入（含预演）一般在登录 U8 之前、任务出队后各检查一次；arap/voucher/delete 要读出凭证才能判断它是否属于上表的处理凭证，因此在登录 U8 之后、事务里任何写入之前检查：

1. 桥 config.json 的 enableReplicatedWrites 为 true（缺省 false），否则 403 feature_disabled。
2. 账套在桥的 testAccounts 中，否则 403 test_account_only。

健康检查和 meta 的 replicated_writes 报告开关状态。配置方法见 配置参考「第二级写入」。

风险说明。 第二级写入已在测试账套上与 U8 界面执行的 SQL 实测核对，但它们不经过 U8 的业务组件，有以下固有风险：

• 只覆盖实测过的账套选项和业务形态；对其余情形桥尽量在执行前检查并拒绝（409「…接口暂不支持」），但无法保证覆盖 U8 的全部分支。
• U8 打补丁或升级后，界面执行的 SQL 可能变化，而桥不会随之变化。
• U8 依靠自身的任务互斥避免与客户端操作冲突，桥不参与这套互斥；执行期间有人在 U8 客户端操作同一模块、同一期间，结果可能不一致。
• 期初、记账、结账状态的错误会影响后续各期和各年，修正代价高。

因此第二级写入面向测试账套（建账演练、自动化测试、数据准备）。正式账套上的这些操作请在 U8 客户端完成，不要把正式账套加入 testAccounts。

3. 覆盖范围#

U8+ V18 提供给外部调用的程序接口有三类：U8API 原生动作（U8API/<对象>/<动作>，背后是各模块的业务组件）、EAI 导入导出（基础档案、总账凭证、固定资产卡片等）、UAP 单据接口（含质量单据卡片）。用友开放平台 OpenAPI 底层也是这几类接口，不支持事务。

本服务的桥直接创建与 U8API 背后同一批业务组件（VoucherCO_SA、VoucherCO_PU、USERPCO、UFAPBO 等）并在桥的事务中调用；生产订单、物料清单经 U8API 框架调用；总账凭证经 U8 凭证导入组件；基础档案经 EAI；U8 没有可调用组件的操作复现 U8 界面执行的 SQL（第 2 节）。读取和列表多数直接查表。

在 U8 程序接口之上，本服务另外提供：审批流（workflow/*）、参照生单（vouchers/generate）、预演（dry_run）、幂等键、单据查询与批量读取、字段元数据和字段标签、名称解析、只读报表与明细账、订单执行与单据追溯、期初余额与账套体检、附件清单、现存量与增量列表、单据事件（单据事件）、按 U8 操作员继承的读权限、写入策略、公司间接口、经营管理查询、MCP 服务（MCP）。

4. 业务限制#

销售#

• 发货单（dispatch）只接受蓝字。
• 退货单（sale_return，红字发货单）只能参照已审核的蓝字发货单或退货申请单生成；不支持只参照销售订单或无来源的退货单，也不从退货单生成销售出库。参照退货申请单生成的退货行不能改数量、删行（409，删除退货单后重新生成）。
• 退货申请单（sale_return_apply）只能参照蓝字发货单行新增，不做无来源申请；修改只改已有行，不能加行、删行；不做关闭、打开（400）；受审批流控制的申请单不能经接口写入（409 workflow_enabled）。该卡片由 U8 的 .NET 服务自行提交，预演只到调用之前（validate），写入后核对失败返回 504，须人工核对。
• 红字销售发票只能参照已审核、已开票退货（bneedbill=1）的退货单生成，或红冲已复核、非现结的蓝字发票（source_type: sale_invoice）；不做先开票（iDisp=0）的红字发票和无来源红票，现结发票请在 U8 客户端处理。红冲时红蓝关联由桥写在红字行 iSBVID 上（U8 自身数据中没有可用的关联列），U8 客户端做的红冲桥不识别，剩余可冲数量只按桥写的关联计算；发货行、订单行的累计开票数只记审计。红字发票不能修改，可以复核、弃复、删除；复核后又弃复、U8 未退回已复核开票数量时删除返回 409（同蓝字发票）。
• 发货单修改新增行只能加本发货单来源订单的行，没有超发容差；桥在保存后核对。
• 销售出库按行部分生成不是一个事务：先整单 MakeOutVouch 并提交，再在另一个事务中把新单改小或删除；第二步失败时桥删除刚生成的出库单补偿（409），补偿也失败时返回 504 outcome_unknown，按消息中的出库单 id 到 U8 核对。两步之间他人能短暂看到整单生成的出库单。
  • 不能指定仓库。可按行指定批号、货位并按批号 / 货位拆行，这是生成、改数量之后的第三步，同样失败即补偿。U8 生成时已带出货位记录的出库单不能再改批号或货位；保质期管理的存货不能指定批号；需要改数量而 U8 自动带了货位记录的出库单，桥不修改，按失败补偿（409），请整单生成或在 U8 客户端处理。
  • 第一步总是整单生成剩余的全部行，因此带 lines 时该发货单每一个未出完的行都必须能整行出库（库存、货位、批次），否则整个请求 409，即使出问题的行不在 lines 中。
  • 不带 lines 的整单生成也可能执行第二步：此前部分出库过的发货单，U8 会按原剩余数量整份再出（bOverDispOut），桥把多出的部分改回。
• 无来源销售出库只在账套未启用销售管理、库存选项不要求由销售系统生成时可用；不收保质期管理的存货；修改不能换仓库。
• 锁定（vouchers/lock）只做销售订单的整单锁定，不做按行锁定、请购单锁定；已审核的销售订单不能锁定；只有锁定人本人能解锁（按操作员姓名比较，截取 20 个字符；同名或前 20 个字符相同的操作员视为同一人）；本人重复锁定返回 200（already），重复解锁返回 409。他人锁定的销售订单、采购订单，桥只在修改、删除、审核、弃审前拒绝，关闭、打开和参照生单不检查。

采购#

• 采购订单锁定不支持：U8 采购组件的锁定调用实测一律被拒绝，官方锁定接口在本版本也不可用；type=purchase_order 返回 400，只能在 U8 客户端锁定。
• 到货单不允许超订单到货。
• 红字采购发票只能参照红字采购入库单生成（不做参照蓝字发票红冲、不做红蓝行混合的发票），不能修改。红字采购入库只能参照采购退货单生成，或无来源新增（表头 red: true；「普通业务必有订单」打开时也可新增，同 U8 客户端，该选项只限制蓝字）。
• 蓝字采购入库可参照采购订单、来料检验单或到货单生成；来源为采购到货单的蓝字、红字采购入库都能删除（到货 / 退货行的 fValidInQuan 随之退回）。需要来料检验的到货行不能直接入库，须先报检、检验后参照检验单入库。参照外币采购订单生成时，本币 = 原币 × 汇率。
• 采购入库单的新增、修改只做无来源（来源库存）的本币单：新增可以是红字退库，修改只改蓝字；外币供应商、期初采购入库单不支持，红字不能修改（U8 中录入的外币无来源单也不能改）；账套打开「普通业务必有订单」时不能新增蓝字；货位管理仓库的单据不能换仓库。
• 采购退货单（purchase_return）只做参照蓝字到货单或采购订单的普通采购退货，不做无来源退货、拒收单（iBillType=2）、浮动换算率或带自由项的行；审批流已发布时不支持。参照采购订单时可退数量取 iArrQTY，回写 fPoRetQuantity / iArrQTY。
• 请购单（purchase_requisition）只做普通采购、本位币（汇率 1）：只整单关闭、打开，不做按行关闭；不做参照 MRP / 销售订单的请购；不支持外币单价，U8 中录入的外币行不能经桥修改（409）；受审批流控制的请购单不能直接审核。
• 采购手工结算（purchase_settle 的新增，第一级）：U8 的手工结算组件在无界面调用时不执行结算，桥复现手工结算界面的写入。只做普通采购、人民币、专用或普通发票，一张结算单一个供应商；同一发票行不能既对冲又配对（税额无法分摊）。委外、外币、费用分摊、对冲与配对混用的结算返回 400 / 409，请在 U8 客户端手工结算。

库存#

• 有货位记录（InvPosition）的库存单据：
  • 采购入库、其他入出库、销售出库、材料出库、产成品入库的删除都先清货位再删除。
  • 修改时已有行不能改货位（400）；有货位记录的单据不能换仓库，有货位的行不能删除、只能改备注和表体自定义项（409）；新增行可以带货位。
  • 无来源材料出库、材料出库 / 产成品入库生单、采购入库生单（参照采购订单、来料检验单、采购退货单）的行收货位 cposition，货位管理仓库必填；红字入库的货位由调用方指定，不按原蓝字行带出。红字采购入库进入货位管理仓库同样必须给末级货位 cposition；U8 对红字入库在货位仓的 InvPosition、货位存量的处理未经实测。
• 产成品入库：
  • 参照产品检验单或产品不良品处理单生成。合并检验的检验单按来源逐行生单，数量不超过各来源剩余（不按库存选项放开超额入库）；删除时来源、检验单、订单行的累计数全部回退。这样生成的入库单不能修改（409，请删除后重新生成）。
  • 不良品处理单只接处理流程为降级 / 让步接收 / 升级的行，一次一行，且必须一次入库全部处理后数量（U8 不接受部分入库）。
  • 参照生产订单只能 1 行；订单行需要检验（QcFlag=1 且库存选项 ST.bQuality）时拒绝；这种入库单不能修改。库存选项 ST.bOverMPIn 打开时桥不按剩余数量拦截，超额上限交给 U8。
  • 合格入库量达到订单数量时 U8 自动关闭生产订单行；删除入库单时桥不会自动打开订单行，须先用 vouchers/close（action=open，带该 MoDId）或在 U8 中打开生产订单行，再删除。
• 材料出库、产成品入库（生单和无来源新增）不补收发类别，调用方必须给 crdcode（缺少时 400，field 为 head.crdcode）；采购入库生单不给时取采购类型或默认采购类型的收发类别，都未设置时 400。桥不按名称猜测收发类别。
• 无来源发货单、先开票销售发票、无来源到货单、无来源材料出库单只做蓝字、普通销售 / 普通采购 / 领料；发货单、发票可以是外币（须给汇率），到货单只收本位币供应商；发货单、发票、到货单须有部门（请求中或客户 / 供应商的分管部门）。账套选项（SA.bMustSO_ptxs、PU.bPTHavePO、ST.ballowAddnewVouch）禁止时 409。不做这些单据无来源的修改加行；材料出库不收保质期管理的存货，到货单不收浮动换算率的存货；先开票发票删除时 U8 连带删除其生成的发货单，未一并删除时桥回滚并返回 409。
• 形态转换单只做 cVouchType=15，不做组装单、拆卸单。调拨申请单不做关闭 / 打开；参照调拨申请单生成的调拨单不能修改（删除后重新生成），申请单行须有核准数量才能参照（累计调拨数量由 U8 回写）。
• 盘点单不能修改、不能审核：U8 审核时生成盘盈盘亏单需要一个只能由客户端窗体创建的 VB6 Collection，无界面调用一律报「类型不匹配」，只能在 U8 客户端审核、弃审。不做复盘；账面数量缺省按现存量（仓库、存货、批号、自由项逐项相等），不分货位；账套中没有「盘亏出库」收发类别时 cordcode 留空。
• 形态转换单、调拨申请单、盘点单的行都不收货位。形态转换单（以及在 U8 客户端审核的盘点单）生成的其他出入库单不能单独弃审、修改、删除，须在来源单上弃审；生成单已审核时来源单弃审返回 409，请先在 U8 中弃审生成单。调拨单生成的其他出入库单同理。
• 货位调整单不开放修改；审核前后在事务中核对货位台账（每行一出一入）和货位结存变动。

生产制造#

• 受审批流控制的生产订单不能经桥审核、关闭、打开、修改，已提交的不能删除。有在制品的生产订单行不能关闭（U8 界面缺省允许，桥拒绝）。
• 新增不收子件、不关联销售订单，用料由 U8 按标准 BOM 展开。
• 生产订单修改：
  • 只改未关闭的订单（已关闭的先打开）。已审核的订单与 U8 客户端「变更」一样直接修改、不弃审；已领料的订单也能改，但改后子件需求不能少于已领数量（409；已超额领料的子件即使只改备注、日期也返回 409，请在 U8 客户端变更）。
  • U8 修改时会删除并重插子件，AllocateId 随之变化。材料出库单行的子件关联（rdrecords11.iMPoIds）由桥在 U8 提交后改到重插的新子件（调用期间并发领料新增的出库行一并改写）；改写或核对失败返回 504，按审计事件 mo_update_snapshot / mo_update_refs / mo_update_remap 修正。桥写回已知会丢失的列（OpComponentId、VirOpComponentIds、cSubSysBarCode、SoDId、UpperMoQty），MoUpdateCols 名单外的子件列不保证保留。
  • 已报检、已被产成品入库引用、子件被材料出库以外的单据按 AllocateId 引用（领料申请、调拨、替代料出库、材料出库的序列号明细等）的订单不能修改。
  • 不能改开工日期（有产出品子件的行也不能改完工日期），不能新增行、删行、换存货；子件上有母件损耗、偏置期、需求跟踪、累计量等桥无法保留的设置时不能修改；子件带替代料时不能修改；表头只能改备注，自定义项只收文本型且不能清空。改数量时子件按 U8 的算法重算（手工调整过的子件数量会被覆盖），辅计量用量与主用量不一致的子件不能改数量。
• 物料清单只做标准 BOM，不做替代 BOM；带替代料、定位符、分段损耗或自由项的清单不经桥修改，带辅计量的行不改用量。

质量#

• 审批流只接入四种质量单据（QM03 到 QM06）。检验单不能经 vouchers/verify 直接审核，只走 workflow/*。
• 新增只做参照生单：来料报检单参照蓝字到货单、产品报检单参照生产订单、来料 / 产品检验单参照已审核的报检单、其他检验单参照已审核的其他报检单；其他报检单可无来源新增。不做其他来源（委外、发货、库存等）的报检和检验单，不做合并检验、批量检验。一张检验单只检一个报检行；检验项目只能整组覆盖方案的缺省项目。检验方案没有存货对照时缺省取该存货最近一张检验单的方案，一张都没有时调用方须给 project_code。
• 检验单修改（来料 / 产品 / 其他检验单，以及其他报检单）只改表头：不改检验数量、存货、仓库、检验方案、抽检量，不增删检验项目，其他报检单不改表体；只改未提交审批、未审核、没有下游的单据，已审核的不自动弃审。修改由 U8 自行提交，预演只做校验，回读不清时返回 504 outcome_unknown。修改的功能 id 尚未在 U8 客户端逐项点验。
• 报检单（来料、产品）不能修改：U8 的修改调用对报检单不可用（「表体行数必须大于0行！」或「更新发退货报检单失败！」）。
• 报检单不能经接口单独审核（U8 的审核语句要写报检单表上不存在的 IVERIFYSTATE 列，只有保存时的自动审核可用）；产品报检单可以单独弃审，弃审后接口不能再审核。质量管理选项关闭自动审核的账套中，经本服务生成的报检单是未审核的，不能用来生成检验单。
• 删除已审核的报检单时桥先弃审（U8 自行提交），之后删除失败则单据停在未审核：桥返回 504 outcome_unknown 并注明「报检单已弃审且未删除」，接口无法重新审核，请在 U8 客户端处理或再次调用删除。
• 不良品处理单只做参照检验单生单、直接审核和弃审、删除，不做修改；一张检验单只能生成一张处理单，各行数量合计必须等于检验单的不良品数量。受审批流控制的不良品处理单不能直接审核，走 workflow/*。
• 检验单的新增、修改、删除，报检单的删除，不良品处理单的保存、审核、弃审、删除都由 U8 自行提交：预演只能做到校验（参照带入、必输项核对），不能在事务中预演保存；调用异常或回读不清时返回 504 outcome_unknown，须调用方核对。

应收应付#

• 收付款单、应收应付单只处理手工录入的蓝字单据（新增、修改、删除、审核、弃审），只能新建蓝字；票据或网银生成的收付款单不处理。供应商退款、客户退款（ap_refund、ar_refund）的读写、审核同收付款单，可经 arap/voucher 制单，但不能核销、不能用于票据和坏账，这些请在 U8 客户端完成。
• 核销和取消核销（arap/writeoff、arap/writeoff/cancel）：
  • 一次处理一张收付款单的一行对发票、应收应付单。外币要求同币种；单据汇率与收付款单不同时，与 U8 相同按收付款单汇率核销，汇兑差额留给期末汇兑损益（arap/exchange_gain，第二级）。本币按收付款单汇率逐行折算，尾差并入第一项（U8 有时把尾差放在最后一项，合计相同，逐行差 0.01）。预收 / 预付（bPrePay=1）行可以核销。
  • 核销本身不做红票对冲、收付款单之间对冲、汇兑损益、坏账、并账，这些由各自的处理路由完成。受审批流控制的收付款单或单据不能核销（409 workflow_enabled）。
  • U8 在 PO 登录时检查的 Locked_by_Other（LockVouch 表）桥不检查，也不写 LockVouch：U8 客户端正打开同一张单据时桥照样能核销、取消核销，冲突只靠数据库锁。
  • 取消核销只收桥能做出的那种批次：同一张收付款单、本侧 9P、对方是销售发票 / 应收单（采购发票 / 应付单）、未制单、无合同、同一期间；U8 中做的其他核销（多张收付款单、对冲、跨期）请在 U8 客户端取消。不做「保留线索」（bAR2Cancel / bAP2Cancel）：账套打开这两个选项时桥取消后不留线索行，与 U8 不同。应收一侧与 U8 相同，账套中有未审核的收款单（不含现结）时不允许取消，409。销售发票的累计核销经 U8 的回写组件回写（连带订单、发货单、信用额度）。
• 制单和取消制单（arap/voucher、arap/voucher/delete）：
  • U8 没有无界面的制单组件，桥按 U8 的规则组织分录、经凭证导入 U8PzInsert 保存，再复现 U8 的回写，不是 U8 自己的「制单处理」。
  • 一张单据一张凭证，或同类型的 2 到 20 张单据合并成一张凭证（ids，每张各组各的分录、不跨单据合并，凭证行 coutid 各写各的单号）；不做混合类型合并，也不做 U8 合并制单中按摘要 / 结算方式 / 自定义项的合并选项（bUniteDigest 等）。
  • 不做核销制单（bHXNeedZd）和现结制单，不做制单前在凭证界面改分录（U8 选项 bPZMakePZNow）；只做本币蓝字单据，现结 / 现付发票（XJ）返回 409，请在 U8 客户端制单。支持的单据是销售发票、采购发票、收付款单、应收应付单、退款单。退款单表体中往来明细之外的费用行桥不组织分录，借贷不平时 409。汇兑损益、坏账、票据、并账等处理的制单见 arap/process/voucher。
  • 对方科目设置按行上填了的键取最具体的一行，组合键的优先级按桥的规则，可能与 U8 客户端不同；科目、辅助项、现金流量项目无法确定时一律 409，不猜测。
  • 凭证保存和回写不在一个事务中：回写失败（含外部业务号与 U8 客户端同时制单撞号）时桥删除刚生成的凭证（409），删不掉时返回 504；504 之后单据往来明细可能还没有凭证号，重投会被拒绝（409，指出总账中那张未回写的凭证），请先核对、删除后再制单。
  • 取消制单只收上述单据原始行生成的凭证，以及处理制单（应收冲应付、应付冲应收、并账、汇兑损益、红票对冲、票据处理、坏账处理整批）生成的、未记账未审核未签字的凭证；引用它的往来明细上有核销、转账等其他处理行时 409。已记账的凭证请先在总账取消记账。
• 票据登记、删除（notes/create、notes/delete）：不调用 U8 的票据组件（无界面调用时会自行提交、不生成收款单并挂起），桥按 U8 界面的结果在一个事务中写入、删除票据行 AP_Note，并经 UFAPBO 生成、删除收款单；不建条码档案（AA_GeneralBarCode），不做期初票据和改票；分包票据可以登记、删除（sub_start / sub_end）。
• 应收票据处理：结算、贴现、背书冲应付、退回及其取消、制单。退回经 U8 应收单组件另生成一张应收单，分包票据须退回全部可用区间。
• 应付票据（flag 为 AP，第二级）：登记、删除、结算、退回及其取消和制单已在测试账套实测，退回的制单未经实测；应付的票据科目 pjkm 未设置时须在请求中给 note_km；应付票据的贴现、背书、期初应付票据不做。
• 坏账处理（arap/bad_debt，第二级）只做应收：
  • 计提只做应收余额百分比、账龄分析、销售收入百分比三种方法（不做直接销售法）；销售收入百分比的取数区间为 date 所在年度 1 月 1 日到 date，可能与 U8 界面不同。
  • 坏账准备参数取 autoid 最大的一行（同 U8），其年度与处理日期不符时拒绝；没有该年度参数行时拒绝，不像 U8 那样自动新增。
  • 坏账收回只收一整张单行、未审核的收款单（金额等于其全部余额）。做法与 U8 不同：桥先用 U8 的审核组件正式审核收款单（写审核行，贷应收），再写 9H 借方行（借应收，科目同收款单行），两者相抵、客户应收余额不变、坏账准备加回；制单时 9H 凭证同时回写收款单的审核行和表头凭证号。U8 客户端做的坏账收回（收款单没有审核行）桥不取消。
  • 外币坏账发生（9G）不能用 arap/process/voucher 制单，请在 U8 客户端制单。
  • 同一年度计提多次时只能取消最后一次，且会连同前面的计提一起冲掉（U8 参数行只记一个处理号和累计计提额）；该年度有多行参数时不能取消计提。计提（9F）只记在参数行上、没有往来明细，只出现在 arap/process/list 的摘要项中，不在按 Auto_ID 增量的处理记录列表中。
• 汇兑损益（arap/exchange_gain，应收、应付，第二级）：正式账套请在 U8 客户端处理。
• 期初单据（openings/arap，第二级）只做 Ap_Vouch 上的期初应收单 / 应付单，期初发票、期初收付款单和期初票据不做。

总账#

• 凭证只处理手工凭证的修改、作废、删除；删除只能删已作废的凭证；红字冲销凭证和带自定义项的凭证不能修改。凭证类别的数据权限（bVouchCtlPZLB）不在桥中过滤。
• 记账（gl/vouchers/post）走 U8 自己的总账 .NET 组件，只记本年第一个未结账期间：
  • 记账前必须已审核；账套要求出纳签字、主管签字时还须已签（桥不做主管签字）；作废凭证与 U8 相同也记账。
  • 年度首张凭证记账前的期初对账（BalanceRule.QcCheck，会写 GL_merror）在桥内执行失败时返回 409，请在 U8 客户端记本年第一张凭证。
  • 有人在 U8 中汇总了本年度记账范围尚未记账时，桥与 U8 自己的汇总一样覆盖该范围，记完后清除；对方再点「记账」记不到任何凭证、须重新汇总，且此操作会清空 U8 的 Gl_mpostcond 本年度，之后 U8「恢复记账前状态」无法撤销桥的那次记账。
  • 桥记账期间，U8 客户端的汇总、记账须等桥提交；账套要求出纳或主管签字时，同一实例上其他账套的记账也须等待（U8 的 tempdb..GL_jztmp）。
  • 记账耗时超过写入的开始余量时 HTTP 可能先返回 504 而记账照常提交，再记会返回 409「凭证已记账」，先 load 核对。
• 取消记账（gl/vouchers/unpost，第二级）：按记账公式反向处理，只恢复最近一次记账的整批、不能挑选单张；记账时新增的余额行保留为全零的行；依赖这批凭证的期间损益结转不检查；功能 id 按记账检查。核对清单最多 500 张（API、客户端、桥一致），超过时不带清单取消。正式账套记错时用红字冲销或在 U8 客户端处理。
• 红字冲销（gl/vouchers/reverse）只做整张、一次（U8 允许多次和部分冲销）；不冲销带自定义项、数量与金额方向不一致、外币汇率为 0、其他系统生成的凭证；现金流量只复制项目和本币金额（原币、数量、辅助项、自定义项列与新增凭证一样不写）；原凭证没有外部业务号时桥为其补写一个，原凭证所在期间已结账也照补；保存后的补写或回读失败返回 504，此时红字凭证可能已存在但没有写上关联，重发会再冲一次，先核对。
• 期间损益结转、自定义转账（gl/transfer/pnl、gl/transfer/custom，第二级）：
  • U8 的转账生成在客户端中，没有可调用的组件；桥按 GL_bautotran 的定义和已记账余额计算分录、经凭证导入保存，再按 U8 生成的结转凭证补写标记（coutsign、coutno_id、idoc=-1）。对应结转、销售成本结转、汇兑损益结转、修改转账定义、生成后自动审核记账都不做。
  • 只取已记账余额，要求本期凭证全部记账（同 U8）。期间损益按科目余额方向分收入、费用两张凭证，余额在反方向的写成同一边的负数。
  • 自定义转账的公式只支持 QM（一个辅助项参数）、CE、四则运算，其他函数返回 400；QM 只支持按月取数，用到「年」（QM(…,年,…)）的定义不支持（给 tran_id 时 400，不给时跳过），请在 U8 客户端生成。行科目要求辅助核算而定义和公式给不出时跳过，不按辅助项自动展开。
  • 功能权限按填制凭证 GL0201 检查；数据权限按总账查询的口径从严（涉及的科目、辅助项有一个无权即 403）。
  • 不给 tran_id 时桥不能像 U8 那样逐个序号结转再取数：后面的定义要取前面定义本次生成的科目时返回 409，请逐个 tran_id 生成、记账。
  • 期间损益的两张凭证分两次导入，不在一个事务中：只保存了一张时，记账后重新调用补生成另一张。多张凭证时第二张起失败返回 504。

期初、结账与存货核算#

以下写入均为第二级（第 2 节）。

• 期初记账（openings/post）只做采购管理（module=pu）和存货核算（module=ia）；销售、库存、应收、应付、总账的期初记账在 U8 客户端完成。
  • 采购期初记账改 GL_mend.bflag_PU；取消记账按 U8 的条件拒绝（已有月份结账、已有任何采购发票），取消记账的成功路径未经实测。
  • 存货核算期初记账没有可无界面调用的组件，桥复现 U8 界面的取数、汇总和收尾：只取已审核的期初结存单，金额取单据上的金额或单位成本（U8 界面取数后可手工改单价，接口不能，没有成本的行记 0）；不写计价辅助表 IA_ValuationAss，有先进先出 / 后进先出计价的期初行时返回 409「接口暂不支持」；不写发出商品、直运、项目核算的期初；登录日期须在存货核算启用年度。取消期初记账只删除第 0 期的期初数据，不做 U8 的「取消开账」；启用年度已有月份结账或已有日常数据时返回 409（同 U8）。
• 库存期初结存单（stock_opening）新增走 U8 官方 EAI 导入 storeqc，每行建成一张单据，日期固定为库存启用日前一天；审核、弃审、删除走库存组件，审核日期写成单据日期；不能修改（删除后重新录入）。库存启用的第一个月已月结时 U8 不许增删库存期初（409 u8_rejected），存货核算已期初记账后不能增删、弃审库存期初（409 state_mismatch）。
• 应收应付期初单据（openings/arap）：单据日期为启用日前一天，负数金额与 U8 相同存为正数、借贷方向取反；启用月份已结账后不能修改（同 U8）。
• 总账期初余额只读（reports/opening_balance）：U8 的 EAI 期初余额导入（codebalance）无界面调用时报「未设置对象变量」，经官方分发器同样失败。
• U8 只在该模块期初尚未记账时允许修改期初（期初记账标志是 GL_mend 在启用年度第 0 期的 bflag_ST / bflag_AR / bflag_AP / bflag）；启用后的期间结账、年结之后修改期初会导致后续各期和各年的余额不一致。
• 月末结账（periods/close）：
  • 桥完成检查后按 U8 的做法修改 GL_mend 的结账标志，不调用 U8 的结账组件（这些模块没有可无界面调用的组件）；检查项按 U8 界面和存储过程整理。期间按自然月计算。
  • 库存：按 U8 写 / 删 ST_MonthAccount 等五张月结快照，有单据、有结存的月份都处理。以下情形返回 409，请在 U8 中结账：库存选项月结按部门或按收发类别、业务类型汇总（ST_DefineSet 的 cdepcode / item）；账套有保质期管理的存货（bInvQuality=1）；已审核的库存期初单据审核日期与单据日期不同月，或首次库存结账时期初日期早于第一个会计期间。不查货位结存差异、其他出库预算超额、质检人设置、库存期初记账；不写 ST_MonthAccountsbus / ST_MonthAccountVsbus / ST_TotalVenSum；取消结账只做单月。结账时不锁库存单据表（U8 依靠自身的任务互斥）：检查和写快照之后、提交之前若有人在 U8 客户端保存或审核本月单据，快照会落后，结账期间不要在 U8 中改动本月库存单据。
  • 存货核算有数据的月份执行 IA_Close / IA_UnClose，限制同下文「存货核算」。
  • 采购结账要求启用年度已做期初记账。存货核算启用年度第 0 期 bflag_IA 为 0 时照样结账，响应带 warnings ia_opening_not_posted（有月份结账之后仍能做期初记账，但不能再取消）。
  • 总账结账要求已启用的固定资产、薪资、成本已结账，桥不结这几个模块（through 停在总账那一步，409）。取消总账 12 期时，下一年度第 0 期已置标志并且已有凭证则不处理（不回退年度结转）。
  • 模块之间的结账顺序只核对过「采购取消结账要求库存、存货、应付未结账」和「总账最后结账」，其余按 U8 的结账顺序推定。取消结账只能取消最后一个已结账的期间；总账选项要求账套主管口令（bConselClos）时不处理。
  • 不改 UFSYSTEM..UA_Account_sub 的 iModiPeri（桥的请求连接从不写 UFSYSTEM），U8 界面上「最后结账月份」等显示可能落后，以 GL_mend 为准（reports/close_status）。不做年度结转，不做固定资产、成本等其他模块的结账。
• 存货核算（ia/post、ia/period_end，以及 periods/close 的 module=ia）：
  • U8 没有可无界面调用的组件，桥按 U8 界面的存储过程调用顺序执行 T-SQL 脚本，只覆盖实测过的设置。执行前只检查四项：按仓库核算、每个仓库全月平均法、暂估单到回冲、销售成本按发出商品或销售出库单，不符时返回 409「…接口暂不支持」；本月有直接供应的材料出库时在记账脚本中 409 并回滚。标准成本、委外加工等其他设置不在支持范围，桥也不检查，这类账套不要使用本接口。
  • 记账只整月处理，不能按仓库、单据类型或单张单据挑选；U8 无法确定成本的存货不能经接口输入单价，只能整笔拒绝（on_uncosted=refuse）或跳过这些存货（skip）。恢复记账整月恢复，发出商品的销售出库连着下月发票时拒绝。
  • 脚本执行完整的存货核算过程，生产规模的月份需要数分钟，期间持全局写闸门（同一桥上的其他写请求返回 503 busy_timeout）并锁住该月的出入库单据行；超过 iaCommandSeconds 时返回 503 ia_timeout，已回滚。不要在 U8 客户端同时做存货核算。

基础档案#

• 档案不能改编码。可写的档案见 接口参考「基础档案」，其他档案只读。
• 会计科目写入不开放：科目导入组件无界面调用时报「未设置对象变量」，且科目按年度存储、写入年度无法确定。
• 凭证类别不收限制类型和限制科目，新类别一律「无限制」；修改只能改名称；修改、删除走受控 SQL（U8 的 EAI 只提供新增）。
• 币种不能写本位币，已被引用的币种不能修改、删除，删除时连同汇率一起删除。
• 汇率新增按登录年度写入（编码的年度必须是登录年度），一次只写一种汇率，已存在的键不能用新增覆盖（请用修改）；本位币和总账已结账期间的汇率不能写；浮动汇率新增后 U8 存储的日期写法是 yyyy-mm-dd。
• 项目走受控 SQL，可新增、修改；删除只删未被引用的项目（按账套库中带项目大类和编码列的表查引用，用其他列名引用项目的表不查）；不能新增项目大类或分类；项目结构有额外栏目或子表的大类（如现金流量项目、项目管理）不支持。
• 开户银行的账号定长按所属银行（AA_Bank.bComdFixLen / iComAccNoLen）检查。
• 客户、供应商的银行账户、客户联系人一次只写一行：默认账户不能取消默认，也不能在还有其他账户时删除（先把另一个设为默认）；删除账户不查单据（单据中的账号是文字副本）；银行账户只走受控 SQL（U8 的 EAI 按整条客户档案校验）。客户联系人的编码由 U8 自动编号，新增时不能指定；删除只查客户档案的主要联系人、收货地址、销售单据和合同的引用，不查 CRM 的活动、商机等。
• 供应商联系人：新增经 EAI 分发器，修改、删除由桥直接改 Ven_Contact（U8 的分发器不支持改删）。不开放职务 position、个人爱好 favorite；桥不改供应商档案上登记的主要联系人（Vendor.cVenContactCode），设为、取消主要联系人只改联系人的标志，档案上登记的那一个不能取消；采购单据上的联系人列按联系人编码查引用，单据若存储其他写法则查不到。
• 自定义项档案、客户存货对照不做修改（U8 的 EAI 不提供），请删除后重建。
• 名称解析（archives/resolve）的 partial、ambiguous 结果须由人或调用方确认；包含匹配只按名称、简称和存货的「名称 + 规格」，不做拼音、同义词或模糊纠错。

固定资产与设备#

• 固定资产卡片只做新增和撤销本期新增（archives/create、archives/delete 的 fa_card）：经 EAI 导入的是原始卡片，开始使用日期必须早于固定资产当前期间；只支持单部门、本位币。撤销只限当前期间新增录入、只有一个版本（没有变动单、没有减少、没有制单）、本期未计提折旧、资产编号不与其他卡片重复的卡片。卡片不能直接修改。
• 变动单和资产减少（报废、毁损等）在 U8 客户端完成：U8 EAI 没有变动单的导入样式表，资产减少没有 EAI。固定资产结账、计提折旧也在 U8 客户端完成。
• 设备台账（equipment）只做读取和新增：U8 的设备 EAI 只有插入，修改、删除在 U8 客户端完成。

附件、报表与跨账套查询#

• 附件只列清单（gl/vouchers/attachments/list、vouchers/attachments/list），不下载、不上传、不删除：凭证附件的文件在 U8 文件服务器上，没有不经 U8 界面取文件的方式；单据附件可能存在库中（VoucherAccessories.FileContent），也可能只登记了文件服务器上的标识。列出的键按 U8 组件的查询写出，尚未用真实附件核对。UAP 单据（Uap_Attachments）的附件不列出。
• 报表：辅助核算余额表只含已记账凭证；物料清单用量不含损耗率，只展开主 BOM；账龄不单独排除坏账收回（9H）等处理行。含未记账的科目余额表按本服务的口径计算，未与 U8 界面逐项核对。
• 公司间接口：对照（U8CO_IC_MAP_FILE）由站点维护，存货、往来单位、科目都须逐个对上，未对上的不参与对账和合计；对账按存货、数量、日期配对，不比较价格；合并试算只抵销往来，不抵销内部收入成本和未实现利润；买方生单只能参照公司间采购订单（不做其他入库）。
• 经营管理查询：利润表从凭证取数并排除损益结转凭证，口径与 U8 的利润表模板不一定相同；prefix4 假定一级科目为 4 位编码，科目表与 2007 年准则不同的账套须配置利润表行定义；合并时只按 rev_cogs 规则抵销内部收入成本，不抵销存货中未实现的内部利润，往来按对照的往来单位编码抵销；不提供存货周转率；DSO / DPO 按近 12 个月单据金额估算；缓存不区分调用方，U8 中收回权限后最长须等缓存过期（6 小时，期间未结账时 60 秒）。

5. 一致性#

• 销售发票复核后又弃复时，U8 有时不把发货行的已复核开票数量退回。这种发票用 U8 删除后累计开票数也不会回退，因此桥拒绝删除（409），请在 U8 客户端处理。
• U8 的采购组件（VoucherSave2 等）在某些失败路径上会自行结束事务，此时没有写入。若保存成功后本连接上已没有事务，桥的回写核对无法完成也无法回滚，返回 500 internal（经 API 为 502，message「内部错误」），单据可能已落库，须人工核对。预演中遇到这种情况桥返回 504 outcome_unknown，不会声称预演成功。
• 以下写入由 U8 自行提交：凭证导入；档案导入（含币种、凭证类别经凭证导入组件的新增，汇率、供应商联系人经 EAI 分发器的新增，原因码）；期初结存单的新增（EAI 导入）；生产订单、物料清单的新增、修改、删除、审核；检验单的新增、修改、删除，其他报检单的修改，报检单的删除（含删除前的弃审）和产品报检单的弃审；不良品处理单的新增、审核、弃审、删除；退货申请单的新增、修改、删除、审核、弃审；总账红字冲销的保存（凭证导入）；期间损益结转、自定义转账的保存（凭证导入）；审批流操作。调用抛错或回读失败时返回 504 outcome_unknown，结果须调用方核对。
• 单号记录（VoucherHistory）和 UFSystem 中的主键计数在事务回滚后不退回，只会留下断号。
• 请求的 year 是账套库年度，会计年度取登录日期的年份。总账凭证日期必须在登录日期所在年度内。

6. 预演（dry_run）#

• 预演不是免费的只读查询：它与真写一样登录 U8（占用许可点数）、按单据加锁、进入写闸门，rollback 模式还会真实调用 U8 组件、在数据库中持有行锁直到回滚。预演期间其他写入须排队；不要用它做高频轮询。
• 单号可能跳号：rollback 模式的新增、生单中 U8 取过的单号回滚后不退回，响应带 number_may_skip。预演返回的 code、id 不是真做时会得到的号。
• validate 模式只执行桥自己的检查：凭证导入、档案导入、期初结存单导入、生产订单和物料清单的 U8 API、审批服务、检验单和不良品处理单的保存与删除（不良品处理单另有审核、弃审）、报检单删除、总账记账这些由 U8 自行提交的组件不会被调用，U8 在保存时的检查（档案必输项、BOM 结构、凭证导入的校验等）没有执行，响应带 validate_only。预演通过，真做仍可能返回 409 u8_rejected。
• 预演与真做不在一个事务中：其间他人可能修改了单据、库存或余额，以真做时的响应为准。
• U8 组件在预演中自行提交时（桥在提交点发现本连接上已没有事务），写入可能已生效：桥返回 504 outcome_unknown，须按真写的 504 核对。这只在 U8 组件的行为与 rollback 模式的归类不符时出现。开启了事务却未走到提交点的预演同样返回 504（dry_run_no_commit）。
• 销售出库按行生单（带 lines）的预演只到第一步：docs 是 U8 整单 MakeOutVouch 生成的出库单（整张发货单的剩余数量），按行改回数量、批号和货位的后续步骤没有预演，detail.not_previewed 注明。确认时不要把 docs 中的数量当作按行的结果。
• 预演的 docs 读取的是表头表、表体表的原始列，不是 vouchers/load 的 U8 行集；关联表（货位、批次、往来明细等）中的变化只在各路由的 detail 中给出一部分，不是完整的前后对比。
• 只有登记在桥 DryRunModes 中的路由和操作能预演（meta 中可查），其余返回 400。sale-orders/verify、dispatches/verify 两条专用审核路由不支持（改用 vouchers/verify）。
• 只读账套、第二级写入的开放条件和写入策略对预演同样生效。

7. 权限与安全#

传输与部署#

• 桥使用 HTTP，不使用 HTTPS。口令另做 AES 加密、请求有签名，但响应没有签名也没有加密。桥必须放在受信任的网段，只对 API 服务开放端口（SECURITY.md）。
• 随机数缓存在进程内存中，重启即清空：重启后 120 秒内，截获的旧请求可以重放一次。
• 来源白名单按 IP 逐字比较，不支持网段；经过 NAT 时须写桥看到的地址。
• 桥的健康检查不签名、不检查来源 IP，只靠防火墙限制来源，响应中只有线程、队列计数和开关状态。
• API 服务的限流在进程内，多进程或多副本部署时各自计数。
• 经本服务审批时，缺省拦截 U8 移动审批（友空间）的推送，审批人收不到手机通知。桥 config.json 写 "mobilePush": true 可打开推送（配置参考）；开启后的推送链路尚未在真实环境中实测。
• 本地 MCP 服务（mcp/）以配置文件中的 U8 操作员和令牌的身份调用接口，AI 代理能做的就是该操作员和令牌能做的全部。只授予需要的权限：只读场景使用只读令牌并设置 read_only，写入场景在 U8 中给专用操作员最小的功能和数据权限（MCP）。

操作员权限#

• 每个请求以调用方提供的 U8 操作员登录，读路由继承该操作员的功能权限、记录级数据权限和字段权限（接口参考「操作员权限」）：perm/snapshot 返回本人的有效权限；perm/evaluate 查询其他操作员的权限，须在桥 permEvaluateOperators 和信任项 perm_evaluate 两侧同时放行；被字段权限拒绝的列置空并列在 masked_fields，不整张拒绝。
• 读路由的权限快照缓存 60 秒：在 U8 中收回授权或打开数据权限开关后，最多 60 秒内读路由仍按旧权限（写路由不缓存）。字段权限随权限快照一起缓存。
• 字段权限（AA_ColumnAuth）从严：一个金额列被拒绝时同一范围的全部金额列（含桥自己的 amount、cogs 等汇总列）一并置空，可能比 U8 界面遮得多；单据类型与 U8 字段权限对象的对应按 U8 列表对象登记，未登记的类型按字段名在全部对象上比对；reports/mgmt/sales 的销售成本按销售出库单对象、mgmt/cash_stock 的存货金额和库存期初金额按出入库单对象的并集遮蔽，为推定口径，未与 U8 报表逐项对照。档案（如存货档案上的参考成本）、应收应付、总账不遮蔽（U8 没有对应的字段权限对象）。reports/order_execution（发货、收款金额取自发货单金额）、reports/customer_credit（发货单本币价税合计）和存货档案 archives/get 的参考成本 iInvNCost 也不遮蔽：U8 在这些界面上没有字段权限对象。
• 功能 id 按 U8 的授权表（UA_HoldAuth）、授权目录（UA_Auth 名称与 UA_Menu 菜单）和表单按钮表（UFMeta AA_FormButtonAuths、UAP 报表视图）核对，全部 id 尚未在 U8 客户端逐个授权点验。其中：应收单 / 应付单、货位（AS030Q / AS030）、本单位开户银行（AS013Q / AS013）、收发类别（AS016Q / AS016）、行业分类（AS050Q / AS050）、核销与自动核销（AR050201 / AR050202）、取消核销和取消处理（「取消操作」AR0807）、核销记录（AR060107）、客户联系人（CS0202 一组）、月末结账状态（GL1512）、往来账龄分析（AR060301 / AP060301 及 UAP 报表视图的查询 id）；票据处理按操作细分到 U8「票据处理」AR2402 下的结算、贴现、背书、退票子项（另收「票据录入」AR0504；退回另收「票据转出」AR240202，应付退回认「票据转出」AP240202 或 AP0504）。货位、收发类别的写入也由桥先检查功能权限。
• 银行档案（aa_bank）在授权表中没有对应的 id，读取只认账套主管；非主管做银行账户写入时查不到所属银行编码。
• 可空列（如采购类型、收发类别、到货单表体仓库）空值放行按桥的规则，未与 U8 客户端的保存口径逐项对照。
• 总账凭证的读取不做「查询他人凭证控制到操作员」（bFindVouchCtrl）。科目只在 bQryCtlSubj 打开时过滤：科目余额表、辅助余额表、明细账，以及总账凭证（读取、列表、摘要、附件按整张凭证，全部分录科目都有权限才可见）。桥取较严的口径，可能比 U8 客户端少给凭证。
• 固定资产报表（fa_changes、fa_depreciation）和固定资产卡片档案 fa_card 的部门过滤按卡片全部版本的全部使用部门（从严）。
• 项目档案的写入不经 U8 组件，桥只检查项目档案维护的功能权限（「项目目录」AS029 / 「项目编辑」AS029M），不检查项目的记录级数据权限。
• 数据权限的类别级授权（AA_AuthClass）、主管展开和制单人（user）对象不参与读取过滤。U8 的「用户」记录权限对象即使打开且没有任何授权行，实际也不限制查看他人制单的单据（已在测试账套观察）；桥与 U8 的实际表现一致，不按制单人过滤读取（U8 行为说明）。

8. 测试#

• 写操作的验证需要一个专用的测试账套，并能在验证后用备份恢复账套数据；UFSystem 中的登录记录、主键计数等不随账套库恢复（测试「在你自己的 U8 测试账套上验证」）。
• 验证的覆盖面取决于测试账套中的数据：账套里没有某类单据或处于某种状态的单据时，相应操作无法验证，需要先在 U8 客户端准备数据。