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