hamed
684cf1f783
- Refactor multiple admin pages (BlogsPage, ClinicsPage, DoctorsPage, etc.) to utilize the new useUrlState hook for managing pagination, search, and filter states via URL. - Ensure that the state persists in the URL, allowing users to return to the same state when navigating back from detail pages. - Update relevant components to handle state changes appropriately and maintain clean URLs by removing default values. - Add SlotPicker component for selecting appointment slots based on availability. - Create tests for useUrlState to validate its functionality and ensure correct behavior when interacting with the URL. - Update API documentation to reflect changes in appointment creation and slot selection processes.
276 lines
16 KiB
Markdown
276 lines
16 KiB
Markdown
# CLAUDE.md
|
|
|
|
Guidance for Claude Code when working in **ClinicPro** — a clinic management & appointment platform. A Symfony 7.4 REST API backend plus a React 19 admin SPA bundled inside Symfony via Webpack Encore.
|
|
|
|
- **Local:** `https://clinic-pro.ddev.site` — **Admin:** `/admin` — **Swagger:** `/api/doc`
|
|
- Runs inside **ddev**: prefix commands with `ddev exec`.
|
|
- Entire product is Persian/Farsi, **RTL**, Jalali (Shamsi) dates. Keep new strings Persian, dates Jalali.
|
|
|
|
> **Source of truth for design tokens is `assets/admin/styles.css`**, not `docs/admin-ui/ui-design-spec.md`. That spec doc is an older aspirational draft (purple palette, tiptap, date-io) that does **not** match the shipped code (indigo palette, CKEditor, jalaali-js). Trust the code.
|
|
|
|
---
|
|
|
|
## Stack & versions
|
|
|
|
### Backend (`composer.json`)
|
|
- **PHP ≥ 8.2**, **Symfony 7.4**, **Doctrine ORM 3.6** + migrations, **MariaDB 11.8** (via ddev)
|
|
- Auth: **JWT** (`lexik/jwt-authentication-bundle`)
|
|
- Async/scheduled: `symfony/messenger` + `symfony/scheduler` + `symfony/redis-messenger`
|
|
- API docs: `nelmio/api-doc-bundle` + `zircote/swagger-php`; CORS: `nelmio/cors-bundle`
|
|
- Also: `symfony/uid`, `symfony/rate-limiter`, `altcha-org/altcha`, Twig, `symfony/ux-react`
|
|
- PSR-4: `App\` → `src/`, tests `App\Tests\` → `tests/`
|
|
|
|
### Frontend admin SPA (`package.json`)
|
|
- **React 19** + **TypeScript 5**, bundled by **Webpack Encore 6** (not Vite)
|
|
- **Tailwind CSS v4** (`@tailwindcss/postcss`, CSS-first config)
|
|
- Server state: **TanStack Query v5** · Tables: **TanStack Table v8**
|
|
- Client state: **Zustand 5** · Forms: **React Hook Form 7 + Zod 3** (`@hookform/resolvers`)
|
|
- Routing: **React Router v7** · Icons: **Heroicons v2** · Charts: **Recharts 3**
|
|
- Select: `react-select` · Rich text: **CKEditor 5** · Dates: `jalaali-js` · Maps: `leaflet`/`react-leaflet`
|
|
- Toasts: `sonner` (+ `react-hot-toast`) · Font: **Vazirmatn** via `@fontsource/vazirmatn`
|
|
- Tests: **Vitest** + Testing Library (jsdom)
|
|
|
|
### Build entry points (`webpack.config.js`)
|
|
Three Encore entries → `public/build/`:
|
|
| Entry | Source | Purpose |
|
|
|---|---|---|
|
|
| `admin` | `assets/admin/index.tsx` | React admin SPA, mounted at `/admin/*` |
|
|
| `app` | `assets/app.js` | Stimulus/UX React controllers |
|
|
| `home` | `assets/home/index.js` | Public-facing pages |
|
|
|
|
---
|
|
|
|
## Commands (prefix with `ddev exec`)
|
|
|
|
```bash
|
|
# Backend
|
|
php bin/console cache:clear
|
|
php bin/console doctrine:migrations:diff --no-interaction # after any entity change
|
|
php bin/console doctrine:migrations:migrate --no-interaction
|
|
php bin/console debug:router | grep api
|
|
php bin/console messenger:consume async # SMS / async jobs
|
|
php bin/console messenger:consume scheduler_default # scheduled tasks
|
|
php bin/phpunit # tests
|
|
php vendor/bin/phpstan analyse # static analysis (level 5)
|
|
|
|
# Frontend
|
|
yarn dev # one-off build (use to check for errors)
|
|
yarn watch # watch mode
|
|
yarn build # production
|
|
npx tsc --noEmit --project tsconfig.json # type check only (faster)
|
|
yarn test # vitest
|
|
```
|
|
> Known: CSS build has a pre-existing `lightningcss.linux-arm64-gnu.node` native-module error inside ddev; it does not block JS/TS compilation. TypeScript errors still surface in TSC output.
|
|
|
|
---
|
|
|
|
## Folder structure & where things go
|
|
|
|
### Backend — `src/<Domain>/`
|
|
Domain-driven; each domain is its own namespace `App\<Domain>\` holding its own layers:
|
|
```
|
|
src/<Domain>/
|
|
Controller/ # HTTP endpoints — extend BaseController
|
|
Entity/ # Doctrine entities
|
|
Repository/ # Doctrine repositories (DQL / query builders)
|
|
Service/ # domain logic
|
|
Command/ # console commands (optional)
|
|
```
|
|
Domains include: `Doctor`, `Patient`, `Appointment`, `Payment`, `Clinic`, `ClinicInvitation`,
|
|
`ClinicService`, `DoctorService`, `Secretary`, `Staff`, `Settlement`, `Billing`, `Subscription`,
|
|
`Rating`, `Blog`, `Sms`, `Category`, `Location`, `Specialty`, `Insurance`, `Tag`, `Representation`,
|
|
`Auth`, `Admin`, `Dashboard`, `UserProfile`, `Config`.
|
|
|
|
Shared infra:
|
|
```
|
|
src/Shared/Controller/BaseController.php # every controller extends this
|
|
src/Shared/Constant/ErrorCodes.php # all error codes + Persian messages
|
|
```
|
|
Cross-cutting: `migrations/`, `config/`, `templates/`, `docs/api/` (endpoint docs).
|
|
|
|
### Frontend — `assets/admin/`
|
|
```
|
|
index.tsx # entry: mounts <App/>, QueryClientProvider, <Toaster/> (sonner)
|
|
App.tsx # React Router v7 routes
|
|
pages/ # one file per page — XxxPage.tsx (~50 pages)
|
|
components/
|
|
ui/ # shared design-system components (see below)
|
|
*.tsx # feature-specific composites (ServiceTariffModal, ImageCropModal, …)
|
|
hooks/ # useSubscription, usePaymentConfig, usePwaInstall, …
|
|
lib/api.ts # fetch wrapper; reads JWT from localStorage['clinicpro-auth']
|
|
lib/utils.ts # formatRial, formatNumber, formatDate, formatDateTime
|
|
types/index.ts # all shared TypeScript interfaces
|
|
stores/ # authStore.ts (persisted), uiStore.ts (sidebar/ui)
|
|
styles.css # Tailwind entry + all design tokens
|
|
```
|
|
|
|
---
|
|
|
|
## Styling & design tokens
|
|
|
|
Tailwind **v4**, imported in `assets/admin/styles.css`:
|
|
```css
|
|
@import "tailwindcss";
|
|
@import "@fontsource/vazirmatn/{300..800}.css";
|
|
@custom-variant dark (&:where(.dark, .dark *));
|
|
@theme { --font-sans: "Vazirmatn", ui-sans-serif, system-ui, sans-serif; }
|
|
```
|
|
**All design tokens are CSS custom properties in the `:root` block of `styles.css`** — reference them via Tailwind arbitrary values (`bg-[var(--surface)]`) or plain CSS, do not hardcode hex:
|
|
|
|
| Group | Tokens |
|
|
|---|---|
|
|
| Brand | `--primary:#5559CE` (indigo), `--primary-600/700`, `--primary-soft/soft2`, `--on-primary` |
|
|
| Accent | `--accent:#f0682a` (orange, matches clinic-pro-tauri), `--accent-600`, `--accent-bg` |
|
|
| Surfaces | `--bg`, `--bg-2`, `--surface`, `--surface-2/3`, `--border`, `--border-2` |
|
|
| Text | `--text`, `--text-2`, `--text-3` |
|
|
| Status | `--success/-bg`, `--warning/-bg`, `--danger/-bg`, `--info/-bg`, `--violet/-bg` |
|
|
| Stat cards | `--stat-{amber,violet,green,pink}-{bg,fg}` |
|
|
| Radius | `--r-xs:7 · --r-sm:8 · --r:14 · --r-lg:18 · --r-xl:24 · --r-pill:999` (px) |
|
|
| Shadow | `--shadow-sm`, `--shadow`, `--shadow-lg` |
|
|
| Layout | `--sidebar-w:243`, `--collapsed-w:90`, `--topbar-h:64`, `--gap:20`, `--card-pad:22`, `--row-h:56` |
|
|
| Motion | `--ease: cubic-bezier(.22,.61,.36,1)` |
|
|
|
|
Theming: **dark mode** overrides via `[data-theme="dark"]`; **compact density** via `[data-density="compact"]`. oklch color versions applied under `@supports` with sRGB fallbacks for old WebKit.
|
|
|
|
---
|
|
|
|
## Design system components — `assets/admin/components/ui/`
|
|
|
|
Reuse these before building new ones:
|
|
|
|
`DataTable` (sortable, search, skeleton loading, empty state, bulk) · `Modal` · `ConfirmDialog` ·
|
|
`PageHeader` (title + breadcrumb + action + `backTo`) · `BackButton` · `StatCard` · `StatusBadge` ·
|
|
`Pagination` · `SearchableSelect` · `AppointmentStatusDropdown` · `PersianDateInput` / `PersianDatePicker` /
|
|
`PersianCalendar` · `MobileInput` · `PriceInput` · `Portal` · `FeatureGate` · `Altcha` ·
|
|
`InviteDoctorModal` · `PwaInstallBanner` / `PwaLoginCard` / `NotificationMobileCard`.
|
|
|
|
Feature composites (not generic) live one level up in `components/*.tsx`.
|
|
|
|
### دکمهٔ بازگشت — الزامی در صفحات زیرمجموعه
|
|
|
|
هر صفحهای که از دل صفحهٔ دیگری باز میشود (جزئیات، فرم ساخت/ویرایش، زیرصفحههای تنظیمات)
|
|
باید دکمهٔ «بازگشت» داشته باشد، با یک ظاهر و یک رفتار:
|
|
|
|
- صفحاتی که `PageHeader` دارند: فقط `backTo="/admin/…"` بدهید.
|
|
- بقیه: `<BackButton fallback="/admin/…" />` بالای هدر صفحه.
|
|
- دکمهٔ دستساز نسازید — ظاهر مرجع `cp-btn-secondary` با ارتفاع ۳۶ و آیکون `ChevronRightIcon` است
|
|
(همان دکمهٔ صفحهٔ سرویسها) و رفتارش در `hooks/useGoBack.ts` متمرکز است: یک قدم عقب در تاریخچهٔ
|
|
پنل، و در ورود مستقیم/رفرش (`location.key === 'default'`) رفتن به `fallback`.
|
|
|
|
### وضعیت لیستها در URL، نه در state
|
|
|
|
جستجو، فیلترها، شمارهٔ صفحه و نمای هر صفحهٔ لیست باید در query string بنشیند — با
|
|
`hooks/useUrlState.ts`:
|
|
|
|
```tsx
|
|
const [urlState, setUrlState] = useUrlState({ page: '1', search: '', status: '' });
|
|
const page = pageOf(urlState.page);
|
|
const setSearch = (v: string) => setUrlState({ search: v, page: '1' });
|
|
```
|
|
|
|
دلیلش «بازگشت» است: `navigate(-1)` همان URL قبلی را برمیگرداند، پس هرچه در URL باشد سرِ جایش
|
|
برمیگردد و هرچه در `useState` باشد با remount میپرد. سود جانبی: رفرش و اشتراک لینک همان نما را
|
|
میدهد. فیلدِ جستجوی debounceشده local میماند و فقط مقدار نهایی به URL میرود.
|
|
|
|
---
|
|
|
|
## Conventions
|
|
|
|
**Naming:** pages `XxxPage.tsx`, components PascalCase, hooks `useXxx.ts`. Backend PSR-4 `App\<Domain>\<Layer>`; entities singular (`Doctor`), tables snake_case plural (`patient_records`).
|
|
|
|
**Data fetching:** TanStack Query only — `useQuery` / `useMutation`. Query keys `['resource-name', page, filters]`. All HTTP goes through `lib/api.ts`, which injects the JWT automatically.
|
|
- `ApiResponse<T>` (single resource): extract with `data?.data`
|
|
- `PaginatedResponse<T>` (admin lists): items at `data?.data`, total at `data?.meta?.totalRecords`
|
|
|
|
**State management:**
|
|
- **Server state → TanStack Query** (cache, `staleTime: 30s`, `retry: 1`).
|
|
- **Client state → Zustand.** `authStore` (JWT + user, persisted to `localStorage['clinicpro-auth']`), `uiStore` (sidebar/ui flags).
|
|
|
|
**Forms:** React Hook Form + Zod resolver — `z.object({...})`, type via `z.infer<typeof schema>`.
|
|
|
|
**Routing:** React Router v7, `<BrowserRouter>` in `index.tsx`, route table in `App.tsx`, SPA served at `/admin/*`.
|
|
|
|
**Auth:** JWT issued by Symfony. Admin routes guard with `#[IsGranted('ROLE_ADMIN')]` on the controller class/method. Public endpoints are whitelisted in `config/packages/security.yaml`.
|
|
|
|
---
|
|
|
|
## Backend endpoint & model patterns
|
|
|
|
### Response envelope — `BaseController` helpers
|
|
Every controller `extends BaseController`:
|
|
| Method | Shape |
|
|
|---|---|
|
|
| `$this->success($data)` | `{ success, data }` |
|
|
| `$this->paginated($items, $total, $page, $limit)` | `{ success, data:[], meta:{ totalRecords, totalPages, currentPage } }` (flat — no nesting) |
|
|
| `$this->error($code, $message, $status)` | `{ success:false, errors:[{code,message}] }` |
|
|
| `$this->validationError($violations)` | `{ success:false, errors:[{code,field,message}] }` HTTP 422 |
|
|
|
|
- **Errors:** throw `AppException(ErrorCodes::ERR_XXX, null, $httpStatus)` anywhere in a domain; `ExceptionSubscriber` catches it and formats via `$this->error()`. Codes + Persian messages in `src/Shared/Constant/ErrorCodes.php`.
|
|
- **Pitfall — double nesting:** `$this->success(['data' => $x])` yields `{ data: { data: x } }`; the frontend must then read `data?.data?.data`. Prefer passing the payload directly.
|
|
- **Admin list queries** use `->getArrayResult()` (array hydration), never entity getters, to avoid missing-getter errors.
|
|
|
|
### Adding an endpoint (one domain)
|
|
1. `src/<Domain>/Entity/Foo.php` — Doctrine entity (attributes; see model pattern).
|
|
2. `src/<Domain>/Repository/FooRepository.php` — queries.
|
|
3. `src/<Domain>/Service/FooService.php` — logic (optional but preferred).
|
|
4. `src/<Domain>/Controller/FooController.php` — `extends BaseController`, route `/api/v1/...`, guard with `#[IsGranted]`, return a response helper.
|
|
5. `ddev exec php bin/console doctrine:migrations:diff` then `migrate`.
|
|
6. Update the matching `docs/api/*.md` (see Standing Rule).
|
|
|
|
### Model (entity) pattern
|
|
```php
|
|
#[ORM\Entity(repositoryClass: FooRepository::class)]
|
|
#[ORM\Table(name: 'foos')]
|
|
class Foo
|
|
{
|
|
#[ORM\Id] #[ORM\GeneratedValue] #[ORM\Column(type: 'integer')]
|
|
private ?int $id = null;
|
|
|
|
#[ORM\Column(type: 'string', length: 36, unique: true)]
|
|
private string $uuid; // Uuid::v4()->toRfc4122() in constructor
|
|
|
|
#[ORM\Column(name: 'created_at', type: 'integer')]
|
|
private int $createdAt; // Unix timestamp (time()), NOT DateTime
|
|
|
|
#[ORM\ManyToOne(targetEntity: User::class)]
|
|
#[ORM\JoinColumn(nullable: false, onDelete: 'RESTRICT')]
|
|
private User $user;
|
|
}
|
|
```
|
|
Conventions: integer surrogate `id`; string `uuid` (v4) for external references; **timestamps are `int` Unix**, not DateTime; column names snake_case via `name:`; relations `ManyToOne` / `OneToMany`.
|
|
|
|
### Category / bundle system
|
|
Categories are polymorphic via a `bundle` string: `state`, `city`, `specially_doctor`, `doctor_services`, `insurance_type`, `supplementary_insurance`, `tag`. City is an integer FK to `categories.id` where `bundle='city'` (e.g. `Representation.cityId`) — LEFT JOIN `categories` in DQL to get the name. Endpoint: `GET /api/v1/categorys/{bundle}` (typo `categorys` is the real route); its response is double-nested → extract with `data?.data?.data ?? []`.
|
|
|
|
---
|
|
|
|
## Standing Rule — API docs
|
|
|
|
**Whenever any endpoint is created or modified** (route, request/response shape, error code, permission), update the matching file in `docs/api/` **in the same session**. Mapping mirrors `src/<Domain>` → `docs/api/<domain>.md` (e.g. `src/Doctor/*` → `docs/api/doctor.md`, `src/Admin/*` → `docs/api/admin.md`, Category/Location controllers → `docs/api/location.md` + `specialty.md` + `insurance.md` + `tag.md`).
|
|
|
|
## Project skills
|
|
`.claude/skills/`: `add-admin-endpoint`, `add-admin-page`, `sync-db`, `prompt-writer`, `run-prompt`. Prefer them over hand-rolling. Test users: `TEST_USERS.md` (rebuild: `ddev exec php create_test_users.php`).
|
|
|
|
---
|
|
|
|
## جداسازی محیط (tenant)
|
|
|
|
هر دادهٔ عملیاتی به یک محیط تعلق دارد: مطب شخصی یک پزشک، یا یک کلینیک — جفت `(entity_type, entity_id)`.
|
|
|
|
- **entity جدید** یا `App\Shared\Tenant\TenantOwnedTrait` میگیرد، یا با دلیل در `App\Shared\Tenant\GlobalTables` ثبت میشود. `TenantSchemaCoverageTest` هر دو حالت را اجبار میکند و entity طبقهبندینشده را قرمز میکند.
|
|
- **محیط جاری** همیشه از `EntityContextResolver` گرفته میشود، نه از نقش کاربر.
|
|
- `TenantFilter` تور ایمنی است، نه جایگزین authorization — روی SQL خام، `getReference()` و فرزندان aggregate اعمال نمیشود.
|
|
- ایندکسهای لیست باید `entity_type, entity_id` را **ستون اول** داشته باشند.
|
|
|
|
جزئیات و جدول کاملِ «چه تضمین میدهد و چه نمیدهد»: [docs/architecture/tenancy.md](docs/architecture/tenancy.md)
|
|
|
|
## قواعد غیرقابلمذاکره
|
|
1. SOLID در هر کد جدید. کامپوننت/کلاس چندمسئولیتی ننویس.
|
|
2. API جدید فقط وقتی هیچ اندپوینت موجودی — حتی با توسعه — کافی نباشد.
|
|
همیشه اول بگرد، بعد توسعه بده، در آخر بساز. و دلیلش را بنویس.
|
|
3. مستندات کوتاه و دقیق روی هر چیز عمومی. کامنت بدیهی ننویس.
|
|
4. هیچ تسکی بدون تست (موفق + خطا + مرزی) و بدون اجرای موفق تستها تمامشده نیست.
|
|
5. ورودی من فارسی است. اول منظورم را به spec انگلیسی تبدیل کن و برداشتت را
|
|
به فارسی تأیید بگیر. کد و مستندات و کامیت انگلیسی؛ گفتوگو با من فارسی.
|
|
رشتههای UI فارسی و از فایل i18n.
|