feat(tenders): add Tender Management module (SRS, backend, frontend)
- SRS document: docs/SRS_TENDER_MANAGEMENT.md - Prisma: Tender, TenderDirective models; Deal.sourceTenderId; Attachment.tenderId/tenderDirectiveId - Backend: tenders module (CRUD, duplicate check, directives, notifications, file upload, convert-to-deal) - Frontend: tenders list, detail, create/edit forms, directives, convert to deal, i18n (en/ar), dashboard card - Seed: tenders permissions for admin and sales positions - Auth: admin.service findFirst for email check (Prisma compatibility) Made-with: Cursor
This commit is contained in:
Talal Sharabi
259
docs/SRS_TENDER_MANAGEMENT.md
Normal file
259
docs/SRS_TENDER_MANAGEMENT.md
Normal file
@@ -0,0 +1,259 @@
|
||||
# Software Requirements Specification: Tender Management Module
|
||||
# مواصفات متطلبات البرمجيات: موديول إدارة المناقصات
|
||||
|
||||
**Version:** 1.0
|
||||
**Module name (EN):** Tender Management
|
||||
**Module name (AR):** نظام إدارة المناقصات
|
||||
|
||||
---
|
||||
|
||||
## 1. Introduction | مقدمة
|
||||
|
||||
### 1.1 Purpose | الهدف من الموديول
|
||||
|
||||
The Tender Management Module enables the sales team to register all tenders available in the market and track them in an organised way from the moment the announcement is discovered until the appropriate management decision is made. Supported decisions include:
|
||||
|
||||
- Purchase of terms booklet (شراء دفتر الشروط) or securing the terms booklet (تأمين دفتر الشروط)
|
||||
- Visiting the issuing body (زيارة الجهة الطارحة)
|
||||
- Getting to know the relevant committee (التعرف على اللجنة المختصة)
|
||||
- Preparing to enter the tender (الاستعداد للدخول في المناقصة)
|
||||
|
||||
**Scope boundary:** The module’s role ends at this stage. After the initial follow-up and the decision to proceed, the tender is **converted to an Opportunity (Deal)** in the CRM module so the engineering team can study the project.
|
||||
|
||||
---
|
||||
|
||||
## 2. Integration with Other Systems | التكامل مع الأنظمة الأخرى
|
||||
|
||||
### 2.1 HR Module | موديول الموارد البشرية
|
||||
|
||||
The HR module is used for:
|
||||
|
||||
- **User definition:** Users are linked to employees.
|
||||
- **Permissions:** Access control and role-based permissions.
|
||||
- **Assignee selection:** When issuing directives, the responsible employee is chosen from the HR employee list.
|
||||
|
||||
### 2.2 CRM Module | موديول CRM
|
||||
|
||||
After the initial follow-up phase, a tender can be **converted to an Opportunity (Deal)** in CRM. The Deal is then handled by the engineering team. In this system, “Opportunity” is implemented as the **Deal** entity (no separate Opportunity model).
|
||||
|
||||
---
|
||||
|
||||
## 3. Users and Permissions | المستخدمون والصلاحيات
|
||||
|
||||
### 3.1 Sales Team | فريق المبيعات
|
||||
|
||||
**Permissions:**
|
||||
|
||||
- Add new tenders
|
||||
- Edit tender data
|
||||
- Follow up on tenders
|
||||
- Execute assigned tasks
|
||||
- Upload documents
|
||||
- Add notes
|
||||
|
||||
### 3.2 Sales Manager | مدير المبيعات
|
||||
|
||||
**Permissions:**
|
||||
|
||||
- View all tenders
|
||||
- Issue directives
|
||||
- Assign employees to tasks
|
||||
- Add notes
|
||||
- Monitor execution
|
||||
|
||||
### 3.3 Executive Manager | المدير التنفيذي
|
||||
|
||||
**Permissions:**
|
||||
|
||||
- Issue directives
|
||||
- Assign employees
|
||||
- Monitor tenders
|
||||
- View all documents and notes
|
||||
|
||||
**Implementation note:** The system uses a `tenders` module with resources (e.g. `tenders`, `directives`) and actions (`read`, `create`, `update`, `delete`). Roles (Sales, Sales Manager, Executive) are configured in Admin with the appropriate permissions for this module.
|
||||
|
||||
---
|
||||
|
||||
## 4. Creating a New Tender | إنشاء مناقصة جديدة
|
||||
|
||||
Sales registers tenders discovered in the market.
|
||||
|
||||
### 4.1 Basic Tender Data | البيانات الأساسية للمناقصة
|
||||
|
||||
| Field (EN) | Field (AR) | Type | Required | Notes |
|
||||
|--------------------|----------------|--------|----------|--------|
|
||||
| Issuing body name | اسم الجهة الطارحة | Text | Yes | |
|
||||
| Tender title | عنوان المناقصة | Text | Yes | |
|
||||
| Tender number | رقم المناقصة | Text | Yes | **Unique** |
|
||||
| Terms booklet value| قيمة دفتر الشروط | Decimal| Yes | |
|
||||
| Bond value | قيمة التأمينات | Decimal| Yes | |
|
||||
| Announcement date | تاريخ الإعلان | Date | Yes | |
|
||||
| Closing date | تاريخ الإغلاق | Date | Yes | |
|
||||
| Announcement link | رابط الإعلان | URL | No | |
|
||||
| Source | مصدر المناقصة | See §5 | Yes | |
|
||||
| Notes | ملاحظات | Text | No | |
|
||||
| Announcement file | صورة/ملف الإعلان | File | No | Image or document |
|
||||
|
||||
### 4.2 Announcement Type | نوع إعلان المناقصة
|
||||
|
||||
When registering the tender, the announcement type must be set:
|
||||
|
||||
- First announcement (إعلان للمرة الأولى)
|
||||
- Re-announcement, 2nd time (إعلان معاد للمرة الثانية)
|
||||
- Re-announcement, 3rd time (إعلان معاد للمرة الثالثة)
|
||||
- Re-announcement, 4th time (إعلان معاد للمرة الرابعة)
|
||||
|
||||
---
|
||||
|
||||
## 5. Tender Source | مصدر المناقصة
|
||||
|
||||
The system must support recording the tender source by multiple means, including:
|
||||
|
||||
- Government sites (مواقع حكومية)
|
||||
- Official gazette (جريدة رسمية)
|
||||
- Personal relations (علاقات شخصية)
|
||||
- Partner companies (شركات صديقة)
|
||||
- WhatsApp or Telegram groups (مجموعات واتساب أو تلغرام)
|
||||
- Tender portals (بوابات المناقصات)
|
||||
- Email (البريد الإلكتروني)
|
||||
- Manual entry (إدخال يدوي)
|
||||
|
||||
**User interaction:** The user may:
|
||||
|
||||
- Select a source from a predefined list, or
|
||||
- Enter the source as free text, or
|
||||
- Paste the announcement link (stored as link; source may be derived or manual).
|
||||
|
||||
---
|
||||
|
||||
## 6. Duplicate Prevention | منع التكرار
|
||||
|
||||
The system must detect potential duplicate tenders.
|
||||
|
||||
**When:** On creation of a new tender (and optionally on update).
|
||||
|
||||
**Matching criteria:** The system checks for similar tenders using:
|
||||
|
||||
- Issuing body name (اسم الزبون / الجهة الطارحة)
|
||||
- Tender title (عنوان المناقصة)
|
||||
- Terms booklet value (قيمة دفتر الشروط)
|
||||
- Bond value (قيمة التأمينات)
|
||||
- Closing date (تاريخ الإغلاق)
|
||||
- Announcement date (تاريخ الإعلان)
|
||||
|
||||
**Behaviour:** If one or more tenders with matching or very similar data are found:
|
||||
|
||||
1. The system shows a **warning** to the user that a possible duplicate exists.
|
||||
2. The similar record(s) are displayed so the user can:
|
||||
- Review the existing tender
|
||||
- Confirm whether it is a duplicate or a different tender
|
||||
- Decide whether to proceed with creating the new tender or cancel.
|
||||
|
||||
The user can still choose to continue after the warning; the system does not block creation.
|
||||
|
||||
---
|
||||
|
||||
## 7. Administrative Directive | التوجيه الإداري
|
||||
|
||||
After the tender is registered, an **administrative directive** (توجيه إداري) can be issued by the Sales Manager or the Executive.
|
||||
|
||||
### 7.1 Directive Contents | مكونات التوجيه
|
||||
|
||||
- **Directive type:** Selected from a list (e.g. Buy terms booklet, Visit client, Meet committee, Prepare to bid).
|
||||
- **Additional notes:** Free text.
|
||||
- **Responsible employee:** Selected from the HR employee list (the person who will execute the task).
|
||||
|
||||
### 7.2 Examples of Directive Types | أمثلة على التوجيهات
|
||||
|
||||
- Purchase terms booklet (شراء دفتر الشروط)
|
||||
- Visit the client/issuing body (زيارة الزبون)
|
||||
- Get to know the relevant committee (التعرف على اللجنة المختصة)
|
||||
- Prepare to enter the tender (الاستعداد للدخول في المناقصة)
|
||||
|
||||
---
|
||||
|
||||
## 8. Assigning the Responsible Employee | تعيين الموظف المسؤول
|
||||
|
||||
When issuing a directive, the **employee responsible for executing the task** must be selected. The employee is chosen from the list of employees provided by the HR module.
|
||||
|
||||
---
|
||||
|
||||
## 9. Notifications | الإشعارات
|
||||
|
||||
When an employee is assigned to execute a directive:
|
||||
|
||||
- The system sends an **in-app notification** to the **user** linked to that employee.
|
||||
- The notification includes:
|
||||
- Tender name and number (اسم المناقصة + الرقم)
|
||||
- Task/directive type (نوع المهمة)
|
||||
- The administrative directive text
|
||||
- Manager notes (ملاحظات المدير)
|
||||
|
||||
No separate notification table is required; the existing Notification entity is used with a type such as `TENDER_DIRECTIVE_ASSIGNED`.
|
||||
|
||||
---
|
||||
|
||||
## 10. Executing the Task | تنفيذ المهمة
|
||||
|
||||
After receiving the task, the assigned employee can:
|
||||
|
||||
1. Perform the required action.
|
||||
2. Record in the system what was done.
|
||||
3. Add notes or a short report.
|
||||
4. Upload files related to the task (e.g. receipt, visit report).
|
||||
|
||||
---
|
||||
|
||||
## 11. File Management | إدارة الملفات
|
||||
|
||||
### 11.1 Announcement Files | ملفات الإعلان
|
||||
|
||||
- One main file per tender for the announcement (image or document).
|
||||
- Stored and linked to the tender record.
|
||||
|
||||
### 11.2 Task Execution Files | ملفات تنفيذ المهام
|
||||
|
||||
The employee may attach multiple files per directive/task, for example:
|
||||
|
||||
- Terms booklet purchase receipt
|
||||
- Terms booklets (documents)
|
||||
- Visit reports
|
||||
- Other documents related to the tender
|
||||
|
||||
The system must support upload, storage, and association of these files with the tender or the directive/task.
|
||||
|
||||
---
|
||||
|
||||
## 12. Activity Log | سجل النشاط
|
||||
|
||||
The system must log all operations performed on a tender, including:
|
||||
|
||||
- Tender creation
|
||||
- Data updates
|
||||
- Issuing directives
|
||||
- Assigning employees
|
||||
- Executing tasks
|
||||
- Uploading files
|
||||
- Adding notes
|
||||
|
||||
This log is used to display a timeline or history on the tender detail view.
|
||||
|
||||
---
|
||||
|
||||
## 13. End of Module Scope | نهاية دور الموديول
|
||||
|
||||
The Tender Management Module’s scope ends when:
|
||||
|
||||
- Initial directives have been executed,
|
||||
- Initial information has been gathered, and
|
||||
- The decision to prepare to enter the tender has been taken.
|
||||
|
||||
At that point, the user can **convert the tender to an Opportunity (Deal)** in the CRM module. The resulting Deal is then used by the engineering team to study the project. Conversion creates a Deal (Opportunity) and may store a reference to the source tender for traceability.
|
||||
|
||||
---
|
||||
|
||||
## Document History
|
||||
|
||||
| Version | Date | Author/Notes |
|
||||
|--------|------------|--------------|
|
||||
| 1.0 | 2025-03-11 | Initial SRS from client requirements (Arabic). |
|
||||
Reference in New Issue
Block a user