HQD-21: resolved conflicts

Author: VadymHrechukha

.github/workflows/behat-tests.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        php: ['8.3']
+        php: ['8.4']
         coverage-driver: [pcov]
     name: PHP ${{ matrix.php }}
     steps:

.github/workflows/phpunit-tests.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        php: ['8.3']
+        php: ['8.4']
         coverage-driver: [pcov]
     name: PHP ${{ matrix.php }}
     steps:

.github/workflows/psalm-analysis.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        php: [ '8.3' ]
+        php: [ '8.4' ]
         coverage-driver: [ pcov ]
     name: PHP ${{ matrix.php }}
     steps:
@@ -41,4 +41,4 @@ jobs:
         run: composer install -n
 
       - name: Run Psalm
-        run: vendor/bin/psalm
+        run: vendor/bin/psalm

.markdownlint.yaml

@@ -0,0 +1,11 @@
+MD013:
+  line_length: 100
+  heading_line_length: 100
+  code_blocks: false
+  tables: false
+MD022: false
+MD029: false
+MD030: false
+MD031: false
+MD032: false
+MD040: false

CLAUDE.md

@@ -0,0 +1,19 @@
+# Agent Instructions — php-billing
+
+Pure billing domain library. No framework dependency — no Yii2, no config-plugin.
+
+@docs/overview.md
+@docs/domain-model.md
+@docs/price-types.md
+
+## Key domain concepts
+
+Customer → Plan → Price → Action → Charge → Bill.
+Sale represents a subscription binding a Customer to a Target under a Plan.
+
+## Rules
+
+No framework imports allowed — this is a pure domain library.
+Price types (RatePrice, SinglePrice, EnumPrice, ProgressivePrice) implement pricing strategies.
+Formula classes define calculation rules applied to prices.
+Money is a value object — never use floats for monetary values.

README.md

@@ -1,68 +1,32 @@
-# PHP Billing
-
-**PHP Billing Library**
+# PHP Billing Library
 
 [![Latest Stable Version](https://poser.pugx.org/hiqdev/php-billing/v/stable)](https://packagist.org/packages/hiqdev/php-billing)
 [![Total Downloads](https://poser.pugx.org/hiqdev/php-billing/downloads)](https://packagist.org/packages/hiqdev/php-billing)
 ![phpunit-tests](https://github.com/hiqdev/php-billing/actions/workflows/phpunit-tests.yml/badge.svg)
 ![behat-tests](https://github.com/hiqdev/php-billing/actions/workflows/behat-tests.yml/badge.svg)
-[![Build Status](https://img.shields.io/travis/hiqdev/php-billing.svg)](https://travis-ci.org/hiqdev/php-billing)
-[![Scrutinizer Code Coverage](https://img.shields.io/scrutinizer/coverage/g/hiqdev/php-billing.svg)](https://scrutinizer-ci.com/g/hiqdev/php-billing/)
-[![Scrutinizer Code Quality](https://img.shields.io/scrutinizer/g/hiqdev/php-billing.svg)](https://scrutinizer-ci.com/g/hiqdev/php-billing/)
-
-Billing library providing:
-
-- customers with subscriptions
-- orders with actions
-- tariff plans with prices
-- smart discounts with formulas
-- bills with charges
-- calculator and aggregator
-
-- one-time, metered and recurring charging
-
-Please see [additional documentation in russian](docs/ru.md).
-
-## Installation
-
-The preferred way to install this library is through [composer](http://getcomposer.org/download/).
 
-Either run
+A pure domain library for billing and invoicing. It models the full billing pipeline:
+[Customer]s subscribe to [Target]s under [Plan]s (via [Sale]s), metered activities
+are recorded as [Action]s, the [Calculator] matches Actions to [Price]s within Plans
+to produce [Charge]s, and the [Aggregator] groups Charges into [Bill]s.
 
-```sh
-php composer.phar require "hiqdev/php-billing"
-```
+The library supports one-time, metered, and recurring charging with multiple pricing
+strategies (fixed per-unit, percentage-based, tiered/progressive, discrete lookup),
+a formula DSL for smart discounts and installments, and a reseller hierarchy.
 
-or add
+No framework dependency — this is a standalone domain model.
 
-```json
-"hiqdev/php-billing": "*"
-```
+## Core Entities
 
-to the require section of your composer.json.
-
-## Idea
-
-In general the billing functions like this:
-
-For a given [order] a [calculator] finds [plan]s and then matches
-applicable [price]s to [action]s and calculates [charge]s.
-Then [charge]s can be aggregated to [bill]s with [aggregator].
-
-Billing operates such ideas:
-
-- [Action] - [customer]'s metered activity of a certain [type] at a certain [target]
-- [Order] - collection of [action]s
-- [Bill]
-- [Charge]
-- [Plan]
-- [Price]
-- [Customer]
-- [Sale] - a subscription, binding [customer] to a [target] and a [plan]
-- [Target] - object being charged in billing
-- [Type]
-- [Calculator]
-- [Aggregator]
+- **[Action]** — a [Customer]'s metered activity of a certain [Type] at a certain [Target]
+- **[Order]** — a collection of Actions to be billed together
+- **[Sale]** — a subscription binding a [Customer] to a [Target] under a [Plan]
+- **[Plan]** — a tariff containing a set of [Price]s
+- **[Price]** — a billing rule that calculates charges (SinglePrice, EnumPrice, RatePrice, ProgressivePrice)
+- **[Charge]** — the result of matching an Action to a Price
+- **[Bill]** — aggregation of Charges into an invoice line item
+- **[Calculator]** — orchestrates the billing pipeline
+- **[Aggregator]** — groups Charges into Bills
 
 ![Model UML](http://www.plantuml.com/plantuml/proxy?cache=no&src=https://raw.githubusercontent.com/hiqdev/php-billing/master/docs/model.puml)
 
@@ -75,12 +39,17 @@ Billing operates such ideas:
 [Order]:        /src/order/Order.php
 [Plan]:         /src/plan/Plan.php
 [Price]:        /src/price/AbstractPrice.php
-[SinglePrice]:  /src/price/SinglePrice.php
-[EnumPrice]:    /src/price/EnumPrice.php
 [Sale]:         /src/sale/Sale.php
 [Target]:       /src/target/Target.php
 [Type]:         /src/type/Type.php
 
+## Documentation
+
+- [Domain Model](docs/domain-model.md) — core entities, matching rules, immutability, calculator pipeline
+- [Price Types](docs/price-types.md) — SinglePrice, EnumPrice, RatePrice, ProgressivePrice algorithms
+- [Formula DSL and Charge Modifiers](docs/formula-and-modifiers.md) — discount, installment, cap, and modifier system
+- [Codebase Overview](docs/overview.md) — directory map, patterns, and testing
+
 ## Disclaimer
 
 This billing is designed to be flexible and abstract, so supports different use cases.
@@ -112,4 +81,4 @@ because many of them implement customer-specific logic that cannot be disclosed.
 This project is released under the terms of the BSD-3-Clause [license](LICENSE).
 Read more [here](http://choosealicense.com/licenses/bsd-3-clause).
 
-Copyright © 2017-2019, HiQDev (http://hiqdev.com/)
+Copyright © 2017-2026, HiQDev (<http://hiqdev.com/>)

behat.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+use Behat\Config\Config;
+use Behat\Config\Profile;
+use Behat\Config\Suite;
+
+return (new Config())
+    ->withProfile(
+        (new Profile('default'))
+            ->withSuite(
+                (new Suite('php-billing'))
+                    ->withPaths('%paths.base%/tests/behat')
+                    ->withContexts('hiqdev\php\billing\tests\behat\bootstrap\FeatureContext')
+            )
+    );

composer.json

@@ -46,8 +46,7 @@
         "php": "^8.3",
         "moneyphp/money": "^3.0 | ^4.0",
         "hiqdev/php-units": "dev-master",
-        "psr/simple-cache": "^1.0",
-        "cache/array-adapter": "^1.2"
+        "psr/simple-cache": "^2.0 | ^3.0"
     },
     "require-dev": {
         "php": "^8.3",
@@ -65,7 +64,8 @@
         "opis/closure": "3.x-dev as 3.6.x-dev",
         "cache/array-adapter": "*",
         "matthiasnoback/behat-expect-exception": "^v0.3.0",
-        "behat/gherkin": "~v4.11.0"
+        "behat/gherkin": "~v4.11.0",
+        "rector/rector": "dev-main"
     },
     "suggest": {
         "ext-intl": "intl extension is required for formula support",

docs/domain-model.md

@@ -0,0 +1,91 @@
+# Billing Domain Model
+
+## Entity Pipeline
+
+```
+Customer → Plan → Price → Sale
+                            ↓
+                         Action → Calculator → Charge → Aggregator → Bill
+```
+
+## Core Entities
+
+**Customer** — the billable party. Has a seller (reseller hierarchy).
+
+**Plan** — a tariff/pricing plan. Contains a collection of Prices.
+Prices are immutable after assignment (`CannotReassignException`).
+
+**Price** — a billing rule. Applied when `isApplicable(action)` returns true.
+Matching logic: `action.target.matches(price.target) AND action.type.matches(price.type)`.
+
+**Sale** — a subscription binding Customer → Target → Plan. Has optional `closeTime`.
+Can have null Plan (for one-time sales). Represents "customer X uses resource Y under plan Z".
+
+**Action** — a metered activity. The only thing that gets charged.
+Has: type, target, quantity, customer, time, optional sale, optional parent, fractionOfMonth.
+
+**Charge** — result of matching an Action to a Price. Holds: used quantity (usage),
+calculated money (sum), reference to the Price that created it, optional parent charge.
+
+**Bill** — aggregation of Charges. Represents an invoice line item. Immutable once created.
+
+## Matching Constants
+
+- `Target::ANY` (null) — matches any target
+- `Target::NONE` (INF) — matches no target
+- `Type::ANY` (null) — matches any type
+- `Type::NONE` (INF) — matches no type
+
+## Immutability Rules
+
+Once set, these fields cannot be reassigned (throws `CannotReassignException`):
+
+- Plan → prices
+- Price → plan
+- Action → sale
+- Sale → id
+- Charge → id, parent
+
+**Rationale:** billing history integrity. To update a tariff, create a new Plan with new ID.
+
+## Execution Flow
+
+### Calculator Pipeline
+
+1. `findSales(order)` — matches Actions to Sales (direct or via repository)
+2. `findPlans(order)` — resolves Plans from Sales (loads from repository if needed)
+3. `calculatePlan(plan, action)` — iterates all Prices in the Plan
+4. `calculatePrice(price, action)` — calls `calculateCharge()`, then applies `ChargeModifier` if price has one
+5. `calculateCharge(price, action)` — core calculation:
+   - Checks `action.isApplicable(price)` (target + type matching)
+   - Checks sale time is not in the future
+   - Calculates usage via `price.calculateUsage(quantity)`
+   - Calculates sum via `price.calculateSum(quantity)`
+   - Specializes type/target via Generalizer
+   - Returns a Charge
+
+### Generalizer
+
+**Generalizer** (`src/charge/Generalizer.php`) maps Charges to Bills. It is the customization point
+for downstream projects that need different aggregation behavior.
+
+Key responsibilities:
+- `createBill(charge)` — converts a Charge into a Bill (negates sum for accounting)
+- `specializeType(priceType, actionType)` — resolves which Type to use on the Charge (base: returns price type)
+- `specializeTarget(priceTarget, actionTarget)` — resolves which Target to use (base: returns price target)
+
+### Aggregator
+
+**Aggregator** groups Charges into Bills using `Bill.getUniqueString()` as the aggregation key.
+
+Bill unique key composition:
+```
+currency + customer.uniqueId + target.uniqueId + type.uniqueId + time (ISO 8601)
+```
+
+Bills with the same key are merged: sums are added, quantities are added (if same unit), charge arrays are concatenated.
+
+## Money and Units
+
+Money is a value object — never use floats for monetary values.
+Uses `hiqdev\php\units` for quantity handling.