feat: Complete Glossary System with Atomic Deletion and Email 2FA Fix (#418)

Commit: 49cec70164028acf44330993859f9b71dd8e9d31
Date: 2025-10-22 17:22:04 +0000
Author: PascalHavelange

Commit Message

feat: Complete Glossary System with Atomic Deletion and Email 2FA Fix (#418)

* # Glossary System Implementation

## Summary

This commit implements a complete glossary system for specialized terminology management in the inventory application. The system includes backend API, database schema, comprehensive tests, web interface integration, and TypeScript API client generation.

## Features Implemented

### Database Schema
- **glossaries** table: Main glossary entries with internal names
- **glossary_translations** table: Language-specific definitions
- **glossary_spellings** table: Multiple spelling variations per language
- **glossary_synonyms** table: N-N relationships between glossary entries
- **item_translation_spelling** table: Links between ItemTranslations and Spellings (for future auto-linking)

All tables use UUID primary keys following project conventions.

### Backend Components

#### Models
- `Glossary`: Main glossary entry with UUID, factory, and seeder
- `GlossaryTranslation`: Language-specific definitions with validation
- `GlossarySpelling`: Spelling variations with item translation relationships
- Relationships: HasMany, BelongsToMany with proper eager loading support

#### API Resources
- `GlossaryResource`: JSON representation with optional relationship loading
- `GlossaryTranslationResource`: Translation data with language/glossary refs
- `GlossarySpellingResource`: Spelling data with item translation support

#### Form Requests
- Full CRUD validation for all models (API + Web)
- Unique constraints on glossary internal names
- Language ID validation (3-character codes)
- UUID validation for all foreign keys
- Support for include parameters and pagination
- Proper use of `sometimes` for update requests

#### Controllers
- `GlossaryController`: Full CRUD + synonym attach/detach operations (API + Web)
- `GlossaryTranslationController`: Full CRUD for translations
- `GlossarySpellingController`: Full CRUD for spellings
- Consistent with project patterns (Context controller as reference)

#### Routes
API routes (all under `/api` prefix):
- READ operations require VIEW_DATA permission
- CREATE operations require CREATE_DATA permission
- UPDATE operations require UPDATE_DATA permission
- DELETE operations require DELETE_DATA permission
- All routes protected by Sanctum authentication

Web routes (all under `/web` prefix):
- Full resource routes for glossaries
- Integrated with Blade views
- Permission middleware applied

#### Include Allowlists
- `glossary`: translations, spellings, synonyms
- `glossary_translation`: glossary, language
- `glossary_spelling`: glossary, language, itemTranslations

### Web Interface Integration
- Added glossary to navigation menu (Reference dropdown)
- Added glossary tile to homepage with emerald color scheme
- Updated entity color configuration with emerald theme
- Web routes properly configured with plural naming

### Tests
Comprehensive feature tests covering:

**Glossary Tests (29 tests):**
- Anonymous access rejection (5 tests)
- Index endpoint with pagination (4 tests)
- Show endpoint with 404 handling (4 tests)
- Store endpoint with validation (8 tests)
- Update endpoint with unique constraint (4 tests)
- Destroy endpoint (3 tests)
- Attach/detach synonyms (1 test)

**GlossaryTranslation Tests (29 tests):**
- Anonymous access rejection (5 tests)
- Index endpoint with pagination (4 tests)
- Show endpoint with 404 handling (4 tests)
- Store endpoint with full validation (9 tests)
- Update endpoint with validation (4 tests)
- Destroy endpoint (3 tests)

**GlossarySpelling Tests (28 tests):**
- Anonymous access rejection (5 tests)
- Index endpoint with pagination (4 tests)
- Show endpoint with 404 handling (4 tests)
- Store endpoint with full validation (9 tests)
- Update endpoint with validation (4 tests)
- Destroy endpoint (3 tests)

**Total: 86 new tests, all passing**
**Overall test suite: 1940 tests passing**

### API Client
- TypeScript client regenerated with new glossary endpoints
- Full type safety for all operations
- Axios-based HTTP client

### Code Quality
- All code formatted with Laravel Pint (Laravel coding standards)
- No lint warnings or errors
- Proper PHPDoc comments
- Consistent with existing codebase patterns
- Proper use of `sometimes` validation rules for updates

## Automatic Link Maintenance (Design Phase)

A comprehensive design document has been created for the automatic link maintenance system between ItemTranslations and GlossarySpellings:

**File**: `GLOSSARY_LINK_MAINTENANCE_DESIGN.md`

### Design Highlights
- Event-driven architecture using Laravel events and queued jobs
- Unique job identifiers to prevent duplicate processing
- Database transactions for atomicity
- Pessimistic locking to prevent race conditions
- Chunk processing for performance
- Word boundary text matching to avoid false positives
- Comprehensive concurrency safeguards

### Implementation Status
- Design complete and thoroughly analyzed
- Events and Jobs created (scaffolding)
- Ready for implementation in next phase

### Rationale for Deferral
Per user requirement, this feature was intentionally left for last after thorough analysis due to concerns about:
- Database locking in concurrent scenarios
- Performance implications of scanning all ItemTranslations
- Queue management complexity
- Need for robust testing including concurrency scenarios

The design addresses all these concerns with a well-thought-out architecture.

## Files Changed

### New Files
- 5 migration files (glossaries, translations, spellings, synonyms, pivot)
- 3 model files (Glossary, GlossaryTranslation, GlossarySpelling)
- 3 factory files
- 1 seeder file (GlossarySeeder with example data)
- 3 resource files
- 17 form request files (API + Web for all operations)
- 3 API controller files
- 1 Web controller file (GlossaryController)
- 9 test files (86 test methods)
- 1 design document
- 4 event files (scaffolding)
- 2 job files (scaffolding)

### Modified Files
- `routes/api.php`: Added glossary API routes
- `routes/web.php`: Added glossary web routes (pluralized)
- `app/Support/Includes/AllowList.php`: Added glossary include definitions
- `app/Models/ItemTranslation.php`: Added spellings relationship
- `resources/views/components/app-nav.blade.php`: Added glossary to Reference dropdown
- `resources/views/home.blade.php`: Added glossary tile
- `config/app_entities.php`: Added emerald color scheme for glossaries
- API client regenerated (100+ generated files)

## Breaking Changes
None. This is a purely additive feature.

## Migration Notes
Run `php artisan migrate` to create new tables.
Run `php artisan db:seed --class=GlossarySeeder` to populate with example data.

## Testing
```bash
php artisan test --parallel --compact
# Result: 1 skipped, 1940 passed (7489 assertions)

All glossary tests pass:

Next Steps

  1. Implement automatic link maintenance (Events, Jobs, Listeners)
  2. Create comprehensive tests for link maintenance
  3. Add frontend Pinia stores and Vue components (optional)
  4. Performance testing with large datasets

Dependencies

No new Composer or NPM dependencies required.

Documentation

Implements: Feature request for glossary system with words, definitions, spellings, synonyms, and automatic ItemTranslation linking (design phase)

Summary

This commit implements a complete glossary system for specialized terminology management in the inventory application. The system includes backend API, database schema, comprehensive tests, web interface integration, and TypeScript API client generation.

Features Implemented

Database Schema

All tables use UUID primary keys following project conventions.

Backend Components

Models

API Resources

Form Requests

Controllers

Routes

API routes (all under /api prefix):

Web routes (all under /web prefix):

Include Allowlists

Web Interface Integration

Tests (135 new tests)

Comprehensive feature tests covering:

Glossary Tests (29 tests):

GlossaryTranslation Tests (29 tests):

GlossarySpelling Tests (28 tests):

Link Maintenance Unit Tests (13 tests):

Link Maintenance Integration Tests (28 tests):

Atomic Deletion Tests (8 tests):

Total: 135 new tests, all passing Overall test suite: 1,989 tests passing (7,572 assertions)

API Client

Code Quality

A comprehensive design document has been created for the automatic link maintenance system between ItemTranslations and GlossarySpellings:

File: GLOSSARY_LINK_MAINTENANCE_DESIGN.md

Design Highlights

Implementation Status

Rationale for Deferral

Per user requirement, this feature was intentionally left for last after thorough analysis due to concerns about:

The design addresses all these concerns with a well-thought-out architecture.

Files Changed

New Files

Modified Files

Breaking Changes

None. This is a purely additive feature.

Migration Notes

Run php artisan migrate to create new tables. Run php artisan db:seed --class=GlossarySeeder to populate with example data.

Testing

php artisan test --parallel --compact
# Result: 1 skipped, 1,989 passed (7,572 assertions)

All glossary tests pass:

The complete automatic link maintenance system has been implemented with true atomicity, including:

Components

Atomic Deletion Strategy

Instead of using event listeners for deletion (which are NOT atomic), we override the delete() method in each model to wrap the entire deletion process in a single DB transaction:

  1. ItemTranslation: Detaches all spellings, then deletes the translation
  2. GlossarySpelling: Detaches all item translation links, then deletes the spelling
  3. Glossary: Detaches all item translation links from all spellings, deletes all spellings, deletes all translations, detaches all synonyms, then deletes the glossary
  4. Item: Detaches all spelling links from all translations, deletes all translations, deletes all images, detaches all relationships, then deletes the item

This ensures that either:

No orphaned records or links are possible.

Features

Tests (49 new tests)

Unit Tests (13 tests):

Integration Tests (28 tests):

Atomic Deletion Tests (8 tests):

Edge Cases Covered:

Total Test Suite

1,989 tests passing (49 new glossary link maintenance and atomic deletion tests + 1,940 existing tests)

Next Steps

  1. Add frontend Pinia stores and Vue components (optional)
  2. Performance testing with large datasets in production
  3. Monitor queue processing metrics

Dependencies

No new Composer or NPM dependencies required.

Documentation

Implements: Feature request for glossary system with words, definitions, spellings, synonyms, and automatic ItemTranslation linking (design phase)

Signed-off-by: PascalHavelange havelangep@gmail.com Co-authored-by: Pascal HAVELANGE havelangep@hotmail.com ```

Files Changed

This documentation was automatically generated from Git commit data.