Initial commit, v0.1.0-b

2020-01-11 14:30:25 +08:00
commit 1db2d5b49f
67 changed files with 7680 additions and 0 deletions
--- a/docs/documents.md
+++ b/docs/documents.md
@@ -0,0 +1,159 @@
+# Работа с документами
+
+Объект документа инициализируется следующим образом:
+
+```php
+$doc = new AtolOnline\Entities\Document();
+```
+
+Для документов **прихода, возврата прихода, расхода и возврата расхода** должны быть указаны все следующие обязательные атрибуты:
+* [клиент](/docs/client.md);
+* [компания](/docs/company.md);
+* [предметы расчёта](/docs/items.md);
+* [оплаты](/docs/payments.md).
+
+Для документов **коррекции прихода и коррекции расхода** должны быть указаны все следующие обязательные атрибуты:
+* [компания](/docs/company.md);
+* [оплаты](/docs/payments.md);
+* [ставки НДС](/docs/vats.md);
+* [данные коррекции](/docs/correction_info.md).
+
+Для любых документов также могут быть указаны следующие необязательные атрибуты:
+* ФИО кассира (тег ФФД - 1021).
+
+Установка атрибутов документа происходит через сеттеры.
+
+## Работа с клиентом
+
+Для этого существуют следующие методы:
+
+```php
+$doc->setClient($client);
+$doc->getClient();
+```
+
+> О работе с клиентами более подробно читайте [здесь](/docs/client.md).
+
+## Работа с компанией
+
+Для этого существуют следующие методы:
+
+```php
+$doc->setCompany($company);
+$doc->getCompany();
+```
+
+> О работе с компаниями более подробно читайте [здесь](/docs/company.md).
+
+## Работа с предметами расчёта
+
+Внутри документа существует [массив предметов расчёта](/docs/items.md#array).
+По умолчанию он пуст.
+Напрямую для манипуляций объект массива недоступен.
+Работа с ним происходит через методы документа:
+
+```php
+$doc->setItems([$item1, $item2]);
+$doc->addItem($item3);
+$doc->getItems();
+```
+
+Соответственно, эти методы выбрасывают те же исключения, что методы самого массива.
+
+## Работа с оплатами
+
+Внутри документа существует [массив оплат](/docs/payments.md#array).
+По умолчанию он пуст.
+Напрямую для манипуляций объект массива недоступен.
+Работа с ним происходит через методы документа:
+
+```php
+$doc->setPayments([$payment1, $payment2]);
+$doc->addPayment($payment3);
+$doc->getPayments();
+```
+
+Соответственно, эти методы выбрасывают те же исключения, что методы самого массива.
+
+Следует отметить, что если при выполнении метода `addPayment()` выполняются следующие условия:
+* аргументом передан объект оплаты, у которого не задана сумма, 
+* ранее документу не задавались оплаты,
+то автоматически этому объекту оплаты задаётся полная сумма чека.
+
+## Работа со ставками НДС
+
+Внутри документа существует [массив ставок НДС](/docs/vats.md#array).
+По умолчанию он пуст.
+Напрямую для манипуляций объект массива недоступен.
+Работа с ним происходит через методы документа:
+
+```php
+$doc->setVats([$vat1, $vat2]);
+$doc->addVat($vat3);
+$doc->getVats();
+```
+
+Соответственно, эти методы выбрасывают те же исключения, что методы самого массива.
+
+Также существует метод `clearVats()`, который удаляет все вложенные объекты ставок НДС - из предметов расчёта и самого документа.
+
+Следует отметить, что если при выполнении метода `addVat()` выполняются следующие условия:
+* аргументом передан объект ставки, у которого не задана сумма, 
+* ранее документу не задавались ставки,
+то автоматически этому объекту налога задаётся полная сумма чека, от которой расчитывается итоговый размер налога.
+
+## Общая сумма документа
+
+Расчёт происходит автоматически в следующих случаях:
+* изменение предметов расчёта (`setItems()`, `addItem()`);
+* добавление оплат (`addPayment()` в случае, когда оплата передана без суммы);
+* изменение ставок НДС (`setVats()`, `clearVats()`, `addVat()` в случае, когда ставка передана без суммы);
+* приведение объекта документа к строке.
+
+Также можно вызвать вручную метод `calcTotal()`.
+Он расчитывает полную сумму чека по предметам расчёта и пересчитывает **все** налоговые ставки.
+
+Получить итог можно с помощью метода `getTotal()`.
+
+Всё в рублях.
+
+<a name='correction'></a>
+## Работа с данными коррекции
+
+Если документ создаётся с целью коррекции прихода или расхода, то он обязательно должен содержать [данные коррекции](/docs/correction_info.md).
+
+Задать и получить эти данные очень просто:
+
+```php
+$doc->setCorrectionInfo(new AtolOnline\Entities\CorrectionInfo(
+    AtolOnline\Constants\CorrectionTypes::SELF, // тип коррекции
+    '01.01.2019', // дата документа коррекции
+    '12345', // номер документа коррекции
+    'test' // описание коррекции
+));
+$doc->getCorrectionInfo();
+```
+
+## Работа с кассиром
+
+Для этого существуют следующие методы:
+
+```php
+$doc->setCashier('Иванова Лариса Васильевна');
+$doc->getCashier();
+```
+
+## Прочее
+
+Объект класса приводится к JSON-строке автоматически или принудительным приведением к `string`:
+
+```php
+echo $doc;
+$json_string = (string)$doc;
+```
+
+Чтобы получить те же данные в виде массива, нужно вызвать метод `jsonSerialize()`:
+
+```php
+$json_array = $doc->jsonSerialize();
+```