README

为Magento 1/2集成的在线现金注册机模块

此模块旨在完全支持54法对于在Magento 1和2上运行的在线商店服务的要求

АТОЛ онлайн。该模块支持阿托尔服务版本v4（FFD 1.05）。
Чеконлайн。

模块功能

向在线现金注册机传输数据

发送关于账单/退款的详细信息
- 在创建账单时自动发送（可在配置中设置）
- 在创建退款时自动发送（可在配置中设置）
- 通过以下命令之一手动发送
- 从管理后台的账单或退款页面手动发送按钮

重复向在线现金注册机传输数据（Resell）

（不要与调整后的收据混淆）

取消之前收据的收据（根据发票）并发送新的收据。
- 在管理后台点击“Resell”按钮手动操作
- 通过以下命令之一
- 其他模块可以触发 \Mygento\Kkm\Api\Processor\SendInterface::proceedResellRefund

从阿托尔获取数据

从阿托尔获取关于账单/退款状态的数据
- 自动（可在配置中设置）。在处理完阿托尔的数据后，将结果发送回（回调）。默认URL: http://shop.ru/kkm/frontend/callback
- 通过计划任务检查状态
- 从管理后台的账单或退款页面手动发送按钮
- 通过以下命令之一

从Чеконлайн获取数据

Чеконлайн服务的工作基于同步原则，在服务中没有“文档状态”的概念。取而代之的是使用响应缓存。缓存键是Group、RequestId、ClientId字段，这意味着如果发送具有相同指定字段的请求，则服务将返回缓存中的数据。缓存成功响应和一些Kкм设备的错误（请参阅Чеконлайн文档）。

向在线现金注册机发送数据的流程

根据发票或退款实体，创建对象 Mygento\Kkm\Api\Data\RequestInterface。1.1. 在异步传输时 - 对象被放入队列（请参阅Magento队列框架）1.2. 在同步传输时 - 将对象传递给 Vendor 类进行发送
注册数据发送尝试。创建具有 NEW（1）状态的实体 Api\Data\TransactionInterface\TransactionAttemptInterface
以JSON格式发送数据。

3.1. 在成功发送的情况下（HTTP状态之一 [200, 400, 401]）
- 创建事务 - 实体 Magento\Sales\Api\Data\TransactionInterface，其中记录了请求的唯一标识符（UUID - Atol；RequestId - Чеконлайн）和所有传输数据。在管理后台这是“销售”->“事务”网格。
- 发送尝试实体 TransactionAttemptInterface 获得状态 Sent（2）
- 创建订单注释
- 事务获得KКМ状态（kkm_status）
  - 阿托尔 - wait
  - Чеконлайн - done
    
    3.2. 在失败发送的情况下（状态不同于 [200, 400, 401]（同样，Чеконлайн的500），没有从服务器收到响应，发票或退款中的数据不正确）
- 发送尝试实体 TransactionAttemptInterface 获得状态 Error（3）
- 创建订单注释，描述错误原因
- 订单获得“KKM失败”状态
- 如果抛出异常 VendorBadServerAnswerException（服务器无响应等一些情况）且启用了异步传输，则发送将再次放入队列。
- 如果抛出异常 VendorNonFatalErrorException 且启用了异步传输，则
  - 阿特洛 - 执行生成新的 external_id，并将发送再次放入队列。
  - CheckOnline - 事务实体获得状态 wait，并将发送再次放入队列而不会生成新的 external_id，因为非致命错误的响应不会缓存。同样，在 CheckOnline 云服务的工作中可能会出现返回 HTTP 状态码 500 和包含字段 FCEError、ErrorDescription、Device 和 Fatal 的结构。值为 true 的 Fatal 字段表示重复执行请求将导致错误。如果 Fatal 字段值为 false，则发送也将放入队列。
仅阿特洛。模块会自动向阿特洛查询所有具有 wait 状态的 POS 交易的状态。

4.1 当交易获得状态 done 时，停止尝试更新状态。

4.2 POS 模块的最大尝试次数设置。
在失败传输的情况下，会进行多次尝试发送，间隔时间逐渐增加（例如，1 分钟、5 分钟、15 分钟、30 分钟、1 小时）。

5.1 间隔设置可在 POS 模块的设置中找到。

5.2 发送尝试的最大次数也受 POS 模块设置的限制。

5.3 当达到发送尝试的最大次数时，尝试计数器将重置，并在一天后重新开始发送。

数据重新发送（Resell）过程

仅适用于已发送并具有状态 Done 的收据。

根据发票创建退货收据（refund）并将其发送到在线收银机。
为该发票创建新的付款交易记录，它是先前发送 sell 交易的后代。
当发送状态（第 1 点）变为 Done（对于 CheckOnline，如果成功，则发送状态立即变为 Done）时，将形成并发送新的收据收据（sell）。
为新收据创建新的付款交易记录，它是退货交易（第 2 点）的后代。
Resell 被视为完成，如果新的收据收据（第 3 点）获得状态 Done。更新状态的方式与其他所有情况相同（对于 CheckOnline，由于服务是按同步方式工作的，因此不会更新状态）。

报告

模块将发送数据报告发送到在线收银机，并通过电子邮件发送（在配置中）。失败的发送将显示在此电子邮件中，并提供额外的详细信息。此外，还可以在控制台中查看此报告。

每周（上周），每日（当天），每日（昨天）
邮件布局。文件 view/adminhtml/templates/email/kkm_report-mjml.mjml 包含邮件布局。使用 https://mjml.io/ 服务进行编辑

支持阿特洛在线服务的新版本

模块支持 v3 和 v4 版本的服务。如果推出新版本，则需要执行以下步骤

创建一个名为 RequestForVersionX 的类，它是抽象类 Request 的后代
发布其 JSON 表示形式 - 方法 jsonSerialize()
在 Mygento\Kkm\Model\Atol\RequestFactory 中添加创建请求对象的操作
在 Mygento\Kkm\Model\Source\ApiVersion 中添加关于新版本服务的详细信息

使用队列

向在线收银机发送消息可以在两种模式下进行
- 同步（在保存实体后或手动发送）；
- 异步（通过 Magento 的消息队列原生机制）。
工作模式在配置中设置

手动发送数据

在实体页面发送数据
使用控制台命令发送数据，指定实体的 IncrementId

消息记录

模块会记录（在 Stores -> Configuration -> Mygento Extensions -> Extensions and Support 中的 Debug 模式开启时）所有请求（和响应）。
请求日志在模块配置页面中可用

重写列表

无

事件和插件列表，动作和原因描述

事件

sales_order_invoice_save_commit_after:
- 在保存发票后发送数据。
sales_order_creditmemo_save_commit_after:
- 在保存后发送退货数据。

插件

在 ExtraSalesViewToolbarButtons 插件中，向后台管理页面的实体页面添加了“发送到在线收银机”和“检查状态”按钮，该方法为 Magento\Backend\Block\Widget\Button\Toolbar::pushButtons

可用API实现列表

无

内置测试列表，以及它们如何进行测试

无

Cron进程

kkm_statuses
- 仅适用于阿特洛。更新状态：作业更新状态为 wait 的交易状态。默认每分钟更新一次。
kkm_proceed_scheduled_attempt
- 按照预定时间（scheduled_at）执行发送请求的重复尝试。
kkm_report
- 报告：发送报告作业。频率在模块设置页面进行配置。默认每天00:07。

控制台命令

mygento:kkm:report - 显示报告。参数：today，yesterday，week
mygento:kkm:refund - 发送退货。参数：实体的IncrementId
mygento:kkm:sell - 发送账单。参数：实体的IncrementId
mygento:kkm:resell - 启动resell过程。根据当前账单发送退款。参数：实体的IncrementId。指定键 -f 将增加 external_id。
mygento:kkm:update-all - 仅适用于阿特洛。请求指定商店所有状态为 wait 的发送状态的数据。参数：StoreID
mygento:kkm:update-one - 仅适用于阿特洛。请求指定发送的状态数据。参数：UUID

mygento / module-kkm

维护者

详细信息