System use case specification add new specimen - ESG-Project/documentation GitHub Wiki


Identification	UC25
Use case	Add New Specimen
Actors	User
Stakeholders and interests	Field Technician: Needs a straightforward way to record tree measurements accurately as collected. Forest Inventory Analyst: Requires precise and complete data for each individual tree.
Pre-conditions	The user is in the "Species Data" section of an active Phytosociological Analysis (UC24 has been executed).
Minimum guarantees	System prevents saving specimens with invalid or missing mandatory data.
Success guarantees	A new specimen record is successfully added to the Phytosociological Analysis, with automatically calculated DBH and Basal Area.

Main Success Scenario

User Action	System Response
1. This use case begins when the user clicks the "Add Specimen" button in the "Species Data" section.	2. The system presents a form for new specimen registration. Fields include: Species (autocomplete), Plot (number or "Isolated"), Height (m), and up to six CBH (cm) fields. Optional fields: Family, Coordinates, Observations.
3. The user starts typing in the "Species" field.	4. The system, in real-time, displays suggestions of matching species from the global species register.
5. The user selects a species from the suggestions.	6. The system automatically populates the "Family" field based on the selected species (if available).
7. The user fills in the remaining mandatory data (Plot, Height, and at least one CBH value) and optional information.	8. The system automatically calculates DBH (Diameter at Breast Height) and Basal Area (m²) based on the entered Height and CBH values.
9. The user saves the specimen information.	10. The system validates all entered data (e.g., Height and CBH > 0, CBH values count between 1 and 6).
	11. The system saves the new specimen record in the database, associating it with the specified plot and the current analysis.
	12. The system confirms the specimen has been added successfully and displays it in the specimen list.

User Action	System Response
	1. If the species is not found in the suggestions after typing, the system provides an option to "Create New Species" (refer to UC26).
5. The user selects to create a new species and completes UC26.	6. Upon successful creation of the new species (UC26 post-condition), the system automatically selects this new species for the current specimen and returns to step 7 of the Main Success Scenario.

User Action	System Response
	1. The system detects invalid or missing information in mandatory fields (e.g., Height or CBH is zero/negative, CBH count is outside 1-6 range).
	2. The system displays specific error messages next to the problematic fields, requesting correction.
11. The user corrects the information and resubmits.	12. The system re-validates the corrected information and returns to step 10 of the Main Success Scenario.

User Action	System Response
1. The user cancels the action (e.g., clicks "Cancel" button).	2. The system discards all entered information and returns to the "Species Data" section without saving the specimen.

Mandatory Fields: Species, Plot, Height, and at least one CBH (up to 6) are mandatory.
Optional Fields: Family (auto-filled, editable), Coordinates, Observations.
Real-time Autocomplete: Species search must provide real-time suggestions.
Data Validations: Height and CBH values must be positive; CBH must have between 1 and 6 values.
Automatic Calculations: DBH and Basal Area are automatically calculated.
Cancellation: The operation can be canceled.