## Non-Welded Joint Types – Final Roadmap

**Branch:** `feature/weldlog-non-welded-joints`  
**Scope:** Mechanical joints (BJ, FJ, TH, CJ) must be editable in grids but excluded from every welding-related calculation, report and sync path.

---

### 1. Foundation (Database + Helpers)
- `joint_types` table now has `is_welded`, `is_mechanical`, `has_ndt` (see migrations `2025_11_14_181113_*`, `2025_11_14_181220_*`).
- `MechanicalJointTypesSeeder` guarantees the core mechanical joints exist in every environment.
- `JointTypeService` + `app/Functions/joint_type_helpers.php` cache joint-type lists and expose helpers:
  - `apply_welded_filter()` / `apply_mechanical_filter()` wrap any Builder or table name and add the correct `whereIn`.
  - `is_welded_joint`, `is_mechanical_joint`, `requires_ndt`, cache clear helpers.

### 2. DevExtreme Grid Behaviour
- `resources/views/components/table/datagrid*.blade.php` handles everything:
  - Greys out mechanical rows, disables welder/WPS/NDT fields, keeps `fitter_name` + fit-up dates editable.
  - Footer SUM/AVG now send `excludeMechanicalSummary=1`; backend (`SummaryContext` + `AggregateHelper`) runs `CASE WHEN` filters so totals only consider welded joints.
  - `type_of_welds` dropdown restored for Weldlog/Weldmap (joint_types + fallback list).

### 3. Application Surfaces Updated
| Area | Files | Result |
| --- | --- | --- |
| Dashboards & reports | `resources/views/admin-ajax/*`, `resources/views/admin/dashboard/chart/monthly-progress.blade.php` | Every weld log query wraps `apply_welded_filter`, so mechanical rows never inflate KPIs. |
| Cron & sync jobs | `resources/views/cron/*.blade.php`, `app/Http/Controllers/SaveTrigger/test_pack_base_statuses.php` | Spool, paint, NDE and test-package syncs skip mechanical joints automatically. |
| Register Creator & PDFs | `app/Services/RegisterCreator/...`, `resources/views/admin-ajax/pdf/*`, `generate-pdf-*` | Register exports and PDF builders read only welded joints; mechanical rows do not trigger file searches. |
| Page modules | `resources/views/admin/type/weldlog.blade.php`, `weldmap*.blade.php`, `nde-matrix.blade.php`, `manage-ndt.blade.php`, `spool-release*` | All modules share the same helper-based filtering and the DevExtreme UI behaviour. |

### 4. Testing & Tooling
- `php artisan mechanical:verify-summaries --columns=nps_1,...` validates SUM/AVG output; CLI table prints welded vs mechanical totals for audit.
- Guide and roadmap (this file + `mechanical-overview.md`) explain the architecture and test plan.

### 5. Commands & References
```bash
# Seed mechanical joints (first-time environments)
php artisan db:seed --class=MechanicalJointTypesSeeder

# Rebuild helper cache if joint_types table changes
php artisan tinker --execute="clear_joint_types_cache();"

# Run SUM/AVG regression
php artisan mechanical:verify-summaries --columns=nps_1,nps_2,outside_diameter_1,outside_diameter_2,wall_thickness_1,wall_thickness_2
```

### 6. Key Principles
1. **Never** query `weld_logs` without `apply_welded_filter()` unless the screen explicitly needs mechanical rows.
2. Mechanical rows can exist in listings (for fit-up tracking) but should not trigger welding KPIs, NDT scopes, spool or paint logic.
3. DevExtreme grids are the single source of UI logic; avoid duplicating mechanical detection per module.
4. Register/PDF builders must only read welded joints to keep QA documentation aligned with real weld data.

---

**Last Updated:** 2025-11-21  
**Owner:** AI Assistant + Team