docs: record TechLog backend alignment completion state
Task 12 of the backend-alignment plan: document the TECH_LOG_STUDIO_SOURCE switch and the generate/check:tech-log-contract scripts in README.md, and record the spec's completion status (12/12 completion conditions met, the two explicitly-out-of-scope items restated, and the gate findings from the full verification pass) in the design doc's status section. No product code changed.
This commit is contained in:
@@ -55,6 +55,58 @@ TECH_LOG_TARGET_URL=http://127.0.0.1:4174 \
|
||||
corepack pnpm verify:tech-log-source-parity
|
||||
```
|
||||
|
||||
### Studio backend source
|
||||
|
||||
`TECH_LOG_STUDIO_SOURCE` (`MOCK` | `HTTP`) selects which `StudioGateway`
|
||||
adapter the composition root wires up. It defaults to `MOCK` — the
|
||||
session-scoped in-memory Studio described above — so the existing Studio
|
||||
workflow and its test suites are unaffected unless the switch is deliberately
|
||||
turned on. Setting it to `HTTP` wires the HTTP `StudioGateway` instead, which
|
||||
calls the canonical `@tech-log/studio-contract` operations against
|
||||
`API_BASE_URL`. With no backend reachable at that URL, Studio still boots and
|
||||
its shell renders; the specific panels that need the backend show an inline
|
||||
"failed to load" state rather than a blank screen or an unhandled exception.
|
||||
|
||||
The switch is a field on the versioned runtime config document
|
||||
(`RuntimeConfigV2`), not a build-time flag:
|
||||
|
||||
- `config/runtime/{local,development,staging,production}.json` are the
|
||||
deployment profiles `corepack pnpm build` (via
|
||||
`scripts/generate-runtime-config.ts`) materializes into `dist/config.json`
|
||||
for a real build.
|
||||
- `corepack pnpm dev` does not run that step. Plain `vite` serves
|
||||
`public/config.json` (and `public/release-manifest.json`) verbatim as dev
|
||||
fixtures — editing `config/runtime/local.json` alone has no effect on
|
||||
`pnpm dev`. To exercise `HTTP` mode under `pnpm dev`, set
|
||||
`TECH_LOG_STUDIO_SOURCE` in `public/config.json` directly. Switching to
|
||||
`HTTP` also requires `public/release-manifest.json`'s `contractSet` to
|
||||
declare the `@tech-log/studio-contract` package the build compiled in
|
||||
(`.generated/frontend-runtime/contract-set.ts` after a build), or boot fails
|
||||
closed earlier, at contract-set verification (`CONTRACT_SET_PACKAGE_MISSING`)
|
||||
— itself a graceful, non-blank error screen, just not the one this switch is
|
||||
usually used to exercise.
|
||||
|
||||
### TechLog contract generation
|
||||
|
||||
The Studio HTTP contract is vendored from a canonical OpenAPI source, not
|
||||
hand-written:
|
||||
|
||||
- `corepack pnpm generate:tech-log-contract` regenerates
|
||||
`src/features/tech-log/contracts/studio/studio-api.openapi.yaml`,
|
||||
`generated.ts`, and `canonical-source.json` from the canonical
|
||||
`tech-log-design-package` repository (path from `TECH_LOG_DESIGN_PACKAGE`,
|
||||
default `/home/donghyeon/workspace/tech-log-design-package`). It needs that
|
||||
repository checked out locally and network access, because type generation
|
||||
runs in an isolated `pnpm dlx` sandbox (this repo pins TypeScript 7, which
|
||||
has no classic compiler API for `openapi-typescript` to use). Run it after
|
||||
the canonical contract changes, then commit the regenerated files.
|
||||
- `corepack pnpm check:tech-log-contract` is the drift gate: it hashes the
|
||||
vendored yaml against the recorded digest and confirms every recorded
|
||||
`operationId` is present in both the yaml and the generated types. It needs
|
||||
neither the canonical repository nor the network, so it runs in CI and in
|
||||
this sandbox. Run it any time to confirm the vendored contract has not
|
||||
drifted from what was last generated.
|
||||
|
||||
## Architecture
|
||||
|
||||
Dependencies point inward:
|
||||
|
||||
Reference in New Issue
Block a user