merca y ch
This commit is contained in:
Marcelo
185
dev_plan_1.md
Normal file
185
dev_plan_1.md
Normal file
@@ -0,0 +1,185 @@
|
||||
<!-- --># Casa Benell - Dev Plan 1
|
||||
|
||||
## Goal
|
||||
Stabilize UI quality (responsive + proportional typography), adopt final brand assets, and start backend foundations for users/roles/invitations with PostgreSQL and SMTP.
|
||||
|
||||
## Current pain points (from first pass)
|
||||
- Typography scale is too large in several views.
|
||||
- Numeric values overflow cards and break layout.
|
||||
- Desktop-first layout is not fully adaptive on mobile.
|
||||
- Sidebar needs a true mobile hamburger/sheet pattern.
|
||||
- Brand assets in use are placeholders, not final logo/character files.
|
||||
- No DB/auth/invite flow yet (all role switching is local UI state).
|
||||
|
||||
## Inputs confirmed
|
||||
- Final logo source: `/home/mdares03/benell/example_ui_img/benell_logo.webp`
|
||||
- Theme character source: `/home/mdares03/benell/example_ui_img/Logo Benito.png`
|
||||
|
||||
## Implementation strategy (phased)
|
||||
|
||||
### Phase 1 - Responsive UI hardening
|
||||
Scope:
|
||||
- Normalize type scale and spacing so content always fits card boundaries.
|
||||
- Prevent number overflow in KPI cards, tables, and right panels.
|
||||
- Add mobile nav with hamburger + slide-out menu.
|
||||
- Improve responsive behavior for top bar filters/search/role selector.
|
||||
|
||||
Tasks:
|
||||
1. Define responsive typography tokens with `clamp(...)` and semantic utility classes.
|
||||
2. Replace oversized heading/body classes with tokenized scale:
|
||||
- H1/H2/H3/body/label/caption.
|
||||
3. Apply overflow-safe text rules:
|
||||
- `min-w-0` in flex/grid children.
|
||||
- `truncate`/`break-words` where needed.
|
||||
- `tabular-nums` for KPI numeric alignment.
|
||||
4. Refactor cards/tables to use adaptive grids:
|
||||
- desktop: 4 columns where available
|
||||
- tablet: 2 columns
|
||||
- mobile: 1 column
|
||||
5. Build mobile sidebar pattern:
|
||||
- top-left hamburger button
|
||||
- drawer/sheet navigation
|
||||
- keyboard and focus support
|
||||
6. Make Sankey containers responsive with controlled heights by breakpoint.
|
||||
7. Validate at widths: 360, 390, 768, 1024, 1280, 1536.
|
||||
|
||||
Acceptance criteria:
|
||||
- No text or numbers overflow containers at target breakpoints.
|
||||
- Dashboard, Financial Flow, Meetings, People remain usable on mobile.
|
||||
- Navigation works via sidebar (desktop) and hamburger drawer (mobile).
|
||||
|
||||
---
|
||||
|
||||
### Phase 2 - Final brand asset integration
|
||||
Scope:
|
||||
- Replace placeholder brand files with provided official assets.
|
||||
|
||||
Tasks:
|
||||
1. Copy and normalize assets into `/public/brand/`:
|
||||
- `logo.webp` from `benell_logo.webp`
|
||||
- `mascot.png` from `Logo Benito.png`
|
||||
2. Update components to use final files in:
|
||||
- sidebar/header brand block
|
||||
- login page
|
||||
- empty states
|
||||
3. Verify object-fit/crop so assets render clean on desktop + mobile.
|
||||
|
||||
Acceptance criteria:
|
||||
- Only final brand assets are used in app shell and empty states.
|
||||
- No stretching, clipping, or quality loss in common viewport sizes.
|
||||
|
||||
---
|
||||
|
||||
### Phase 3 - PostgreSQL foundation + RBAC data model
|
||||
Scope:
|
||||
- Start real user data layer with psql.
|
||||
- Keep mock business metrics for now, but migrate auth/user/role from local store to DB-backed model.
|
||||
|
||||
Tech decisions (proposed):
|
||||
- ORM: Prisma
|
||||
- DB: PostgreSQL
|
||||
- Auth/session: NextAuth/Auth.js with DB adapter
|
||||
- Password hashing: bcrypt
|
||||
- Email: Nodemailer SMTP transport
|
||||
|
||||
Core schema (initial):
|
||||
1. `users`
|
||||
- `id`, `name`, `email` (unique), `password_hash`, `status`, `created_at`, `updated_at`
|
||||
2. `roles`
|
||||
- `id`, `key` (`owner|leader|employee`), `name`
|
||||
3. `user_roles`
|
||||
- `user_id`, `role_id` (many-to-many)
|
||||
4. `invitations`
|
||||
- `id`, `email`, `role_key`, `token_hash`, `expires_at`, `accepted_at`, `invited_by`, `created_at`
|
||||
5. `user_locations` (optional in this phase, recommended)
|
||||
- `user_id`, `location_id`
|
||||
|
||||
Tasks:
|
||||
1. Add Prisma and configure `DATABASE_URL`.
|
||||
2. Create schema + first migration.
|
||||
3. Add seed script for default roles and bootstrap owner account.
|
||||
4. Add auth route handlers and session callback to include role.
|
||||
5. Add middleware route protection for authenticated app routes.
|
||||
6. Replace UI-only role switcher with role from session (keep optional dev override flag).
|
||||
|
||||
Acceptance criteria:
|
||||
- App can connect to PostgreSQL locally.
|
||||
- At least one owner user can login from DB.
|
||||
- Protected routes reject anonymous requests.
|
||||
- Role can be read from DB session payload.
|
||||
|
||||
---
|
||||
|
||||
### Phase 4 - Invitation flow via SMTP
|
||||
Scope:
|
||||
- Admin/owner can invite users by email and assign role.
|
||||
|
||||
Tasks:
|
||||
1. Add env variables for SMTP and app URLs.
|
||||
2. Create server actions or API routes:
|
||||
- `POST /api/invitations`
|
||||
- `POST /api/invitations/accept`
|
||||
3. Generate secure random invitation tokens; store hash only.
|
||||
4. Send email with invitation link (token + expiry).
|
||||
5. Create acceptance page:
|
||||
- set password
|
||||
- confirm profile basics
|
||||
- finalize user + role assignment
|
||||
6. Add invitation status UI in admin/settings page.
|
||||
|
||||
Acceptance criteria:
|
||||
- Owner can send invite with selected role.
|
||||
- Recipient can accept invite and create account before expiry.
|
||||
- Used/expired tokens are rejected.
|
||||
|
||||
---
|
||||
|
||||
### Phase 5 - Operational readiness and migration cleanup
|
||||
Scope:
|
||||
- Make deployment process stable under existing systemd flow.
|
||||
|
||||
Tasks:
|
||||
1. Add `.env.example` with required vars only (no secrets).
|
||||
2. Add startup checks for missing env values.
|
||||
3. Document production sequence:
|
||||
- `npm run build`
|
||||
- `sudo systemctl restart benell.service`
|
||||
4. Add backup/rollback notes for DB migrations.
|
||||
|
||||
Acceptance criteria:
|
||||
- Clear runbook for local/prod env setup.
|
||||
- No manual guessing for env keys or migration order.
|
||||
|
||||
## Environment variables to add (planned)
|
||||
- `DATABASE_URL=postgresql://...`
|
||||
- `NEXTAUTH_URL=https://benell.maliountech.com.mx`
|
||||
- `NEXTAUTH_SECRET=...`
|
||||
- `SMTP_HOST=...`
|
||||
- `SMTP_PORT=587`
|
||||
- `SMTP_USER=...`
|
||||
- `SMTP_PASS=...`
|
||||
- `SMTP_FROM="Casa Benell <noreply@...>"`
|
||||
- `INVITE_TTL_HOURS=72`
|
||||
|
||||
## Risks and mitigations
|
||||
- Risk: auth migration blocks UI progress.
|
||||
- Mitigation: complete UI responsive fixes first, then backend integration.
|
||||
- Risk: role logic duplicated in client and server.
|
||||
- Mitigation: single source of truth from session role, with temporary dev override only.
|
||||
- Risk: invite token leakage.
|
||||
- Mitigation: store hashed tokens, set short expiry, single-use tokens.
|
||||
|
||||
## Execution order
|
||||
1. Phase 1 (UI hardening)
|
||||
2. Phase 2 (brand assets)
|
||||
3. Phase 3 (DB + auth + RBAC)
|
||||
4. Phase 4 (SMTP invites)
|
||||
5. Phase 5 (runbook + stability)
|
||||
|
||||
## Deliverables for this plan
|
||||
- Responsive and proportional UI baseline.
|
||||
- Mobile hamburger navigation.
|
||||
- Final branding applied.
|
||||
- PostgreSQL user/role foundation.
|
||||
- SMTP invitation workflow.
|
||||
- Updated docs for env and deployment.
|
||||
Reference in New Issue
Block a user