cabloy 5.1.61 → 5.1.63

package/cabloy-docs/backend/backend-contract-emission-output-inspection.md

@@ -0,0 +1,189 @@
+# Backend Contract Emission Output Inspection
+
+This page is a practical inspection companion for one narrow backend question:
+
+> after I understand the controller/DTO/entity inputs, how do I inspect the emitted Swagger/OpenAPI output for one backend contract slice?
+
+It uses one concrete emitted thread as the specimen:
+
+- `GET /training/student/summary/:id`
+
+Use this page together with:
+
+- [OpenAPI Guide](/backend/openapi-guide)
+- [Backend Contract Emission Specimen](/backend/backend-contract-emission-specimen)
+- [Backend Contract Emission Source Reading Map](/backend/backend-contract-emission-source-reading-map)
+- [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
+
+> [!TIP]
+> **Backend emission inspection path**
+>
+> 1. **[OpenAPI Guide](/backend/openapi-guide)** — understand backend emission conceptually
+> 2. **[Backend Contract Emission Specimen](/backend/backend-contract-emission-specimen)** — inspect one concrete emitted action thread
+> 3. **[Backend Contract Emission Source Reading Map](/backend/backend-contract-emission-source-reading-map)** — trace the broader input-side file order
+> 4. **[Backend Contract Emission Output Inspection](/backend/backend-contract-emission-output-inspection)** — inspect the emitted output surfaces themselves
+>
+> **You are here:** step 4.
+> **Previous recommended pages:** [OpenAPI Guide](/backend/openapi-guide), [Backend Contract Emission Specimen](/backend/backend-contract-emission-specimen), and [Backend Contract Emission Source Reading Map](/backend/backend-contract-emission-source-reading-map).
+
+## Why this page exists
+
+The current backend docs already explain three useful layers of the emission story:
+
+- why OpenAPI matters
+- how one concrete emitted action thread is authored
+- which files to read in source order for the broader emission branch
+
+What was still missing was one page that starts from the **emitted output surfaces themselves**.
+
+This page fills that gap.
+
+It is not another broad OpenAPI concept page and not another source-reading map. It is the companion page for inspecting the emitted artifact directly.
+
+## The shortest accurate mental model
+
+For this specimen, there are three things you should compare:
+
+1. the authored controller/DTO inputs
+2. the generated module-level metadata records
+3. the emitted OpenAPI output surfaces
+
+If those three surfaces agree, the emitted backend contract slice is usually correct enough to hand off into the forward-chain frontend generation step.
+
+## Which emitted surfaces to inspect
+
+The current backend docs already name the main inspection surfaces:
+
+- Swagger UI
+- OpenAPI JSON output
+- versioned OpenAPI JSON output
+- RapiDoc
+
+For local emitted JSON inspection, the current public repo docs already use this example endpoint:
+
+- `http://localhost:7102/swagger/json?version=V31`
+
+That is the most practical raw inspection surface when you want to confirm the emitted machine-readable contract itself.
+
+## The specimen to keep in mind
+
+Keep one small emitted path in mind while inspecting output:
+
+- `GET /training/student/summary/:id`
+
+The authored/backend anchors for that path are:
+
+- `vona/src/suite/a-training/modules/training-student/src/controller/student.ts`
+- `vona/src/suite/a-training/modules/training-student/src/dto/studentSummary.tsx`
+- `vona/src/suite/a-training/modules/training-student/src/.metadata/index.ts`
+
+This page is not re-walking those files in depth. It uses them as the comparison baseline for the emitted output.
+
+## What to confirm in emitted output
+
+### 1. Confirm the route path exists
+
+Start by confirming that the emitted OpenAPI output includes the expected route path for the specimen.
+
+For this page, the check is simple:
+
+- the emitted output should expose the summary action path for the Student resource
+
+Compare that against:
+
+- `@Web.get('summary/:id')` in `controller/student.ts`
+- the generated path registration in `.metadata/index.ts`
+
+A practical reading takeaway is:
+
+> the controller action and the emitted path should agree before you think about frontend SDK generation.
+
+### 2. Confirm the emitted response shape matches the DTO contract
+
+Next, inspect the response schema for the summary action.
+
+The source truth for the named response shape is:
+
+- `DtoStudentSummary`
+
+Representative fields in that DTO include:
+
+- `id`
+- `name`
+- `mobile`
+- `level`
+- `levelTitle`
+- `description`
+- `descriptionLength`
+- `summaryText`
+
+When you inspect the emitted OpenAPI output, the important question is:
+
+- does the response schema still reflect the intended named DTO shape?
+
+A practical reading takeaway is:
+
+> for this specimen, `DtoStudentSummary` is the response-shape baseline that the emitted output should mirror.
+
+### 3. Confirm the generated registry agrees with the emitted slice
+
+The generated module surface in:
+
+- `vona/src/suite/a-training/modules/training-student/src/.metadata/index.ts`
+
+should still agree with what you see in emitted output.
+
+The two most useful checks are:
+
+- the DTO registry includes `training-student:studentSummary`
+- the generated API path records include the summary route
+
+That gives you a compact consistency triangle:
+
+- controller action
+- DTO registration
+- emitted OpenAPI path/schema output
+
+## A practical inspection order
+
+When checking one emitted backend contract slice, use this order:
+
+1. confirm the authored controller action is still the intended source truth
+2. confirm the named DTO is still the intended response-shape truth
+3. confirm `.metadata/index.ts` still exposes the expected path and DTO registration
+4. inspect versioned OpenAPI JSON output
+5. only then hand off to frontend generation or bridge diagnostics
+
+That order keeps the inspection process narrow and avoids drifting too early into downstream layers.
+
+## What this page does not re-explain
+
+This page deliberately does **not** re-teach:
+
+- broad OpenAPI concepts -> see [OpenAPI Guide](/backend/openapi-guide)
+- the full emitted action specimen narrative -> see [Backend Contract Emission Specimen](/backend/backend-contract-emission-specimen)
+- the file-order path into controller/DTO/entity inputs -> see [Backend Contract Emission Source Reading Map](/backend/backend-contract-emission-source-reading-map)
+- how emitted backend contract becomes generated frontend consumers -> see [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
+
+Its job is only to help you inspect the emitted backend output itself.
+
+## Where to read next
+
+- If you need the broader conceptual emission page, continue with [OpenAPI Guide](/backend/openapi-guide).
+- If you want a backend-side proof or diagnosis companion after checking emitted output, continue with [Backend Source Reading Verify Playbook](/backend/backend-source-reading-verify-playbook) and [Backend Source Reading Debug Checklist](/backend/backend-source-reading-debug-checklist).
+- If you need the concrete authored action thread again, continue with [Backend Contract Emission Specimen](/backend/backend-contract-emission-specimen).
+- If you need the broader input-side file-order path, continue with [Backend Contract Emission Source Reading Map](/backend/backend-contract-emission-source-reading-map).
+- If the emitted backend output now looks correct and you want the next bridge step, continue with [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk).
+
+## Final takeaway
+
+The cleanest way to inspect one emitted backend contract slice is not to stay only in conceptual OpenAPI docs and not to jump immediately into frontend generation.
+
+For the `summary/:id` specimen, compare:
+
+- the controller action
+- the named DTO shape
+- the generated module registry
+- the emitted OpenAPI output surface
+
+If those surfaces agree, the backend contract slice is usually ready for the forward-chain handoff.

package/cabloy-docs/backend/backend-contract-emission-source-reading-map.md

@@ -0,0 +1,160 @@
+# Backend Contract Emission Source Reading Map
+
+This page is a practical source-reading companion for one narrow backend question:
+
+> if my question is no longer “how one module is wired” but “how controller, entity, and DTO metadata become emitted OpenAPI contract,” which files should I read first, and in what order?
+
+Use this page together with:
+
+- [OpenAPI Guide](/backend/openapi-guide)
+- [DTO Infer and Generation](/backend/dto-infer-generation)
+- [Backend Resource/Module Contract Chain](/backend/backend-resource-module-contract-chain)
+- [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
+
+> [!TIP]
+> **Backend emission reading path**
+>
+> 1. **[Backend Resource/Module Contract Chain](/backend/backend-resource-module-contract-chain)** — understand how one real module is wired
+> 2. **[DTO Infer and Generation](/backend/dto-infer-generation)** — understand how DTO shapes are chosen and wrapped
+> 3. **[Backend Contract Emission Source Reading Map](/backend/backend-contract-emission-source-reading-map)** — trace how those surfaces become emitted OpenAPI contract
+>
+> **You are here:** step 3.
+> **Previous recommended pages:** [Backend Resource/Module Contract Chain](/backend/backend-resource-module-contract-chain) and [DTO Infer and Generation](/backend/dto-infer-generation).
+
+## Why this page exists
+
+The current backend docs already explain:
+
+- how one backend module is wired
+- how DTO helpers and generated metadata work
+- why OpenAPI matters as a backend contract bridge
+
+What was still missing was one source-order page that isolates the emission branch itself.
+
+This page fills that gap.
+
+It is a file-order map for contract emission, not another broad OpenAPI concept page.
+
+## How to use this page
+
+Use this rule of thumb:
+
+1. start with the conceptual pages first
+2. read the first source file to identify the contract input surface
+3. follow the emission path only until you understand where the emitted backend contract comes from
+4. stop and hand off to the fullstack forward bridge once the question becomes frontend generation or consumption
+
+## The shortest accurate mental model
+
+A practical backend emission path looks like this:
+
+1. controllers define route/action request and response contracts
+2. DTOs and entities define named and shared field/metadata surfaces
+3. validation and `v` helpers refine the emitted shape
+4. OpenAPI generation reads those combined surfaces into machine-readable contract output
+5. that emitted contract then hands off to the forward-chain fullstack bridge
+
+That means the emission branch is not the same as the module wiring branch.
+
+It starts from the authored contract surfaces, then stops when the emitted backend contract is ready for downstream consumers.
+
+## Source-confirmed reading path
+
+Use this order:
+
+1. `vona/src/suite/a-training/modules/training-student/src/controller/student.ts`
+2. `vona/src/suite/a-training/modules/training-student/src/dto/studentCreate.tsx`
+3. `vona/src/suite/a-training/modules/training-student/src/dto/studentUpdate.tsx`
+4. `vona/src/suite/a-training/modules/training-student/src/dto/studentView.tsx`
+5. `vona/src/suite/a-training/modules/training-student/src/dto/studentSelectReq.tsx`
+6. `vona/src/suite/a-training/modules/training-student/src/dto/studentSelectRes.tsx`
+7. `vona/src/suite/a-training/modules/training-student/src/dto/studentSelectResItem.tsx`
+8. `vona/src/suite/a-training/modules/training-student/src/entity/student.tsx`
+9. `vona/src/suite/a-training/modules/training-student/src/.metadata/index.ts`
+10. then return to the conceptual emission surface in [OpenAPI Guide](/backend/openapi-guide)
+
+That order starts from the route/action contract surface, descends through the DTO and entity metadata that shape the emitted contract, and then returns to the OpenAPI-specific conceptual layer once the inputs are clear.
+
+## What each source surface clarifies
+
+### `controller/student.ts`
+
+This file shows the route/action contract entry layer:
+
+- `@Web.*` action declarations
+- `@Arg.*` request extraction
+- `@Api.body(...)` response contract surfaces
+- action-level request/response DTO references
+
+Read this file first when the question is:
+
+- which action contracts are even supposed to emit into OpenAPI?
+
+### `dto/*.tsx`
+
+These files show the named request/response contract artifacts that OpenAPI can emit.
+
+Representative distinctions to keep in mind:
+
+- create/update/view DTOs are operation-facing named artifacts
+- select request DTOs may also carry filter-specific shaping and transform logic
+- list/count DTOs may wrap row-item DTOs into emitted list contracts
+
+Read these files when the question is:
+
+- which DTO shape is part of the emitted backend contract?
+
+### `entity/student.tsx`
+
+This file shows the shared field contract surface:
+
+- `@Api.field(...)`
+- validation-oriented field rules
+- OpenAPI-facing titles and metadata
+- field-level render metadata that still belongs to the broader contract story
+
+Read this file when the question is:
+
+- which parts of the emitted contract are shared field truth rather than DTO-local additions?
+
+### `.metadata/index.ts`
+
+This file is not the main emission engine, but it still matters as a generated registry surface.
+
+Read it when the question is:
+
+- how do the DTO/controller/entity contract artifacts become visible as a coherent module-level generated surface?
+
+Its value here is limited and specific:
+
+- it confirms the DTO/controller/entity registrations exist together
+- it shows those artifacts are not isolated local files only
+
+Then stop and move back to the OpenAPI emission docs instead of re-reading the whole module chain.
+
+## What this page does not re-explain
+
+This page deliberately does **not** re-teach:
+
+- full module wiring and generated registration inventory -> see [Backend Resource/Module Contract Chain](/backend/backend-resource-module-contract-chain)
+- explicit vs inferred DTO strategy -> see [DTO Infer and Generation](/backend/dto-infer-generation)
+- frontend SDK generation and consumption -> see [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
+- general OpenAPI concepts -> see [OpenAPI Guide](/backend/openapi-guide)
+
+Its job is only to show the shortest file-order path through the backend contract-emission inputs.
+
+## Where to read next
+
+- If you need the broader conceptual emission page, continue with [OpenAPI Guide](/backend/openapi-guide).
+- If you want one concrete emitted action thread before widening back out, continue with [Backend Contract Emission Specimen](/backend/backend-contract-emission-specimen).
+- If you want a backend-side proof or diagnosis companion for the source-reading path itself, continue with [Backend Source Reading Verify Playbook](/backend/backend-source-reading-verify-playbook) and [Backend Source Reading Debug Checklist](/backend/backend-source-reading-debug-checklist).
+- If you want to inspect the emitted output surfaces themselves after the source-order path, continue with [Backend Contract Emission Output Inspection](/backend/backend-contract-emission-output-inspection).
+- If your next question is still about DTO helper and wrapping mechanics, return to [DTO Infer and Generation](/backend/dto-infer-generation).
+- If your next question is about how one real module is wired before emission, return to [Backend Resource/Module Contract Chain](/backend/backend-resource-module-contract-chain).
+- If your next question is about how the emitted backend contract becomes generated frontend consumers, continue with [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk).
+
+## Final takeaway
+
+The cleanest way to read backend contract emission is not to stay only in conceptual OpenAPI docs and not to reread the whole module chain every time.
+
+Start from controller + DTO + entity contract inputs, confirm how those surfaces shape the emitted contract, then hand off to the forward-chain bridge once the emitted backend truth is clear.

package/cabloy-docs/backend/backend-contract-emission-specimen.md

@@ -0,0 +1,170 @@
+# Backend Contract Emission Specimen
+
+This page is a concrete backend specimen for one narrow question:
+
+> how does one real controller action become one emitted backend contract slice?
+
+It uses one emitted path only:
+
+- `GET /training/student/summary/:id`
+
+Use this page together with:
+
+- [OpenAPI Guide](/backend/openapi-guide)
+- [Backend Contract Emission Source Reading Map](/backend/backend-contract-emission-source-reading-map)
+- [Backend Resource/Module Contract Chain](/backend/backend-resource-module-contract-chain)
+- [DTO Infer and Generation](/backend/dto-infer-generation)
+- [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
+
+> [!TIP]
+> **Backend emission reading path**
+>
+> 1. **[OpenAPI Guide](/backend/openapi-guide)** — understand backend contract emission conceptually
+> 2. **[Backend Contract Emission Specimen](/backend/backend-contract-emission-specimen)** — inspect one real emitted controller-action thread
+> 3. **[Backend Contract Emission Source Reading Map](/backend/backend-contract-emission-source-reading-map)** — widen back out to the broader file-order emission path
+>
+> **You are here:** step 2.
+> **Previous recommended page:** [OpenAPI Guide](/backend/openapi-guide).
+
+## Why this specimen exists
+
+The current backend docs already explain several adjacent parts of the story:
+
+- `OpenAPI Guide` explains why OpenAPI matters conceptually
+- `Backend Resource/Module Contract Chain` explains how one module is wired
+- `DTO Infer and Generation` explains how DTO shapes are chosen and wrapped
+- `Backend Contract Emission Source Reading Map` explains the broader file-order path for emission inputs
+
+What was still missing was one compact specimen that stays on a single emitted thread.
+
+This page fills that gap.
+
+It is not another broad OpenAPI guide and not another full module walkthrough. It is a specimen page for one emitted backend contract slice.
+
+## The shortest accurate mental model
+
+For this specimen, the emitted backend contract comes from three main authored surfaces:
+
+1. the controller action declares the route and response contract entry
+2. the DTO class declares the named response body shape
+3. the module’s generated metadata surface exposes the registered route and DTO presence together
+
+That is enough to answer the practical question:
+
+- which action is being emitted?
+- which DTO shape is part of that emitted contract?
+- where can I confirm the route path and DTO registration in the generated module surface?
+
+## Source-confirmed reading path
+
+Use this order:
+
+1. `vona/src/suite/a-training/modules/training-student/src/controller/student.ts`
+2. `vona/src/suite/a-training/modules/training-student/src/dto/studentSummary.tsx`
+3. `vona/src/suite/a-training/modules/training-student/src/.metadata/index.ts`
+
+That order is intentionally small.
+
+It starts at the emitted action contract entry, moves into the DTO response shape, then ends at the generated module-level registration surface.
+
+## 1. Controller action: the emitted route and response entry
+
+The first source to read is:
+
+- `vona/src/suite/a-training/modules/training-student/src/controller/student.ts`
+
+Representative source facts:
+
+- `@Web.get('summary/:id')`
+- `@Api.body(v.optional(), v.object(DtoStudentSummary))`
+- action method `summary(...)`
+
+This file answers the first emission question:
+
+- which route/action contract is supposed to be emitted?
+
+For this specimen, the answer is clear:
+
+- the route is `summary/:id`
+- the response contract is declared through `DtoStudentSummary`
+
+A practical reading takeaway is:
+
+> the controller action is the contract entry point for the emitted backend slice.
+
+## 2. DTO surface: the named emitted response shape
+
+The next source to read is:
+
+- `vona/src/suite/a-training/modules/training-student/src/dto/studentSummary.tsx`
+
+Representative source facts:
+
+- `@Dto<IDtoOptionsStudentSummary>()`
+- fields such as `id`, `name`, `mobile`, `level`, `levelTitle`, `description`, `descriptionLength`, and `summaryText`
+- `@Api.field(...)` metadata on each field
+
+This file answers the second emission question:
+
+- which named response body shape is part of the emitted contract?
+
+It is also a useful boundary reminder.
+
+This page is not about infer-vs-explicit DTO strategy in general. It is only showing that this concrete action emits a concrete named DTO artifact.
+
+A practical reading takeaway is:
+
+> for this emitted slice, `DtoStudentSummary` is the clearest response-shape truth to inspect.
+
+## 3. Generated module surface: route path and DTO registration together
+
+The final source to read is:
+
+- `vona/src/suite/a-training/modules/training-student/src/.metadata/index.ts`
+
+Representative source facts for this specimen:
+
+- the DTO registry includes `training-student:studentSummary`
+- the generated API path record includes `'/training/student/summary/:id'`
+
+This file is not the emission engine itself, but it is still useful because it confirms that the action and DTO are visible together in the generated module-level surface.
+
+For this specimen, it answers the third emission question:
+
+- where can I confirm the summary route path and DTO presence together without re-reading the whole controller and DTO directories?
+
+A practical reading takeaway is:
+
+> `.metadata/index.ts` is the compact generated confirmation surface after you already know which action and DTO you are tracing.
+
+## What this specimen does not cover
+
+This page deliberately does **not** re-teach:
+
+- the whole backend module wiring chain -> see [Backend Resource/Module Contract Chain](/backend/backend-resource-module-contract-chain)
+- explicit vs inferred DTO mechanics -> see [DTO Infer and Generation](/backend/dto-infer-generation)
+- general OpenAPI concepts and `bean.openapi` capabilities -> see [OpenAPI Guide](/backend/openapi-guide)
+- frontend generation and consumption after emission -> see [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
+
+Its job is only to keep one emitted action thread small and concrete.
+
+## Where to read next
+
+- If you want the broader conceptual emission page, continue with [OpenAPI Guide](/backend/openapi-guide).
+- If you want a backend-side proof or diagnosis companion for this emitted-thread path, continue with [Backend Source Reading Verify Playbook](/backend/backend-source-reading-verify-playbook) and [Backend Source Reading Debug Checklist](/backend/backend-source-reading-debug-checklist).
+- If you want to inspect the emitted output itself after this authored specimen, continue with [Backend Contract Emission Output Inspection](/backend/backend-contract-emission-output-inspection).
+- If you want the broader file-order path through emission inputs, continue with [Backend Contract Emission Source Reading Map](/backend/backend-contract-emission-source-reading-map).
+- If you want the full module wiring specimen around this action, continue with [Backend Resource/Module Contract Chain](/backend/backend-resource-module-contract-chain).
+- If you want to follow this emitted backend contract into generated frontend consumers, continue with [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk).
+
+## Final takeaway
+
+The cleanest way to understand one emitted backend contract slice is not to reread the entire module or stay only in broad OpenAPI concepts.
+
+For the `summary/:id` specimen, read:
+
+- the controller action for the emitted route/response entry
+- the DTO for the emitted response body shape
+- the generated module surface for route and DTO confirmation
+
+That keeps the backend emission story concrete without flattening it into a much larger module walkthrough.