Cabloy

Appearance

Backend Metadata to Frontend Table Actions Debug Checklist ​

This page is a symptom-first verify/debug companion for one narrow fullstack question:

when a visible Student row action is wrong, stale, hidden, or missing, which layer should I check next?

Use this page together with:

TIP

Mixed-chain diagnosis path

  1. Backend Metadata to Frontend Table Actions — understand the mixed chain conceptually
  2. Backend Metadata to Frontend Table Actions Source Reading Map — trace the Student row-action chain in file order
  3. Backend Metadata to Frontend Table Actions Debug Checklist — verify which layer is wrong when the visible action still fails

You are here: step 3. Previous recommended pages: Backend Metadata to Frontend Table Actions and Backend Metadata to Frontend Table Actions Source Reading Map.

Why this page exists ​

The current docs already explain the mixed chain in two useful ways:

  • conceptually, through the mixed-chain explainer page
  • structurally, through the mixed-chain source-reading map

What was still missing was one page that starts from symptoms.

This page fills that gap.

It is not another contract-loop overview and not another table-runtime deep dive. It is a practical checklist for debugging one Student row-action chain.

Fastest mental model for diagnosis ​

A visible row action can fail at several different layers:

  1. backend row metadata may not point to the intended action resource
  2. custom backend action semantics may not have refreshed the generated frontend contract surface
  3. the frontend action resource may be missing or stale
  4. the page block/runtime handoff may not be feeding the right row schema into ZTable
  5. the table runtime may finally be filtering or resolving the action differently than expected

The fastest debugging strategy is:

check the earliest possible source of truth first, and only descend into deeper runtime layers when the earlier layers already look correct.

Debugging checklist by layer ​

1. Check the backend row metadata first ​

Start here when:

  • the action is missing entirely
  • the wrong action appears in the operations column
  • the custom action is not present in the backend contract surface at all

Primary source anchor:

  • vona/src/suite/a-training/modules/training-student/src/dto/studentSelectResItem.tsx

What to confirm:

  • the row metadata still uses the intended ZovaRender.cell(...) identity
  • nested ZovaRender.tableActionRow(...) entries include the expected action names
  • custom actions such as training-student:actionSummary or training-student:actionDeleteForce are still present where expected

If this layer is wrong, stop here and fix the metadata truth first.

2. Check the forward-generated contract only when custom action semantics changed ​

Only do this when the visible action depends on a changed backend endpoint such as:

  • summary/:id
  • deleteForce/:id

Primary source anchors:

  • vona/src/suite/a-training/modules/training-student/src/controller/student.ts
  • zova/src/suite/a-training/modules/training-student/cli/openapi.config.ts
  • zova/src/suite/a-training/modules/training-student/src/api/trainingStudent.ts
  • zova/src/suite/a-training/modules/training-student/src/model/student.ts

What to confirm:

  • the backend controller still exposes the intended custom endpoint
  • the frontend module OpenAPI config still owns the expected operation slice
  • the generated frontend API surface still contains the expected typed method
  • the thin model facade still delegates to the correct generated API path while keeping the existing resource-owner story intact

If the endpoint changed but the generated contract did not refresh, the issue is not the visible action resource yet. It is a forward-chain regeneration problem.

3. Check that the frontend action resource exists and matches the metadata identity ​

Start here when:

  • backend metadata looks correct
  • generated contract also looks correct
  • but the visible action still does not render or behaves like the wrong action implementation

Primary source anchors:

  • zova/src/suite/a-training/modules/training-student/src/bean/tableCell.actionSummary.tsx
  • zova/src/suite/a-training/modules/training-student/src/bean/tableCell.actionDeleteForce.tsx
  • zova/src/suite/cabloy-basic/modules/basic-table/src/bean/tableCell.actionOperationsRow.tsx

What to confirm:

  • the expected custom or built-in action bean exists
  • the resource identity in backend metadata still matches the frontend bean identity
  • the custom action bean is still thin and delegates to the right model or command path
  • actionOperationsRow is still able to include and render the child action resources

4. Check the page handoff into the list/table runtime ​

Start here when:

  • backend metadata and action resources both look correct
  • but the list page still does not expose the action as expected

Primary source anchors:

  • zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockPage/controller.tsx
  • zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockTable/controller.tsx

What to confirm:

  • schemaRow is still exposed from the stable resource owner
  • permissions are still flowing through the shared page runtime
  • blockTable is still bridging the expected schemaRow, data, and tableScope into ZTable

If this layer is wrong, the problem is in the page/runtime handoff, not in the action bean itself.

5. Only then check final table/runtime resolution ​

Go here last when:

  • metadata truth is correct
  • generated contract is correct
  • action resources exist
  • page block handoff also looks correct
  • but the action still renders incorrectly

Primary final-runtime anchor:

  • zova/src/suite-vendor/a-zova/modules/a-table/src/component/table/controller.tsx

At this point, switch from contract debugging into deeper table-runtime debugging.

For the broader table runtime reading path, continue with Zova Table Source Reading Map.

How to classify the failure ​

Visible action missing entirely ​

Most likely checks, in order:

  1. backend row metadata truth
  2. frontend action resource identity exists
  3. page block/schema handoff

Visible action exists but uses stale behavior ​

Most likely checks, in order:

  1. if custom semantics changed, inspect the forward-generated contract path
  2. distinguish generated-output drift from local dependency drift
  3. then confirm the action bean still delegates to the expected model/API path

Visible action exists but wrong permissions or visibility ​

This is often a narrower visibility problem rather than a full mixed-chain problem.

When that is the real issue, continue with Table Action Visibility and Permission Flow Guide.

Visible action exists but wrong runtime/render resolution ​

Treat this as the deepest layer.

Only go here after upstream contract, generation, action-resource, and page handoff checks already pass.

Generated-output drift vs local dependency drift ​

A useful distinction is:

Generated-output drift ​

This is the problem when:

  • the custom backend contract changed
  • but the generated frontend API/model surface was not refreshed correctly

Typical response:

  1. confirm backend contract truth first
  2. refresh the generated frontend contract surface
  3. verify the generated output itself before debugging the visible action

Local dependency drift ​

This is the problem when:

  • the generated output already contains the expected action contract or types
  • but local consumers still behave as if the old version is installed

Typical response:

  1. stop editing source truth
  2. prove the generated handoff is already correct
  3. rerun the normal sync flow
  4. only then repair local install state if needed

For the broader drift vocabulary, continue with Contract Loop Playbook.

What this page does not re-explain ​

This page deliberately does not re-teach:

Its job is only to tell you which layer to verify next when the visible Student row action still fails.

Final takeaway ​

The cleanest way to debug a visible Student row action is not to start from the deepest table runtime file.

Start from backend row metadata truth, then only move into generated contract follow-up, action resource existence, page handoff, and final runtime resolution as needed.

Released under the MIT License.

Copyright © 2016-present Cabloy