docs: define acl and import backend work

2026-07-12 19:00:47 +02:00
1 parent 84e4123f09
commit 63ab21616c
@@ -0,0 +1,94 @@
+# ACL and Import Backend Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Complete ACL management and activate every existing administration import workflow.
+
+**Architecture:** Use the normalized ACL tables as the single authorization source and map emulator ranks to `rank_<id>` roles. Port the proven import core and services from `habbo-next`, expose them through locale-free API routes guarded server-side, and verify DB plus filesystem outputs.
+
+**Tech Stack:** Next.js 16 route handlers, React 19, TypeScript, Prisma/MariaDB, Vitest, Node filesystem and streams.
+
+## Global Constraints
+
+- Work directly in `E:\Users\simol\Desktop\EpicNext-cms`; no worktree or subagents.
+- Preserve and never stage the existing `package.json` modification.
+- Pull `main` before publication and never force-push.
+- Do not copy generated Prisma files.
+- Every import API requires `admin.assets.import`; destructive catalog operations also require `admin.catalog.edit`.
+- Import success requires database and required filesystem/FurnitureData outputs.
+
+---
+
+### Task 1: Lock ACL and route coverage with failing contracts
+
+**Files:**
+- Create: `src/lib/admin/acl-management-contract.test.ts`
+- Create: `src/lib/import-backend-contract.test.ts`
+
+- [ ] Assert that permission mutations use `adminAction` with `PERMS.PERMISSIONS_MANAGE`, write normalized ACL tables, and do not write legacy housekeeping permission tables.
+- [ ] Assert that every API referenced by `src/app/admin/import/**` exists and contains a server-side `PERMS.ASSETS_IMPORT` guard.
+- [ ] Run both tests and verify they fail on the missing management/API implementation.
+- [ ] Commit with `test: define acl and import backend contracts`.
+
+### Task 2: Normalize ACL persistence and management
+
+**Files:**
+- Modify: `src/actions/permissions.ts`
+- Modify: `src/app/admin/permissions/page.tsx`
+- Modify: `src/app/admin/permissions/[id]/page.tsx`
+- Modify: `src/app/admin/permissions/[id]/rank-edit-client.tsx`
+- Use: `src/lib/services/permission-ranks.ts`
+- Create: `prisma/migrations/0014_complete_acl_and_import_permissions.sql`
+
+- [ ] Add focused failing tests for rank service and ACL assignment behavior.
+- [ ] Replace legacy writes with emulator rank service and normalized ACL assignments.
+- [ ] Seed and migrate roles/permissions idempotently, using `Role` and `User` discriminator casing.
+- [ ] Invalidate permission cache, update RCON, and log each mutation.
+- [ ] Run ACL tests and migration contract tests; commit with `fix: complete acl management`.
+
+### Task 3: Port shared import core and domain services
+
+**Files:**
+- Create: `src/lib/services/import/core/*.ts`
+- Create: `src/lib/services/{clone-import,clothing-set-import,effect-import,figure-import,furni-import,nitro-assets,pet-import}.ts`
+- Modify: `src/lib/services/furni-asset-dirs.ts`
+- Modify: `src/lib/services/furni-data.ts`
+- Test: matching `*.test.ts` files
+
+- [ ] Port tests first and verify failures from missing modules.
+- [ ] Port reference implementations, adapting Prisma model names and EpicNext settings.
+- [ ] Preserve Windows absolute-path handling and live Nitro mirroring.
+- [ ] Run all import service tests; commit with `feat: add asset import services`.
+
+### Task 4: Add guarded import route handlers
+
+**Files:**
+- Create: `src/app/api/admin/import/**/route.ts`
+- Create: `src/app/api/nitro-assets/bundled/furniture/[...path]/route.ts`
+
+- [ ] Add badge, clone, clothing, effects, furni, pets, and repair handlers used by the existing clients.
+- [ ] Apply server-side API context plus `PERMS.ASSETS_IMPORT` to every handler.
+- [ ] Require `PERMS.CATALOG_EDIT` for deletion, repair, resync, and catalog-mutating operations.
+- [ ] Run route contract, API authorization, and service tests; commit with `feat: add guarded asset import api`.
+
+### Task 5: Align pages, actions, and permissions
+
+**Files:**
+- Modify: `src/app/admin/import/**/page.tsx`
+- Modify: `src/actions/import-badges.ts`
+- Modify: `src/actions/import-furni.ts`
+- Modify: `src/lib/permission-slugs.ts`
+
+- [ ] Make every import page use `PERMS.ASSETS_IMPORT` consistently.
+- [ ] Replace stub cleanup/deletion behavior with guarded service calls.
+- [ ] Run contract tests and TypeScript; commit with `fix: connect admin import workflows`.
+
+### Task 6: Complete verification and publish
+
+**Files:**
+- Verify all committed files; exclude `package.json`.
+
+- [ ] Run `git diff --check origin/main...HEAD`.
+- [ ] Run `pnpm test`, `pnpm typecheck`, and `pnpm build`.
+- [ ] Confirm `git status --short` contains only ` M package.json`.
+- [ ] Fetch `origin/main`, require it to be an ancestor of `HEAD`, and push `main` without force.
@@ -0,0 +1,33 @@
+# ACL and import backend design
+
+## Goal
+
+Complete the administration ACL management and make every existing asset-import page functional end to end.
+
+## ACL architecture
+
+`acl_permissions`, `acl_roles`, `acl_model_permissions`, and `acl_model_roles` are the only CMS authorization source. Emulator ranks remain in `permission_ranks`; each rank maps to the CMS role `rank_<id>`. Legacy `website_permissions` and `website_housekeeping_permissions` may be migrated but are not written by the new management flow.
+
+The permissions screen manages emulator ranks, rank roles, role permission assignments, and direct user roles/permissions. Rank creation, editing, and deletion use the emulator rank service, refresh RCON permissions, invalidate the permission cache, and log staff activity. Every mutation requires `admin.permissions.manage` and fails closed.
+
+## Import authorization
+
+All import pages and every `/api/admin/import/**` handler require `admin.assets.import`. Catalog deletion or repair operations that mutate catalog data additionally require `admin.catalog.edit`. Page-level checks are navigation guards only; API handlers repeat authorization before reading remote sources, writing the database, or writing files.
+
+## Import pipeline
+
+Port the reference import core, services, API routes, and tests for badges, clone, clothing, effects, furni, pets, and repair. Adapt imports to EpicNext's generated Prisma names and locale-free routes. Do not copy generated Prisma files.
+
+The furni success boundary is atomic at the workflow level: verify database rows, repository asset output, configured live Nitro asset output, and `FurnitureData.json`. External Windows paths use the existing cross-platform resolver. Repair/audit reports partial state instead of treating a database insert as success.
+
+## Migration
+
+Add an idempotent migration that seeds `admin.assets.import`, normalizes ACL discriminator casing to `Role` and `User`, creates missing `rank_<id>` roles, migrates compatible legacy permission assignments, and grants the highest rank explicit management/import permissions. Dynamic highest-rank bypass remains an emergency compatibility path, not the persisted assignment model.
+
+## Error handling and verification
+
+Remote download errors, invalid archives/data, filesystem failures, schema mismatches, and partial writes return structured errors and are logged without exposing secrets. Contract tests assert route coverage and server-side ACL guards. Service tests cover path resolution, batch behavior, data reconciliation, and fail-closed authorization. Final verification runs all tests, TypeScript, and the production build.
+
+## Scope boundary
+
+This block does not add moderation, analytics, detailed logs, or DevOps pages. Those remain the next phase after ACL and imports are verified.