citrus-cms/resources/views/guide/implementation_roadmap.md

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

# 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