Software Requirements Specification (SRS) for Milacci

--- title: Software Requirements Specification (SRS) for Milacci tags: milacci, ackee --- # Software Requirements Specification for `Milacci` ## System roles | Role | Objective| |-|-| |Chatbot|User who can see list of users and their detail with hour rates.| |User|User with valid Google account who can primary create invoices and check self details such as hour rates, time entries, notifications and invoice history.| |Team leader|User with same rights as employee but moreover can manage their team members.| |Admin|System administrator who can manage whole system and use all features.| ## Product functions ### `Authentication` - Users (aka active users) are authenticated via Google login - Suspended users and users without local account cannot log into app - Deleted user cannot log into app, Google account and Redmine #### Login - Users can login with their Ackee email (`{name}.{surname}@ackee.cz`). - `Chatbot` users can login with their email & password combination ### `User management` #### User registration - User fills in the following information - Email - Contact email - Password - User state - Sumbitting the data - The user role will be set to `chatbot` #### Creating the new user - User fills in the following information about the user he wants to add - User's name - required - User's surname - required - Contact email - required - Work type (agreement, registration number or employment contract) - required - Start date - required - Registration number - State which says user is or is not internal - User's phone number - Job title (backend, frontend, etc.) - each user can be placed to one of these groups only, required - System role - User's team leader - required - Hourly capacity in format number of hours per month - User's date of birth - Notes - An email address for the new user is created in format `{name}.{surname}@ackee.cz` - Submitting the data - Creates a remote user account at Google, using the new email - Creates a remote user account at Redmine, using the new email - Creates a local user account - Adds the new email as a subscriber for `ackee.zip` Mailchimp list - Sends a [registration email](#Registration-email) - Requires following role: Admin #### User update - Admin can update each field of each user - User can update following fields - Birth date - Registration number (IČO) - TODO: vyresit s Katou User with role `admin` can update each field of each user. User with role `user` can update only own birth date and registration number (IČO). #### User list User with role `admin` can list all users. User with role `teamLeader` can see users from his / her team only. User with role `user` cannot list users. - Admin can list all users with their hour rates - Team leader can list users with [hour rates](#Hour-rates-management) from their team with hour rates - User cannot list users #### User detail User with role `admin` can see all fields of each users. User with role `user` can see his / her own detail but only start date (TODO: zjistit od Kati). `teamLeader` can see detail of users from his / her team such as email, phone number, work type, hour rates, next vacation. - Admin can see all fields of each users - User can see following fields - TODO: vyresit s Katou - Start date - Hour rates - Team leader can see detail of users from their team with following fields - Email - Phone number - Work type - Hour rates - Next vacation #### Google groups synchronization - App can manage Ackee's Google groups - Users are moved to following Google groups depending on their internal state - Internal (milacci@ackee.cz) for internal users - External (ackee-externisti@ackee.cz) for external users - Users are moved to following Google groups depending on their job title - Backend - iOS - Android - Frontend - Marketing - Design - Tester - DevOps - Other teams dont have Google groups - Sync process starts automatically each day - It takes all active users - It synces the user groups in GSuite - One way synchronization (the cron only adding users to the groups) #### Registration email - Registration email is sent automatically after [user is created](#User-registration) - Email is sent to user's contact email - Email contains following information - Google credentials - Username - Password - must be changed after first login - Login URL to the app - Link to [První den v Ackee](https://wiki.ack.ee/doku.php?id=navody:prvni_den_v_ackee) page. ### `Hour rates management` Allows users to manage user's hour rates. Hour rate is user's salary per hour. #### Hour rate create - User fills in following information - Since date - indicates from which date is hour rate active - Value - Submitting the data - Creates hour rate - Deactivates previous hour rate from specified date (`since date`) - There should be only one active hour rate - Requires roles: `admin` #### Hour rate list - `User` can list all own hour rates with following information - Since date - Value - Percentage increase - against previous hour rate - `Valid to` date - `Team leader` can list all own hour rates and all hour rates of their team members with members - `Admin` can list all hour rates with their users #### Hour rate update Use this only if it is necessary. `Delete` and `create` process is much better because of history of hour rates. - User can fill following information - Since date - previous hour rate would not be deactivated / updated from this new date (need to do it manually) - Value - percentage of increase would not be recalculated - Percentage of increase - `Valid to` date - Requires roles: `admin` #### Hour rate delete - Use this for example if user filled bad data - Valid date of previous hour rate would not be reverted - Recommended way after deleting the hour rate is create the new one - Requires roles: `admin` #### Hour rate detail - User can see following information - `Valid to` date - Since date - Percentage of increase - against previous hour rate - Value - User - hour rate owner - Team leader can see own hour rates and hour rates of users from his / her team - Admin can see all hour rates #### Hour rate stats - User can read hour rate stats within the whole company - There is average of increase the hour rate value which is calculated each month - Requires roles: `admin` ### `Invoices` Allows users manage invoices. Also provides informations about time entries which are synced from Redmine. #### Invoice create - Current month invoices are automatically created each hour for each user - If invoice in current month does not exist the new invoice is created - Invoice is set to not issued state #### Manual create - User fills in the following information about the invoice he / she wants to create - Items of invoice - Title with work description - Quantity - number of hours user worked - Hour rate - VAT rate - Period of issue - Requires roles: `admin` #### Invoice update - User can upload PDF file with original invoice - Submitting the data - Check if invoice is first for current month - If not --> throws an error (user can have only one invoice per month) - Synces users time entries - Finds all time entries for specified period of issue - Validation - Checks invoice for specified period doesnt exist - Counts real value of invoice (sum of found time entries and user's hour rate which is related to time entry period) - Pairs time entries with new invoice - Set invoice state to waiting - If file is deleted the invoice state is set to not issued - If the current state is equal to waiting #### Invoices list - User with role admin can list all invoices - Another users can list only own invoices - User can see following information - PDF file name - Total value - Invoice state - Number of spent hours #### Invoice detail - User with role admin can see detail of each invoice - Another users can see only own invoices - Synces users time entries - Finds all time entries for specified period of issue - Counts real value of invoice (sum of found time entries and user's hour rate which is related to time entry period) - Pairs time entries with new invoice - User can see following information - PDF invoice link - valid for 1 hour - PDF file name - Invoice state Number of spent hours - User detail - the invoice owner #### Time entry list - User can list own time entries - User with role `admin` is allowed to list all time entries - User can see following information - Time where the time entry was spent - Spent hours - Total value - salary - Description - Tracking system project #### Tracking system project synchronization - Tracking system projects are synced automatically each hour - It takes all tracking system projects - Map tracking system projects to projects in time entries - Add project name if projects are successfully mapped #### DPP invoice creation DPP is special type of invoice. Only users who have work type equal to `agreement` can create this type of invoice. If invoice value is bigger than 10.000 CZK warning notification is created before form submit. After submutting form is time entries validated and XLS doc with all time entries for current month, hour rates and spent hours is created. Generated XLS file includes header with year and month in `YYYY-MM` format and user's name and surname, time entry description, spent hours, date of spending hours and creation date in the end of file. If time entry has not description then is description generated randomly from existing descriptions of other time entries. - User fills in followed informations - Period of issue - If invoice value is bigger then 10.000 CZK user is notified about it before submitting the form - Submitting the data - Synces user's time entries - Finds time entries for specified period - Checks invoice for specified period doesnt exist - Creates local invoice - Pairs time entries with new invoice - Creates XLS document with following information - Header with period of issue and user's name and surname - Time entry - Work description (if its empty then randomly choose description from time entries with description) - Number of spent hours - Date of spending hours - Date of invoice creation - Uploads XLS document to Google bucket under `/invoices/{userId}` folder #### Invoice download User with role `admin` can download compressed zip file with filtered or all uploaded invoices. ### `Working days` User with role `admin` is allowed to check how many hours in month each employee worked and check if they fulfilled their contract. This module takes days in month, filter weekends and public holidays. This value is compared to employee's time entries. ### `Notifications` Allows users to see their notifications. Each notification type has base settings which contains: - `email notification` - notification will be sent also as email - Values: `yes` or `no` - Usage: if is needed to highlight importance of notification - `additional users` - these users also receives created user's notification - Values: list of emails - Usage: if is needed to notify department or another users (for example: HR, finance department, bosses) - `days in advance` - notification will be created before action or event is happening - Values: number of days - Usage: if is needed to prepare for action or event (for example: buy gifts for users with birthday) - `notify team leader` - team leader will be notified about action / event - Values: `yes` or `no` - Usage: if is needed to user's team leader know about action / event This settings can be changed on backend side for each notification type. #### Types ##### Birthday *Default settings* ``` email notification = yes, additional users = katerina.kebzova@ackee.cz, days in advance = 21, notify team leader = no, ``` - Birthday notification is created before user's birthday - Finds users with set birth date - Checks if users will have birthday - Creates notification which is shown in app - Sends email notification Three weeks before user's birthday (need to set birthday in his / her profile) is created notification which is shown to HR. *Notification texts* - Title: `Miláček bude mít narozeniny!` - Body: `Miláček {name} {surname} bude mít narozeniny (DD.MM.YYYY), bude mu X let!` *Email texts* - Title: `Miláček bude mít narozeniny!` - Body: `Miláček {name} {surname} bude mít narozeniny (DD.MM.YYYY), bude mu X let!` ##### Invoice *Default settings* ``` email notification = yes, additional users = katerina.kebzova@ackee.cz, days in advance = 21, notify team leader = no, ``` - Invoice notification is created each last day in month at 11 p.m. - Finds users whose did not create invoice for current month - Creates notification which is shown in app - Sends email notification - Email for user is sent to Ackee email Last day in month at 11 p.m. will be created notification which notify user about creating the invoice if is not already created. Notification is sent to HR and user also as email. *Notification texts* - Title: `TODO` - not implemented yet - Body: `TODO` - not implemented yet *Email texts* - Title: `TODO` - not implemented yet - Body: `TODO` - not implemented yet ##### Three month review *Default settings* ``` email notification = yes, additional users = katerina.kebzova@ackee.cz, days in advance = 21, notify team leader = yes, ``` - Three month review notification is created - Finds users whose are 3 months after boarding in company - Creates notification which is shown in app - Sends email notification - Email for user is sent to Ackee email Three weeks before three month boarding is sent notification (also email notification) to team leader, HR and user which contains. *Notification texts - for `user`* - Title: `Hodnocení po zkušebce` - Body: `Blíží se hodnocení po zkušebce, nastoupil/a jsi k nám DD.MM.YYYY, kontaktuj svého team leadera a HR!` *Notification texts - for `additional users` & `team leader`* - Title: `Hodnocení po zkušebce` - Body: `Miláček X Y bude mít hodnocení po zkušebce, nastoupil k nám DD.MM.YYYY!` *Email texts - for `user`* - Title: `Hodnocení po zkušebce` - Body: `Blíží se hodnocení po zkušebce, nastoupil/a jsi k nám DD.MM.YYYY, kontaktuj svého team leadera a HR!` *Email texts - for `additional users` & `team leader`* - Title: `Hodnocení po zkušebce` - Body: `Miláček X Y bude mít hodnocení po zkušebce, nastoupil k nám DD.MM.YYYY!` ##### Ackeeversary *Default settings* ``` ackeeversary form url = https://forms.gle/QWDmBRvvMSvBy7HZ7, email notification = yes, additional users = katerina.kebzova@ackee.cz, martin.pulpitel@ackee.cz, days in advance = 21, notify team leader = yes, ``` - Ackeeversary notification is created each year after user's boarding - Finds users with start date - Checks if it is user's next year in company - Creates notification which is shown in app - Sends email notification - Email for user contains link to [Ackeeversary form](https://forms.gle/QWDmBRvvMSvBy7HZ7) and is sent to user's Ackee email Three weeks before year boarding is sent notification (also email notification) to team leader, HR, Martin Půlpitel and user which contains [link to Ackeeversary form](https://forms.gle/QWDmBRvvMSvBy7HZ7). *Notification texts - for `user`* - Title: `Ackeeversary` - Body: `Blíží se roční hodnocení, nastoupil/a si k nám DD.MM.YYYY vyplň prosím formulář, který jsme ti poslali na mail a dej vědět HR!` *Notification texts - for `additional users` & `team leader`* - Title: `Ackeeversary` - Body: `Miláček X Y bude mít roční hodnocení, nastoupil k nám DD.MM.YYYY!` *Email texts - for `user`* - Title: `Ackeeversary` - Body: `Blíží se roční hodnocení, nastoupil/a si k nám DD.MM.YYYY vyplň prosím formulář, který jsme ti poslali na mail a dej vědět HR!` *Email texts - for `additional users` & `team leader`* - Title: `Ackeeversary` - Body: `Miláček X Y bude mít roční hodnocení, nastoupil k nám DD.MM.YYYY!` #### Notification list User with role `admin` can list all notifications, other users can list own notifications only. #### Notification updation User with role `admin` can update each notification, other users can mark their notification as read or resolved. #### Notification deletion Notifications are deleted each year at 1. 1. 00:00 via background process which removes all notifications from past year. Notification can be also deleted by user with role `admin`. #### Notification creation Notifications are created via background process every day. Process create all defined types for all active users which meets conditions specified in `Types` chapter. Notification can be also created by user with role `admin`. #### Notification detail Each user can read own notification. User with role `admin` can read all notifications. ## Documentation * [Milacci API docs](https://console.cloud.google.com/storage/browser/aglio-docs.ack.ee/milacci2-api/development/?project=infrastruktura-1307) * [Wireframes](https://projects.invisionapp.com/d/main#/projects/prototypes/17788608) * [Design](https://projects.invisionapp.com/d/main#/projects/prototypes/18116264) * [FE dev](milacci-frontend-development.ack.ee)

Syntax	Example	Reference
# Header	Header	基本排版
- Unordered List	Unordered List
1. Ordered List	Ordered List
- [ ] Todo List	Todo List
> Blockquote	Blockquote
Bold font	Bold font
Italics font	Italics font
~~Strikethrough~~	~~Strikethrough~~
19^th^	19^th
H~2~O	H₂O
++Inserted text++	Inserted text
==Marked text==	Marked text
[link text](https:// "title")	Link
![image alt](https:// "title")	Image
`Code`	`Code`	在筆記中貼入程式碼
```javascript var i = 0; ```	`var i = 0;`
:smile:		Emoji list
{%youtube youtube_id %}	Externals
$L^aT_eX$	L^aT_eX
:::info This is a alert area. :::	This is a alert area.