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

Last change on this file since 11102 was 10798, checked in by Henrik Bettermann, 11 years ago

Each service belongs to one or more business units.

File size: 12.1 KB
Line 
1
2.. |n0| replace:: n\ :sub:`0`
3.. |m0| replace:: m\ :sub:`0`
4
5.. _label-data-entities:
6
7Data Entities
8=============
9
10These are the data entities the new system is supposed to model. Each
11of these entities should be addable, editable, and removable as
12covered in more detail in :ref:`label-use-cases`.
13
14For each entity we give a short description to tell what it means,
15what its purpose is and in what regards (and how) it should be handled
16by the system. Again the more detailed actions on these entities
17provided by the system are described in the :ref:`label-use-cases`
18section.
19
20The data entities are sorted alphabetically, not by importance or
21similar. Used description terms should link to other respective
22entities/terms where possible.
23
24Each data entitiy description provides a list of use cases and other
25data entities connected. Connections to other data entities contain a
26relationship telling how many instances of the described entity are
27connected to how many instances of the related entity.
28
29The following relation types may occur (in both directions):
30
31  - 1:1 (one on one)
32  - n:1 (many on one)
33  - n:m (many on many)
34  - p:1 (many or none on one)
35  - p:q (many or none on many or none)
36  - p:n (many or none on many)
37  - b:1 (one or none on one)
38
39with
40
41  - n, m element of {1, 2, ...},
42  - p, q element of {0, 1, 2, ...}
43  - b element of {0, 1}
44
45Examples:
46
471:p service-contract relation means that each service
48offered can result in various contracts, but each contract is
49only based on one service.
50
51p:q useraccount-userrole relation means that each user account can have no role
52or several roles and each role can be assigned to no user account
53or several user accounts.
54
55Relations can always be read in two directions.
56
57
58.. _label-business-unit:
59
60Business Unit
61-------------
62
63An organisational unit for grouping of :ref:`label-officer`\ s
64(staff members) and  :ref:`label-service`\ s.
65
66A business unit may correspond with an administrative division (geographical
67unit, government area) or any department or body of the distribution company.
68Business units can be nested, i.e. a business unit may contain
69other business units like wards, districts or undertakings.
70
71Connected to: :ref:`label-officer` (n:p),
72:ref:`label-service` (n:p),
73
74
75.. _label-contact-address:
76
77Contact Address
78---------------
79
80A postal address.
81
82Connected to: :ref:`label-contact-data` (p:1)
83
84
85.. _label-contact-data:
86
87Contact Data
88------------
89
90The data neccessary to contact some :ref:`label-customer`,
91:ref:`label-officer` or similar entity. Contact data might contain several
92addresses, phone numbers, emails, etc.
93
94Connected to: :ref:`label-customer` (1:1),
95:ref:`label-contact-address` (1:p), :ref:`label-contact-email`
96(1:n), :ref:`label-contact-phone` (1:p)
97
98
99.. _label-contact-email:
100
101Contact Email
102-------------
103
104An email address with optional additional clear name. For email
105addresses we store some timestamp that indicates when the respective
106email address was last checked successfully (thus marking it a 'valid'
107one). No timestamp means, the email address has never been checked.
108
109Connected to: :ref:`label-contact-data` (n:1),
110:ref:`label-timestamp` (1:q),
111:ref:`label-user-account` (1:b)
112
113Used in the following use cases: :ref:`label-uc-user-add`,
114:ref:`label-uc-user-manage`, :ref:`label-uc-service-manage`
115
116
117.. _label-contact-phone:
118
119Contact Phone
120-------------
121
122Mobile phone number which is capable of receiving sms text messages.
123
124Connected to: :ref:`label-contact-data` (p:1)
125
126Used in the following use cases: :ref:`label-uc-user-add`,
127:ref:`label-uc-user-manage` , :ref:`label-uc-service-manage`
128
129
130.. _label-contract:
131
132Contract
133--------
134
135A contract is created whenever a :ref:`label-customer` orders some
136:ref:`label-service` from the system. It is always connected to a
137:ref:`label-customer` and a :ref:`label-service` .
138
139A contract is not necessarily written on paper and signed by
140people. Instead it is an abstraction used inside the system.
141
142It is always created from a :ref:`label-service`, which tells about
143the basic data, with additional parameters set that depend on the type
144of :ref:`label-service` ordered.
145
146Contracts can trigger :ref:`label-transaction`\ s. For instance if some
147:ref:`label-customer` orders a service. When the service charges
148become due, a respective :ref:`label-transaction` is triggered.
149
150Contracts can have multiple :ref:`label-supp-contract`\ s.
151
152Connected to: :ref:`label-service` (p:1), :ref:`label-customer` (p:1),
153:ref:`label-supp-contract` (1:p), :ref:`label-transaction` (1:p),
154:ref:`label-meter` (1:b)
155
156
157.. _label-customer:
158
159Customer
160--------
161
162A user data entity and beneficiary of :ref:`label-contract`\ s.
163
164Customers are added to the system by initial import (migration phase),
165being created by staff or can register themselves (self-registration)
166to the system.
167
168Each customer has a :ref:`label-user-account`.
169
170Customers have to provide :ref:`label-contact-data` and get
171:ref:`label-login-credentials` to login to the system.
172
173Once logged in, customers get a 'My Eko-Disco' page where they can
174
175- see their current orders
176
177- watch their consumption
178
179- order more services
180
181- handle contractual problems
182
183- get help if problems arise
184
185- retrieve bills
186
187- change their passwords
188
189Customers can order :ref:`label-service`\ s and pay these (kinds of
190payment depend on the type of service/good ordered and the available
191payment methods).
192
193Customers and their data can be managed by customers themselves (for
194instance when postal addresses change), and by officers.
195
196Connected to: :ref:`label-contract` (1:p),
197:ref:`label-contact-data` (1:1), :ref:`label-login-credentials` (1:1),
198:ref:`label-user-account` (b:1)
199
200
201.. _label-location:
202
203Location
204--------
205
206A real-world location. Used for instance for meters to store
207information about their place. The location of a meter does not necessarily
208correspond with one of the :ref:`label-contact-address`\ es.
209Locations can either be less formal, for instance describing a location
210in words, or very precise by using GPS data.
211
212Connected to: :ref:`label-meter` (1:p)
213
214
215.. _label-login-credentials:
216
217Login Credentials
218-----------------
219
220A set of username and password assigned to user accounts. Passwords are
221stored inside the system using strong cryptographic hash functions.
222
223Passwords can be reset on request.
224
225Connected to: :ref:`label-customer` (1:1), :ref:`label-user-account` (1:1)
226
227
228.. _label-meter:
229
230Meter
231-----
232
233A meter measures power consumption. It has a place where it is
234installed and might be connected to one or several contracts. For a
235given time a meter can be connected to one or zero contracts.
236
237Each meter has to provide a :ref:`label-location` that tells, where it
238is installed.
239
240Meters also contain a history of meter values
241(:ref:`label-meter-value`), which is basically a list of meter values
242at a given time.
243
244Connected to: :ref:`label-contract` (b:1),
245:ref:`label-meter-value` (1:n), :ref:`label-location` (p:1)
246
247
248.. _label-meter-value:
249
250Meter Value
251-----------
252
253The value of a :ref:`label-meter` at a certain point in time
254(providing a :ref:`label-timestamp`) authorized by some user or device.
255
256It serves mainly for computing power consumption of
257:ref:`label-customer`\ s.
258
259When a new meter value is added to the system (the respective
260:ref:`label-meter` is 'updated'), the system also registers how the
261the new value was entered, i.e. by whom and when.
262
263The system will be prepared to collect meter values in two ways:
264
265a) (push-method): by being fed with respective data by authorized
266   users (officers)
267
268b) (pull-method): by polling dedicated hardware that provides the
269   neccessary interface (automatic remote-reading).
270
271The second choice requires appropriate hardware to be in place, which
272in detail is not part of this specs. The system will, however, be
273prepared to collect meter data from external devices.
274
275Connected to: :ref:`label-meter` (n:1), :ref:`label-timestamp` (1:1),
276:ref:`label-user-account` (p:1)
277
278
279.. _label-officer:
280
281Officer
282-------
283
284A user data entity of a staff member with certain permissions to manage
285portal data.
286
287Each officer has a :ref:`label-user-account`.
288
289Actors are called :ref:`Manager <label-actors>`\ s if they are officers with
290local managing permission.
291
292Connected to: :ref:`label-login-credentials` (1:1),
293:ref:`label-user-account` (b:1),
294:ref:`label-user-role` (1:p),
295:ref:`label-business-unit` (p:n)
296
297
298.. _label-report:
299
300Report
301------
302
303Administrative report or list to give overviews over current state of
304business. Includes lists of customers sorted by various categories
305(type of contract, amount of fees paid, etc.), lists of services
306sorted by various categories, etc.
307
308Reports are generated as PDF documents and are available for download
309by authorized users.
310
311Connected to: (almost everything else)
312
313
314.. _label-service:
315
316Service
317-------
318
319Services are provided to :ref:`label-customer`\ s.
320They can have arbitrary forms, including
321one-time services (like installation of meters) and open-ended
322long-time services (like delivering power based on contract).
323
324Services are offered by :ref:`label-business-unit`\ s which means,
325each service belongs to one or more business units. They are
326managable by staff like goods offered in a shop.
327
328Services define the conditions under which they can be ordered by
329:ref:`label-customer`\ s, including prices, runtimes, etc.
330
331Services also serve as factories for :ref:`label-contract`\ s.
332
333Connected to: :ref:`label-contract` (1:p),
334:ref:`label-business-unit` (p:n)
335
336
337.. _label-supp-contract:
338
339Supplementary Contract
340----------------------
341
342A supplementary contract always belongs to some already existing
343:ref:`label-contract` but comes with an own set of
344parameters. A typical supplementary contract materialises if a customer
345orders an amount of electrical energy on the bases of a 'main' contract
346achieved between the customer and the distribution company.
347The parent contract for instance may guarantee a special price
348per kilowatt hour of electrical energy.
349
350Supplementary contracts are created by :ref:`label-contract`\ s.
351
352Connected to: :ref:`label-contract` (p:1),
353:ref:`label-service` (p:1), :ref:`label-customer` (p:1),
354:ref:`label-transaction` (1:p)
355
356
357.. _label-timestamp:
358
359Timestamp
360---------
361
362A timestamp can be a calendar date or a calendar date plus some day
363time.
364
365The system will internally use UTC-based timestamps only to minimize
366ambiguities. In menus, frontends, etc. timestamps are displayed in
367local Lagos time.
368
369Connected to: :ref:`label-meter-value` (1:1),
370:ref:`label-contact-email` (p:1)
371
372
373.. _label-transaction:
374
375Transaction
376-----------
377
378A transaction is some business-relevant action taken. A transaction
379means basically, that something happened, that leads to increased or
380decreased customer accounts. Normally this is something like a
381payment, some service order or similar.
382
383Transactions do always belong to one certain customer account. They
384also contain some amount of money which is thereby transfered to or
385from a customer's account. They also always reference a service which
386is consumed, purchased, or (pre-)paid by the respective customer.
387
388Connected to: :ref:`label-customer` (p:1), :ref:`label-service`
389(p:1), :ref:`label-contract` (p:1)
390
391
392.. _label-user-account:
393
394User Account
395------------
396
397A user account is a set of user data and :ref:`label-login-credentials`
398which allows a user (agent) to authenticate against the system and
399let the system store some information required for user handling,
400such as real name, email address and/or mobile phone number. An email
401address and/or phone number ensures that the user can be contacted
402electronically by the system.
403
404:ref:`label-user-role`\s are assigned to user accounts and managed by the
405system to grant authorization for the various views of the portal.
406Real-world officers (staff members) and customers are different to the
407system as they will get different roles. Also anonymous users
408(users without user account) are accepted by the system to provide
409marketing pages, service offers, etc.
410
411Users can be blocked or removed from the system.
412
413Connected to: :ref:`label-login-credentials` (1:1),
414:ref:`label-customer` (1:b),
415:ref:`label-user-role` (p:q),
416:ref:`label-contact-email` (b:1)
417
418
419.. _label-user-role:
420
421User Role
422---------
423
424A set of permissions assigned to a group of :ref:`label-user-account`\ s.
425
426Connected to: :ref:`label-user-account` (p:q)
427
Note: See TracBrowser for help on using the repository browser.