forked from smudge/shifts
-
Notifications
You must be signed in to change notification settings - Fork 1
/
README
executable file
·137 lines (100 loc) · 7.88 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
Basic Guide to Shifts
Creator: Adam Bray
Contributors/Maintainers: (add your names here :-)) Harley Trung, Michael Libertin, Ryan Laughlin, Ben Somers, Nathan Griffith, Laura Tomas, Derek Zhao, Aashish Manchanda, Kobby Antwi-Boasiako, Cassandra Kildow, Wei Yan, AJ Espinosa, and Bob Qu
h1. Introduction
Shifts is a program that allows the easy tracking of employees who work scheduled (and even unscheduled) hours in various locations and times. It also offers payform features, allowing automatic logging of when employees work shifts, with the option for adding addition hours worked outside of shifts.
There are two sections of the application, one for employees who work shifts, and another for administrators, who manage these employees (Note: administrators can use the application as both administrators and employees, allowing them to perform administrative duties on top of using payforms, shifts, etc.)
Let's begin by explaining some of the concepts of the application from an employee's point-of-view.
Shift
A shift is a scheduled block of time. A shift specifically contains the following info:
Who is working? (Each shift has one owner)
When are they working? (Start and end time)
Where are they working? (Each shift must be in a Location)
A shift basically gives ownership of a spot to an employee. They are responsible for working that shift. However, the program allows the option of the employee to file a sub request.
Report
A shift report is created once a employee(user) signs in, and finalized when the user signs out. It consists of timestamped line items. The first line item records the login IP address and the last logout IP address. Every 10-15 minutes or so the logged-in employee is supposed to add line items to the report.
Sub Request
When an employee files a sub request for a future scheduled shift, a request is emailed to the people that this employee inputs or everybody that is allowed to take that shift (a group email defined in the Location Group's settings). For example, if John (a senior tech) has filed a request for a sub for his shift in the 'technology troubleshooting office' location, the request is emailed to the address defined for the 'senior staff' Location Group. You would likely want to define this address to be a mailing list that sends to all the senior techs but not the junior techs.
Locations
Locations are places where you have employees working. Examples might be a front desk, troubleshooting office, or computing cluster. Locations could even be for non-physical locations, where you have a defined staff working, such for tasks. For example, if you have staff who work on tasks such as an on-duty courier, you could define this as a location.
Locations have the following properties:
Name
Short Name (Used in certain display contexts where name lengths should be shorter)
Report Email Address (The email address to which reports are sent to. More will be said on reports later on)
Priority (More on this in the later)
Max and Min Staffing Desired
Location Groups
Every Location must belong to exactly one location group. Location groups not only serve as logical groupings, but more importantly, are used for access control. Permissions for things like who can work where are set by location group. This may be explained best by exapmle:
Say you have two classes of employees, junior staff, and senior staff. You have four locations/positions where you regularly have staffing: a front desk, a courier, an assistant, and a supervisor. If you intend for the assistant and the supervisor shifts to only be staffed by senior staff, you would want to create two location groups. The first group would contain the 'front desk' and 'courier' locations, and the second group would contain the 'assistant' and 'supervisor' locations.
You could then define your groups such that only senior staff could sign up for, or work shifts in the 'assistant' and 'supervisor' locations.
Location groups have the following properties:
Name
Short Name
Maximum Shift Length
Minimum Shift Length
Sub Request Email Address
Time Slots
TODO: explains how time slots are used to allow shifts to be signup-able
h2. Implementation
We will use Ruby on Rails terminology here to make easier to explain. Each of the headings below corresponds to a model name and its controller name in plural. We try to stick to the RESTful approach. Note that for some controllers (eg subs controller) we do not need all 7 standard actions (index, new, create, edit, update, show, destroy) - try to keep the design simple by not including unnecessary actions and views. Sometimes additional actions are needed.
Shift
new: a shift sign-up page letting the user choose the start/end times and the location to work a shift in
- (admin only) allow selecting users
create: takes the submitted form and verify that request shift can be created. Checking the following
- is there a time slot open for that period
- is there any constraint? E.g. shift too short/too long, the user is exceed the number of shift hours allowed, there is another location that is more important to work for during that time, etc
- if a shift is legal, checks if it can be combined to another adjacent shift
edit (loc group admin only): allows an admin to change the details of a shift
update: similar to create with validation and saving
index: show all shifts, maybe restricted to a location or loc group or department
destroy (admin only): allows an admin to cancel a certain shift for another user
Sub
(sub routing should be nested in shift)
new: lets a user create a sub request
create: validates and saves.
destroy (loc group admin only): allows an admin to cancel a sub
*note that there is no editing of a sub. one should request an admin to delete it and create a new one
Report
(report routing should be nested in shift)
new: this is the sign in page, it shows the confirmation that the employee wants to log in
create: as usual, redirected from new
show: display all line items belonging to this report (line items have shift report id)
*there is no index/edit/update/destroy
Location
*only a loc group admin can manage locations
Loc Group
*only a department admin can manage loc groups
*before_validation hooks are used to create/update/destroy permissions associated to creating/updating/desdtroying a loc group (signup vs view-only vs admin)
Department/User
*only a superuser can manage departments and all users
*before_validation hooks are used to create/update/destroy an associated permission
User
*only superuser can manage all users or department admin can manage all users in that department
Role
new: let the admin create a new name and a selection of permissions associated to it
*only a department admin can manage roles
Permission
index: display all permissions pertaining to current_department
no other CRUD actions necessary because permissions are only created indirectly (when a new log group or new department is created)
Time Slot
TODO: A lot more is needed here.
h3. Admin stuff
We have the following before_filter methods that allow us to perform authorization at controllers' level
require_superuser
require_department_admin
require_loc_group_admin
h4. Routing
shallow routing is used but bear in mind form_for must be treated differently for new and edit. see code (eg view code for loc group) for more information
/departments
list all departments (require_superuser)
/departments/users (or /users)
list all users (require_superuser)
/departments/:department_id/*
(require_department_admin)
asterisk here can be lots of things nested under a department such as roles, users, loc_groups, etc
/:department_name/*
we can actually implement a check for this: if department_name is actually a real department name
we treat it just like /departments/:department_id/
thus we can have urls such as /stc/users or /itg/roles or /stc/shifts etc
/loc_groups/:loc_group_id/*
(require_loc_groug_admin)