Files
pages/docs/design/city-organization-ui.md
T
Anya Tokugawa c1175d389f Implement Knowledge City platform, organizer and DAV integration
Capture accumulated application, UI, CLI, regression tests and design documentation changes, including task project mapping and default CalDAV list naming.

Keep deployment data, backups, local credentials and build artifacts out of Git. Move the Compose enrollment token to an ignored local environment file.
2026-09-27 14:44:43 +09:00

4.8 KiB

City organization UI

Implemented follow-up, 2026-09-13. This is a bounded manual editing slice of the City review, not the automatic outbox or Worker pipeline.

User model

Hierarchy remains Quartier → Street → Spot → Page; a Spot cannot own a Spot. Yellow-green points are unclassified Pages, not nested Spot objects.

  • Context menu or inspector pencil: edit a locality's display title. UUID, slug/name and Path remain unchanged. Japanese titles are accepted.
  • Ctrl/Command-click toggles selection of Page buildings/points or whole Spots. Selection persists while navigating between Streets. As of 2026-09-14, ordinary Spot clicks explore a courtyard; Page buildings and the separate portal link navigate to documents. See immersive map projection.
  • The floating icon toolbar/context menu can combine the selection into an existing Spot, or create one Spot containing the selected Pages.
  • Whole-Spot merge archives the sources, transfers Page placements and incoming/outgoing relations, deduplicates relations and drops self-relations. Source descriptions/charters remain on archived rows; they are not concatenated into the destination. Existing destination labels take precedence over duplicates.
  • Move relocates whole Spots to a Street, retaining UUIDs. Path boundaries change atomically with Street placement. Single moves allow a custom boundary; bulk moves use the old boundary's final segment under the new Street. Conflicts or invalid ancestry reject the entire operation.

These operations preserve document URLs, Page UUIDs, Revisions and content. Moving a Spot captures its existing inferred members as explicit memberships; the moved boundary may infer new Pages too. This is a City/SpotGraph operation, not recursive filesystem/URL rename. The modal explains the distinction before submission. Changing document URLs remains a separate Path operation.

Backend contract

  • POST /_/api/v1/city/{zones|spots}/{uuid}/title: title and mandatory base_version; zones additionally supply kind=quartier|street.
  • POST /_/api/v1/city/organize: mandatory base_version, action=merge|move, whole-Spot UUIDs and/or {spot_uuid,page_uuid} selections. Merge chooses exactly one of target_spot_uuid and a new_spot definition. Move accepts whole Spots and a destination Street only.
  • Both routes require existing Domain administrator/manage authorization. Targets, sources, parents and Page membership are revalidated inside the transaction against the current Domain. Stale topology returns 409.
  • Selection is limited to 200 entries. Expansion is capped at 2,000 Page-edge placements and 2,000 affected relations; larger operations fail without partial application. This is not a background bulk-import API.
  • Transfer, archive/move, overrides and one topology event/version increment commit together. Title no-ops do not increment versions. Validation/DB failures roll back everything; retries using an old version cannot reapply.
  • Audit events store requests, source placements and previous Path/Street boundaries. No automatic undo UI or exact reverse-operation endpoint exists yet; this is not a complete reversible merge implementation.

city_page_overrides(domain_uuid,page_uuid,spot_uuid) records manual placement. Active overrides prevent autoplan reconstructing old assignments and suppress inferred membership in other Spots. Other explicit MagicPage edges remain valid. An archived destination no longer suppresses inference; overrides are carried forward when its whole Spot is merged again. This is not the future full generation-provenance/outbox design or a general exclusion-management UI.

Normal and popup views share a themed native modal and selection toolbar; Ctrl/Command-click in a popup must not trigger top-window navigation. The generator seed no longer includes topology version, and its in-page fabric is reused on reload so renaming does not randomly rebuild the town. Allocation can still change with membership weights; Worker generation and persistent geometry caching remain open.

Verification and remaining work

Store/API tests cover Unicode titles, identity/URL preservation, stale requests, admin denial, invalid/cross-Domain selections, relation transfer/deduplication, inference preservation, and rollback after injected mid-write failure. Chromium tests exercise Ctrl selection/deselection, grouping undefined Pages, rename, whole-Spot merge, relocation and autoplan overrides in normal/popup modes.

Remaining: editable slug aliases and redirects for merged Spot detail URLs; per-Page override management/undo; URL-renaming with explicit preview; bounded automatic reconciliation; projection authorization/read scaling; Worker/geometry capacity fixes and directional keyboard navigation.