2.6 KiB
2.6 KiB
Context
Device-fingerprint capability spans the data layer, switch-orchestration layer, and UI management layer. Historical proposals split the same capability across multiple change IDs, which fragmented implementation and acceptance criteria. This design combines "feature completeness + robustness" into a single constraint set to keep implementation, verification, and release aligned.
Goals / Non-Goals
- Goals:
- Unify scope and acceptance criteria for device-fingerprint capability.
- Ensure behavioral consistency and diagnosability for local/cloud switching.
- Keep consistent behavior on default paths across Windows/macOS/Linux.
- Keep legacy-data compatibility predictable and verifiable.
- Non-Goals:
- Support for non-default runtime configuration paths.
- Business strategy expansion unrelated to this capability.
Decisions
- Decision: Use a single change ID to manage the complete capability.
- Rationale: Reduce governance overhead caused by duplicate proposals.
- Decision: Apply fingerprint using a two-phase flow with strict pre-commit verification.
- Rationale: Reduce mixed-state risk caused by partial success.
- Decision: Use versioned payload + boundary validation for fingerprint/history data.
- Rationale: Avoid silent data contamination and define clear compatibility/failure boundaries.
- Decision: Use fail-fast semantics for switch failures and return structured failure reasons.
- Rationale: Make failure behavior predictable and observable.
- Decision: Trigger safe mode for temporary degradation after consecutive failures.
- Rationale: Keep switching flow available during fault windows.
Risks / Trade-offs
- Risk: Stricter validation may reject legacy dirty data.
- Mitigation: Normalize missing optional fields; fail-fast only for critical structure errors.
- Risk: Validation and diagnostic extensions add minor performance cost.
- Mitigation: Keep validation lightweight and limited to critical boundaries.
- Risk: More UI management actions may increase user misoperations.
- Mitigation: Add confirmation interactions and unit-test coverage for failure branches.
Migration Plan
- Use
update-device-fingerprint-hardeningas the single active proposal. - Merge historical duplicate proposal content into this proposal (
proposal/design/tasks/spec). - Close and remove duplicate proposal directories.
- Deliver with unified task checklist and acceptance checklist.
Open Questions
- Should safe mode exit only by time window, or also allow manual recovery?
- Should diagnostic snapshots be exposed in the renderer as a visual panel?