Nikolay Tatarinov
fa22976e75
- Updated Mini App design guidelines to include detailed instructions on UI changes, accessibility rules, and verification processes. - Refactored multiple components to utilize `MiniAppScreen` and `MiniAppScreenContent` for consistent layout structure across the application. - Improved error handling in `GlobalError` and `NotFound` components by integrating new layout components for better user experience. - Introduced new hooks for admin functionality, streamlining access checks and data loading processes. - Enhanced documentation to reflect changes in design policies and component usage, ensuring clarity for future development.
120 lines
4.7 KiB
Markdown
120 lines
4.7 KiB
Markdown
# Webapp-next Refactor Baseline Audit
|
|
|
|
This note captures the baseline before the phased refactor. It defines current risks,
|
|
duplication hotspots, and expected behavior that must not regress.
|
|
|
|
## 1) Screens and boundaries
|
|
|
|
- Home route orchestration: `webapp-next/src/app/page.tsx`
|
|
- Chooses among `AccessDeniedScreen`, `CurrentDutyView`, `CalendarPage`.
|
|
- Controls app visibility via `appContentReady`.
|
|
- Admin route orchestration: `webapp-next/src/app/admin/page.tsx`
|
|
- Thin route, but still owns shell duplication and content-ready signaling.
|
|
- Calendar composition root: `webapp-next/src/components/CalendarPage.tsx`
|
|
- Combines sticky layout, swipe, month loading, auto-refresh, settings button.
|
|
- Current duty feature root: `webapp-next/src/components/current-duty/CurrentDutyView.tsx`
|
|
- Combines data loading, error/access states, back button, and close action.
|
|
- Admin feature state root: `webapp-next/src/components/admin/useAdminPage.ts`
|
|
- Combines SDK button handling, admin access, users/duties loading, sheet state,
|
|
mutation and infinite scroll concerns.
|
|
|
|
## 2) Telegram integration touchpoints
|
|
|
|
- SDK/provider bootstrap:
|
|
- `webapp-next/src/components/providers/TelegramProvider.tsx`
|
|
- `webapp-next/src/components/ReadyGate.tsx`
|
|
- `webapp-next/src/lib/telegram-ready.ts`
|
|
- Direct control usage in feature code:
|
|
- `backButton` in `CurrentDutyView` and `useAdminPage`
|
|
- `settingsButton` in `CalendarPage`
|
|
- `closeMiniApp` in `CurrentDutyView`
|
|
- Haptics in feature-level handlers:
|
|
- `webapp-next/src/lib/telegram-haptic.ts`
|
|
|
|
Risk: platform behavior is spread across feature components instead of a narrow
|
|
platform boundary.
|
|
|
|
## 3) Layout and shell duplication
|
|
|
|
Repeated outer wrappers appear across route and state screens:
|
|
- `content-safe min-h-[var(--tg-viewport-stable-height,100vh)] bg-background`
|
|
- `mx-auto flex w-full max-w-[var(--max-width-app)] flex-col`
|
|
|
|
Known locations:
|
|
- `webapp-next/src/app/page.tsx`
|
|
- `webapp-next/src/app/admin/page.tsx`
|
|
- `webapp-next/src/components/CalendarPage.tsx`
|
|
- `webapp-next/src/components/states/FullScreenStateShell.tsx`
|
|
- `webapp-next/src/app/not-found.tsx`
|
|
- `webapp-next/src/app/global-error.tsx`
|
|
|
|
Risk: future safe-area or viewport fixes require multi-file edits.
|
|
|
|
## 4) Readiness and lifecycle coupling
|
|
|
|
`appContentReady` is set by multiple screens/routes:
|
|
- `page.tsx`
|
|
- `admin/page.tsx`
|
|
- `CalendarPage.tsx`
|
|
- `CurrentDutyView.tsx`
|
|
|
|
`ReadyGate` is route-agnostic, but signaling is currently ad hoc.
|
|
Risk: race conditions or deadlock-like "hidden app" scenarios when screen states
|
|
change in future refactors.
|
|
|
|
## 5) Async/data-loading duplication
|
|
|
|
Repeated manual patterns (abort, retries, state machine):
|
|
- `webapp-next/src/hooks/use-month-data.ts`
|
|
- `webapp-next/src/components/current-duty/CurrentDutyView.tsx`
|
|
- `webapp-next/src/components/admin/useAdminPage.ts`
|
|
|
|
Risk: inconsistent retry/access-denied behavior and difficult maintenance.
|
|
|
|
## 6) Store mixing concerns
|
|
|
|
`webapp-next/src/store/app-store.ts` currently mixes:
|
|
- session/platform concerns (`lang`, `appContentReady`, `isAdmin`)
|
|
- calendar/domain concerns (`currentMonth`, `pendingMonth`, duties/events)
|
|
- view concerns (`currentView`, `selectedDay`, `error`, `accessDenied`)
|
|
|
|
Risk: high coupling and larger blast radius for otherwise local changes.
|
|
|
|
## 7) i18n/a11y gaps to close
|
|
|
|
- Hardcoded grid label in `CalendarGrid`: `aria-label="Calendar"`.
|
|
- Hardcoded sr-only close text in shared `Sheet`: `"Close"`.
|
|
- Mixed language access strategy (`useTranslation()` vs `getLang()/translate()`),
|
|
valid for bootstrap/error boundary, but not explicitly codified in one place.
|
|
|
|
## 8) Telegram Mini Apps compliance checklist (baseline)
|
|
|
|
Already implemented well:
|
|
- Dynamic theme + runtime sync.
|
|
- Safe-area/content-safe-area usage via CSS vars and layout classes.
|
|
- `ready()` gate and Telegram loader handoff.
|
|
- Android low-performance class handling.
|
|
|
|
Needs explicit policy/consistency:
|
|
- Vertical swipes policy for gesture-heavy screens.
|
|
- Closing confirmation policy for stateful admin flows.
|
|
- Main/Secondary button usage policy for primary actions.
|
|
- Terminology alignment with current official docs:
|
|
`safeAreaInset`, `contentSafeAreaInset`, fullscreen events.
|
|
|
|
## 9) Expected behavior (non-regression)
|
|
|
|
- `/`:
|
|
- Shows access denied screen if not allowed.
|
|
- Opens current-duty view for `startParam=duty`.
|
|
- Otherwise opens calendar.
|
|
- `/admin`:
|
|
- Denies non-admin users.
|
|
- Loads users and duties for selected admin month.
|
|
- Allows reassignment with visible feedback.
|
|
- Error/fallback states:
|
|
- `not-found` and global error remain full-screen and theme-safe.
|
|
- Telegram UX:
|
|
- Back/settings controls remain functional in Telegram context.
|
|
- Ready handoff happens when first useful screen is visible.
|