jigx-acumatica

Jigx Acumatica

将此技能与通用 jigx 技能配合使用。阅读通用 Jigx 参考资料，了解屏幕、表单、数据源、选项卡、媒体和 PDF 模式。此技能仅用于 Acumatica 专属的集成规则。

工作流

1. 阅读 references/recipe-index.md。
2. 对于新的集成，先阅读 references/acumatica-discovery.md：根据实例构建版本查找客户的版本，按任务选择通道，并确保每个会话都以注销结束。SOAP/UI 探测仅用于 Agent 端发现和 Acumatica 配置；Jigx 移动端无法执行 SOAP 调用，必须通过通用查询/OData、合同 REST 或明确提供的服务端桥接，使用已发现的屏幕信息。
3. 在屏幕上设计任何内容之前，阅读 references/acumatica-screen-logic.md 并使用 jigx-acumatica-kb。存在连接时，应与实时实例核对；客户添加的字段和未解析的字段仅视为架构信息。
4. 确认任务属于入站查找同步、本地优先出站同步、直接提交、文件上传，还是重试/错误处理。对于任何离线/批量创建或更新，在设计表或操作之前阅读 references/acumatica-sync.md。
5. 确认使用 REST 还是 OData。尽可能优先使用 REST。
6. 在实现需要嵌套数据的查找之前，确认必需的 $expand 值。
7. 保持 Acumatica 配置的大小写完全一致：acumaticaURL 和 acumaticaOdataURL。
8. 使用类型/值为 acuerp 的 accessToken；不要硬编码访问令牌。
9. 除非应用明确使用直接提交，否则保留本地优先行为。
10. 对于每个选择器和每次写入，都要阅读 references/acumatica-selectors-and-cascades.md 和 references/integration-verification.md。在实例上解析仅限运行时的选择器，通过可写端点往返验证查找值，并在认定写入完成前运行强化测试。
11. 按照 references/acumatica-reads-and-sync-contract.md 声明每个列表读取：基于查询、按修改字段进行增量读取、连接行的行标识，以及任何需要地址或父项的读取都必须设置必需参数。

参考资料索引

• references/recipe-index.md - 何时阅读每项 Acumatica 参考资料。

• references/acumatica-discovery.md - 探测实例、Jigx 移动端的 SOAP/UI 探测边界、按任务选择三个通道、根据构建版本确定版本、会话和许可证规范，以及读取 Acumatica 错误。

• references/acumatica-screen-logic.md - 屏幕知识库包含的内容、版本规则、与实时实例核对、来源信息及其无法确定的内容。

• references/acumatica-selectors-and-cascades.md - 存储列约定、所有者选择器和 ContactID、查找级联、诊断被拒绝的值、往返验证、强化测试、值语义、工作流操作。

• references/acumatica-reads-and-sync-contract.md - 列表查询、创建查询、增量同步、按地址和由父项驱动的读取、行标识、行数上限。

• references/acumatica-endpoints-and-files.md - 作为后备方案的合同 REST、明细集合、创建缺失的端点、将文件附加到记录。

• references/acumatica-rest.md - REST 函数、参数、负载、错误。

• references/acumatica-sync.md - 本地优先同步、Remote 状态、命令队列、父子搜索/替换、重试。

• references/acumatica-lookups-expands.md - 查找同步、OData/REST 差异、$expand、强制同步、下拉字段。

• references/acumatica-files-submit.md - 文件上传、PDF 附件、服务订单提交模式。

• references/integration-verification.md - 通过生成的请求测试应用填充的数据、经授权的实时写入及远程回读。

防护措施

• 绝不猜测或默认 Acumatica 版本。应从构建信息中确定版本，或向用户询问；对于知识库未覆盖的版本，应根据实时架构设计，而不是参考相邻版本。
• 绝不生成会执行 SOAP、WSDL 调用或 Acumatica SOAP 会话的 Jigx 移动端代码。使用 SOAP/UI 探测来了解和配置 Acumatica，然后通过 Generic Inquiries/OData、contract REST、文件/操作，或明确可用的服务端桥接来实现移动端集成。
• 绝不通过屏幕 API 或 contract REST 同步大型列表。列表应通过 Generic Inquiry 获取。
• 绝不让 Acumatica 会话保持打开状态。登录、操作、注销，失败时也不例外。
• 绝不臆造下拉列表的行、枚举值或级联关系。应复现行来源，从实例中获取枚举值，并通过读取验证级联关系。
• 绝不发布未经可写端点往返验证的查找项。
• 绝不使用表的全局同步为按用户区分的字段提供数据。
• 绝不将工作流状态作为字段写入；应通过屏幕操作变更状态。
• 绝不在检查存储列和数据填充情况之前，就将被拒绝的选择器值视为错误数据。
• 绝不在未指明环境且未获得明确同意的情况下发布自定义包；应先验证，并在生产环境部署前进行测试。
• 绝不对 Acumatica 访问令牌进行硬编码。
• 绝不更改 acumaticaURL 或 acumaticaOdataURL 的大小写。
• 绝不在未使用 $expand 的情况下假定存在嵌套字段。
• 绝不向 Acumatica 发送 Jigx 内部字段。
• 绝不在屏幕保存操作中构建排队的 Acumatica 载荷；应传递标识符，并在队列排空时根据本地表构建请求体。
• 对于本地优先的创建/更新操作，绝不为同一实体创建单独的队列表，除非业务流程明确需要不同的表。默认使用实体的本地表，并设置 Remote: "new" | "dirty" | "remote"。
• 绝不丢失失败的命令。应使用命令队列重试，或显式记录错误。
• 如果队列中仍包含临时 ID，绝不在子记录中覆盖本地 ID，除非同时替换排队的引用。