source: main/eko-disco-specs/trunk/data.rst @ 10729

.. |n0| replace:: n\ :sub:`0`
.. |m0| replace:: m\ :sub:`0`

.. _label-data-entities:

Data Entities
=============

These are the data entities the new system is supposed to model. Each
of these entities should be addable, editable, and removable as
covered in more detail in :ref:`label-use-cases`.

For each entity we give a short description to tell what it means,
what its purpose is and in what regards (and how) it should be handled
by the system. Again the more detailed actions on these entities
provided by the system are described in the :ref:`label-use-cases`
section.

The data entities are sorted alphabetically, not by importance or
similar. Used description terms should link to other respective
entities/terms where possible.

Each data entitiy description provides a list of use cases and other
data entities connected. Connections to other data entities contain a
relationship telling how many instances of the described entity are
connected to how many instances of the related entity [#]_.

.. _label-account:

Account
-------

A customer account contains the assets/debts of a :ref:`customer
<label-customer>`. It is *not* a system account (see
:ref:`label-login-credentials` for that) but a virtual financial
account kept by the system. Basically it tells, how much money a
certain :ref:`customer <label-customer>` owes or is eligible for. Each
account is connected to exactly one customer.

Connected to: :ref:`label-customer` (1:1), :ref:`label-payment` (1:n),
:ref:`label-consumption` (1:n)

Used in the following use cases: :ref:`label-uc-account-add`


.. _label-contact-address:

Contact Address
---------------

A postal address.

Connected to: :ref:`label-contact-data` (n:1)

Used in the following use cases:


.. _label-contact-data:

Contact Data
------------

The data neccessary to contact some customer, staff person or similar
entity. Contact data might contain several addresses, phone numbers,
emails, etc.

Connected to: :ref:`label-customer` (1:1),
:ref:`label-contact-address` (1:|n0|), :ref:`label-contact-email` (1:|n0|)

Used in the following use cases:


.. _label-contact-email:

Contact Email
-------------

An email address with optional additional clear name. For email
addresses we store some timestamp that indicates when the respective
email address was last checked successfully (thus marking it a 'valid'
one).

Connected to: :ref:`label-contact-data` (|n0|:1)

Used in the following use cases:


.. _label-contact-phone:

Contact Phone
-------------

A phone number.

Connected to: :ref:`label-contact-data` (|n0|:1)

Used in the following use cases:


.. _label-contract:

Contract
--------

A contract is created whenever a customer orders some service from the
system. It is always connected to a customer and a service.

A contract is not necessarily written on paper and signed by
people. Instead it is an abstraction used inside the system.

It is always created from a service, which tells about the basic data,
with additional parameters set that depend on the type of service
ordered.

Contracts can have contract additions.

Connected to: :ref:`label-service` (1:1), :ref:`label-customer`

Used in the following use cases:


.. _label-contract-types:

Contract Types
--------------

.. _label-contract-termination:

Contract Termination
--------------------

.. _label-consumption:

Consumption
-----------

.. _label-customer:

Customer
--------

Beneficiary of a contract

.. _label-login-credentials:

Login Credentials
-----------------

.. _label-meter:

Meter
-----

.. _label-meter-status:

Meter Status
------------

.. _label-meter-value:

Meter Value
-----------

.. _label-meter-reader:

Meter Reader
------------

.. _label-payment:

Payment
-------

.. _label-point-of-consumption:

Point of Consumption
--------------------

.. _label-report:

Report
------


.. _label-service:

Service
-------

The system will provide different services to customers. These can
have arbitrary forms, including one-time services (like installation
of meters) and open-ended long-time services (like delivering power
based on contract). Services are managable by staff like goods offered
in a shop.

Services define the conditions under which they can be ordered by
customers, including prices, runtimes, etc.

Services also serve as factories for contracts.

Connected to: :ref:`label-contract` (1:|n0|)

Used in the following use cases:



.. _label-timestamp:

Timestamp
---------


.. _label-transaction:

Transaction
-----------

A transaction is some business-relevant action taken. A transaction
means basically, that something happened, that leads to increased or
decreased customer accounts. Normally this is something like a
payment, some service order or similar.

Transactions do always belong to one certain customer account. They
also contain some amount of money which is thereby transfered to or
from a customer's account. They also always reference a service which
is consumed or purchased by the respective customer.

.. todo:: this is an initial draft, by no means the final version

Connected to: :ref:`label-customer` (1:|n0|), :ref:`label-service`
(|n0|:1)

Used in the following use cases:


.. [#] Relation types: (1:1): One-to-one, (1:n): One-to-many, (n:1):
       many-to-one, (n:m): many-to-many. ``n`` and ``m`` mean some
       value ``1..n``. To indicate zero or more (``0..n``) relations,
       we use |n0| and |m0| respectively.