gitea-actions[bot]
64 lines
2.1 KiB
Markdown
64 lines
2.1 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.
|
|
- 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.
|