greeneclipse
8580c996c3
Drop one-shot tmp/axe scripts and agent i18n scratch so the Gitea tree is deployable.
98 lines
4.1 KiB
Markdown
98 lines
4.1 KiB
Markdown
# 06 — Admin KB + auto-reply settings UI
|
|
|
|
**Agent:** 6/10 (`support-auto`)
|
|
**Date:** 2026-08-05
|
|
**Status:** Implemented (frontend + AI config columns)
|
|
|
|
---
|
|
|
|
## PROBLEM
|
|
|
|
Full platform admins need a clean place to manage support knowledge articles/templates, toggle FAQ auto-match + AI fallback (enable, thresholds, draft vs auto-send), and see which admin AI role powers fallback — without giving `support_staff` settings mutation.
|
|
|
|
---
|
|
|
|
## Routes & auth
|
|
|
|
| Surface | Path | Gate |
|
|
|---------|------|------|
|
|
| UI | `/admin/support/knowledge` | `requirePlatformAdmin()` |
|
|
| Nav | Admin shell **Manage → Support KB** | `fullAdminOnly` |
|
|
| Inbox shortcut | Support Center actions (full admin) | `fullAdmin` |
|
|
| API articles | `/api/admin/support/kb/articles*` | `RequirePlatformAdmin` |
|
|
| API templates | `/api/admin/support/templates*` | `RequirePlatformAdmin` |
|
|
| API settings | `/api/admin/support/auto-config` | `RequirePlatformAdmin` |
|
|
|
|
**ASSUMPTION:** Contract lists KB CRUD as platform-admin only; staff do **not** get a read-only KB UI in this pass (inbox remains their surface).
|
|
|
|
---
|
|
|
|
## Files
|
|
|
|
| File | Intent |
|
|
|------|--------|
|
|
| `apps/web/src/lib/support/admin-kb-api.ts` | Typed client for articles, templates, auto-config |
|
|
| `apps/web/src/routes/admin/support/knowledge/+page.svelte` | Tabs: Articles · Templates · Auto-reply |
|
|
| `apps/web/src/lib/components/AdminNav.svelte` | Support KB nav + active-state split from ticket inbox |
|
|
| `apps/web/src/routes/admin/support/+page.svelte` | Link to knowledge page for full admins |
|
|
| `apps/api/sql/schema/033_support_auto_ai_config.sql` | AI columns on `support_auto_config` |
|
|
| `apps/api/internal/support/kb_types.go` | Extended `AutoConfig` / `AutoConfigInput` |
|
|
| `apps/api/internal/support/match_auto_reply.go` | Get/UpdateAutoConfig read/write AI fields |
|
|
| `apps/api/internal/support/errors.go` | `ErrInvalidAIThreshold`, `ErrInvalidAIDelivery` |
|
|
|
|
Backend CRUD handlers already from agent 3: `support_kb_handlers.go` + mounts in `server.go`.
|
|
|
|
---
|
|
|
|
## UX
|
|
|
|
1. **Articles** — list, create/edit dialog (slug, markdown body, keywords, intents, categories, publish, weight), delete.
|
|
2. **Templates** — same pattern; placeholders `{{subject}}` / `{{category}}`.
|
|
3. **Auto-reply** — two cards:
|
|
- FAQ: master enable, faq_enabled, match threshold, retry-on-first-reply
|
|
- AI: ai_enabled, delivery (`draft` \| `auto_send`), AI threshold, use global support role, optional overrides
|
|
4. **Support AI role card** — loads `ai_roles.support` from `GET /api/admin/settings`; links to `/admin/settings` AI roles tab. Key always from that role; overrides only provider/model/base URL.
|
|
|
|
Matches admin shell: `PageShell`, dark `.dark` tokens, `TableShell` / `Tabs` / `Dialog` / `Card`.
|
|
|
|
---
|
|
|
|
## Settings contract mapping
|
|
|
|
| UI control | `AutoConfig` JSON field | Default |
|
|
|------------|-------------------------|---------|
|
|
| Enable automatic first responses | `enabled` | false |
|
|
| FAQ / template matching | `faq_enabled` | true |
|
|
| Match confidence | `match_confidence_threshold` | 0.78 |
|
|
| Retry on first customer reply | `retry_on_first_customer_reply` | false |
|
|
| Enable AI fallback | `ai_enabled` | false |
|
|
| Delivery mode | `ai_delivery` | `draft` |
|
|
| AI confidence | `ai_confidence_threshold` | 0.65 |
|
|
| Use platform support role | `ai_use_global_support_role` | true |
|
|
| Overrides | `ai_*_override` | empty |
|
|
|
|
Rate-limit fields from contract §8 are **not** in this UI yet (table has no columns); agent 4/9 can add later.
|
|
|
|
---
|
|
|
|
## Verification
|
|
|
|
```powershell
|
|
cd apps\web
|
|
npm run check
|
|
```
|
|
|
|
Manual:
|
|
|
|
1. Full admin → Manage → Support KB → create published article with keywords → save auto settings (FAQ on, AI draft).
|
|
2. Confirm Platform settings → AI roles → Support shows as the fallback provider card.
|
|
3. `support_staff` → Support KB nav hidden; deep link `/admin/support/knowledge` → forbidden empty state.
|
|
4. After migrate 032+033, settings persist via `PUT /api/admin/support/auto-config`.
|
|
|
|
---
|
|
|
|
## Notes for integrator (agent 10)
|
|
|
|
- Migration order: `032_support_kb_auto_reply.sql` then `033_support_auto_ai_config.sql`.
|
|
- `GetAutoConfig` falls back to FAQ-only SELECT if AI columns are missing (pre-033).
|
|
- No git commit from this agent. |