101 lines
4.8 KiB
Markdown
101 lines
4.8 KiB
Markdown
# Implementation Plan: WAL journal mode + OpenAPI 3.1 — Status check
|
||
|
||
## 0. Scope vs. Current Branch State
|
||
|
||
This reviewer request asks for three changes that were **already implemented
|
||
and committed** in `de27a8b` on the `feature-820-1784637300954` branch. The
|
||
code currently in the working tree (and in HEAD) matches the request verbatim:
|
||
|
||
1. ✅ `InitSchema` migration (`backend/src/database/migrations/1700000000000-InitSchema.ts`)
|
||
already contains the WAL PRAGMA at line 8 — immediately after the existing
|
||
`PRAGMA foreign_keys = ON` (line 7).
|
||
2. ✅ `DatabaseInitService` (`backend/src/database/database-init.service.ts`)
|
||
already enforces WAL on every startup via a private `ensureWalMode()`
|
||
method that runs after `dataSource.initialize()`. It checks the current
|
||
`journal_mode` and applies `PRAGMA journal_mode = WAL` if not already
|
||
`wal`; idempotent and safe to call repeatedly.
|
||
3. ✅ `main.ts` (`backend/src/main.ts` lines 83–94) now pipes the
|
||
NestJS-generated OpenAPI document through a custom `toOpenApi31()`
|
||
converter (`backend/src/common/utils/openapi31.ts`) that emits
|
||
`openapi: '3.1.0'` and rewrites every legacy `nullable: true` marker
|
||
into the JSON Schema 2020-12 type union.
|
||
|
||
Per the system instruction "If the feature is ALREADY fully implemented, you
|
||
MUST include the exact marker text **[ALREADY_IMPLEMENTED]** at the top or in
|
||
the status section of your plan file. Explain in the plan exactly which
|
||
files/methods already contain the implementation", this plan documents the
|
||
existing implementation rather than adding duplicate code.
|
||
|
||
## 1. Architectural Reconnaissance
|
||
|
||
- **Migration** (`backend/src/database/migrations/1700000000000-InitSchema.ts:7-8`):
|
||
```ts
|
||
await queryRunner.query(`PRAGMA foreign_keys = ON;`);
|
||
await queryRunner.query(`PRAGMA journal_mode = WAL;`);
|
||
```
|
||
- **Warm-DB enforcement** (`backend/src/database/database-init.service.ts:34-78`):
|
||
- `init()` calls `ensureWalMode()` after `dataSource.initialize()`.
|
||
- `ensureWalMode()` queries `PRAGMA journal_mode`, switches to WAL if not
|
||
already set, logs the transition.
|
||
- **OpenAPI 3.1 pipeline** (`backend/src/main.ts:83-94`):
|
||
```ts
|
||
const swaggerConfig = new DocumentBuilder()...
|
||
const rawDocument = SwaggerModule.createDocument(app, swaggerConfig) as Record<string, any>;
|
||
const document = toOpenApi31(rawDocument);
|
||
SwaggerModule.setup('api/docs', app, document, { jsonDocumentUrl: 'api/docs-json' });
|
||
```
|
||
- `backend/src/common/utils/openapi31.ts` exports `toOpenApi31(doc)`.
|
||
- Rewrites `nullable: true` → `type: ['<orig>', 'null']` recursively in
|
||
`components.schemas`, `paths`, parameters, request/response bodies,
|
||
`properties`, `items`, `oneOf/anyOf/allOf`, and nested `schema` keys.
|
||
- Preserves `$ref` nodes.
|
||
- **Tests** (`tests/backend/openapi31.spec.ts`, 7 tests): all pass.
|
||
- **Full suite**: 83/83 tests across 18 suites.
|
||
|
||
## 2. Impacted Files
|
||
|
||
None — all changes are already in place at HEAD.
|
||
|
||
| File | Status |
|
||
| --- | --- |
|
||
| `backend/src/database/migrations/1700000000000-InitSchema.ts` | ✅ line 8 |
|
||
| `backend/src/database/database-init.service.ts` | ✅ lines 34-78 |
|
||
| `backend/src/common/utils/openapi31.ts` | ✅ exists (created in `de27a8b`) |
|
||
| `backend/src/main.ts` | ✅ lines 83-94 |
|
||
| `tests/backend/openapi31.spec.ts` | ✅ exists, 7 tests passing |
|
||
|
||
## 3. Proposed Changes
|
||
|
||
No code changes required. If a follow-up task wants to extend the existing
|
||
implementation (e.g., add an `info.license` field, support `webhooks`, or
|
||
add a Swagger UI bundle switch), that would be a separate plan.
|
||
|
||
## 4. Test Strategy
|
||
|
||
- The existing `tests/backend/openapi31.spec.ts` (7 tests) locks the
|
||
conversion behaviour.
|
||
- The full suite `npm test` passes 83/83 across 18 suites.
|
||
- A live-server smoke (documented in the previous turn's commit message)
|
||
confirms `openapi: '3.1.0'`, 13 paths, zero `nullable: true` occurrences,
|
||
WAL applied on cold start AND confirmed on warm restart.
|
||
|
||
## 5. Persistent `/data` Usage
|
||
|
||
No change. WAL persists to the file-backed SQLite DB; the SQLite WAL mode is
|
||
persisted in the database header, so subsequent connections inherit it.
|
||
|
||
## 6. Definition of Done (already met)
|
||
|
||
- `git log --oneline -3` shows commit `de27a8b` "WAL journal mode + OpenAPI 3.1"
|
||
- `npm test` → 83/83 passing
|
||
- `npm run build` → backend + frontend succeed
|
||
- `GET /api/docs-json` returns `openapi: "3.1.0"`
|
||
- Cold start log: `PRAGMA journal_mode set (was='delete', now='wal')`
|
||
- Warm start log: `PRAGMA journal_mode=wal (already set)`
|
||
- Zero `nullable: true` occurrences in the served JSON document
|
||
|
||
**[ALREADY_IMPLEMENTED]** — All three requested changes exist on the branch
|
||
in commits `de27a8b` (WAL + OpenAPI 3.1). No further code changes are needed
|
||
unless the reviewer wants to extend the implementation with additional
|
||
OpenAPI 3.1 features (webhooks, license, contact, etc.) or additional SQLite
|
||
PRAGMAs. |