README

IOI City Mall 销售文件生成器是一个 Laravel 包，用于简化为 IOI City Mall 店铺创建每日销售数据文件。它可以无缝集成到 Laravel 项目中，简化零售管理的数据生成。

安装

通过 composer 安装包

composer require retail-cosmos/ioi-city-mall-sales-file

使用以下命令发布配置文件

php artisan vendor:publish --tag="ioi-city-mall-sales-file-config"

请设置配置文件中所有选项的值。

用法

功能分为两部分。第一部分是文件生成，第二部分是文件上传（SFTP）。

文件生成

请按照以下步骤进行文件生成。

在您的 Laravel 项目中添加一个计划任务，每天午夜调用 generate:ioi-city-mall-sales-files 命令。它为每个店铺生成前一天的销售文件，如应用程序返回的那样。

$schedule->command('generate:ioi-city-mall-sales-files')->daily();

提示

如果您想生成特定的销售文件，可以在命令中传递以下选项

date - 要生成特定日期销售文件的 YYYY-MM-DD 格式的日期。
store_identifier - 仅生成特定店铺的销售文件。

在 App/Services 命名空间中创建一个名为 IOICityMallSalesDataService 的新类，并添加一个 storesList() 方法。它应该返回店铺的集合。键需要是
- store_identifier (String)
- machine_id (String. 来自 IOI City Mall 的机器 ID)
- sst_registered (Boolean)

当您将 store_identifier 作为选项传递给销售文件生成命令时，包将其作为参数传递给 storesList() 方法。

点击这里查看 storesList() 方法的示例代码

public function storesList(string $storeIdentifier = null): Collection
{
    return collect([
        [
            'store_identifier' => 'my_store_46592',
            'machine_id' => 48623791,
            'sst_registered' => false,
        ],
        [
            'store_identifier' => 'my_store_97314',
            'machine_id' => 37196428,
            'sst_registered' => true,
        ],
    ]);
}

提示

如果您返回一个空的集合，则命令不会生成任何销售文件，只会记录一条消息。

在 IOICityMallSalesDataService 类中添加一个 salesData() 方法。包将调用此方法来获取销售数据。该方法接收以下参数
- store_identifier (string) - 来自 storesList() 方法或作为选项传递给销售文件生成命令。
- date (string) - YYYY-MM-DD 格式

这是实现的主要部分。您需要添加代码以便此方法能够获取指定日期指定店铺的销售数据并返回销售数据的集合。键需要是

    - 'happened_at' (Date and time of the sale)
    - 'net_amount' (Total amount of the sale after discount and before SST)
    - 'discount' (Total discount amount of the sale. Item-wise division is not needed)
    - 'SST'
    - 'payments': (Amount of the payment type after discount and before SST)
        - 'cash'
        - 'tng'
        - 'visa'
        - 'mastercard'
        - 'amex'
        - 'voucher'
        - 'others'

重要

您可以使用 RetailCosmos\IoiCityMallSalesFile\Enums\PaymentType 枚举作为付款键。

点击这里查看 salesData() 方法的示例代码

public function salesData(string $storeIdentifier, string $date): Collection
{
    return collect([
        [
            'happened_at' => '2024-01-20 15:41:37',
            'net_amount' => 100,
            'discount' => 20,
            'SST' => 6,
            'payments' => [
                PaymentType::CASH->value => 50,
                PaymentType::TNG->value => 0,
                PaymentType::VISA->value => 30,
                PaymentType::MASTERCARD->value => 0,
                PaymentType::AMEX->value => 0,
                PaymentType::VOUCHER->value => 0,
                PaymentType::OTHERS->value => 20,
            ],
        ],
        [
            'happened_at' => '2024-01-20 16:18:09',
            'net_amount' => -50,
            'discount' => -5,
            'SST' => 0,
            'payments' => [
                PaymentType::CASH->value => -50,
                PaymentType::TNG->value => 0,
                PaymentType::VISA->value => 0,
                PaymentType::MASTERCARD->value => 0,
                PaymentType::AMEX->value => 0,
                PaymentType::VOUCHER->value => 0,
                PaymentType::OTHERS->value => 0,
            ],
        ],
    ]);
}

提示

请注意，您需要返回商店所有收银机/登记处的销售数据。商场期望将所有收银机的销售数据合并到文件中。

🚀 就是这样。计划任务每天都会调用该命令，包生成销售文件并将其按配置放入文件系统。接下来，您可以按照文件上传部分的步骤进行操作。

禁用文件生成

本软件包提供了一个 .env 变量 IOI_CITY_MALL_ENABLE_FILE_GENERATION，如果您希望禁用文件生成功能。如果此 .env 变量设置为 false，即使运行命令，文件也不会生成。

关于生成的销售文件说明

生成的文件按照您的配置存储到磁盘上。其中包含两个目录：pending_to_upload 和 uploaded（如果这两个目录不存在，则会自动生成）
生成的文件完整日志根据您的日志通道配置进行准备和存储。如果设置了通知配置，会发送电子邮件通知。您也可以选择只接收失败通知。

关于销售退货说明

在退款的情况下，您可以提供所有负数。根据规格说明，退款金额应从销售金额中扣除，因此它将在软件包按记录分组时自动处理。

关于批次 ID 说明

批次 ID 由软件包管理。根据商场规格，它需要从 1 开始的连续数字，用于第一个生成的文件。您可以在配置中设置 first_file_generation_date。软件包从该日期开始计算每次的批次 ID。如果配置中没有设置日期，将抛出异常。

文件上传（SFTP）

启动文件上传只有一个步骤。

在您的 Laravel 项目中添加一个定时器，每天凌晨 12:30 调用命令 upload:ioi-city-mall-sales-files。它将按照您的配置通过 SFTP 上传 pending_to_upload 目录中的所有文件，并将这些文件移动到 uploaded 目录。

$schedule->command('upload:ioi-city-mall-sales-files')->dailyAt('00:30');

上传文件的完整日志根据您的日志通道配置进行准备和存储。如果设置了通知配置，会发送电子邮件通知。您也可以选择只接收失败通知。

禁用文件上传（SFTP）

本软件包提供了一个 .env 变量 IOI_CITY_MALL_ENABLE_FILE_UPLOAD，如果您希望禁用文件上传功能。如果此 .env 变量设置为 false，即使运行命令，文件也不会上传。

更新日志

请参阅更新日志了解最近的变化。

贡献

请参阅贡献指南了解详情。

安全漏洞

请参阅我们的安全策略了解如何报告安全漏洞。

鸣谢

许可协议

MIT 许可协议（MIT）。请参阅许可文件了解更多信息。

retail-cosmos / ioi-city-mall-sales-file

维护者

详细信息