Contents
Assignment 1 1
Topic 1
Timeline 2
Gym Usage Admin System 2
Background 2
Scope 2
Your Recognition of Completing this Topic 2
Functional Requirements 3
Use Case Names – User Stories 3
Acceptance Criteria of User Stories 3
Data Glossary 4
CSV File Format 5
Student Import File 5
Staff Import File 5
Quality Requirements 5
Capacity 5
Response time 5
Distributed Locations 5
Robustness 5
Technologies/Techniques Helpful to Your Assignment 6
Building a line of comma separated values from a list/tuple 6
Processing CSV files 6
Performance Testing with Locust 6
Unit Testing ImportNew 6
models Class 7
Assignment 1
Topic
An assignment topic of building a gym usage administration system will be presented next. Oliver will perform some requirements analysis as an example of how you could start a small project. In case you do not like the topic, you are free to propose another assignment topic. But then, you will have to perform requirements analysis on your proposed assignment topic.
Whether you choose the gym usage administration system or propse your own topic, you can continue assignment 2 and final project of this course based on the same topic or a new topic. In all cases, you cannot use one piece of work to fulfil the requirements of multiple courses. Doing so without acknowledgement is considered plagiarism. For example, you cannot write a program submitted as a part of the FYP course and COMP S363F.
Timeline
If you choose the gym usage admin system, the information in this document could be sufficient for you to start coding. If you choose anoher topic, please observe the following timeline.
Assignment related activities and completion date
Asgn 1
Asgn 2
1. Assignment topic
Feb-28
April-4
2. User stories
March-7
April-11
3. Acceptance criteria
March-14
April-18
4. Tested code and documentation (screens & refection)
March-21
April-25
Gym Usage Admin System
Background
OUHK has just opened a new fitness gym on 9/F of the new IOH Building. There are 3 categories of gym users for the gym: students, employees and retirees. They can earn the privilege to use the gym by completing an in-house/government-run training course. There may be other qualification/evidence that Student Affairs Office (SAO) would accept as sufficient knowledge to use the fitness equipment safely.
Currently, SAO issues a gym card to each eligible user. When users come to the gym, they need to give their student/employee/retiree card and gym card to the entrance staff. After finishing the workout, users will get their cards back. Usage of the gym is on first-come-first-served. No booking is required. There is a limit to the number of users allowed in the gym at any one time. Under the current risk of COVID-19, the maximum number of users is set quite low at 12. The number may change in the future or from time to time.
The current arrangement has overhead in the making/collection/distribution of the gym cards. From the user’s point of view, carrying an additional card is a nuisance. Lost cards and their replacements are additional chore for the administrative staff.
If gym cards carry expiry date, the making and distribution of gym cards must repeat every year. If gym cards do not carry expiry date, there will be a loophole for students to continue using the gym after quitting or graduation because they may hold on to their student cards and gym cards.
Scope
You will create a system using Python and Django for staff to manage the procedures of users entering and leaving the gym. The management would like to have gym usage summary reports to make future decisions to alter/enhance the opening hours and services of the gym.
Your Recognition of Completing this Topic
Oliver will select one or two best completed assignment for SAO to see. If SAO likes your program, they may want to use it. Of course, they will get your permission to use your program. SAO and/or Oliver will present you a small gift as a token of appreciation. You can mention it in your CV to help you land a programming position after graduation.
Functional Requirements
Below is not my initial version of the requirements. For example, I initially had a user story to import and export CSV file for database updates. As I wrote the acceptance criteria for it, I realize that it is probably too big. The import and export operations also have different priorities. Therefore, I only keep the higher priority import user story for assignment 1.
Use Case Names – User Stories
User stories are often identified with story IDs. But when we add/delete/change user stories, we would have to renumber user stories. To eliminate the renumbering chore, we are giving each user story a use case name which is bolded below.
• ImportNew – As a backoffice staff, I want to import new gym users in a CSV file so that user database updates can be completed relatively quickly.
• ImportReplace – As a backoffice staff, I want to import all gym users in a CSV file so that I can start with a clean user database.
• SetMaxUser – As a backoffice staff, I want to set the maximum number of users so that the gym will not be too crowded.
• BlockTime – As a backoffice staff, I want to set a time period so that users are not allowed to use the gym.
• AdmitUser – As a gym admin staff, I want to admit only legitimate gym users so that other attempts to enter the gym will be denied.
• LeaveGym – As a gym admin staff, I want to record the leaving legitimate gym user so that in case a waiting user can be admitted.
Acceptance Criteria of User Stories
Use Case
Priority
Acceptance Criteria
ImportNew
H
• The new users will be added to the database only if there are no invalid data in the input file. (This is an all-or-nothing operation.)
• The input file will be renamed to show the date and time of the successful operation.
• If there are invalid data in the input file, a result file will be created showing all the invalid input data, their line number and reasons of rejection.
• The system will try to find new student users in student.new file in the data directory of this application.
• The system will try to find new employee users in employee.new file in the data directory of this application.
Future enhancement
• Importing new retiree users.
ImportRemove
H
• The users listed in the file will be removed from the database. (This is an all-or-nothing operation.)
• The input file will be renamed to show the date and time of the successful operation.
• If there are invalid data in the input file, a result file will be created showing all the invalid input data, their line number and reasons of rejection.
• The system will try to find student users to remove in student.rem file in the data directory of this application.
• The system will try to find employee users to remove in employee.rem file in the data directory of this application.
Future enhancement
• Removing retiree users.
SetMaxUsers
H
• I can set the maximum number of gym users allowed.
• I can choose effective now or a future datetime.
BlockTime
M
AdmitUser
H
• I can search for a legitimate gym user by student/employee ID or name.
• I can admit a legitimate gym user.
• I can admit user using one or more of the following information: student/employee ID, name and remarks regardless he/she is a legitimate gym user.
• Usage record is created with Admission time.
• A user arriving when the gym is full may be placed on a waiting list which is first-in-first-out (FIFO).
• I can admit/remove the first user in the waiting list.
LeaveGym
H
• I can record the departure of a user currently using the gym.
• Usage record is created with Admission time.
• I will be notified if there is someone on the admission waiting list.
Acceptance criterion 3 in AdmitUser allows SAO to organize special activites that does not require participants to have any prior training.
Data Glossary
The following data have been revised to have separate tables for student users and employee users.
• Student ID – 8 decimal digits
• Employee ID – 6 decimal digits
• Name – 32 alphnumeric character
• Student gym usage – Student ID, start datetime, end datetime
• Employee gym usage – Employee ID, start datetime, end datetime
• Student User – student ID, Name
• Employee User – employee ID, Name
• Registered User – If a user has received inhouse training offered by SAO to use fitness equipment or provided equivalent proof of relevant knowledge to SAO, the user is registered. Students, employees and retirees are illigible to register. The registration takes place prior to the user’s visit to use the gym. The time required of registration could be hours or days depending on the internal operation of SAO.
• Special Events – Normally the gym is open only for registered users. But SAO may book certain time period for special events so that non-registered users or guests may use the gym. Examples include training/ gym experience courses.
• Block time – start datetime, end datetime, recurrence (no/daily/weekly/monthly/yearly), event type
• Reasons of input data rejection – ID too long, ID too short, ID contains invalid character(s), user already exists on the system (for ImportNew), user does not exist (for ImportRemove)
We have considered the data of “member since” to hold the datetime of when the user first became a member but this is probably not necessary. We have also considered replacing a single name field with given names and family name. We don’t think it adds values. In both cases, we go for the simplest solutions.
CSV File Format
We think inputting new users to the system can be more efficiently accomplished by means of comma separated values (CSV) in a text file than having someone typing the user information on a UI. We shall use the first column to show the student ID or employee ID in the CSV file. The length of IDs immediately tells us whether the file is holding student gym users or employee gym users. Not shown, we have also considered the option of putting students and employees in the same file. But this would require an additional column to indicate the user type thus increasing the data input effort.
Student Import File
12345678, Yiu Man Yuen
87654321, Wing Hong Chu
Staff Import File
123456, Oliver Au
654321, Vanessa Ng
Quality Requirements
Capacity
At present, we may only have a few hundreds registered gym users. We want the system to be able to hold up to 2,500 registered users.
Response time
The operations of users to enter and leave the gym for regular usage should be quick. The entering and leaving of users on special event could be slightly longer but should still be efficient.
The operations of adding/updating registered users do not happen frequently and there is no gym user waiting at the entrance. The response time of adding/updating can takes up to 10 to 15 minutes so long as the chance of error that requires retry is low.
Distributed Locations
The admin staff may prepare the user registration files in the office not at the gym counter.
Robustness
The gym admin staff should be able to record entering and leaving of gym users even when the network is down. It may be advantageous for the system and its database to locate at the gym counter. A printed registered user list may be used to check whether someone has been registered.
Technologies/Techniques Helpful to Your Assignment
Building a line of comma separated values from a list/tuple
Processing CSV files
https://realpython.com/python-csv/ has sample code and explanation for the followings.
• Format of a csv files (column names and data)
• Reading CSV files; each row goes to a list
• Reading CSV files; each row goes to a dictionary
• Writing CSV files one row at a time
https://docs.python.org/3/library/csv.html has the official Python documentation on CSV.
Performance Testing with Locust
COMP S362F has covered cProfile for analysis of Python programs. You can refer to the lecture slide or https://therenegadecoder.com/code/how-to-performance-test-python-code/. However, cProfile is more useful when your objective is to identify the part of the program to optimize for most performance improvement. But it is not best to tell you how many transactions the system can perform in a given time period.
Selenium has bee around for over 10 years. It is a GUI-based test automation tool that allows you to record an interaction with a GUI. You can later play back the recorded sequence often after you have aded some code to perform some checking. But GUI-based testing is fragile and will break with the smallest update to the GUI.
Locust seems to be enjoying inceased popularity for load testing. It is less than 5 year old written in Python. https://medium.com/@kundan3034/write-your-first-performance-load-test-in-python-e8e2132ef775 introduces Locust. We shall try to find time to cover performance testing in this course.
JMeter is another popular testing tool over 20 years old written in Java. But we will not cover it in this course. Of course, you are free to use it if you want.
Unit Testing ImportNew
Even we have covered unit testing in COMP S362F but half the class did not apply it well in the course end project. It is not enough to write code to run something and use your eyes to visually look for correct return values. When you have many things to check, you may overlook an error from the visual checking. In practice, there may be several hundreds or even thousands of test cases.
Suppose you want to test importing a new user Yiu Man Yuen using the ImportNew operation. Also assume Wing Hon CHU is already in database before the ImportNew operation. Unit testing steps:
• Query database to confirm Win Hon CHU is on gym user table.
• Query database to confirm Yiu Man Yuen is NOT on gym user table.
• Check number of users in gym user table. Store it in variable N1.
• Run ImportNew with the file that contain Yiu Man Yuen. Assume the input file has 23 new users.
• Query database to confirm Win Hon CHU is still on gym user table as before.
• Query database to confirm Yiu Man Yuen is NOW on gym user table.
• Check number of users in gym user table. Store it in variable N2.
• Make sure N2 = N1 + 23
The above steps give us confidence that existing users are not affected by the ImportNew. In addition to checing one new user, you could check three new users, e.g. the first one, the middle one and the last one in the input file. You can also check adding new employee users.
models Class
We have discussed one-to-many and many-to-many database relationships using the examples in https://docs.djangoproject.com/en/3.0/topics/db/models/. We covered both many-to-many relationship with/without additional details in the relationship. For example, Oliver belonging to running club and dragon boat club is many-to-many because other people can belong to those clubs too. Sometimes we just need to know the relationship. Other times we want totrack additional information like when did the person join the club.