mejoras en la gestión de nombres y códigos de proyectos y documentos según la norma ISO 19650

2025-10-25 11:30:59 +02:00
parent d8ae8c8894
commit 88e526cf6c
13 changed files with 917 additions and 46 deletions
--- a/docs/ISO19650_Naming_Convention.md
+++ b/docs/ISO19650_Naming_Convention.md
@@ -0,0 +1,93 @@
+# ISO 19650 Project Naming Convention
+
+## Overview
+This document outlines the naming convention for projects based on the ISO 19650 standard. The naming convention ensures consistency, clarity, and compliance with industry standards.
+
+## Naming Fields
+The naming convention consists of the following fields:
+
+| Field              | Definition                                                                 | Requirement       | Length       |
+|--------------------|---------------------------------------------------------------------------|-------------------|--------------|
+| **Proyecto**       | Identificador del expediente, contrato o proyecto                        | Requerido         | 2-12         |
+| **Creador**        | Organización creadora del documento                                       | Requerido         | 3-6          |
+| **Volumen o Sistema** | Agrupaciones, áreas o tramos representativos en los que se fragmenta el proyecto | Requerido         | 2-3          |
+| **Nivel o Localización** | Localización dentro de un Volumen o Sistema                          | Requerido         | 3            |
+| **Tipo de Documento** | Tipología de documento, entregable o auxiliar                          | Requerido         | 3            |
+| **Disciplina**     | Ámbito al que se corresponde el documento                                | Requerido         | 3            |
+| **Número**         | Enumerador de partes                                                    | Requerido         | 3            |
+| **Descripción**    | Texto que describe el documento y su contenido                          | Opcional          | Sin límite   |
+| **Estado**         | Situación, temporal o definitiva, del documento                         | Opcional/Metadato | 2            |
+| **Revisión**       | Versión del documento                                                   | Opcional/Metadato | 4            |
+
+## Field Details
+
+### Proyecto
+- **Definition**: Identifies the project, contract, or file.
+- **Requirement**: Required
+- **Length**: 2-12 characters
+
+### Creador
+- **Definition**: Organization responsible for creating the document.
+- **Requirement**: Required
+- **Length**: 3-6 characters
+
+### Volumen o Sistema
+- **Definition**: Representative groupings, areas, or sections of the project.
+- **Requirement**: Required
+- **Length**: 2-3 characters
+
+### Nivel o Localización
+- **Definition**: Location within a Volume or System.
+- **Requirement**: Required
+- **Length**: 3 characters
+
+### Tipo de Documento
+- **Definition**: Document type, deliverable, or auxiliary.
+- **Requirement**: Required
+- **Length**: 3 characters
+
+### Disciplina
+- **Definition**: Scope to which the document corresponds.
+- **Requirement**: Required
+- **Length**: 3 characters
+
+### Número
+- **Definition**: Part enumerator.
+- **Requirement**: Required
+- **Length**: 3 characters
+
+### Descripción
+- **Definition**: Text describing the document and its content.
+- **Requirement**: Optional
+- **Length**: Unlimited
+
+### Estado
+- **Definition**: Temporary or definitive status of the document.
+- **Requirement**: Optional/Metadata
+- **Length**: 2 characters
+
+### Revisión
+- **Definition**: Document version.
+- **Requirement**: Optional/Metadata
+- **Length**: 4 characters
+
+## Example
+A sample project name following this convention:
+```
+PRJ001-ORG01-V01-L01-DOC-ARC-001-Description-ST-0001
+```
+Where:
+- **PRJ001**: Project identifier
+- **ORG01**: Creator organization
+- **V01**: Volume
+- **L01**: Level
+- **DOC**: Document type
+- **ARC**: Discipline
+- **001**: Part number
+- **Description**: Description of the document
+- **ST**: Status
+- **0001**: Revision
+
+## Notes
+- All fields marked as "Required" must be included.
+- Optional fields can be omitted if not applicable.
--- a/docs/ProjectNamingCodeGenerator.md
+++ b/docs/ProjectNamingCodeGenerator.md
@@ -0,0 +1,80 @@
+# Project Naming Code Generator
+
+## Overview
+The `ProjectNamingSchema` class provides a utility to generate project names based on the ISO 19650 naming convention. This ensures consistency and compliance with industry standards.
+
+## Installation
+Ensure the `ProjectNamingSchema` class is located in the `App\Helpers` namespace. No additional installation steps are required.
+
+## Usage
+To generate a project name, use the `generate` method of the `ProjectNamingSchema` class. This method accepts an associative array of fields and returns the generated project name.
+
+### Example
+```php
+use App\Helpers\ProjectNamingSchema;
+
+$fields = [
+    'project' => 'PRJ001',
+    'creator' => 'ORG01',
+    'volume' => 'V01',
+    'level' => 'L01',
+    'documentType' => 'DOC',
+    'discipline' => 'ARC',
+    'number' => '1',
+    'description' => 'Description',
+    'status' => 'ST',
+    'revision' => '1',
+];
+
+$projectName = ProjectNamingSchema::generate($fields);
+
+// Output: PRJ001-ORG01-V01-L01-DOC-ARC-001-Description-ST-0001
+```
+
+## Fields
+The following fields are supported:
+
+| Field              | Definition                                                                 | Requirement       | Length       |
+|--------------------|---------------------------------------------------------------------------|-------------------|--------------|
+| **project**        | Identifies the project, contract, or file.                                | Required          | 2-12         |
+| **creator**        | Organization responsible for creating the document.                      | Required          | 3-6          |
+| **volume**         | Representative groupings, areas, or sections of the project.             | Required          | 2-3          |
+| **level**          | Location within a Volume or System.                                      | Required          | 3            |
+| **documentType**   | Document type, deliverable, or auxiliary.                                | Required          | 3            |
+| **discipline**     | Scope to which the document corresponds.                                 | Required          | 3            |
+| **number**         | Part enumerator.                                                         | Required          | 3            |
+| **description**    | Text describing the document and its content.                            | Optional          | Unlimited     |
+| **status**         | Temporary or definitive status of the document.                         | Optional          | 2            |
+| **revision**       | Document version.                                                        | Optional          | 4            |
+
+## Validation
+The `generate` method validates that all required fields are provided. If any required field is missing, an `InvalidArgumentException` is thrown.
+
+### Example
+```php
+$fields = [
+    'creator' => 'ORG01',
+    'volume' => 'V01',
+    'level' => 'L01',
+    'documentType' => 'DOC',
+    'discipline' => 'ARC',
+    'number' => '1',
+];
+
+try {
+    $projectName = ProjectNamingSchema::generate($fields);
+} catch (InvalidArgumentException $e) {
+    echo $e->getMessage(); // Output: The field 'project' is required.
+}
+```
+
+## Testing
+Unit tests for the `ProjectNamingSchema` class are located in the `tests/Unit/ProjectNamingSchemaTest.php` file. Run the tests using the following command:
+
+```bash
+vendor\bin\pest --filter ProjectNamingSchemaTest
+```
+
+## Notes
+- All fields marked as "Required" must be included.
+- Optional fields can be omitted if not applicable.