workspace create

2026-07-09 10:09:47 +03:30
parent 9043cd4cb2
commit 43dc693061
11 changed files with 450 additions and 29 deletions
@@ -0,0 +1,109 @@
+---
+name: danak-admin
+description: Documents danak-admin React admin panel conventions — page structure, routing, TanStack Query hooks, axios services, sidebar, and Persian i18n. Use when adding pages or features, wiring API calls, updating navigation, or working in this repository.
+---
+
+# Danak Admin
+
+Persian (RTL) admin panel: React 19, Vite, TypeScript, React Router 7, TanStack Query, Formik/Yup, Tailwind, iconsax-react.
+
+## Stack
+
+| Layer | Location / tool |
+|-------|-----------------|
+| Routes (paths) | `src/config/Pages.ts` |
+| Route components | `src/router/Main.tsx` |
+| Auth routes | `src/router/Auth.tsx` |
+| HTTP client | `src/config/axios.ts` — `import axios from "../../../config/axios"` |
+| Shared UI | `src/components/` |
+| Layout | `src/shared/` (Header, SideBar, Footer) |
+| i18n | `src/langs/fa.json`, namespace `global`, `useTranslation('global')` |
+| Env | `VITE_BASE_URL`, `VITE_TOKEN_NAME`, `VITE_REFRESH_TOKEN_NAME` |
+
+## Feature folder layout
+
+Each domain lives under `src/pages/{feature}/`:
+
+```
+{feature}/
+├── List.tsx              # index table view
+├── Create.tsx            # create form
+├── Update.tsx            # edit form (uses :id param)
+├── hooks/use{Feature}Data.ts
+├── service/{Feature}Service.ts
+├── types/{Feature}Types.ts
+└── components/           # feature-specific UI (Delete, filters, etc.)
+```
+
+Mirror an existing feature (e.g. `customer/`, `ads/`) before inventing new patterns.
+
+## Data layer
+
+**Service** — plain async functions, one API call each:
+
+```typescript
+import axios from "../../../config/axios";
+import { CreateCustomerType } from "../types/CustomerTypes";
+
+export const getCustomers = async (page: number) => {
+  const { data } = await axios.get(`/users/customers?page=${page}&paginate=1`);
+  return data;
+};
+
+export const createCustomer = async (params: CreateCustomerType) => {
+  const { data } = await axios.post(`/users/customers`, params);
+  return data;
+};
+```
+
+**Hooks** — TanStack Query wrappers in `hooks/use{Feature}Data.ts`:
+
+- Lists: `useQuery({ queryKey: ["customers", page], queryFn: () => api.getCustomers(page) })`
+- Detail: add `enabled: !!id`
+- Mutations: `useMutation` + `queryClient.invalidateQueries({ queryKey: ["customers"] })`
+- Export hooks as `useGetX`, `useCreateX`, `useUpdateX`, `useDeleteX`
+
+**Types** — `{Feature}ItemType`, `Create{Feature}Type` in `types/`.
+
+## Page patterns
+
+**List** — header + optional filters + `PageLoading` while pending + `<table>` with `Td` + `Pagination`. Link actions via `Pages.{feature}.*`.
+
+**Create / Update** — Formik + Yup validation, `toast.success(t('success'))` on success, `toast.error(error.response?.data?.error.message[0])` on error (`ErrorType` from `src/helpers/types.ts`). Navigate back to list with `useNavigate()` + `Pages.*`.
+
+**Delete** — small component using `ModalConfrim` + mutation hook; call `refetch()` or rely on query invalidation.
+
+## Adding a feature
+
+Follow the checklist in [add-feature.md](add-feature.md). Minimum steps:
+
+1. Add paths to `src/config/Pages.ts`
+2. Create page files under `src/pages/{feature}/`
+3. Register `<Route>` entries in `src/router/Main.tsx` (static imports, no lazy loading)
+4. Add sidebar entry in `src/shared/SideBar.tsx` if user-facing
+5. Add translation keys to `src/langs/fa.json`
+
+Dynamic routes use string concat: `Pages.customer.update + ":id"`.
+
+## Sidebar & submenu
+
+- Main items: `SideBarItem` in `SideBar.tsx` with `link`, `isActive`, `activeName`
+- Features with sub-nav: add segment to `SideBarItemHasSubMenu` in `src/config/SideBarSubMenu.ts`, create `{Feature}SubMenu.tsx` in `src/shared/components/`, render it in the `subMenuName === "..."` block at bottom of `SideBar.tsx`
+- Submenu items use `SubMenuItem` with `Pages.*` links
+- `subMenuName` is derived from first URL segment (`location.pathname.split("/")[1]`)
+
+## Conventions
+
+- Components: `const MyPage: FC = () => { ... }; export default MyPage`
+- Styling: Tailwind utility classes; `clx()` from `src/helpers/utils` for conditional classes
+- Icons: `iconsax-react` (Outline/Bold variants, `#8C90A3` inactive / `black` active)
+- Do not add lazy-loaded routes — project uses direct imports in `Main.tsx`
+- Keep API paths relative to `VITE_BASE_URL`; auth token is attached automatically by axios interceptor
+- Prefer reusing `Button`, `Input`, `Select`, `Textarea`, `Pagination`, `PageLoading`, `ModalConfrim` from `src/components/`
+
+## Do not
+
+- Commit `.env` or secrets
+- Introduce new state libraries (Zustand is only used in `sharedStore` for layout)
+- Add English-only UI strings — add keys to `fa.json`
+- Change axios/auth/token refresh logic unless explicitly requested
@@ -0,0 +1,83 @@
+# Add Feature Checklist
+
+Copy and track when adding a new admin section (e.g. `coupons`):
+
+```
+- [ ] Pages.ts paths
+- [ ] types/{Feature}Types.ts
+- [ ] service/{Feature}Service.ts
+- [ ] hooks/use{Feature}Data.ts
+- [ ] List.tsx (+ Create/Update if CRUD)
+- [ ] components/ (Delete, filters, etc.)
+- [ ] Main.tsx routes + imports
+- [ ] SideBar.tsx (+ SubMenu if multi-page)
+- [ ] fa.json translations
+```
+
+## 1. Pages.ts
+
+```typescript
+coupons: {
+  list: "/coupons/list",
+  create: "/coupons/create",
+  detail: "/coupons/detail/",
+},
+```
+
+Use kebab-case URL segments consistent with existing routes.
+
+## 2. Service + hooks + types
+
+Copy structure from `src/pages/customer/` or `src/pages/ads/`. Adjust API paths to match backend.
+
+## 3. Main.tsx
+
+Add import at top, then route(s):
+
+```tsx
+import CouponsList from "../pages/coupons/List";
+// ...
+<Route path={Pages.coupons.list} element={<CouponsList />} />
+<Route path={Pages.coupons.create} element={<CreateCoupon />} />
+<Route path={Pages.coupons.detail + ":id"} element={<UpdateCoupon />} />
+```
+
+## 4. Sidebar (optional)
+
+**Single-page feature** — add `SideBarItem`:
+
+```tsx
+<SideBarItem
+  icon={<TicketDiscount variant={isActive("coupons") ? "Bold" : "Outline"} color={isActive("coupons") ? "black" : "#8C90A3"} size={iconSizeSideBar} />}
+  title={t("sidebar.coupons")}
+  isActive={isActive("coupons")}
+  link={Pages.coupons.list}
+  activeName="coupons"
+/>
+```
+
+**Multi-page feature** — also:
+
+1. Add `"coupons"` to `SideBarItemHasSubMenu` in `src/config/SideBarSubMenu.ts`
+2. Create `src/shared/components/CouponsSubMenu.tsx` (copy `CustomerSubMenu.tsx`)
+3. Import and add branch in `SideBar.tsx`: `subMenuName === "coupons" ? <CouponsSubMenu /> : ...`
+4. Point main sidebar link to list path; first URL segment must match `activeName` / submenu key
+
+## 5. Translations
+
+Add keys under logical groups in `src/langs/fa.json`:
+
+```json
+"sidebar": { "coupons": "کوپن‌ها" },
+"submenu": { "coupon_list": "لیست کوپن‌ها" },
+"coupon": { "coupon_list": "لیست کوپن‌ها", "add_coupon": "افزودن کوپن" }
+```
+
+Use `t('coupon.add_coupon')` in components.
+
+## 6. Verify
+
+- `npm run build` passes
+- List loads, create/update navigate correctly
+- Sidebar highlights on correct routes
+- Mutation invalidates list query cache