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

.. |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-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 :ref:`label-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|), :ref:`label-contact-phone` (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
-------------

Mobile phone number which is capable of receiving sms text messages.

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

Used in the following use cases:


.. _label-contract:

Contract
--------

A contract is created whenever a :ref:`label-customer` orders some
:ref:`label-service` from the system. It is always connected to a
:ref:`label-customer` and a :ref:`label-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 :ref:`label-service` , which tells about
the basic data, with additional parameters set that depend on the type
of :ref:`label-service` ordered.

Contracts can trigger :ref:`label-transaction`\ s. For instance if some
:ref:`label-customer` orders a service. When the service charges
become due, a respective :ref:`label-transaction` is triggered.

Contracts can have multiple :ref:`label-contract-addon`.

Connected to: :ref:`label-service` (|n0|:1), :ref:`label-customer` (|n0|:1),
:ref:`label-contract-addon` (1:|n0|), :ref:`label-transaction` (|n0|, |m0|)

Used in the following use cases:


.. _label-contract-addon:

Contract Addon
--------------

Kind of 'sub contract' that always belongs to some already existing
:ref:`label-contract` but comes with an own set of
parameters. Contract addons are created by :ref:`label-contract`\ s.

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


.. _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-point-of-consumption:

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


.. _label-report:

Report
------


.. _label-service:

Service
-------

The system will provide different services to
:ref:`label-customer`\ s. 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
:ref:`label-customer`\ s, including prices, runtimes, etc.

Services also serve as factories for :ref:`label-contract`\ s.

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, purchased, or (pre-)paid by the respective customer.

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.