# JÁ² Backoffice — API Documentation

> **Status (13.5.2026)**: Backoffice je teď **interní tool pro JÁ² tým**.
> User-facing Context Store byl **odstraněn** — žije v akademii
> (`apps/akademie/`) jako "Studio" workspace. Per-user data se
> automaticky migrovala (viz `supabase/migrations/20260513000002_migrate_context_store_to_studio.sql`).
>
> **Backoffice MCP** je nyní pure-admin: CRM, support, check-in,
> integrace, skills knihovna. **`list_files` / `read_file` /
> `write_file` / `delete_file` / `search_files` tooly odstraněny.**

## Overview

Backoffice slouží JÁ² týmu (David, Honza, Eva, Petra, Martin) pro:

- **CRM** — customers, happenings, check-in, FAPI / SmartEmailing /
  Affilbox / Quiz pages integrace
- **Support inbox** — Gmail-backed unified tickets, AI drafts
- **Admin** — `/admin/uzivatele` (správa userů + rolí),
  `/admin/roles` (permissions matrix), happenings settings, voucher
  mappings, brigádníci přístup
- **Skills knihovna** — sdílené AI skills přes MCP `skill_list` /
  `skill_get`

### Vztah k akademii

| App | Doména | Pro koho | Per-user kontext |
|---|---|---|---|
| `apps/web` (backoffice — toto) | `ja2.davidkirs.cz` | Interní tým | žádný — bez user files |
| `apps/akademie` | `akademie.davidkirs.cz` | Koncoví uživatelé | 3-tier sloty + Studio workspace |

Obě sdílí Supabase DB, ale každá má **vlastní MCP server**:

- Backoffice MCP: `/api/mcp` — REST tools pro interní agenty
  (skills, crm, support, check-in, integrace, users)
- Akademie MCP: `/api/mcp` — JSON-RPC 2.0 dispatcher (18 tools:
  11 context + 7 Studio)

Pro propojení vlastního Claude / Cursor s vlastním kontextem použij
**akademii** (`akademie.davidkirs.cz/api/mcp`). Backoffice MCP je
primárně pro internal agent workflows.

---

## Quick Start (interní tým)

### 1. Get an API Token

1. Sign in na backoffice
2. Settings → API Tokens
3. Click **New Token**, name it (např. "Skill bootstrap")
4. Copy — token shown only once

### 2. Connect Your AI Agent

```json
{
  "mcpServers": {
    "ja2-backoffice": {
      "url": "https://ja2.davidkirs.cz/api/mcp",
      "token": "cs_your-token-here"
    }
  }
}
```

### 3. Available tool modules

Po odstranění Context Store je backoffice MCP rozdělen do těchto
modulů (viz `lib/mcp/index.ts`):

| Modul | Role | Co dělá |
|---|---|---|
| `skills` | public | `bootstrap`, `skill_list`, `skill_get` — vstupní point pro AI agenta |
| `crm` | admin | Customers, entitlements, attributions |
| `happenings` | admin | Event CRUD, products |
| `team` | admin | Team roles, internal people |
| `checkin` | admin | Check-in ops, dev seed |
| `integrations` | admin | FAPI / Affilbox / SmartEmailing sync |
| `users` | admin | Whitelist + module access |
| `support` | admin | Support inbox CRUD + reply |

> File-system tools (`list_files`, `read_file`, …) **byly odstraněny**.
> User-facing kontext žije v akademii (Studio + sloty).

---

## API Endpoints

### MCP

| Endpoint | Auth | Description |
|----------|------|-------------|
| `POST /api/mcp` | Bearer token | MCP protocol endpoint pro internal AI agents |
| `GET /api/health` | None | Server health check |
| `GET /api/docs` | None | This documentation (raw Markdown) |
| `GET /api/docs/mcp` | None | MCP tools documentation |

### CRM / Quiz integration

| Endpoint | Auth | Description |
|----------|------|-------------|
| `POST /api/webhooks/quiz` | `X-Webhook-Secret` | Lead push z externích quiz pages (4 zdroje) |
| `GET /api/crm/leads` | Bearer `CRM_API_KEY` | List leads (pagination, since, source filter) |
| `GET /api/crm/leads/[leadId]` | Bearer | Single lead detail |
| `GET /api/crm/leads/[leadId]/report` | Bearer | AI report pokud ready |
| `GET /api/crm/health` | None | Health check |

### FAPI / Webhooks

| Endpoint | Auth | Description |
|----------|------|-------------|
| `POST /api/webhooks/fapi` | Secret v URL query | FAPI events (paid invoice, voucher used) |
| `POST /api/webhooks/smartemailing` | Bearer | SE batch events (open, click, unsubscribe) |

> `/api/webhook/github-sync` byl **odstraněn** z backoffice. Auto-sync
> Studio souborů žije v akademii: `apps/akademie/src/app/api/webhooks/github-sync/`.

---

## Authentication

### MCP tokens (backoffice)

```
Authorization: Bearer cs_your-token-here
```

SHA-256 hashed v `api_tokens.token_hash`. Tokeny per user. Multiple
tokens, individually revocable.

### CRM API

```
Authorization: Bearer <CRM_API_KEY>
```

Single shared secret pro pull integrace (quiz API serverem). Read-only.

### Webhook secrets

URL query nebo `X-Webhook-Secret` header. Timing-safe compare proti env.

---

## More Documentation

- **Backoffice-specific**:
  - [MCP Tools Reference](/docs/mcp) — admin tools (skills, CRM, support, …)
  - [`platform/architecture.md`](./platform/architecture.md) — vrstvy
  - [`platform/admin.md`](./platform/admin.md) — admin guide
  - [`platform/integrations.md`](./platform/integrations.md) — FAPI, quiz, SmartEmailing
  - [`platform/security.md`](./platform/security.md) — RLS, RBAC, audit
- **Akademie protějšek** (pro user-facing context):
  - `apps/akademie/src/docs/index.md` — entry point
  - `apps/akademie/src/docs/mcp.md` — JSON-RPC 2.0 dispatcher + 18 tools
  - `apps/akademie/src/docs/studio.md` — power-user workspace + index API
  - `apps/akademie/src/docs/permissions.md` — sdílené RBAC schema

---

## Změny 13.5.2026 (Context Store removal)

Backoffice Context Store byl kompletně odstraněn ze user-facing app:

- ❌ `/store` route (file-tree editor) — smazán
- ❌ `/api/export` (ZIP download) — smazán
- ❌ `/api/webhook/github-sync` — smazán, port v akademii
- ❌ `/settings/github` — smazán, port v akademii
- ❌ 5 MCP tools (`list_files`, `read_file`, `write_file`, `delete_file`, `search_files`)
- ❌ `lib/store/`, `lib/github/`, `components/store/` — smazáno
- ✅ Data **zachovaná** v DB (`context_files` table zůstává jako backup, drop přijde po verifikaci)
- ✅ Auto-migrace data do `user_context_files(scope='workspace')`
  proběhla migrací `20260513000002_migrate_context_store_to_studio.sql`

**Co to znamená pro tým**: pokud jsi měl/a obsah ve `/store`, najdeš
ho v akademii Studio (`/studio` route, ikona FolderTree v sidebaru).
Potřebuješ `akademie.workspace` permission — admin (`*`) ji má
automaticky.