93 lines
5.8 KiB
Markdown
93 lines
5.8 KiB
Markdown
# PagesWiki design documentation
|
||
|
||
## Current reading order
|
||
|
||
The reorganized Japanese handbook is [ja/index.md](ja/index.md), published under
|
||
`https://pages.anya.jp/lab/pageswiki-dev/`. It separates implemented slices,
|
||
proposals, unresolved decisions and delivery gates. Its chapter identifiers are
|
||
language-neutral; existing English source documents remain here for traceability
|
||
and future aligned translations, not as automatically current English editions.
|
||
|
||
- Concepts and boundaries: chapters 1–6.
|
||
- [Organizer navigation and personal dashboard](ja/organizer-dashboard.md): shared navigation,
|
||
personal settings, resizable widgets, owner-scoped layout storage and extension boundaries.
|
||
- [Task capture, work reporting and private address book](ja/task-productivity-contacts.md):
|
||
shared Web/CLI API, neomutt, defaults, daily digest and home search commands.
|
||
- Existing product and runtime: chapters 7–11.
|
||
- Organizer / task / calendar / RSS / mail / HTML editing proposals: chapters 12–17.
|
||
- Operations, i18n, ordered work, decisions and sources: chapters 18–22.
|
||
- [Source-to-chapter inventory](ja/sources.md).
|
||
- [Decision and inconsistency register](ja/decisions.md).
|
||
- [Component names and responsibilities](ja/component-names.md): adopted subsystem names,
|
||
all eight initial extractions, compatibility boundaries and the remaining component work.
|
||
- [Dregarnuhr scheduler contract](ja/dregarnuhr.md): application registration, queue persistence,
|
||
concurrency/retry tests and the remaining lease/HA/shutdown work.
|
||
- [Geduldh document storage contract](ja/geduldh.md): immutable local payloads, bounded scratch copies,
|
||
compatibility facades, Range/backfill/DR verification and remaining backend work.
|
||
- [Mestionora search and index contract](ja/mestionora.md): SQLite/City lookup, explicit read policies,
|
||
bounded enrichment, query-plan compatibility and remaining indexing/policy work.
|
||
- [Ordoschnellic notification delivery contract](ja/ordoschnellic.md): bounded Web Push dispatch,
|
||
transactional Inbox enqueue, privacy, retry/lease compatibility and remaining fencing/observability work.
|
||
- [Schutzaria authorization and publication contract](ja/schutzaria.md): pure policy evaluation,
|
||
immutable request snapshots, retained application checks and remaining consistency/reviewer work.
|
||
- [Kunstzeal projection and renderer contract](ja/kunstzeal.md): stable adapter selection, bounded
|
||
Kroki execution, source authorization, atomic derived cache and remaining provider/runtime work.
|
||
- [Seheweit observation contract](ja/seheweit.md): bounded local collection, compatible snapshots,
|
||
history windows/retention, cancellation and remaining availability/rollup/provider metrics work.
|
||
- [Editor resilience subproject](ja/editor-resilience.md): drafts, conditional saves,
|
||
conflict resolution, mobile authoring, language/history, round-trip preservation and collaboration gates.
|
||
- [Storage portability and operations](storage-portability-and-operations.md): backend contracts,
|
||
migration/backfill, backup/export/import and setup phases;
|
||
[read-only schema preflight and rollout](../operations/storage-schema-rollout.md).
|
||
|
||
## Document roles
|
||
|
||
DRの詳細設計・初版CLI・復旧手順は [単一writerのDR](ja/disaster-recovery.md) を参照。
|
||
インスタンス単位の停止snapshotと手動昇格を先行し、自動切替・オンライン同期は未実装。
|
||
|
||
次段階のDR-D1は**詳細設計完了・実装未着手**:
|
||
[役割分離と再参加](ja/dr-authority-and-rejoin.md)、
|
||
[protocol・同期・切替](ja/dr-protocol-and-sync.md)、
|
||
[実施計画と受入試験](ja/dr-delivery-plan.md)。DB別件と独立して文書化し、
|
||
保存側の能力契約が未提供の場合は自動切替を有効化しない。
|
||
|
||
`arch.md`, `address-model.md`, `access-model.md`, `auth.md` and `i18n-delivery.md`
|
||
include original conceptual drafts. Detailed topic documents describe contracts
|
||
and implementation slices. `implementation-status.md` contains dated progress;
|
||
older paragraphs are historical and may be superseded. The roadmap is a task
|
||
inventory; the execution ledger is verification/deployment history, not a blanket
|
||
feature-completeness claim.
|
||
|
||
For new work, update the relevant chapter and detailed contract together. Keep
|
||
stable identity, authorization and bounded processing constraints. Do not convert
|
||
design proposals into active features or public grants merely by documenting them.
|
||
|
||
## Publication
|
||
|
||
Japanese Markdown under `ja/` is the editing source. The documentation export
|
||
tool renders canonical HTML with the application's Markdown renderer, validates
|
||
chapter links, and emits a manifest. Upload through the trusted data CLI with an
|
||
explicit Domain and `PAGESWIKI_LANG=ja`; no authentication/publication policy is
|
||
changed. Record resulting Page/Revision identities separately from source text.
|
||
English publication is deferred until an aligned translation and language UI
|
||
are ready. Never overwrite Japanese with English at language `und`.
|
||
|
||
Generate a fresh, empty staging directory, then run:
|
||
|
||
```sh
|
||
go run ./tools/design-export -out /tmp/pageswiki-design-staging
|
||
go test ./tools/design-export
|
||
```
|
||
|
||
The tool does not access the database or network. Review `manifest.json`, check
|
||
destination collisions, and select the correct database/Domain explicitly before
|
||
using `data/pageswiki-cli put` for each rendered HTML file and manifest Path.
|
||
The index maps to `/lab/pageswiki-dev`, not `/lab/pageswiki-dev/index`.
|
||
Do not blindly replace existing Wiki edits on a later publication: compare the
|
||
recorded Revision UUID/hash with the current head and resolve divergence first.
|
||
|
||
The initial upload receipt is [publication-ja-2026-09-19.json](publication-ja-2026-09-19.json).
|
||
All 23 canonical payloads were read back and compared. Source hashes and stored
|
||
Page/Revision identities support later language alignment. Anonymous HTTPS access
|
||
still redirects to login; this upload did not change public access settings.
|