# Requirement Document

<figure><img src="https://869823119-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpyWVnmtszkUSqMcP8ips%2Fuploads%2Fg7DgpkmEu61HP0wKXpxj%2Fdepositphotos_133252866-stock-illustration-requirements-lin-icon-removebg-preview.png?alt=media&#x26;token=0c68258b-43ef-4afe-bd82-67ab732be376" alt="" width="125"><figcaption></figcaption></figure>

### Table of Contents

1. Introduction
2. Users and Permissions
3. Functionality Specification
4. List of Tables

***

### Introduction

This document aims to describe the functionalities of the 9line Spaces booking system and specify the resources used to implement these functionalities. The subsequent sections will identify user types and their respective permissions within the system.

The 9line Spaces system is a space booking platform that allows users to schedule the use of spaces (such as pools, party halls, etc.) on specific dates and times, implementing a clean architecture (Clean Architecture) with Domain Driven Design (DDD).

***

### Users and Permissions

Permissions are structured as `resource_identifier:operation_identifier`. The `:` character means the concatenation of words. For more details, consult the "Access Control Document".

The table below specifies the supported resources and operations:

#### Table 1 - Nomenclature used in permissions

| **RESOURCES**       | **OPERATIONS**  |
| ------------------- | --------------- |
| `us = user`         | `c = create`    |
| `sp = space`        | `r = read`      |
| `ap = appointment`  | `ra = read all` |
| `rt = rating`       | `u = update`    |
| `rb = rbac`         | `d = delete`    |
| `nt = notification` | `ap = approve`  |
| `au = auth`         | `rj = reject`   |
| `hl = health`       | `lg = login`    |
| `rf = refresh`      | `ot = logout`   |

#### Table 2 - Admin user permissions

| Column 1 | Column 2 | Column 3 | Column 4 | Column 5 | Column 6 |
| -------- | -------- | -------- | -------- | -------- | -------- |
| `us:c`   | `us:r`   | `us:ra`  | `us:u`   | `us:d`   | `sp:c`   |
| `sp:r`   | `sp:ra`  | `sp:u`   | `sp:d`   | `ap:c`   | `ap:r`   |
| `ap:ra`  | `ap:u`   | `ap:d`   | `ap:ap`  | `ap:rj`  | `rt:c`   |
| `rt:r`   | `rt:ra`  | `rt:u`   | `rt:d`   | `rb:c`   | `rb:r`   |
| `rb:ra`  | `rb:u`   | `rb:d`   | `nt:c`   | `nt:r`   | `nt:ra`  |
| `nt:u`   | `nt:d`   | `au:lg`  | `au:rf`  | `au:ot`  | `hl:r`   |

#### Table 3 - Manager user permissions

| Column 1 | Column 2 | Column 3 | Column 4 | Column 5 | Column 6 |
| -------- | -------- | -------- | -------- | -------- | -------- |
| `us:r`   | `us:u`   | `sp:c`   | `sp:r`   | `sp:ra`  | `sp:u`   |
| `sp:d`   | `ap:c`   | `ap:r`   | `ap:ra`  | `ap:u`   | `ap:d`   |
| `ap:ap`  | `ap:rj`  | `rt:c`   | `rt:r`   | `rt:ra`  | `rt:u`   |
| `rt:d`   | `nt:r`   | `nt:ra`  | `au:lg`  | `au:rf`  | `au:ot`  |
| `hl:r`   |          |          |          |          |          |

#### Table 4 - User permissions

| Column 1 | Column 2 | Column 3 | Column 4 | Column 5 | Column 6 |
| -------- | -------- | -------- | -------- | -------- | -------- |
| `us:r`   | `us:u`   | `sp:r`   | `sp:ra`  | `ap:c`   | `ap:r`   |
| `ap:ra`  | `ap:u`   | `ap:d`   | `rt:c`   | `rt:r`   | `rt:ra`  |
| `rt:u`   | `rt:d`   | `nt:r`   | `nt:ra`  | `au:lg`  | `au:rf`  |
| `au:ot`  | `hl:r`   |          |          |          |          |

***

### Functionality Specification

#### RQ01 - User Authentication/Authorization

Only duly authorized users must be able to access the functionalities provided by the system. For this, the following are necessary:

**a. Authentication:** Access credential validation will be done through REST requests to the 9line Spaces system. The system uses JWT (JSON Web Tokens) for authentication.

**b. Authorization:** After the authentication process is completed, the user will receive a JWT token with configurable validity to perform operations. Only requests made with the token will be responded to.

**c. The password recovery process must be done through the notification system.**

#### RQ02 - Maintain User Profiles

The space booking system has a total of 3 types of users, namely: Administrators, Managers, and Users. Each user type has a set of permissions that identify which operations they can perform. For more information on permissions, consult the Users and Permissions section.

Therefore, it is necessary for the system to provide the functionality for the administrator user to manage the profiles of other users in the system.

**RQ02.1 - User Profile Management**

**A. The system will start with only one Admin type user. This user will be responsible for registering other user profiles;**

**B. The permissions of new users will be defined at the time of user profile creation by choosing the user profile type;**

**C. Equivalent to the User resource documented in swagger.**

#### Table 5 - User Profile resource specification

| Attr. Name          | Type     | Desc                                                                                                          | Examples                   |
| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------- | -------------------------- |
| \**id #*            | `string` | Unique identifier generated by the backend                                                                    | `clx1234567890abcdef`      |
| \*\*name \*\*\*     | `string` | User's name. Minimum 2, maximum 90 characters. Should not contain HTML tags                                   | `João Silva`               |
| \*\*email \*\*\*    | `string` | User's email. Must be unique in the system                                                                    | `joao@example.com`         |
| \*\*password \*\*\* | `string` | User's login password. Between 4 and 30 characters, must contain at least one uppercase letter and one number | `Joao*159`                 |
| **status**          | `enum`   | User status: ACTIVE, INACTIVE, BLOCKED                                                                        | `ACTIVE`                   |
| **role**            | `enum`   | User role: ADMIN, MANAGER, USER                                                                               | `USER`                     |
| **created\_at #**   | `string` | User creation date                                                                                            | `2024-01-01T09:15:42.000Z` |
| **updated\_at #**   | `string` | Last update date                                                                                              | `2024-01-01T21:45:51.264Z` |
| **deleted\_at**     | `string` | Deletion date (soft delete)                                                                                   | `null`                     |

#### RQ03 - Maintain Spaces

**RQ03.1 - Space Management**

**A. Equivalent to the Space resource documented in swagger;**

**B. Spaces are managed by Manager and Admin type users;**

**C. Each space has a responsible host, who is a system user.**

#### Table 6 - Space resource specification

| Attr. Name             | Type     | Desc                                       | Examples                                              |
| ---------------------- | -------- | ------------------------------------------ | ----------------------------------------------------- |
| \**id #*               | `string` | Unique identifier generated by the backend | `f95f0723-5fe9-4648-b2a6-c42c116fa8b3`                |
| \*\*title \*\*\*       | `string` | Space title                                | `Recanto Nossa Senhora de Fátima`                     |
| \*\*description \*\*\* | `string` | Detailed space description                 | `Space with large pool, barbecue area and green area` |
| **photos**             | `array`  | Array of space photo URLs                  | `["https://example.com/foto1.jpg"]`                   |
| \*\*hostId \*\*\*      | `string` | ID of the user responsible for the space   | `ec94e8c9-7370-4f4f-bea8-581375df31cf`                |
| **rules**              | `string` | Space usage rules                          | `No loud music after 10pm`                            |
| **averageRating**      | `number` | Space average rating                       | `4.5`                                                 |
| **created\_at #**      | `string` | Space creation date                        | `2024-01-01T09:15:42.000Z`                            |
| **updated\_at #**      | `string` | Last update date                           | `2024-01-01T21:45:51.264Z`                            |
| **deleted\_at**        | `string` | Deletion date (soft delete)                | `null`                                                |

#### Table 7 - Address resource specification

| Attr. Name         | Type     | Desc                                       | Examples                               |
| ------------------ | -------- | ------------------------------------------ | -------------------------------------- |
| \**id #*           | `string` | Unique identifier generated by the backend | `a1b2c3d4-e5f6-7890-abcd-ef1234567890` |
| \*\*street \*\*\*  | `string` | Street name                                | `Rua das Palmeiras`                    |
| \*\*number \*\*\*  | `string` | Address number                             | `123`                                  |
| \*\*city \*\*\*    | `string` | City                                       | `Campina Grande`                       |
| \*\*state \*\*\*   | `string` | State                                      | `PB`                                   |
| \*\*zipCode \*\*\* | `string` | ZIP code                                   | `58400-000`                            |

#### Table 8 - Geographic Location resource specification

| Attr. Name           | Type     | Desc                                       | Examples                               |
| -------------------- | -------- | ------------------------------------------ | -------------------------------------- |
| \**id #*             | `string` | Unique identifier generated by the backend | `b2c3d4e5-f6g7-8901-bcde-f23456789012` |
| \*\*latitude \*\*\*  | `number` | Location latitude                          | `-7.2307`                              |
| \*\*longitude \*\*\* | `number` | Location longitude                         | `-35.8811`                             |

#### RQ04 - Maintain Appointments

**RQ04.1 - Appointment Management**

**A. Equivalent to the Appointment resource documented in swagger;**

**B. Appointments are created by users and can be approved/rejected by managers;**

**C. Each appointment has change control based on user type.**

#### Table 9 - Appointment resource specification

| Attr. Name           | Type     | Desc                                            | Examples                               |
| -------------------- | -------- | ----------------------------------------------- | -------------------------------------- |
| \**id #*             | `string` | Unique identifier generated by the backend      | `a727ff76-a9f7-4461-baab-00980a272010` |
| \*\*userId \*\*\*    | `string` | ID of the user who created the appointment      | `e1f6dd2f-349a-4fb8-bdab-d01ef874c48e` |
| \*\*spaceId \*\*\*   | `string` | ID of the booked space                          | `9d9a0b99-ac06-457b-802c-b45a05157882` |
| \*\*date \*\*\*      | `string` | Appointment date                                | `2025-07-31T17:36:09.663Z`             |
| \*\*startTime \*\*\* | `string` | Start time                                      | `2025-07-31T09:00:00.663Z`             |
| \*\*endTime \*\*\*   | `string` | End time                                        | `2025-07-31T20:30:00.663Z`             |
| **status**           | `enum`   | Status: PENDING, CONFIRMED, CANCELLED, REJECTED | `PENDING`                              |
| **cancelReason**     | `string` | Cancellation reason                             | `Event cancelled`                      |
| **originalDate**     | `string` | Original date (for change control)              | `2025-07-31T17:36:09.663Z`             |
| **changeCount**      | `number` | Number of changes made                          | `0`                                    |
| **maxChanges**       | `number` | Maximum change limit                            | `3`                                    |
| **created\_at #**    | `string` | Creation date                                   | `2024-01-01T09:15:42.000Z`             |
| **updated\_at #**    | `string` | Last update date                                | `2024-01-01T21:45:51.264Z`             |

#### RQ05 - Maintain Ratings

**RQ05.1 - Rating Management**

**A. Equivalent to the Rating resource documented in swagger;**

**B. Ratings are created by users for spaces;**

**C. Each user can rate a space only once.**

#### Table 10 - Rating resource specification

| Attr. Name         | Type     | Desc                                       | Examples                               |
| ------------------ | -------- | ------------------------------------------ | -------------------------------------- |
| \**id #*           | `string` | Unique identifier generated by the backend | `4c9217e7-3aac-4f56-ad47-a70d46880489` |
| \*\*spaceId \*\*\* | `string` | ID of the rated space                      | `f95f0723-5fe9-4648-b2a6-c42c116fa8b3` |
| \*\*userId \*\*\*  | `string` | ID of the user who made the rating         | `c6a58a23-9c14-47b5-9ba4-d7b26da0866c` |
| \*\*score \*\*\*   | `number` | Rating from 1 to 5                         | `5`                                    |
| **comment**        | `string` | Rating comment                             | `Great space!`                         |
| **created\_at #**  | `string` | Creation date                              | `2024-01-01T09:15:42.000Z`             |
| **updated\_at #**  | `string` | Last update date                           | `2024-01-01T21:45:51.264Z`             |

#### RQ06 - RBAC System (Role-Based Access Control)

**RQ06.1 - Role and Permission Management**

**A. Equivalent to the RBAC resource documented in swagger;**

**B. The system allows assigning roles to users with expiration date;**

**C. Each role has a specific set of permissions.**

#### Table 11 - Role resource specification

| Attr. Name        | Type      | Desc                                        | Examples                               |
| ----------------- | --------- | ------------------------------------------- | -------------------------------------- |
| \**id #*          | `string`  | Unique identifier generated by the backend  | `bb82e254-8d8e-4f80-b7e7-25985fd2a27f` |
| \*\*name \*\*\*   | `string`  | Role name                                   | `ADMIN`                                |
| **description**   | `string`  | Role description                            | `System Administrator`                 |
| **level**         | `number`  | Hierarchy level: 0=USER, 1=MANAGER, 2=ADMIN | `2`                                    |
| **isSystem**      | `boolean` | Indicates if it's a system role             | `true`                                 |
| **created\_at #** | `string`  | Creation date                               | `2024-01-01T09:15:42.000Z`             |
| **updated\_at #** | `string`  | Last update date                            | `2024-01-01T21:45:51.264Z`             |

#### Table 12 - Permission resource specification

| Attr. Name          | Type     | Desc                                       | Examples                               |
| ------------------- | -------- | ------------------------------------------ | -------------------------------------- |
| \**id #*            | `string` | Unique identifier generated by the backend | `c3d4e5f6-g7h8-9012-cdef-345678901234` |
| \*\*name \*\*\*     | `string` | Permission name                            | `users:create`                         |
| **description**     | `string` | Permission description                     | `Create users`                         |
| \*\*resource \*\*\* | `string` | Permission resource                        | `users`                                |
| \*\*action \*\*\*   | `string` | Permission action                          | `create`                               |
| **created\_at #**   | `string` | Creation date                              | `2024-01-01T09:15:42.000Z`             |
| **updated\_at #**   | `string` | Last update date                           | `2024-01-01T21:45:51.264Z`             |

#### Table 13 - Role Assignment resource specification

| Attr. Name        | Type     | Desc                                       | Examples                               |
| ----------------- | -------- | ------------------------------------------ | -------------------------------------- |
| \**id #*          | `string` | Unique identifier generated by the backend | `d4e5f6g7-h8i9-0123-defg-456789012345` |
| \*\*userId \*\*\* | `string` | User ID                                    | `59195c9b-8efd-43f8-be21-8e6a1c1b898c` |
| \*\*roleId \*\*\* | `string` | Role ID                                    | `bb82e254-8d8e-4f80-b7e7-25985fd2a27f` |
| **assignedBy**    | `string` | ID of the user who assigned the role       | `59195c9b-8efd-43f8-be21-8e6a1c1b898c` |
| **assignedAt #**  | `string` | Assignment date                            | `2024-01-01T09:15:42.000Z`             |
| **expiresAt**     | `string` | Expiration date                            | `2025-12-31T23:59:59.000Z`             |

#### RQ07 - Notification System

**RQ07.1 - Notification Management**

**A. Equivalent to the Notification resource documented in swagger;**

**B. The system allows sending notifications via email, SMS and push;**

**C. Notifications use configurable templates.**

#### Table 14 - Notification Template resource specification

| Attr. Name        | Type      | Desc                                       | Examples                               |
| ----------------- | --------- | ------------------------------------------ | -------------------------------------- |
| \**id #*          | `string`  | Unique identifier generated by the backend | `15f412b5-a8a4-48cb-98c7-20b5a35e94e1` |
| \*\*name \*\*\*   | `string`  | Template name                              | `welcome-email`                        |
| \*\*type \*\*\*   | `string`  | Type: EMAIL, SMS, PUSH                     | `EMAIL`                                |
| **subject**       | `string`  | Subject (for emails)                       | `Welcome to 9line Spaces!`             |
| \*\*body \*\*\*   | `string`  | Message body                               | `Hello {{userName}}, welcome!`         |
| **variables**     | `array`   | Variables available in the template        | `["userName", "userEmail"]`            |
| **isActive**      | `boolean` | Indicates if the template is active        | `true`                                 |
| **created\_at #** | `string`  | Creation date                              | `2024-01-01T09:15:42.000Z`             |
| **updated\_at #** | `string`  | Last update date                           | `2024-01-01T21:45:51.264Z`             |

#### Table 15 - Notification resource specification

| Attr. Name            | Type     | Desc                                             | Examples                               |
| --------------------- | -------- | ------------------------------------------------ | -------------------------------------- |
| \**id #*              | `string` | Unique identifier generated by the backend       | `clx1234567890abcdef`                  |
| \*\*userId \*\*\*     | `string` | ID of the user who will receive the notification | `8f4aa90f-0564-465a-a836-693f15d5fd31` |
| \*\*type \*\*\*       | `string` | Type: EMAIL, SMS, PUSH                           | `EMAIL`                                |
| \*\*templateId \*\*\* | `string` | ID of the template used                          | `15f412b5-a8a4-48cb-98c7-20b5a35e94e1` |
| **status**            | `string` | Status: PENDING, SENT, FAILED                    | `SENT`                                 |
| **payload**           | `object` | Data to fill the template                        | `{"userName": "João Silva"}`           |
| **error**             | `string` | Error in case of failure                         | `null`                                 |
| **sentAt**            | `string` | Sending date                                     | `2024-01-01T12:00:00Z`                 |
| **created\_at #**     | `string` | Creation date                                    | `2024-01-01T09:15:42.000Z`             |
| **updated\_at #**     | `string` | Last update date                                 | `2024-01-01T21:45:51.264Z`             |

#### RQ08 - Health Check

**RQ08.1 - System Monitoring**

**A. Equivalent to the Health resource documented in swagger;**

**B. The system provides endpoints to check application status;**

**C. Includes database and Redis connectivity verification.**

#### Table 16 - Health Check resource specification

| Attr. Name      | Type     | Desc                    | Examples               |
| --------------- | -------- | ----------------------- | ---------------------- |
| **status**      | `string` | Application status      | `ok`                   |
| **timestamp**   | `string` | Check timestamp         | `2024-01-01T12:00:00Z` |
| **uptime**      | `number` | Uptime in seconds       | `3600`                 |
| **environment** | `string` | Application environment | `development`          |

***

### List of Tables

* **Table 1 - Nomenclature used in permissions.**
* **Table 2 - Admin user permissions.**
* **Table 3 - Manager user permissions.**
* **Table 4 - User permissions.**
* **Table 5 - User Profile resource specification.**
* **Table 6 - Space resource specification.**
* **Table 7 - Address resource specification.**
* **Table 8 - Geographic Location resource specification.**
* **Table 9 - Appointment resource specification.**
* **Table 10 - Rating resource specification.**
* **Table 11 - Role resource specification.**
* **Table 12 - Permission resource specification.**
* **Table 13 - Role Assignment resource specification.**
* **Table 14 - Notification Template resource specification.**
* **Table 15 - Notification resource specification.**
* **Table 16 - Health Check resource specification.**

***

**Version**: 1.0.0\
**Last Update**: July 2025\
**Author**: Antonio Silva\
**Email**: <contato@antoniobsilva.com.br>
