README

本Laravel包旨在创建、存储和处理由俄罗斯联邦税务服务通过税务数据运营商（FDO，俄语 ОФД）接受的54FZ兼容收据。目前，它支持大多数税务数据格式（FDF，俄语 ФФД）1.05标签和通过补充驱动程序的ATOL Online服务API v4。

2. 要求

PHP 8.1或更高版本；
Laravel框架10或更高版本；
强烈推荐：支持JSON列的RDBMS；
ATOL Online & FDO合同和连接要求（测试目的不需要）。

3. 安装

安装过程简单直接，几乎与任何Laravel包一样。

您可以通过Composer安装Fiscal Registrar包：composer require ttbooking/fiscal-registrar

如果为您的项目配置了包发现，包的服务提供者和外观别名将自动在您的应用程序中注册。

接下来，您需要发布包配置文件（必需）和数据库迁移（可选，如果您需要更改表名或添加列等）。

# Publish configuration
php artisan vendor:publish --provider=TTBooking\FiscalRegistrar\FiscalRegistrarServiceProvider --tag=config

# Publish migration
php artisan vendor:publish --provider=TTBooking\FiscalRegistrar\FiscalRegistrarServiceProvider --tag=migrations

# Publish everything package-related
php artisan vendor:publish --provider=TTBooking\FiscalRegistrar\FiscalRegistrarServiceProvider

然后，如果您已发布迁移，您需要在其上进行必要的更改，然后再进行下一步。在默认的Laravel安装中，在这里查找：{/database/migrations/blahblah_receipts.php}。

最后，您应该应用数据库迁移，这将创建用于存储收据的表：php artisan migrate

4. 配置

4.1. 使用可定制的收据模型

首先，如果您在包安装过程中更改了数据库迁移（尤其是表名），这一步是强制性的。否则，它完全可选。在应用程序的模型命名空间（或其它地方）中创建Eloquent模型，例如（App\Models\Receipt），并从包补充的默认实现（TTBooking\FiscalRegistrar\Models\Receipt）扩展它。最终结果将如下所示

<?php

namespace App\Models;

use TTBooking\FiscalRegistrar\Models\Receipt as BaseReceipt;

class Receipt extends BaseReceipt
{
    protected $table = 'custom_receipts';
}

注意$table属性 - 它应指向实际的收据表。当然，您可以按需自定义此模型，只需不要破坏已经正常工作的部分即可 :)

4.2. 配置选项

您可以在安装步骤发布的Fiscal Registrar配置文件（位于这里：{/config/fiscal-registrar.php}）中找到配置选项。

主要选项包括

path - 路由（API & UI）将挂载（分组）的路径。
middleware - 添加到包路由的中件。
model - 在此处注册您的自定义收据模型，它将全局（包范围内）替换默认模型。
connection - 默认连接实例及其驱动程序和配置选项。（最好使用环境变量，见下文）
connections - 每个连接的配置，将传递给驱动程序实例。
connections.<name>.driver - 用于连接的驱动程序；如果省略，将尝试通过连接的名称解析驱动程序。
connections.<name>.callback - 如果提供商和驱动程序支持，回调URL。默认情况下，回调URL是自动生成的，不需要显式定义。为了禁用此行为，您可以手动定义回调URL或完全禁用回调，通过将false（在）分配给选项。
connections.<name>.* - 其他与驱动程序特定的选项。

此外，还有一个名为FR_CONNECTION的环境变量，您可以在项目的.env文件中使用它来选择默认连接。

5. 通用用法

在客户端代码中，最直接的使用方式是通过使用TTBooking\FiscalRegistrar\Contracts\FiscalRegistrar接口进行依赖注入。此接口有两个方法

public function register(Operation $operation, string $externalId, Receipt $data): string

使用Receipt DTO ($data参数) 通过$operation注册方法注册收据。您还必须使用$externalId参数提供您系统中收据的唯一标识符。在最简单的情况下，您可以使用Str::uuid()辅助函数生成此标识符。此方法的返回值将是提供方的唯一收据标识符。

Receipt DTO主要类似于ATOL Online文档中描述的类似结构。

public function report(string $id): ?Result

使用由register方法返回的标识符检查当前收据的状态。

6. 非存储特定性的FiscalRegistrar外观

7. 具有流畅接口的收据外观

8. receipt()辅助函数

9. 网络API对应项

此包也可以通过其RESTful API作为一个微服务运行。

ttbooking / fiscal-registrar

维护者

详细信息