<?php
/* vim: set noexpandtab sw=8 ts=8 sts=8: */
/*
Copyright Jean-Marc MORIN (2015)

doekia@gmail.com

This software is a computer program whose purpose is to compute order
accurate amount based on unit prices, series of rules and taxes.

This software is governed by the CeCILL-C license under French law and
abiding by the rules of distribution of free software.  You can  use,
modify and/ or redistribute the software under the terms of the CeCILL-C
license as circulated by CEA, CNRS and INRIA at the following URL
"http://www.cecill.info".

As a counterpart to the access to the source code and  rights to copy,
modify and redistribute granted by the license, users are provided only
with a limited warranty  and the software's author,  the holder of the
economic rights,  and the successive licensors  have only  limited
liability.

In this respect, the user's attention is drawn to the risks associated
with loading,  using,  modifying and/or developing or reproducing the
software by the user in light of its specific status of free software,
that may mean  that it is complicated to manipulate,  and  that  also
therefore means  that it is reserved for developers  and  experienced
professionals having in-depth computer knowledge. Users are therefore
encouraged to load and test the software's suitability as regards their
requirements in conditions enabling the security of their systems and/or
data to be ensured and,  more generally, to use and operate it in the
same conditions as regards security.

The fact that you are presently reading this means that you have had
knowledge of the CeCILL-C license and that you accept its terms.
*/

namespace Calculus;

interface ITax
{
	/** @const TAX_CUSTOM for future use (or not) */
	const TAX_CUSTOM	= 1;
	/** @const TAX_VAT regular Goods and Services Tax AdValorem */
	const TAX_VAT		= 2;
	/** @const TAX_UNIT per unit of sales (probably matchable with other settings) */
	const TAX_UNIT		= 4;
	/** @const TAX_TAXEXC the tax computes on tax_excluded_price (e.g: US local/regional taxes or split tax) */
	const TAX_TAXEXC	= 8;
	/** @const TAX_WHOLESALE tax applies on wholesale */
	const TAX_WHOLESALE	= 16;
	/** @const TAX_GROSS Dunno if this will ever be used (probably on an entire order anyway) */
	const TAX_GROSS		= 32;

	/** @const TAX_TURNOVER Actually synonym of TAX_VAT|TAX_NODISCARD  */
	const TAX_TURNOVER	= 514;	//
	
	/** @const TAX_SPECIES Mask for tax species */
	const TAX_SPECIES	= 0x0FF;
	/** @const TAX_FLAGS Mask for tax flags */
	const TAX_FLAGS		= 0x0FF00;
	
	/** @const TAX_TRIGGER Tax kicks on certain level, $extra hold the trigger value (applied on whole price if trigger is negative, price above if trigger positive) e.g: Massachusset's clothing tax */
	const TAX_TRIGGER	= 256;	//
	/** @const TAX_NODISCARD No tax exclusion permitted (eg:ecotax), the tax is NEVER excluded */
	const TAX_NODISCARD	= 512;
	/** @const TAX_NOCHANGE The tax is computed / accumulated but does not change final price (eg:ecotax) */
	const TAX_NOCHANGE	= 1014;
	
	public function manifest();
	public function summary();
}

interface IDiscount
{
	public function manifest();
	public function summary();
}

interface IOrderLine
{
	/**
	 * attach a Discount to this Line
	 *
	 * @param string $name
	 * @param number $value - positive float express percent (0.1 = 10%), negative value express amount
	 * @param number $capped - the unit discounted amount that SHOULD NOT be exceeded
	 * @param number $divisor - negative divisor is discrete (discount from n), positive is quantum (discount per n)
	 * @param boolean $force - the amount superceed (replace) actual unit price (only one forced discount per line other are ignored)
	 *
	 * @return OrderLine instance (for fluent coding)
	 */
	public function addDiscount($name, $value, $capped = 0, $divisor = 0, $force = false);

	/**
	 * attach a Tax to this Section
	 *
	 * @param string $code - a tax code, passing similar code will return a uniq instance
	 * @param string $name - a long name
	 * @param number $rate - the rate, positive float express percent (0.1 = 10%), negative value express amount
	 * @param integer $mode - bitmask of ITax::TAX_* constant (e.g: ITax::TAX_VAT|ITax::TAX_NODISCARD)
	 * @param mixed $extra - extra hold amount threshold for ITax::TAX_TRIGGER, when ITax::TAX_CUSTOM implemented will hold the logic patern
	 * @param string $legal - some legal sentense associated with the tax
	 *
	 * @return OrderLine instance (for fluent coding)
	 */
	public function addTax($code, $name, $rate, $mode = ITax::TAX_VAT, $extra = null, $legal = null);
}

interface IOrderSection
{
	/**
	 * attach an OrderLine to the OrderSection
	 *
	 * @param string $uuid a unique line id - mainly for OrderSlip targetting
	 * @param string $ref a reference information (no processsing)
	 * @param string $desc a line description (no processing)
	 * @param number $pricenotax the initial unit price
	 * @param number $qty the quantity
	 * @param number $wholesaleprice[=0] the wholesaleprice (only required if any ITax::TAX_WHOLESALE)
	 *
	 * @return OrderLine instance
	 */
	public function addLine($uuid, $ref, $desc, $pricenotax, $qty = 1, $wholesaleprice = 0);
	
	/**
	 * attach a Discount to this Section
	 *
	 * @param string $name
	 * @param nimber $value - positive float express percent (0.1 = 10%), negative value express amount
	 * @param number $capped - the unit discounted amount that SHOULD NOT be exceeded
	 *
	 * @return OrderSection instance (for fluent coding)
	 */
	public function addDiscount($name, $value, $capped = 0);

	/**
	 * attach a Tax to this Section
	 *
	 * @param string $code - a tax code, passing similar code will return a uniq instance
	 * @param string $name - a long name
	 * @param number $rate - the rate, positive float express percent (0.1 = 10%), negative value express amount
	 * @param integer $mode - bitmask of ITax::TAX_* constant (e.g: ITax::TAX_VAT|ITax::TAX_NODISCARD
	 * @param mixed $extra - extra hold amount threshold for ITax::TAX_TRIGGER, when ITax::TAX_CUSTOM implemented will hold the logic patern
	 * @param string $legal - some legal sentense associated with the tax
	 *
	 * @return OrderSection instance (for fluent coding)
	 */
	public function addTax($code, $name, $rate, $mode = ITax::TAX_VAT, $extra = null, $legal = null);

	/**
	 * attach a Voucher to this Section
	 * really a semantic alias for addDiscount() accepting only negative amount
	 *
	 * @param string $name
	 * @param number $value - negative amount
	 *
	 * @throws Exception if value is not negative
	 *
	 * @return OrderSection instance (for fluent coding)
	 */
	public function addVoucher($name, $value);
}

interface IOrder
{
	/** @const TAXINC the Order compute all taxes */
	const TAXINC = 1;
	/** @const TAXEXC the Order ignore taxes but the ITax::TAX_NODISCARD */
	const TAXEXC = 2;
	
	/**
	 *
	 * @param integer $use_tax one of IOrder::TAXINC or IOrder::TAXEXC
	 * @param number $precision[=2] number of significant decimals
	 * @param callable $round_func[=null] a rounding user defined function rounder($value,$precision), default is internal libc agnostic round() in mode PHP_ROUND_HALF_UP
	 */
	public function __construct($use_tax = IOrder::TAXINC, $precision = 2, $round_func = null);

	/**
	 *
	 * @param string $manifest a serialized manifests
	 * @param string[] $refunds[] array of serialized manifests
	 */
	public function __from_manifest($manifest, array $refunds);
	
	/**
	 * attach an OrderSection to this Order
	 *
	 * @param string $name[='products'] name of the section (e.g: addSection('shipping') )
	 *
	 * @return OrderSection instance
	 */
	public function addSection($name = 'products');
	
	/**
	 * attach a Discount to this (whole) Order
	 *
	 * @param string $name
	 * @param nimber $value - positive float express percent (0.1 = 10%), negative value express amount
	 * @param number $capped - the unit discounted amount that SHOULD NOT be exceeded
	 *
	 * @return Order instance (for fluent coding)
	 */
	public function addDiscount($name, $value, $capped = 0);

	/**
	 * attach a Tax to this (whole) Order
	 *
	 * @param string $code - a tax code, passing similar code will return a uniq instance
	 * @param string $name - a long name
	 * @param number $rate - the rate, positive float express percent (0.1 = 10%), negative value express amount
	 * @param integer $mode - bitmask of ITax::TAX_* constant (e.g: ITax::TAX_VAT|ITax::TAX_NODISCARD
	 * @param mixed $extra - extra hold amount threshold for ITax::TAX_TRIGGER, when ITax::TAX_CUSTOM implemented will hold the logic patern
	 * @param string $legal - some legal sentense associated with the tax (default is $name)
	 *
	 * @return Order instance (for fluent coding)
	 */
	public function addTax($code, $name, $rate, $mode = ITax::TAX_VAT, $extra = null, $legal = null);

	/**
	 * attach a Voucher to this (whole) Order
	 * really a semantic alias for addDiscount() accepting only negative amount
	 *
	 * @param string $name
	 * @param number $value - negative amount
	 *
	 * @throws Exception if value is not negative
	 *
	 * @return Order instance (for fluent coding)
	 */
	public function addVoucher($name, $value);

	/**
	 * create an OrderRefund based on this Order
	 *
	 *  @return OrderRefund instance (for fluent coding)
	 */
	public function addOrderRefund();
	
	public function manifest();
	public function summary();
}

interface IOrderRefund
{
	/**
	 * refund one OrderLine
	 *
	 * @param string $uuid a unique line id
	 * @param number $qty quantity to refund (positive quantity)
	 *
	 * @throws Exception if $qty is negative or $uuid does not exist or exhausted
	 * @return OrderRefund instance (for fluent coding)
	 */
	public function refundLine($uuid, $qty = 1);

	public function manifest();
	public function summary();
}