source: main/waeup.kofa/trunk/docs/source/userdocs/hostels.rst @ 13172

Last change on this file since 13172 was 13172, checked in by Henrik Bettermann, 9 years ago

Add line breaks.

File size: 9.7 KB
Line 
1.. _accommodation_section:
2
3Accommodation Section
4*********************
5
6The accommodation sections is a built-in hostel management system.
7African universities usually run their own student hostels which are
8built on their huge university campuses. They combine the booking of
9beds with the registration process. There are two major use cases.
10Students either have to book a bed space before they can continue
11with the registration, or they are only allowed to book, if they
12have reached a certain registration state. In the first case, the
13university requires students to stay on campus. They usually have
14enough beds for all of their students and need to fill up the
15hostels. In the second case, bed space is limited. Since
16accommodation on campus is usually very reasonable and much safer
17than on the free market outside, students prefer to stay on campus.
18If bed allocation e.g. requires the payment of school fees, the
19university benefits from bed shortage, because students are forced
20to pay in order to get the highly coveted hostel bed.
21
22From the database's point of view, the accommodation section is a
23container of type `HostelsContainer` with id ``hostels``, which is
24located in the `IUniversity` instance. It contains hostels
25(instances of `IHostel`) which again contain the beds (instances of
26`IBed`).
27
28The :ref:`treelike storage of objects <object_database>` in the
29accommodation section can be figured as follows::
30
31
32  Accommodation Section (HostelsContainer)
33  |
34  +---> Hostel
35        |
36        +---> Bed
37
38Interfaces
39==========
40
41`IHostelsContainer`
42-------------------
43
44The unique hostels container serves also as a configuration object.
45It defines for which academic session booking is enabled. The
46student's `current_session` must match the `accommodation_session`.
47It also defines the booking period and the registration workflow
48states for which booking is allowed, see :ref:`bed_tickets`. The
49only property attribute is `expired` which returns ``True`` if the
50current datetime is within the booking period.
51
52.. literalinclude:: ../../../src/waeup/kofa/hostels/interfaces.py
53   :pyobject: IHostelsContainer
54
55`IHostel`
56---------
57
58The hostels container contains the various `Hostel` objects. Hostels
59are buildings with blocks, floors rooms and beds. When adding a
60hostel, the form page is requesting the hostel's name. The
61`hostel_id` is derived from the name by applying
62:code:`lower().replace(' ','-').replace('_','-')` to it. As usual,
63the id will be omitted in manage forms and can thus not be changed
64after hostel creation.
65
66The add and manage form pages let us define the 'dimensions' of the
67hostel and and configure blocks with their assignment to either
68female or male students. And they are requesting the number of
69floors per block as well as the number of rooms per floor. All
70blocks have the same number of floors with a fixed number of rooms
71and a fixed number of beds per room. If beds or even entire rooms do
72not exist on a floor, these beds must be later marked reserved, so
73that they are skipped during the automatic allocation process, see
74below.
75
76.. note::
77
78  Blocks for either female or male students? Does Kofa's hostel
79  management accommodate girls and boys strictly separately? No, it
80  doesn't. Blocks are not necessarily real buildings. They can be used
81  as virtual subunits. If the entire hostel has only one block, then
82  yes, either only female or only male students can be hosted in such
83  a hostel. If two blocks are configured (one for male and one for
84  female students), beds of the same room can be assigned to either
85  the female or the male block, which means - even though very
86  uncommon - girls and boys would be accommodated in the same room.
87
88.. literalinclude:: ../../../src/waeup/kofa/hostels/interfaces.py
89   :pyobject: IHostel
90
91Beds can be dedicated to pre-study students, fresh students
92(`entry_session` and the hostels container's `accommodation_session`
93correspond), final-year students (`current_level` and the
94certificate's `end_level` correspond, or is even higher) and
95returning students (non-fresh and non-final-year students). Or they
96can be made bookable for all students (beds without category). The
97latter bed type can be configured but is not being used in the base
98package by
99:py:meth:`getAccommodationDetails<waeup.kofa.students.utils.StudentsUtils.getAccommodationDetails>`,
100the method which determines the appropriate bed type of the
101student.
102
103Usually, not every student can be accommodated in every hostel.
104Faculties are sometimes far apart and do manage their own student
105hostels. These hostels require a 'special handling' in
106:py:meth:`getAccommodationDetails<waeup.kofa.students.utils.StudentsUtils.getAccommodationDetails>`.
107The special handling code must be set on the add and manage form
108pages of hostels.
109
110The interface defines also two schema invariants
111(invariant-decorated methods). These methods validate one or more
112depending schema fields. In our case, the methods take care that
113blocks and beds are not assigned twice.
114
115All the parameters above define the construction rules for beds when
116filling the hostel with beds, which is done by the `updateBeds`
117method described further below.
118
119`IBed`
120------
121
122.. literalinclude:: ../../../src/waeup/kofa/hostels/interfaces.py
123   :pyobject: IBed
124
125The `bed_id` contains the 'coordinates' of the bed. It tells us
126precisely in which hostel, in which block, on which floor and in
127which room the bed can be found. The bed id is composed as follows:
128``[hostel id]_[block letter]_[room number]_[bed letter]``. The room
129number contains the floor level: :code:`room_nr = floor*100 + room`.
130Example: ``hall-1_A_101_C`` means that the bed is located in Hostel
1311, Block A, 1st Floor, Room 101 (or 1) and labelled with 'C'.
132
133The `bed_type` attribute is similarly being constructed. It
134describes which kind of student can be allocated: ``[special
135handling code]_[sex]_[stage]``. Example: ``regular_female_re`` means
136that this bed can be booked by regular female returning students.
137Other stages are: ``fr`` (fresh), ``pr`` (pre-study), ``fi``
138(final-year) and ``all`` (all students).
139
140Beds of each hostel are consecutively numbered (`bed_number`).
141
142Except for `owner`, all attributes of bed objects are being
143determined by the system, no matter if they are property or schema
144field attrributes. They can neither be edited nor imported (there is
145no batch processor for beds). The `owner` attribute contains the
146student id, if the bed is occupied. This attribute is either set by
147Kofa when the student creates a bed ticket (see :ref:`bed_tickets`),
148or can be set via the `BedManageFormPage`, see below. The
149`allowed_owners` schema invariant ensures (1) that the selected user
150exists, (2) that the student's current session corresponds with the
151accommodation session and (3) that the student doesn't reside in
152another bed.
153
154Browser Pages
155=============
156
157Update Beds
158-----------
159
160Hostels are empty after creation and configuration. They do not
161contain any bed. The hostel's
162:py:meth:`Hostel.updateBeds<waeup.kofa.hostels.hostel.Hostel.updateBeds>`
163method must be called to fill the hostel with beds according to
164the hostel's configuration parameters. This is done by the
165same-named action of the `HostelManageFormPage`. `Hostel.updateBeds`
166iterates over all block letters, floor levels, room numbers and bed
167letters, which haven been configured on the `HostelManageFormPage`.
168In each bed letter iteration loop a bed is added and the `bed_id`,
169`bed type` as well as the consecutive `bed_number` are determined
170and stored with the bed.
171
172As the method's name already promises, it does not only add beds to
173an empty hostel container, but also updates existing beds after
174re-configuration. It does this by removing all empty beds before the
175iteration starts. Occupied beds remain in the hostel but get the bed
176number ``9999``. When iterating over the newly configured blocks,
177floors, rooms and bed letters, Kofa checks first, if the bed belongs
178to the group of remaining beds, which could not be removed because
179they are occupied. If so, the bed type is adjusted and the bed
180number changed. The bed remains occupied by the same student, no
181matter if the student meets the newly configured conditions or not.
182
183It might happen that e.g. a room for male students is converted into
184a room for female students, but a male student still resides in this
185room. This has to be checked and the student has to be relocated
186manually, see :ref:`student_relocation`. Moreover, due to the
187reconfiguration of the hostel, an occupied bed may no longer exist
188or offered for booking. This is then indicated by the bed number
189``9999``. Also these students must be relocated manually.
190
191
192Switch Reservations
193-------------------
194
195Beds can be blocked by switching ther reservation status. The switch
196replaces the stage part of `bed_type` by ``_reserved``. Example:
197``regular_female_re`` becomes ``regular_female_reserved``. Switching
198again, reverts this process.
199
200Reserved beds won't be allocated automatically. The beds remains
201empty during the hostel booking period. Students can only be
202allocated manually to reserved beds, which is done via the
203`BedManageFormPage`, see below.
204
205Release Beds
206------------
207
208Releasing a bed does not simply mean clearing the `owner` attribute
209of the bed object. The student has to be notified that booking has
210been cancelled. This is done by replacing the `bed_coordinates` of
211the student's bed ticket. Instead of the coordinates, the student
212will read: ``-- booking cancelled on <datetime of cancellation> --``.
213
214Manage Bed
215----------
216
217Not many things can be managed on this form page. As mentioned above,
218only the `owner` attribute can be changed by entering a student id.
219The id is being validated by a schema invariant. The manage form
220page cannot be accessed, if a student has aleady been allocated.
221Beds must be released first, before they can be allocated to other
222students.
Note: See TracBrowser for help on using the repository browser.