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

.. |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.

The following relation types may occur (in both directions):

  - 1:1 (one on one)
  - n:1 (many on one)
  - n:m (many on many)
  - p:1 (many or none on one)
  - p:q (many or none on many or none)
  - p:n (many or none on many)
  - b:1 (one or none on one)

with

  - n, m element of {1, 2, ...},
  - p, q element of {0, 1, 2, ...}
  - b element of {0, 1}

Examples:

1:p service-contract relation means that each service
offered can result in various contracts, but each contract is
only based on one service.

p:q useraccount-userrole relation means that each user account can have no role
or several roles and each role can be assigned to no user account
or several user accounts.

Relations can always be read in two directions.


.. _label-business-unit:

Business Unit
-------------

An organisational unit for grouping of :ref:`label-officer`\ s
(staff members) and  :ref:`label-service`\ s.

A business unit may correspond with an administrative division (geographical
unit, government area) or any department or body of the distribution company.
Business units can be nested, i.e. a business unit may contain
other business units like wards, districts or undertakings.

Connected to: :ref:`label-officer` (n:p),
:ref:`label-service` (n:p),


.. _label-contact-address:

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

A postal address.

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


.. _label-contact-data:

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

The data neccessary to contact some :ref:`label-customer`,
:ref:`label-officer` 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:p), :ref:`label-contact-email`
(1:n), :ref:`label-contact-phone` (1:p)


.. _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). No timestamp means, the email address has never been checked.

Connected to: :ref:`label-contact-data` (n:1),
:ref:`label-timestamp` (1:q),
:ref:`label-user-account` (1:b)

Used in the following use cases: :ref:`label-uc-user-add`,
:ref:`label-uc-user-manage`, :ref:`label-uc-service-manage`


.. _label-contact-phone:

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

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

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

Used in the following use cases: :ref:`label-uc-user-add`,
:ref:`label-uc-user-manage` , :ref:`label-uc-service-manage`


.. _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-supp-contract`\ s.

Connected to: :ref:`label-service` (p:1), :ref:`label-customer` (p:1),
:ref:`label-supp-contract` (1:p), :ref:`label-transaction` (1:p),
:ref:`label-meter` (1:b)


.. _label-customer:

Customer
--------

A user data entity and beneficiary of :ref:`label-contract`\ s.

Customers are added to the system by initial import (migration phase),
being created by staff or can register themselves (self-registration)
to the system.

Each customer has a :ref:`label-user-account`.

Customers have to provide :ref:`label-contact-data` and get
:ref:`label-login-credentials` to login to the system.

Once logged in, customers get a 'My Eko-Disco' page where they can

- see their current orders

- watch their consumption

- order more services

- handle contractual problems

- get help if problems arise

- retrieve bills

- change their passwords

Customers can order :ref:`label-service`\ s and pay these (kinds of
payment depend on the type of service/good ordered and the available
payment methods).

Customers and their data can be managed by customers themselves (for
instance when postal addresses change), and by officers.

Connected to: :ref:`label-contract` (1:p),
:ref:`label-contact-data` (1:1), :ref:`label-login-credentials` (1:1),
:ref:`label-user-account` (b:1)


.. _label-location:

Location
--------

A real-world location. Used for instance for meters to store
information about their place. The location of a meter does not necessarily
correspond with one of the :ref:`label-contact-address`\ es.
Locations can either be less formal, for instance describing a location
in words, or very precise by using GPS data.

Connected to: :ref:`label-meter` (1:p)


.. _label-login-credentials:

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

A set of username and password assigned to user accounts. Passwords are
stored inside the system using strong cryptographic hash functions.

Passwords can be reset on request.

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


.. _label-meter:

Meter
-----

A meter measures power consumption. It has a place where it is
installed and might be connected to one or several contracts. For a
given time a meter can be connected to one or zero contracts.

Each meter has to provide a :ref:`label-location` that tells, where it
is installed.

Meters also contain a history of meter values
(:ref:`label-meter-value`), which is basically a list of meter values
at a given time.

Connected to: :ref:`label-contract` (b:1),
:ref:`label-meter-value` (1:n), :ref:`label-location` (p:1)


.. _label-meter-value:

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

The value of a :ref:`label-meter` at a certain point in time
(providing a :ref:`label-timestamp`) authorized by some user or device.

It serves mainly for computing power consumption of
:ref:`label-customer`\ s.

When a new meter value is added to the system (the respective
:ref:`label-meter` is 'updated'), the system also registers how the
the new value was entered, i.e. by whom and when.

The system will be prepared to collect meter values in two ways:

a) (push-method): by being fed with respective data by authorized
   users (officers)

b) (pull-method): by polling dedicated hardware that provides the
   neccessary interface (automatic remote-reading).

The second choice requires appropriate hardware to be in place, which
in detail is not part of this specs. The system will, however, be
prepared to collect meter data from external devices.

Connected to: :ref:`label-meter` (n:1), :ref:`label-timestamp` (1:1),
:ref:`label-user-account` (p:1)


.. _label-officer:

Officer
-------

A user data entity of a staff member with certain permissions to manage
portal data.

Each officer has a :ref:`label-user-account`.

Actors are called :ref:`Manager <label-actors>`\ s if they are officers with
local managing permission.

Connected to: :ref:`label-login-credentials` (1:1),
:ref:`label-user-account` (b:1),
:ref:`label-user-role` (1:p),
:ref:`label-business-unit` (p:n)


.. _label-report:

Report
------

Administrative report or list to give overviews over current state of
business. Includes lists of customers sorted by various categories
(type of contract, amount of fees paid, etc.), lists of services
sorted by various categories, etc.

Reports are generated as PDF documents and are available for download
by authorized users.

Connected to: (almost everything else)


.. _label-service:

Service
-------

Services are provided to :ref:`label-customer`\ s.
They 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 offered by :ref:`label-business-unit`\ s which means,
each service belongs to one or more business units. They 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:p),
:ref:`label-business-unit` (p:n)


.. _label-supp-contract:

Supplementary Contract
----------------------

A supplementary contract always belongs to some already existing
:ref:`label-contract` but comes with an own set of
parameters. A typical supplementary contract materialises if a customer
orders an amount of electrical energy on the bases of a 'main' contract
achieved between the customer and the distribution company.
The parent contract for instance may guarantee a special price
per kilowatt hour of electrical energy.

Supplementary contracts are created by :ref:`label-contract`\ s.

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


.. _label-timestamp:

Timestamp
---------

A timestamp can be a calendar date or a calendar date plus some day
time.

The system will internally use UTC-based timestamps only to minimize
ambiguities. In menus, frontends, etc. timestamps are displayed in
local Lagos time.

Connected to: :ref:`label-meter-value` (1:1),
:ref:`label-contact-email` (p:1)


.. _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` (p:1), :ref:`label-service`
(p:1), :ref:`label-contract` (p:1)


.. _label-user-account:

User Account
------------

A user account is a set of user data and :ref:`label-login-credentials`
which allows a user (agent) to authenticate against the system and
let the system store some information required for user handling,
such as real name, email address and/or mobile phone number. An email
address and/or phone number ensures that the user can be contacted
electronically by the system.

:ref:`label-user-role`\s are assigned to user accounts and managed by the
system to grant authorization for the various views of the portal.
Real-world officers (staff members) and customers are different to the
system as they will get different roles. Also anonymous users
(users without user account) are accepted by the system to provide
marketing pages, service offers, etc.

Users can be blocked or removed from the system.

Connected to: :ref:`label-login-credentials` (1:1),
:ref:`label-customer` (1:b),
:ref:`label-user-role` (p:q),
:ref:`label-contact-email` (b:1)


.. _label-user-role:

User Role
---------

A set of permissions assigned to a group of :ref:`label-user-account`\ s.

Connected to: :ref:`label-user-account` (p:q)