docs: define front-door module

2026-08-13 06:15:49 +08:00
parent d008c792ee
commit 60556ee187
5 changed files with 171 additions and 12 deletions
@@ -0,0 +1,85 @@
+# Phase 9.0R8 Front-Door Runtime Contract
+
+## State Map
+
+```text
+BOOT -> TITLE -> MAIN_MENU
+MAIN_MENU -> YARD
+MAIN_MENU <-> GAME_INTRO
+MAIN_MENU <-> SETTINGS
+gameplay Home/confirmed Restart -> MAIN_MENU
+```
+
+`BOOT` is automatic resource verification. `TITLE` is the visual identity and
+one explicit entry action. `MAIN_MENU` is the navigation authority. These are
+different states even when they reuse the same background.
+
+## Stable Controls
+
+| Page | Required controls |
+|---|---|
+| Title | `EnterGameButton` |
+| Main menu | `StartNewGameButton`, `GameIntroButton`, `SettingsButton` |
+| Introduction | `IntroductionBackButton` |
+| Settings | `SettingsLocaleButton`, `SettingsTextScaleButton`, `SettingsMotionButton`, `SettingsMuteButton`, `SettingsBackButton` |
+
+The main menu must not render `Continue`, `Load`, `Account` or release/store
+actions while their systems are absent.
+
+## Introduction Copy Authority
+
+The page answers four questions in player language:
+
+1. **Who am I?** The guild captain rebuilding an expedition Company across
+   broken wind roads.
+2. **What do I do first?** Choose one front and one rear Recruit, then depart.
+3. **Why is combat automatic?** The player builds the Company and reads the
+   threat; recruited roles execute the committed plan.
+4. **What changes between battles?** Diagnose the result, adapt equipment,
+   choose routes and train an individual member so the next encounter changes.
+
+It describes only the currently playable R7 flow. It does not advertise
+future chapters, saves, a Market or a complete profession catalog as present.
+
+## Settings Semantics
+
+Settings are session-local presentation values and never mutate gameplay:
+
+- language: `简体中文` / `English`;
+- text: `100%` / `130%`;
+- motion: `标准` / `减少动态`;
+- sound: `开启` / `静音`.
+
+Each row names the category, current value and effect. Tapping cycles the two
+declared values and immediately rerenders the current Settings page. Back keeps
+the selected presentation values and returns to Main Menu.
+
+## New Game And Home
+
+- `start_new_game` is legal only from Main Menu.
+- It calls the existing complete transient cleanup exactly once, then opens
+  the Guild Yard with the preserved first-choice guidance.
+- `go_home` and confirmed Restart clear the same transient state and return to
+  Main Menu.
+- Title entry, Introduction, Settings and Back never clear or create gameplay
+  state.
+
+## Presentation
+
+- Title remains an immersive world scene with identity and one command.
+- Main Menu uses the world as the dominant surface and one quiet command rail;
+  it is not a settings form or nested card dashboard.
+- Introduction uses an expedition path composition with four numbered beats.
+- Settings uses one parchment workbench with four full-width named rows.
+- Primary landscape is `844x390`; no scrolling; all actions at least 44px.
+- Portrait continues to request landscape orientation.
+
+## Evidence
+
+- Domain/navigation test proves legal page transitions, no fake Continue,
+  gameplay mutation boundaries and Home/Restart cleanup.
+- Real parsed ScreenTouch covers Title -> Main Menu -> Introduction -> Back ->
+  Settings -> all four changes -> Back -> New Game.
+- Normal rendering covers Boot success, Title, Main Menu, Introduction and
+  Settings in Chinese plus English/130% Settings.
+- P9.0R7 focused, touch and R3-R6 regressions remain green.