radionica3d/docs/admin_tutorial.md

Tutorial: Adding a New Section to the Admin Dashboard

This guide provides a step-by-step walkthrough for developers who want to extend the Admin Dashboard with a new management section (e.g., "Analytics" or "Coupons").

---

Step 1: Backend Setup (The Data Source)

1.1 Create a New Router

Create a new file in backend/routers/ or add to admin.py. If the section is complex, a new file is better: backend/routers/coupons.py.

from fastapi import APIRouter, Depends
from backend.auth_utils import get_current_active_admin
from backend.db import get_db

router = APIRouter(prefix="/admin/coupons", tags=["Coupons"])

@router.get("/")
async def get_all_coupons(admin=Depends(get_current_active_admin), db=Depends(get_db)):
    # Logic to fetch data from DB
    return {"coupons": []}

1.2 Register the Router

In backend/main.py, include your new router:

from backend.routers import coupons
app.include_router(coupons.router)

---

Step 2: Localization (The Text)

The Admin Dashboard uses a dedicated localization system.

2.1 Add the Tab Name

Edit src/locales/master_admin/tabs.json and add your new tab ID:

{
  "orders": "Orders",
  "new_section": "My New Section"
}

2.2 Create a Content Fragment

Create a new file src/locales/master_admin/new_section.json for all texts within that section.

2.3 Generate Language Files

Run the following command to update the frontend JSONs:

backend\.venv\Scripts\python.exe scripts\manage_locales.py split

---

Step 3: Frontend Component

3.1 Create the Section Component

Create src/components/admin/NewSection.vue. Use existing sections as templates (e.g., ServicesSection.vue).

<template>
  <div class="space-y-6">
    <h2 class="text-2xl font-bold">New Management Section</h2>
    <!-- Your UI here -->
  </div>
</template>

<script setup lang="ts">
import { onMounted, ref } from 'vue';
import { adminGetNewData } from '@/lib/api';

const data = ref([]);
onMounted(async () => {
  data.value = await adminGetNewData();
});
</script>

3.2 Add API Call

Add the corresponding function in src/lib/api.ts to call your new backend endpoint.

---

Step 4: Integration in Admin Dashboard

Finally, register your new section in src/pages/Admin.vue.

4.1 Import the Component

import NewSection from "@/components/admin/NewSection.vue";

4.2 Update the Tabs List

Add your tab ID to the tabs array and the Tab type definition:

const tabs: { id: Tab }[] = [
  ...
  { id: "new_section" },
];

type Tab = "orders" | ... | "new_section";

4.3 Add the Component to the Template

Add the component inside the <!-- Modular Sections --> block:

<NewSection v-if="activeTab === 'new_section'" />

---

Summary Checklist

1. Backend Router: Endpoint created and secured.
2. Backend Register: Router included in main.py.
3. Localization: Tab name added and manage_locales.py split executed.
4. API Client: Method added to src/lib/api.ts.
5. Vue Component: Created in src/components/admin/.
6. Admin Page: Tab registered and component added to template.