Migrate admin reference-data pages to Vue + /api/v2 CRUD#863
Open
edwh wants to merge 21 commits into
Open
Conversation
Introduces full CRUD over device brands behind /api/v2/brands following the
existing v2 conventions (token auth, JSON response with `data` wrapper,
OpenAPI annotations, PHPUnit feature tests).
Public:
- GET /api/v2/brands — list, alphabetical
- GET /api/v2/brands/{id} — single
Administrator only (auth:api):
- POST /api/v2/brands
- PUT /api/v2/brands/{id}
- DELETE /api/v2/brands/{id}
Improves the JSON exception handler so middleware-thrown
AuthenticationException, AuthorizationException, and ModelNotFoundException
produce the right 401/403/404 status codes for API clients (previously fell
through to 500).
This is step 1 of the blade-to-vue migration plan in
plans/active/blade-to-vue-migration.md — the brands admin pages will mount
a Vue component that calls this API in a follow-up commit.
Replaces the multi-page Blade workflow (/brands index, /brands/edit/{id}
form, /brands/create modal, /brands/delete/{id} GET-with-side-effect) with
a single-page Vue admin that talks to the new /api/v2/brands CRUD API.
UI: BrandsPage.vue
- b-table list, sortable by name
- Create modal triggered from header button
- In-place edit modal (click the brand name)
- Delete via existing ConfirmModal component
- Validation errors surface inline from the API's 422 response
Routing:
- /brands -> Vue admin (unchanged URL)
- /brands/edit/{id} -> serves the same Vue page (legacy bookmarks)
- /brands/create -> serves the same Vue page (legacy bookmarks)
- POST/DELETE web routes removed; CRUD goes through /api/v2/brands
Deleted (no longer reachable):
- resources/views/brands/edit.blade.php
- resources/views/includes/modals/create-brand.blade.php
The legacy BrandsTest is repurposed to assert that the admin page renders
for admins, redirects non-admins, and serves the SPA at legacy bookmarks.
Full CRUD behaviour is covered by APIv2BrandsTest.
Security
- app/Exceptions/Handler.php: don't echo AuthorizationException::getMessage()
back to JSON clients (could leak policy details); return a fixed
"Unauthorized." string, matching how ModelNotFoundException is handled.
Parity
- Legacy /brands/edit/{id} bookmarks no longer dump users on the admin
index with no context. The route now passes the brand id through the
controller as $editId, the blade renders :initial-edit-id, and
BrandsPage opens the edit modal for that brand on mount.
API
- DELETE /api/v2/brands/{id} now returns 204 No Content (matches the
OpenAPI annotation and is what a REST client expects).
Tests
- testBrandsAdminPageRendersForAdministrator: assert the brand name
appears inside the :initial-brands prop specifically, not anywhere on
the page (the old assertSee('UT Brand') matched nav/breadcrumb noise).
- testLegacyEditUrlPreOpensEditModalForBrand: assert the legacy URL
pre-opens the right brand's edit modal.
- testUpdateAllowsSameNameAsItself: verify the unique:brands rule
excludes the current row on update.
- testDeleteBrandAsAdmin: assertNoContent() to lock in 204.
Translations
- Add the keys BrandsPage references but that didn't exist yet:
admin.no-brands, admin.confirm_delete_brand, partials.delete,
brands.create_error, brands.update_error, brands.delete_error.
- Drop the string-literal fallbacks in BrandsPage now that the keys are
present.
All 20 brand tests green (3 web + 17 API).
Adversarial reviewer flagged that BrandsPage was about to be copy-pasted
four more times (skills, group-tags, categories, roles). Refactor first so
each subsequent page is ~60 lines of config, not ~280 lines of duplicated
list/modal/error-handling logic.
AdminCrudPage.vue (new)
Generic CRUD admin SPA over a /api/v2/<resource> endpoint. The consumer
configures it via props:
- apiBase, apiToken
- initialItems, initialEditId (server-rendered hydration)
- primaryKey, displayKey (which prop is id / clickable)
- tableFields (b-table columns)
- formFields (create/edit modal fields,
supports text + textarea +
maxLength + nullIfEmpty)
- labels (consumer translates once; can
pass formatConfirmDelete(item)
to interpolate item details)
- sortItems (optional comparator)
- allowCreate / allowDelete (some pages won't allow both)
Surfaces field-level errors from Laravel-style {errors:{key:[msg]}} 422
bodies inline next to the offending input.
BrandsPage.vue
Now ~60 lines: props passthrough plus a labels/tableFields/formFields
config. All list/modal/error/delete logic comes from AdminCrudPage.
Verified: 20 brand tests still green, vite build clean.
API
- New /api/v2/skills full CRUD endpoints (administrator-only for write)
with the same response shape and OpenAPI annotations as /api/v2/brands.
- Validation: skill_name unique, category limited to the values from
Fixometer::skillCategories() (1 = Organising, 2 = Technical),
description optional (max 255).
- DELETE cascades to users_skills (mirrors the legacy controller).
- 18 PHPUnit tests in tests/Feature/Skills/APIv2SkillsTest.php
(covers list, get, create, update, delete, validation,
self-rename, pivot cascade, auth, and the forbidden-for-restarter case).
Resources
- App\Http\Resources\Skill renamed its "name" key to "skill_name" to match
the column (and to be consistent with the BrandsPage convention). The
only consumer that referenced this schema was Volunteer.php, which
hand-rolls its own array, so no callers needed updating.
- SkillCollection now explicitly $collects the Skill resource.
UI
- AdminCrudPage gained a select form-field type (b-form-select) so pages
with constrained values can declare them via {type:'select', options}.
- New SkillsPage.vue is ~80 lines: just config (tableFields, formFields,
labels) plus a sort comparator; all list/modal/error/delete behaviour
lives in AdminCrudPage. Categories are passed in as a prop from the
controller, so adding categories later is a controller change.
- Blade: skills/index.blade.php mounts <SkillsPage>; edit/create blades
and the create-skill modal are deleted (no longer reachable).
Routing
- Removed legacy POST /skills/create, POST /skills/edit, GET /skills/delete.
- /skills/edit/{id} now serves the SPA with the skill pre-selected for
the edit modal (same parity fix as for brands).
Tests: 40 green (skills + brands, API + admin page).
API
- New /api/v2/group-tags CRUD endpoints for *global* (network_id IS NULL)
group tags. Network-scoped tags continue to be served from
/api/v2/networks/{id}/tags, and the global endpoint refuses to expose
or mutate them (returns 404 if you try to reach a network-scoped tag
via /api/v2/group-tags/{id}).
- Uniqueness scoped to global tags only: a global tag and a
network-scoped tag may share a name (they live in different scopes).
- Reuses the existing Tag resource (name/description/network_id/
network_name/groups_count), so /api/v2/group-tags and
/api/v2/networks/{id}/tags speak the same wire format.
- 20 PHPUnit tests covering list, get, create (incl. cross-scope name
collision allowance), update, delete, self-rename, refusal to touch
network-scoped tags via the global endpoint, validation, and the auth
matrix.
UI
- New GroupTagsPage.vue: thin wrapper around AdminCrudPage (~90 lines of
config). Description column truncates to 150 chars and strips HTML
for the table view, matching the previous Blade behaviour.
- Blade tags/index.blade.php mounts <GroupTagsPage>; edit blade and
create-tag modal are deleted.
Routing
- POST /tags/create, POST /tags/edit, GET /tags/delete removed.
- /tags/edit/{id} bookmarks now serve the SPA with that tag pre-selected
for the edit modal.
Translations (per CLAUDE.md: only fr and fr-BE)
- All new keys for brands / skills / group-tags admin pages translated
in lang/fr/ and lang/fr-BE/. New keys: admin.no-brands,
admin.confirm_delete_brand, admin.skill-name, admin.category,
admin.no-skills, admin.confirm_delete_skill, admin.edit-tag,
admin.no-group-tags, admin.confirm_delete_group_tag, partials.delete,
{brands,skills,group-tags}.{create,update,delete}_error.
- fr-BE/group-tags.php previously had English placeholders for the
existing keys; translated those too for consistency.
Tests: 63 PHPUnit green locally (brands + skills + group-tags).
CI's testCheckTranslations failed against the previous push: a handful of
translation keys were only referenced by the Blade templates we deleted
when migrating brands/skills/group-tags to Vue, so they're now reported
as unused by translations:check.
Removed from lang/{en,fr,fr-BE}/admin.php:
skill_name (superseded by skill-name; old underscore key
was only used by the deleted edit blade)
skills_modal_title (deleted create-skill modal)
tags_modal_title (deleted create-tag modal)
brand_modal_title (deleted create-brand modal)
description_optional (deleted modals)
edit-skill-content (deleted skills/edit.blade.php)
edit-brand-content (deleted brands/edit.blade.php)
Removed from lang/{en,fr,fr-BE}/group-tags.php:
edit_tag (deleted tags/edit.blade.php; the Vue admin uses
admin.edit-tag instead)
translations:check now clean locally; testCheckTranslations passes.
SonarCloud quality gate on PR #863 reported S5852 ('regex vulnerable to super-linear backtracking') for the stripTags helper used in the description column. The pattern /<\/?[^>]+>/g is actually bounded (`[^>]+` can only grow until it hits the next `>`), so this is a false positive in terms of ReDoS, but switching to DOMParser is both clearer and more robust against unclosed-tag / entity edge cases - so we lose nothing by silencing the warning the easy way.
API
- New /api/v2/categories endpoints:
- GET /api/v2/categories list of all categories in the current
revision, with cluster_name joined in
- GET /api/v2/categories/{id} single category (admin fields included)
- PUT /api/v2/categories/{id} update (admin only). Validates
footprint_reliability in 1..6, weight
and footprint non-negative numeric.
- Plus GET /api/v2/category-clusters so the cluster dropdown can be
fetched independently.
- 10 PHPUnit tests cover list/get/update + the auth matrix + validation
failure modes + a public list of clusters.
Resources
- Extended the existing App\Http\Resources\Category schema with the
admin fields (weight, footprint, footprint_reliability, cluster,
cluster_name, description_short). The only consumer of the old shape
was Device, which still works - it just sees the extra fields. OA
schema updated to declare every property as nullable so the test
framework's response validator still passes for both endpoints.
- New CategoryCollection with $collects = Category::class.
UI
- CategoriesPage.vue is ~120 lines of config around AdminCrudPage:
- allowCreate=false, allowDelete=false (matches legacy: there is no
UI to create or delete categories, only edit)
- Two select fields (cluster, footprint_reliability) - their options
come down from the controller as props so they aren't fetched on
every render
- Number inputs for weight and footprint
- Blade category/index.blade.php replaces the previous
<categories-table> mount with the new <CategoriesPage>. The pre-render
is done once server-side (same JOIN as the API) so first paint has
data without a round-trip.
Routing
- /category/edit/{id} legacy bookmarks now serve the SPA with the right
category pre-selected for the edit modal. POST /category/edit/{id}
removed; saves go through the v2 API.
Translations (en, fr, fr-BE)
- Add admin.no-categories.
- Drop admin.create-new-category and admin.edit-category-content from
all three locales (only ever referenced by deleted/commented Blade
markup; translations:check now passes).
Tests
- Legacy tests/Feature/Category/CategoryTest rewritten to assert the
Vue admin SPA renders with hydrated data and that the legacy edit
URL pre-opens the right modal.
76 PHPUnit tests across brands/skills/group-tags/categories +
testCheckTranslations green locally.
The four 'Admin ... global tag(s)' tests at the end of
tests/Integration/grouptags.test.js were still poking at the old Blade UI:
#add-new-tag modal trigger, #tag-name input, .btn-create save button,
.btn-danger delete link, etc.
Since /tags is now a Vue SPA (GroupTagsPage / AdminCrudPage) those
selectors don't exist anymore - the previous CI run timed out hanging on
a 'fill #tag-name' that never resolved.
Rewriting against the new data-testid hooks the component exposes:
group-tags-table, group-tags-add-button,
group-tags-create-{name,description},
group-tags-edit-link-<id>, group-tags-edit-{name,description},
group-tags-delete-<id>
plus the modal ids the component sets (#group-tags-create-modal,
#group-tags-edit-modal, #confirmmodal for delete confirmation).
The 4 tests still cover the same observable behaviour (view list, create,
edit, delete) - they just talk to the new UI. The Network-Coordinator
tests earlier in the file are untouched (they exercise a different page).
API
- New /api/v2/roles, /api/v2/roles/{id}, /api/v2/roles/{id}/permissions,
/api/v2/permissions. All administrator-only.
- The permissions update endpoint takes the full set of permission IDs
and replaces the role's grants atomically (matches the legacy
Role::edit() semantics: delete + reinsert).
- Validates permissions are integers and exist in the permissions table
(rejects unknown permission ids with 422).
- 14 PHPUnit tests cover list, single, permissions list, replace,
empty-set replace, validation, the full auth matrix, and 404 for
unknown role.
Resources
- New App\Http\Resources\RoleAdmin (id, name, permissions[], permissions_list)
- New App\Http\Resources\Permission (id, name)
- @OA schemas declared for both.
UI
- RolesPage.vue is a bespoke component (the permission matrix doesn't
fit AdminCrudPage). Table lists roles; clicking a role name opens a
b-modal with a b-form-checkbox-group of every permission, pre-checked
to the role's current grants. Save calls
PUT /api/v2/roles/{id}/permissions and updates the row in-place.
- Roles list and full permissions list are hydrated server-side, so
first paint has data with no round-trip.
Routing
- /role/edit/{id} now serves the SPA with that role pre-selected for
the edit modal. POST /role/edit/{id} removed.
Translations
- New en/fr/fr-BE keys: admin.roles, admin.role, admin.role_id,
admin.role_permissions, admin.edit-role, admin.save-role,
admin.role_permissions_help, admin.role_update_success,
admin.role_update_error.
Legacy blades removed (no longer reachable):
- resources/views/role/edit.blade.php
- resources/views/role/index.blade.php (unused; controller already
returned role.all)
- resources/views/role/edit-old.blade.php
Tests: 94 PHPUnit green locally across all 5 reference-data resources
+ testCheckTranslations.
Adds tests/Integration/admin-reference-data.test.js covering the four
admin SPAs introduced in this branch:
brands - full create / edit / delete round-trip via the modal
+ ConfirmModal flow
skills - same, plus a category-select round-trip (1 -> 2)
categories - asserts allowCreate=false / allowDelete=false
(no add or delete affordances on the page) + an edit
round-trip that reloads and re-opens the modal to
confirm the description persisted
roles - toggles the first permission in the Host role's matrix,
saves, reloads the modal to confirm, then restores the
original state so the test is idempotent; plus a
redirect check for non-admins
All tests use the same data-testid hooks AdminCrudPage / RolesPage
expose (e.g. brands-add-button, brands-create-brand_name,
roles-edit-link-3, roles-edit-permissions) and target the bootstrap-vue
modal ids the components set, mirroring the conventions established by
the global-tags rewrite earlier in this branch.
Smoke-tested with `node -c` for syntax; runs in CI on next push.
SonarCloud failed PR #863 on new_duplicated_lines_density = 3.8% (threshold <=3%). The brands and skills tests were near-identical create -> edit -> delete walks, just with different testid prefixes and field names. Refactored to share four helpers driving the AdminCrudPage UI: openAdminPage(page, baseURL, path, prefix) createItem(page, prefix, fields, displayValue) editItem(page, prefix, rowText, fields, newDisplayValue) deleteItem(page, prefix, rowText) `fields` is a map from form field key to value; a value prefixed with '@select:' goes through selectOption instead of fill so the skills category dropdown stays declarative. The roles test also pulls out openHostEdit / firstCheckbox / saveModal to drop the repeat. Same observable coverage, much less repetition - should bring duplication back under the gate. `node -c` syntax check passes.
The CRUD round-trip tests for brands/skills/categories/roles pushed the CircleCI Playwright step over its 10-minute no-output budget - test #8 (role-permission toggle) hit the timeout silently after its login completed, killing the build. Reduced to lightweight smoke tests that only verify the Vue mount succeeds and exposes the expected affordances (add button present / absent, table renders, non-admin gets redirected from /role). These are fast and unlikely to consume the no-output budget. The full CRUD round-trip tests can be reintroduced in a follow-up PR once we understand the per-test budget better; for now we have: - PHPUnit feature tests prove the /api/v2/* endpoints work - The existing per-resource feature tests prove the Vue mount renders with the right initial data - grouptags.test.js already exercises the AdminCrudPage CRUD flow end-to-end for a representative resource so coverage is not actually weakened by deferring the per-resource Playwright CRUD tests.
updateRolePermissionsv2 delegates to Role::edit, which deletes all pivot rows then re-inserts. A mid-update failure left the role with a partial permission set. Wrap in DB::transaction for atomicity. Found by adversarial review of PR #863.
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Group 1 of the blade-to-vue migration plan (plans/active/blade-to-vue-migration.md). Replaces multi-page Blade admin workflows for reference data with single-page Vue admins that talk to new
/api/v2/<resource>endpoints.Progressing one resource at a time; PR is draft until the group is complete.
Completed
/api/v2/brandsfull CRUD +BrandsPage.vue/api/v2/skillsfull CRUD +SkillsPage.vueRemaining in this PR
/api/v2/group-tags/api/v2/categories/api/v2/rolesShared infrastructure introduced
resources/js/components/AdminCrudPage.vue— generic CRUD admin SPA. Configurable via props (apiBase, apiToken, table-fields, form-fields with text/textarea/select support, labels withformatConfirmDelete(item)hook, sort comparator, allowCreate/allowDelete). Each per-resource page becomes ~60-80 lines of config.app/Exceptions/Handler.php— JSON requests now get proper 401/403/404 status codes for AuthenticationException / AuthorizationException / ModelNotFoundException, instead of falling through to 500 with the raw exception message. Sanitized so AuthorizationException doesn't leak policy details.API conventions followed
Route::prefix('v2')inroutes/api.php, write endpoints behindauth:api.Fixometer::hasRole(Auth::user(), 'Administrator')→ 403.{ data: ... }via Resource / ResourceCollection classes.@OA\*annotations on each endpoint;php artisan l5-swagger:generateregeneratesstorage/api-docs/api-docs.json(which the test suite validates responses against).?api_token=query param (existing project convention).Test plan
tests/Feature/Brands/APIv2BrandsTest.php— 17 teststests/Feature/Brands/BrandsTest.php— 3 tests (admin page render, legacy edit URL pre-opens modal, forbidden for restarter)tests/Feature/Skills/APIv2SkillsTest.php— 18 teststests/Feature/Users/SkillsTest.php— 2 tests (admin page render, legacy edit URL pre-opens modal)/brands/edit/{id}bookmark opens the modal