data: scaffold word deck registry

2026-05-10 11:42:46 +09:00
commit 3b9e3a2d36
14 changed files with 700 additions and 0 deletions
@@ -0,0 +1,63 @@
+# Japanese Word Trainer Deck Registry
+
+This repository is the public word-deck data registry for the 0.3 package model.
+It keeps JSON as the source of truth and publishes zip package artifacts that the
+app can download and verify.
+
+## Layout
+
+- `registry.json` is the root registry file read by the app.
+- `sources/official/<slug>/` contains editable official deck package JSON.
+- `sources/custom/<slug>/` contains editable published custom deck package JSON.
+- `packages/*.zip` contains generated app-installable package artifacts.
+- `scripts/build_packages.py` builds packages and refreshes registry checksums.
+- `scripts/validate_registry.py` validates source JSON, packages, and checksums.
+
+Each package zip contains exactly:
+
+```text
+manifest.json
+words.json
+refs.json
+```
+
+## Build
+
+Run from the repository root:
+
+```bash
+python3 scripts/build_packages.py
+python3 scripts/validate_registry.py
+```
+
+`build_packages.py` fills each word `contentHash`, creates deterministic zip
+files in `packages/`, and updates `registry.json` with `wordCount`, `packageUrl`,
+and `sha256`.
+
+By default, `generatedAt` is left unchanged to avoid noisy rebuild diffs. Use
+`--update-generated-at` when intentionally publishing a freshly generated
+registry:
+
+```bash
+python3 scripts/build_packages.py --update-generated-at
+```
+
+## Package Rules
+
+- Stable deck keys use `{registryId}:deck:{slug}`.
+- Stable word keys use `{registryId}:word:{slug-or-id}`.
+- `versionCode` changes when package content changes.
+- `contentHash` is computed from a word record excluding `contentHash`.
+- `refs.json` owns deck membership and display order.
+- The same package shape is used for official, registry custom, imported, and
+  local-exported decks.
+
+## Current Samples
+
+- `official:deck:jlpt-n5` is a tiny official sample based lightly on the app
+  seed vocabulary. It is not the full JLPT N5 set.
+- `official:deck:travel-basic` is a sample published custom deck under the
+  official registry.
+
+The sample data is intentionally small so app migration, import, and checksum
+handling can be tested before the full public deck corpus is populated.