gitea-actions[bot]
67 lines
2.3 KiB
Markdown
67 lines
2.3 KiB
Markdown
# 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. A ref may point to a word
|
|
supplied by the same package or to an already installed dependency such as an
|
|
official deck word.
|
|
- The same package shape is used for official, registry custom, imported, and
|
|
local-exported decks.
|
|
|
|
## Current Decks
|
|
|
|
- `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:japan-travel-essentials` is a cleaned custom deck generated
|
|
from the user-provided Japan travel CSV, with example sentences added for
|
|
app-side import and study testing.
|
|
|
|
This repository is still intentionally small so app migration, import, and
|
|
checksum handling can be tested before the full public deck corpus is populated.
|