chore: initial commit

2026-06-25 00:34:34 +08:00
commit 3cce1be162
295 changed files with 30971 additions and 0 deletions
@@ -0,0 +1,34 @@
+# ADR 0001: LCD Expression and Presentation Ownership
+
+## Status
+
+Accepted
+
+## Context
+
+LCD behavior now needs multiple reusable expressions that can be triggered by
+different runtime conditions. The system must keep semantic expression ownership
+separate from low-level LCD playback so future expressions can be added without
+copying cross-layer contracts or coupling orchestration code to asset paths.
+
+## Decision
+
+- `domain` owns LCD expression semantics and declares `domain_expression_*` in
+  `components/domain/include/domain.h`.
+- `control_plane` owns trigger policy: it decides when a runtime condition
+  requests a semantic expression.
+- `platform` owns LCD presentation playback primitives and declares
+  `platform_lcd_presentation_*` in `components/platform/include/platform.h`.
+- Domain runtime adapters map semantic expressions to platform presentation
+  requests.
+- Platform LCD internals serialize presentation requests and perform all LVGL
+  object mutation inside the LCD render task.
+
+## Consequences
+
+- Adding a new expression requires a domain expression ID and catalog mapping,
+  plus an optional control-plane trigger rule.
+- Public upper-layer facades must not expose platform playback types.
+- Platform public APIs must not expose domain semantic expression IDs.
+- High-priority expressions can interrupt lower-priority presentations without
+  leaking policy logic into the LCD driver.
@@ -0,0 +1,37 @@
+# ADR 0002: Daily Fortune Contract Ownership
+
+## Status
+
+Accepted
+
+## Context
+
+The device needs to receive a user birth profile over its LAN configuration
+page, persist it, fetch a daily fortune after wall-clock
+synchronization, and apply the returned wealth direction. This workflow crosses
+transport, storage, domain data, and orchestration boundaries.
+
+## Decision
+
+- `platform` owns opaque persistent blob storage, SNTP time synchronization,
+  and bounded raw LAN HTTP transport primitives.
+- `domain` owns the typed birth-profile and daily-fortune result contracts,
+  persistence adapters, direction-name aliases, and user configuration routes.
+- `control_plane` owns HTTP fetch, retry, local-midnight scheduling, result
+  refresh policy, configuration-server connectivity lifecycle, and the
+  wealth-direction apply sequence.
+- `app_composition` continues to start the existing control-plane runtime worker
+  set and does not gain fortune policy logic.
+- The favorable-color element is persisted and logged. LCD color presentation
+  is deferred because it requires a separate semantic expression contract and
+  assets.
+
+## Consequences
+
+- The stateless server can be called every day because the device retains the
+  birth profile in NVS through an opaque platform storage API.
+- Upper layers do not include platform types or call platform LCD primitives.
+- Cardinal server values such as `正北` are normalized by the domain direction
+  catalog rather than by orchestration code.
+- Any future favorable-color animation requires a new ADR or an explicit update
+  to the existing LCD expression ownership decision.
@@ -0,0 +1,33 @@
+# ADR 0003: LAN User Configuration Transport and Lifecycle
+
+## Status
+
+Accepted
+
+## Context
+
+The browser-based birth-profile workflow previously depended on Web Bluetooth
+and an externally hosted page. It must instead run from the ESP32 and be
+reachable by devices on the same local network.
+
+## Decision
+
+- Remove the BLE provisioning transport and Web Bluetooth utility.
+- Retain the existing `TQ-EYE` SoftAP portal only for initial Wi-Fi setup.
+- `platform` owns a bounded raw HTTP server contract, socket worker lifecycle,
+  mDNS publication, request limits, and deterministic stop fallback.
+- `domain` owns the embedded page, `/api/profile` and `/api/fortune` semantics,
+  validation, persistence calls, and mapping to platform HTTP types.
+- `control_plane` starts the domain web service while STA is connected, stops
+  it on disconnect or runtime shutdown, and retries start after reconnect.
+- The service is plain HTTP without authentication and is intended only for a
+  trusted LAN. It is advertised as `tq-cat.local` and logs the DHCP address.
+
+## Consequences
+
+- Browsers no longer need Web Bluetooth support or a separately hosted page.
+- User information is readable and writable by any client on the same LAN.
+- SoftAP and LAN pages remain separate, so the vendored Wi-Fi portal does not
+  need project-specific user-profile semantics.
+- A future authentication or HTTPS requirement needs a separate decision and
+  credential lifecycle design.
@@ -0,0 +1,35 @@
+# ADR 0004: Device Auth Persistence Port Ownership
+
+## Status
+
+Accepted
+
+## Context
+
+Device authentication persists long-lived key material and runtime JWT/backoff
+state. The bytes are meaningful only to the authentication policy, but the
+storage location also needs legacy migration names and must stay off the
+generic platform key/value API at upper layers.
+
+## Decision
+
+- `platform` owns only opaque blob key/value primitives and NVS mechanics.
+- `domain` owns the narrow auth persistence port: the public auth record slot
+  enum, mapping to storage namespaces/keys, legacy migration target names, and
+  atomic load/save adapter.
+- `control_plane` owns the serialized auth key/state schemas, challenge/response
+  policy, JWT refresh policy, retry/backoff state transitions, and factory
+  rotation behavior.
+- Upper layers must not call generic storage adapters for auth records. They
+  must use `domain_runtime_auth_store_load_record()` and
+  `domain_runtime_auth_store_save_record()`.
+
+## Consequences
+
+- Auth persistence has one facade declaration without exposing platform storage
+  types to `control_plane`.
+- Changing the serialized record layout remains a `control_plane` migration
+  concern.
+- Changing NVS namespace/key migration names remains a `domain` adapter concern.
+- A future secure-element or encrypted-storage backend can replace the platform
+  blob primitive without changing auth policy contracts.