soroush.asadi
03376b3ea1
Rewrites dashboard and finder Dockerfiles to use a clean multi-stage build (deps → builder → runner) that installs npm packages inside Alpine Linux, avoiding the SWC musl binary issue when building from Windows host. Uses registry.npmmirror.com for reliable installs from restricted networks (Iran). - docker/api/Dockerfile: .NET 10 multi-stage build - docker/web/Dockerfile: Node 20-alpine multi-stage, npmmirror - docker/finder/Dockerfile: Node 20-alpine multi-stage, npmmirror - docker/website/Dockerfile: marketing website build - scripts/: PowerShell helper scripts for local dev Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
394 lines
16 KiB
Markdown
394 lines
16 KiB
Markdown
# Meezi — Feature Roadmap Plan
|
||
|
||
> **Purpose:** Implementation plan for growth, operations, integrations, platform, and quality items.
|
||
> **Audience:** Product + engineering (solo/small team with Cursor).
|
||
> **Conventions:** `.cursorrules`, `ApiResponse<T>`, multi-tenant `CafeId`, `messages/{fa,ar,en}.json`, plan tiers Free / Pro / Business / Enterprise.
|
||
> **Last updated:** 2026-05-22
|
||
|
||
### Implementation status (started)
|
||
|
||
| Item | Status |
|
||
|------|--------|
|
||
| Q-1 `docs/SECURITY.md` | Done |
|
||
| Q-2 Playwright (`web/dashboard/e2e/`) | Done (API smoke + discover page) |
|
||
| Q-3 k6 `tests/load/public-abuse.js` | Done |
|
||
| G-1 API discover filters | Done |
|
||
| G-1 UI `/[locale]/discover` | Done (MVP) |
|
||
| Order `DisplayNumber` (digits-only) | Done |
|
||
| Table board SignalR (via KDS hub) | Done |
|
||
| O-4 Terminal Redis enforcement | Done (API + settings UI) |
|
||
| P-1 Admin split (`web/admin` + compose) | Partial (redirect from dashboard) |
|
||
| G-1 discover detail + Neshan embed | Done |
|
||
| G-6 Review owner reply (dashboard + public) | Done |
|
||
| G-4 Loyalty earn on pay | Done (1 pt / 10k ت) |
|
||
| O-1 Public queue ticket + plan gate + SMS | Done |
|
||
| O-3 Shift close UI | Done (`/shifts`) |
|
||
| I-2 Snappfood outbound on status/pay | Done |
|
||
|
||
---
|
||
|
||
## How to use this doc
|
||
|
||
- Work in **phases** (below); each phase is 2–4 weeks of focused PRs.
|
||
- Split work into **small PRs**: `api` | `dashboard` | `mobile` | `infra` | `docs`.
|
||
- Mark items **Built (thin)** vs **Greenfield** — don’t rebuild what already exists.
|
||
- **Plan gates** are called out per feature; wire via `IPlatformCatalogService` + `PlanLimitMiddleware` / `IPlanLimitChecker`.
|
||
|
||
---
|
||
|
||
## Current baseline (relevant to this roadmap)
|
||
|
||
| Area | Already in repo |
|
||
|------|------------------|
|
||
| Discover profile | `CafeDiscoverProfile`, merchant/admin editor, `GET /api/public/discover`, taxonomy |
|
||
| Reviews | `CafeReview`, public create; **`OwnerReply` on entity** — UI/public display thin |
|
||
| Queue | `QueueController`, `queue-screen.tsx`, feature flag `queue` in seeder |
|
||
| Loyalty | `Customer.LoyaltyPoints` field — **no earn/redeem rules or UI** |
|
||
| Delivery | Inbound webhooks (Snappfood/Tap30/Digikala), `DeliveryStatusSyncService` — **outbound Snappfood partial** |
|
||
| Terminals | `PlanLimits.MaxTerminals`, JWT/header patterns — **enforcement incomplete** |
|
||
| Security | Turnstile + Redis abuse limits — **`docs/SECURITY.md` missing** |
|
||
| Admin | `Meezi.Admin.API` exists; **admin UI still in `web/dashboard`** |
|
||
|
||
---
|
||
|
||
## Phase overview
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
P0[Phase 0\nQuality + Ops]
|
||
P1[Phase 1\nDiscover public]
|
||
P2[Phase 2\nGrowth CRM]
|
||
P3[Phase 3\nOperations]
|
||
P4[Phase 4\nIntegrations]
|
||
P5[Phase 5\nPlatform Enterprise]
|
||
P0 --> P1
|
||
P1 --> P2
|
||
P2 --> P3
|
||
P3 --> P4
|
||
P1 --> P4
|
||
P4 --> P5
|
||
```
|
||
|
||
| Phase | Theme | Outcome | Duration |
|
||
|-------|--------|---------|----------|
|
||
| **0** | Quality & ops docs | Safe public surface, CI confidence | 1–2 weeks |
|
||
| **1** | Public discover | Consumer-facing کافهیاب for Tehran/Karaj | 2–3 weeks |
|
||
| **2** | Growth & community | Loyalty, reviews 2.0, badges | 3–4 weeks |
|
||
| **3** | Operations | Queue polish, printers, shifts, terminals | 3–4 weeks |
|
||
| **4** | Integrations | Maps, delivery parity, hardware onboarding | 3–4 weeks |
|
||
| **5** | Platform & Enterprise | Admin split, API keys, audit, export | 4–6 weeks |
|
||
|
||
---
|
||
|
||
## Phase 0 — Quality & operations (do first)
|
||
|
||
### Q-1 — `docs/SECURITY.md` (ops)
|
||
|
||
| | |
|
||
|--|--|
|
||
| **Effort** | S (1 day) |
|
||
| **Deliverable** | Turnstile setup, Redis limits, rate-limit table, Arvan WAF/CDN rules (OTP, `/api/public/*`, `/api/q/*`), `X-Forwarded-For`, incident checklist |
|
||
| **Acceptance** | On-call can enable CAPTCHA and edge rules without reading source |
|
||
|
||
### Q-2 — Playwright E2E (dashboard)
|
||
|
||
| | |
|
||
|--|--|
|
||
| **Effort** | M (3–5 days) |
|
||
| **Scope** | `web/dashboard/e2e/`: auth OTP mock or test phone, POS happy path (table → item → pay), QR public order smoke (optional second project) |
|
||
| **CI** | Job on PR; secrets for test DB/API |
|
||
| **Acceptance** | 2–3 stable tests green in GitHub Actions |
|
||
|
||
### Q-3 — Load tests (public QR + OTP)
|
||
|
||
| | |
|
||
|--|--|
|
||
| **Effort** | M (2–3 days) |
|
||
| **Tool** | k6 or NBomber script in `tests/load/` |
|
||
| **Scenarios** | `GET /api/q/{code}`, `GET /api/public/.../menu`, `POST` guest order, `POST /api/auth/send-otp` |
|
||
| **Acceptance** | Document p95 targets; verify `429` / `RATE_LIMITED` under abuse |
|
||
|
||
### Q-4 — Package / Docker hardening
|
||
|
||
| | |
|
||
|--|--|
|
||
| **Effort** | S | NU1903 bumps, `nuget.config` + Dockerfile (done), CI `docker compose build api` optional job |
|
||
|
||
**Phase 0 exit:** SECURITY doc published, 2+ E2E tests, load script runnable locally.
|
||
|
||
---
|
||
|
||
## Phase 1 — Growth: public discover homepage
|
||
|
||
### G-1 — Public discover web app (Tehran / Karaj)
|
||
|
||
| | |
|
||
|--|--|
|
||
| **Effort** | L (1.5–2 weeks) |
|
||
| **Plan** | Free to browse; Pro+ cafés appear when `discover_profile` filled & `IsVerified` |
|
||
| **Route** | `web/dashboard/src/app/[locale]/(public)/discover/` **or** separate `web/discover` (lighter SEO) — recommend **public routes inside dashboard** first to reuse API client + i18n |
|
||
| **API** | Extend `GET /api/public/discover` with filters: `city` (تهران/کرج), `themes[]`, `vibes[]`, `occasions[]`, `spaceFeatures[]`, `noise`, `priceTier`, `minRating`, `sort` (rating, distance later) |
|
||
| **Backend** | Filter in SQL/EF on deserialized `DiscoverProfileJson` (JSONB query on PostgreSQL) or materialized columns if perf needed |
|
||
| **UI** | Filter chips (taxonomy from `GET /api/public/discover-profile/taxonomy`), café cards (cover, rating, badges, price tier), detail page → menu link / map link |
|
||
| **i18n** | `discoverPublic.*` in fa/ar/en |
|
||
| **Acceptance** | User can filter “date + outdoor + کرج” and open café detail; RTL correct |
|
||
|
||
### G-2 — Neshan maps (discover + detail) — *can start in Phase 1 or 4*
|
||
|
||
See **I-1** below; for discover MVP, static map embed on detail is enough.
|
||
|
||
**Phase 1 exit:** Public discover listing + detail live at `/fa/discover` (or dedicated host).
|
||
|
||
---
|
||
|
||
## Phase 2 — Growth & community (depth)
|
||
|
||
### G-3 — Customer accounts (lightweight)
|
||
|
||
| | |
|
||
|--|--|
|
||
| **Effort** | L (2 weeks) |
|
||
| **Plan** | Pro+ for “registered guests”; optional SMS OTP customer auth |
|
||
| **Model** | `CustomerAccount` (phone PK per platform or per cafe), link to `Customer` on first order; JWT `role=customer` scoped to optional `cafeId` or global |
|
||
| **API** | `POST /api/auth/customer/send-otp`, `verify-otp`, `GET /api/customers/me/orders`, `GET /api/customers/me/reservations` |
|
||
| **Apps** | `meezi_app`: login, order history; discover web: “my orders” |
|
||
| **Acceptance** | Returning guest sees past orders after OTP; no merge with staff JWT |
|
||
|
||
### G-4 — Loyalty points (earn / redeem)
|
||
|
||
| | |
|
||
|--|--|
|
||
| **Effort** | M–L (1.5 weeks) |
|
||
| **Built** | `Customer.LoyaltyPoints` |
|
||
| **Rules** | `LoyaltyRule` per cafe: earn % of paid order, min redeem, expiry; Business+ feature flag `loyalty` |
|
||
| **API** | Earn on order `Paid`; redeem as discount line on POS; `PATCH` adjust (manager) |
|
||
| **UI** | CRM customer row, POS pay panel preview, SMS on milestone (optional) |
|
||
| **Acceptance** | Closed order increases points; redeem reduces total with audit row |
|
||
|
||
### G-5 — Café badges (Enterprise)
|
||
|
||
| | |
|
||
|--|--|
|
||
| **Effort** | M (1 week) |
|
||
| **Plan** | Enterprise only; admin assigns badges |
|
||
| **Model** | `CafeBadge` (key, labelFa, icon, assignedAt) or JSON on `Cafe` |
|
||
| **API** | Admin CRUD; public discover DTO includes `badges[]` |
|
||
| **UI** | Admin café detail; discover cards show badge chips |
|
||
| **Acceptance** | Only Enterprise cafés display admin-assigned badges |
|
||
|
||
### G-6 — Review photos + owner responses (polish)
|
||
|
||
| | |
|
||
|--|--|
|
||
| **Effort** | M (1 week) |
|
||
| **Built** | `OwnerReply`, `OwnerRepliedAt` on `CafeReview` |
|
||
| **Photos** | `CafeReviewPhoto` (url, sort); upload via public or authenticated; max 3 photos, 5MB, MIME validate |
|
||
| **API** | `POST /api/public/cafes/{slug}/reviews` multipart; `PATCH /api/cafes/{cafeId}/reviews/{id}/reply` (owner) |
|
||
| **UI** | Dashboard reviews screen: reply editor; public discover detail: reviews + photos |
|
||
| **Moderation** | `IsHidden` flag; admin can hide (abuse) |
|
||
| **Acceptance** | Owner reply visible on public page; photos optional |
|
||
|
||
**Phase 2 exit:** Loyalty + review 2.0 + badges; customer OTP optional for pilot.
|
||
|
||
---
|
||
|
||
## Phase 3 — Operations
|
||
|
||
### O-1 — Queue / waitlist (polish, not greenfield)
|
||
|
||
| | |
|
||
|--|--|
|
||
| **Effort** | S–M (3–5 days) |
|
||
| **Built** | `IQueueService`, `queue-screen.tsx` |
|
||
| **Gaps** | Plan gate `queue` (Business+); public “take number” QR/tablet; SMS when called (Kavenegar); TV display mode (fullscreen Next page); branch-scoped boards |
|
||
| **API** | `POST /api/public/{cafeId}/queue/tickets` (anonymous, rate limited) |
|
||
| **Acceptance** | Walk-in gets number; staff calls next; plan limit blocks Free tier |
|
||
|
||
### O-2 — Kitchen printer routing per station
|
||
|
||
| | |
|
||
|--|--|
|
||
| **Effort** | L (2 weeks) |
|
||
| **Model** | `KitchenStation` (name, printerAddress/bluetoothId), `MenuCategory.StationId`, order route split on submit |
|
||
| **API** | CRUD stations; KDS ticket includes `stationId` |
|
||
| **Dashboard** | Settings → stations; map categories |
|
||
| **Mobile POS** | `meezi_pos` Phase 2: `bluetooth_print` per station ticket |
|
||
| **Acceptance** | Drink items print to bar printer; food to kitchen |
|
||
|
||
### O-3 — Cash drawer / shift close reports
|
||
|
||
| | |
|
||
|--|--|
|
||
| **Effort** | M–L (1.5 weeks) |
|
||
| **Model** | `CashShift` (openedAt, closedAt, openingFloat, countedCash, expectedCash, variance, userId) |
|
||
| **API** | Open/close shift; Z-report snapshot (orders, payments, voids, discounts) |
|
||
| **UI** | POS: “بستن شیفت”; PDF/printable summary; manager-only |
|
||
| **HR tie-in** | Optional link to `Employee` clock-out |
|
||
| **Acceptance** | Cannot close shift with open tables; report matches day orders |
|
||
|
||
### O-4 — Multi-terminal enforcement
|
||
|
||
| | |
|
||
|--|--|
|
||
| **Effort** | M (1 week) |
|
||
| **Built** | `PlanLimits.MaxTerminals`, `X-Meezi-Terminal-Id` mentioned for POS |
|
||
| **Implementation** | Redis set `terminals:{cafeId}` with TTL; register on staff login/refresh; reject 4th terminal on Free with `PLAN_LIMIT_REACHED` |
|
||
| **Dashboard** | Settings → active terminals list + revoke |
|
||
| **Acceptance** | Free cafe blocked on 2nd concurrent terminal session |
|
||
|
||
**Phase 3 exit:** Queue production-ready; shift close; terminals enforced; printer routing MVP.
|
||
|
||
---
|
||
|
||
## Phase 4 — Integrations
|
||
|
||
### I-1 — Neshan maps (discover + delivery radius)
|
||
|
||
| | |
|
||
|--|--|
|
||
| **Effort** | M (1 week) |
|
||
| **Config** | `Neshan:ApiKey` in platform settings / cafe settings |
|
||
| **Discover** | Geocode café address; embed map on detail; optional “near me” sort (browser geolocation + distance) |
|
||
| **Delivery radius** | `Cafe.DeliveryRadiusKm` + circle check for guest delivery orders (future) |
|
||
| **Acceptance** | Map loads on café page; cities filtered Tehran/Karaj |
|
||
|
||
### I-2 — Snappfood outbound status updates
|
||
|
||
| | |
|
||
|--|--|
|
||
| **Effort** | M (1 week) |
|
||
| **Built** | `DeliveryStatusSyncService`, `ISnappfoodClient` |
|
||
| **Work** | On order status → Ready/OutForDelivery/Delivered call Snappfood API; idempotent; Hangfire retry; log failures to `WebhookLog` |
|
||
| **Dashboard** | Delivery settings: vendor id, test webhook |
|
||
| **Acceptance** | Status change in KDS triggers outbound call when `SnappfoodOrderId` set |
|
||
|
||
### I-3 — Digikala / Tap30 delivery parity
|
||
|
||
| | |
|
||
|--|--|
|
||
| **Effort** | L (2 weeks) |
|
||
| **Built** | Normalizers + webhook ingress pattern |
|
||
| **Work** | Symmetric outbound sync; commission rules; admin integration toggles; menu mapping table `DeliveryMenuMapping` |
|
||
| **Acceptance** | Same lifecycle as Snappfood for each enabled platform |
|
||
|
||
### I-4 — Hardware bundle onboarding (tablet + printer)
|
||
|
||
| | |
|
||
|--|--|
|
||
| **Effort** | M (1 week product + 1 week ops) |
|
||
| **Not code-only** | SKU in admin; café `HardwareBundlePurchasedAt` |
|
||
| **App flow** | Wizard: download POS APK, pair printer (BLE), register terminal id, test print |
|
||
| **Docs** | PDF checklist Farsi; support ticket auto-tag `hardware` |
|
||
| **Acceptance** | New Pro signup can complete wizard end-to-end |
|
||
|
||
**Phase 4 exit:** Maps on discover; delivery platforms symmetric; hardware wizard documented.
|
||
|
||
---
|
||
|
||
## Phase 5 — Platform & Enterprise
|
||
|
||
### P-1 — Separate admin web + Compose services
|
||
|
||
| | |
|
||
|--|--|
|
||
| **Effort** | L (2–3 weeks) |
|
||
| **Work** | New `web/admin` Next app; move `src/app/[locale]/admin/**`; env `NEXT_PUBLIC_ADMIN_API_URL`; `docker-compose.admin.yml` (admin-api + admin-web); CORS split |
|
||
| **API** | Merchant `Meezi.API` strips `/api/admin/*` when migration complete |
|
||
| **Acceptance** | Admin users never hit merchant dashboard origin; two compose profiles documented |
|
||
|
||
### P-2 — API keys (Enterprise)
|
||
|
||
| | |
|
||
|--|--|
|
||
| **Effort** | M (1 week) |
|
||
| **Model** | `CafeApiKey` (hash, prefix, scopes, expiresAt, lastUsedAt) |
|
||
| **Auth** | `Authorization: Bearer mk_...` middleware path; scopes: `orders:read`, `menu:write`, etc. |
|
||
| **UI** | Dashboard settings (Enterprise): create/revoke keys |
|
||
| **Acceptance** | External script can `GET` orders with key; keys tenant-scoped |
|
||
|
||
### P-3 — Audit log for owners
|
||
|
||
| | |
|
||
|--|--|
|
||
| **Effort** | M (1 week) |
|
||
| **Model** | `AuditEvent` (cafeId, userId, action, entityType, entityId, diffJson, ip, at) |
|
||
| **Instrument** | Order void, refund, settings change, plan change, employee role change |
|
||
| **UI** | Settings → audit feed; filter by date/user |
|
||
| **Acceptance** | Owner sees who voided a line item |
|
||
|
||
### P-4 — Data export & GDPR-style tooling
|
||
|
||
| | |
|
||
|--|--|
|
||
| **Effort** | M–L (1.5 weeks) |
|
||
| **Export** | Hangfire job: ZIP JSON (customers, orders, reviews) per café; signed download link 24h |
|
||
| **Delete** | Soft-delete existing; `POST /api/cafes/{id}/privacy/erase-customer` anonymize PII (phone hash, name redacted) |
|
||
| **Retention** | Document policy in privacy page |
|
||
| **Acceptance** | Owner can export month of CRM; erase one customer on request |
|
||
|
||
**Phase 5 exit:** Admin split deployed; Enterprise API keys + audit; export/erase available.
|
||
|
||
---
|
||
|
||
## Cross-cutting requirements (every phase)
|
||
|
||
| Rule | Action |
|
||
|------|--------|
|
||
| Multi-tenant | All EF queries filter `CafeId` |
|
||
| Plans | Feature flags in `PlatformPlanDefinitions` + `IsFeatureEnabledForCafeAsync` |
|
||
| Public abuse | Rate limit + optional Turnstile on new `POST` routes |
|
||
| i18n | No hardcoded UI strings |
|
||
| Tests | At least one integration test per new controller; E2E for critical UX |
|
||
|
||
---
|
||
|
||
## Suggested PR order (first 10 PRs)
|
||
|
||
1. `docs/SECURITY.md` (Q-1)
|
||
2. Playwright smoke POS (Q-2)
|
||
3. Public discover filters API + page (G-1)
|
||
4. Discover map embed Neshan (I-1 minimal)
|
||
5. Review reply UI + public display (G-6 partial)
|
||
6. Loyalty earn on pay (G-4)
|
||
7. Terminal enforcement (O-4)
|
||
8. Queue public ticket + plan gate (O-1)
|
||
9. Snappfood outbound hardening (I-2)
|
||
10. Shift close MVP (O-3)
|
||
|
||
---
|
||
|
||
## Effort summary
|
||
|
||
| Bucket | Items | Rough total |
|
||
|--------|-------|-------------|
|
||
| Quality | Q-1–Q-4 | ~2 weeks |
|
||
| Growth & community | G-1–G-6 | ~6–8 weeks |
|
||
| Operations | O-1–O-4 | ~5–6 weeks |
|
||
| Integrations | I-1–I-4 | ~5–6 weeks |
|
||
| Platform | P-1–P-4 | ~6–8 weeks |
|
||
|
||
**Calendar (1 dev):** ~20–24 weeks sequential. **Parallel (2 dev):** Phase 1 + 0 in parallel; Phase 3 + 4 overlap after Phase 2 API stable.
|
||
|
||
---
|
||
|
||
## Out of scope (unless product changes)
|
||
|
||
- Full Sepidz parity
|
||
- Native iOS/Android store apps separate from Flutter
|
||
- Real-time ML ranking for discover (start with filter + sort)
|
||
- Full Taraz production (see `CURRENT_STATE_FOR_PLANNING.md`)
|
||
|
||
---
|
||
|
||
## Planning prompts for Cursor
|
||
|
||
Copy into a session with this file attached:
|
||
|
||
1. *“Implement G-1 PR-1 only: extend `GET /api/public/discover` filters + tests.”*
|
||
2. *“Implement O-4 terminal registration with Redis and PlanLimits.”*
|
||
3. *“Scaffold `web/admin` and move admin routes from dashboard.”*
|
||
|
||
---
|
||
|
||
*End of roadmap — update phase exit criteria as items ship.*
|