Files
Suman/docs/implementation-plan/phase-03-admin-isolation-by-country.md
Nermin Karic f5e2fcbf98 first commit
2026-11-22 21:49:17 +01:00

164 lines
5.4 KiB
Markdown

# Faza 3: Admin Izolacija po Državama (Backend Middleware Interceptor)
## 3.1. Svrha i Ciljevi Faze
Zvanični Medusa Admin v2 je zamišljen kao centralizovani panel sa globalnim uvidom u sve podatke.
Cilj ove faze je implementacija **potpune izolacije podataka po državama** bez pravljenja novog admin panela ili račvanja (forkovanja) koda zvaničnog dashboarda.
Rješenje se implementira na backend nivou kroz **Medusa HTTP Middleware Interceptore** koji presreću administratorske API zahtjeve i filtriraju narudžbe i kupce prema prodajnom kanalu dodijeljenom ulogovanom korisniku.
---
## 3.2. Sigurnosna Arhitektura
```
[Admin Korisnik (Klaus - DE Admin)]
↓
[Zahtjev: GET /admin/orders]
↓
[Medusa Autentifikacija: Session / Bearer Token]
↓
[Custom Middleware: isolateSalesChannelMiddleware]
├── Provjerava req.auth_context.actor_id
├── Učitava user.metadata.sales_channel_id
├── Ako postoji restricirani ID:
│ ├── GET /admin/orders → Injektuje req.query.sales_channel_id = [id]
│ └── GET /admin/orders/:id → Ako narudžba ne pripada kanalu → 403 Forbidden
└── Ako je null (Super Admin) → Propušta zahtjev bez izmjena
↓
[Medusa Core API Handler] → [Vraća samo narudžbe za DE]
```
---
## 3.3. Implementacija Middleware Interceptora
Uredite ili kreirajte datoteku `apps/backend/src/api/middlewares.ts`:
```typescript
import {
defineMiddlewares,
AuthenticatedMedusaRequest,
MedusaResponse,
MedusaNextFunction,
} from "@medusajs/framework/http"
import { ContainerRegistrationKeys, MedusaError } from "@medusajs/framework/utils"
/**
* Middleware koji provjerava da li admin korisnik ima restrikciju
* na specifičan prodajni kanal i nameće filtriranje.
*/
async function enforceAdminSalesChannelIsolation(
req: AuthenticatedMedusaRequest,
res: MedusaResponse,
next: MedusaNextFunction
) {
const userId = req.auth_context?.actor_id
// Ako korisnik nije autentifikovan, standardni guard će ga odbiti
if (!userId) {
return next()
}
const query = req.scope.resolve(ContainerRegistrationKeys.QUERY)
// 1. Dobavljanje korisničkih metapodataka
const {
data: [user],
} = await query.graph({
entity: "user",
fields: ["id", "metadata"],
filters: { id: userId },
})
const restrictedChannelId = user?.metadata?.sales_channel_id as string | undefined
// Ako korisnik ima dodijeljen prodajni kanal (Regionalni Admin)
if (restrictedChannelId) {
// A) Zahtjev za listu narudžbi (GET /admin/orders)
if (req.method === "GET" && !req.params.id) {
// Forsiramo filtriranje po sales channelu
req.query.sales_channel_id = [restrictedChannelId]
}
// B) Zahtjev za pojedinačnu narudžbu (GET /admin/orders/:id)
if (req.method === "GET" && req.params.id) {
const {
data: [order],
} = await query.graph({
entity: "order",
fields: ["id", "sales_channel_id"],
filters: { id: req.params.id },
})
if (order && order.sales_channel_id !== restrictedChannelId) {
throw new MedusaError(
MedusaError.Types.NOT_ALLOWED,
"Zabranjen pristup: Nemate ovlaštenje za pregled narudžbi iz ovog prodajnog kanala."
)
}
}
}
// Super Admini (bez sales_channel_id u metadata) vide sve narudžbe
return next()
}
export default defineMiddlewares({
routes: [
{
matcher: "/admin/orders*",
method: ["GET"],
middlewares: [enforceAdminSalesChannelIsolation],
},
],
})
```
---
## 3.4. Dodjela i Ažuriranje Kanala Korisnicima u Bazi
Regionalnom adminu se kanal može dodijeliti programski ili kroz skriptu `setup-umbrella-platform.ts`. Ukoliko želite postojećem korisniku dodijeliti ili promijeniti kanal, koristi se zvanični `updateUserWorkflow`:
```typescript
// Primjer skripte za dodjelu kanala korisniku:
await updateUserWorkflow(container).run({
input: {
id: "usr_01J...",
user: {
metadata: {
sales_channel_id: "sc_germany_01J...",
},
},
},
})
```
---
## 3.5. Korak-po-Korak Testiranje i Verifikacija
1. **Kreirajte dvije testne narudžbe:**
- Jednu narudžbu preko Storefronta DE (kanal `channelDE.id`).
- Drugu narudžbu preko Storefronta AT (kanal `channelAT.id`).
2. **Prijavite se u Medusa Admin (`http://localhost:9000/app`) sa nalogom `admin.de@suncobrani.com`:**
- Otvorite sekciju **Orders**.
- **Provjera 1:** U tabeli narudžbi se prikazuje isključivo narudžba iz Njemačke. Narudžba iz Austrije se uopšte ne pojavljuje.
3. **Pokušaj direktnog pristupa austrijskoj narudžbi preko URL-a:**
- U browseru unesite direktan link austrijske narudžbe: `http://localhost:9000/app/orders/order_austria_id`.
- **Provjera 2:** Backend odbija zahtjev sa statusom `403 NOT_ALLOWED` i porukom o zabrani pristupa.
4. **Prijavite se sa nalogom Super Admina:**
- Otvorite **Orders**.
- **Provjera 3:** Super Admin vidi narudžbe iz obje države.
---
## 3.6. Kriterijumi Prihvatljivosti (Acceptance Criteria)
- [ ] Middleware se uspješno kompajlira bez TypeScript grešaka (`pnpm --filter @dtc/backend build`).
- [ ] Regionalni admin Njemačke ne može vidjeti listu narudžbi niti detalje pojedinačne narudžbe iz Austrije.
- [ ] Zvanični Medusa Admin interfejs ostaje netaknut i stabilan (nema grešaka u konzoli niti rušenja aplikacije).