mirror of
https://github.com/clash-verge-rev/clash-verge-rev.git
synced 2026-10-26 14:12:10 +08:00
Tunglies
70d1298bc9
Layering rules for the contract flow: generated contract as the only wire-typing source, event bus as the only listen/emit site, pure-reducer store for event-derived state, the mutate funnel for user intent, and invoke only in the services layer — each backed by the CI gates.
2.2 KiB
2.2 KiB
Frontend Architecture Guardrails
These rules supplement the repository's root AGENTS.md. They define the
layering introduced by the frontend contract flow; violating any of them is
rework, not a review note.
- Contract is generated, never hand-typed. Event names, payload shapes,
and the
NoticeStatusunion come fromsrc/services/contract.ts(@generated). Regenerate withpnpm gen:contractafter changing the backend wire contract, and commit the result; CI regenerates and fails on a diff. Adding a backend status requires updating the exhaustive notice table (src/services/notice-handlers.ts) in the same PR — theRecord<NoticeStatus, …>type enforces it. No exceptions. listen(/emit(live only in the event bus. All Tauri event subscriptions and emissions go throughsrc/services/bus/, which mounts exactly once at the layout root and registers exactly one handler per event name. Components and pages never touch@tauri-apps/api/event. Window-lifecycle helpers that do not use the event-module API may stay with their owning component.- Event-derived state lives in the app store. Cross-component state
produced by events is written only through pure reducer actions dispatched
by the bus or the funnel (
src/store/). Handlers may perform documented side effects (SWR revalidation, notices) but must not write store state directly. New event-consumed state needs a reducer action first, not a localuseStatein a page. - User intent funnels through
mutate. Every mutating backend command call goes throughsrc/services/mutate.ts— components, hooks, and dialogs included. Give each intent a stableid; express optimistic writes asoptimistic/rollbackand success refreshes asrevalidate/onFulfilled. Flows with bespoke error UX keep it viaerrorNotice: false; suppressing both the funnel's and the site's handling is a bug. invoke(lives only in services. Backend commands are wrapped insrc/services/cmds.ts; mihomo-plugin mutations are governed by rule 4. Pages and components import the wrapper, never@tauri-apps/api/core. CI greps for this and rule 2 (node scripts/check-architecture.mjs listen emit invokemust stay clean).