docs: "Admin console — using every screen" guide (en/ko)

docs/guides/admin-console.ko.md

@@ -0,0 +1,110 @@
+# Admin 콘솔 — 모든 화면 사용법
+
+[admin 콘솔](https://github.com/devslab-kr/devslab-kit-admin-ui)은 kit이 관리하는 모든 것을
+다루는 완성형 웹 UI입니다. 이 가이드는 **모든 메뉴**를 단계별로 설명합니다. 여기 나오는 작업은
+전부 [관리자 REST API](../reference/admin-api.md)로도 할 수 있습니다.
+
+!!! info "콘솔 열기"
+    admin-ui 실행(`npm run dev` → `http://localhost:5173`); dev에서는 `/admin/api` 를 `:8080`
+    의 앱으로 프록시합니다. 플랫폼 계정(예: 부트스트랩 `admin`)으로 로그인하세요. 왼쪽
+    사이드바는 화면을 **Identity & Access**, **Platform**, **Observability** 로 묶습니다. 각 행의
+    동작은 오른쪽 작은 아이콘 버튼이며 **아이콘에 마우스를 올리면 툴팁**이 뜹니다.
+
+---
+
+## Identity & Access
+
+### Users (사용자)
+로그인하고 접근 권한을 받을 수 있는 플랫폼 계정.
+
+- **생성** — 우측 상단 **Create**: 로그인 id, 이메일(선택), 비밀번호, 공급자(기본 `LOCAL`).
+- **행별 동작**(아이콘에 호버하면 라벨):
+    - **잠금 / 해제**(자물쇠) — 로그인 차단/복구.
+    - **비밀번호 초기화**(열쇠).
+    - **역할 관리**(신분증) — 두 칸 선택기(*가능* | *할당*)에서 역할을 옮기고 **저장**. 여기서 준 역할은 사용자에게 직접 적용.
+    - **그룹 관리**(사람들) — 그룹 멤버십을 같은 선택기로.
+    - **상태 변경**(연필) — `ACTIVE` / `LOCKED` / `DISABLED` / `PENDING_VERIFICATION`.
+    - **삭제**(휴지통).
+
+### Roles (역할)
+권한 묶음.
+
+- **생성** — **Create**: `code`(예: `LIBRARIAN`) + 표시 이름.
+- **행별**: **권한 관리**(열쇠) → 권한 코드의 *가능 | 할당* 선택기 → **저장**; **이름 변경**(연필); **삭제**(휴지통).
+- 사용자의 유효 권한 = 직접 역할 + 소속 그룹의 역할의 합집합.
+
+### Permissions (권한)
+`resource.action` 형태(예: `book.read`)의 세분화된 권한.
+
+- **생성** — 전체 문자열을 타이핑하지 않습니다: **resource**(기존 네임스페이스 자동완성)를 고르거나 입력, **action**(`read`/`write`/`delete`/`manage`/… 또는 직접 입력)을 고릅니다. 합쳐진 코드(`book.read`)가 실시간 미리보기됩니다. 설명(선택) 후 **Create**.
+- 설명 **수정** 또는 **삭제**. 새 리소스는 그 리소스로 첫 권한을 만들 때 새 이름을 입력하면 자동 생성됩니다.
+
+### Groups (그룹)
+역할을 공유하는 사용자 모음 — 사용자마다 붙이는 대신 한 번에.
+
+- **생성** — `code` + 이름.
+- **행별**: **멤버**(사람들) → 사용자 선택; **역할**(열쇠) → 모든 멤버에게 흐르는 역할 선택; **이름 변경**; **삭제**.
+
+---
+
+## Platform
+
+### Menus (메뉴)
+제품 UI가 사용자별로 렌더할 수 있는 권한 필터링 네비게이션 트리.
+
+- **트리**로 표시됩니다. 루트 항목을 **Create** 하거나, 노드의 **자식 추가** 동작을 사용.
+- 각 항목은 라벨, 경로, 아이콘, **필요 권한**(기존 권한 코드 드롭다운 — 그 권한을 가진 사용자만 항목을 봄), 표시 순서를 가집니다. 노드별 **수정** / **삭제**.
+- kit은 로그인 사용자에게 필터된 트리를 제공하고, 그리는 방식은 프런트엔드가 정합니다([Menus 가이드](menus.md)).
+
+### Tenants (테넌트)
+격리된 작업공간; 모든 플랫폼 데이터는 테넌트 단위.
+
+- 테넌트 **생성**(`code` + 이름). **상태 변경**(`ACTIVE` / `SUSPENDED` / `ARCHIVED`). **삭제**.
+- 단일 테넌트 모드면 보통 `default` 하나만 둡니다.
+
+### Policies (ABAC)
+역할 위에 얹는 속성 기반 규칙. **정책은 코드**입니다(당신이 `Policy` 빈을 구현 —
+[Access 가이드](access.md#abac-정책) 참고). 이 화면은 등록된 정책을 **나열**하고 **테스트**합니다.
+
+- 정책을 고르고 **주체**(사용자/테넌트), **자원**(타입·id·속성), **환경** 속성을 채운 뒤 **Test**.
+- 결과는 **결정**(`PERMIT` / `DENY` / `NOT_APPLICABLE`)에 **이유**와 **매칭된 규칙**까지 — 부작용 없는 dry-run.
+
+### Settings (설정)
+kit의 **적용된 설정**(`devslab.kit.*`)을 읽기 전용으로 보는 화면 — JWT, 테넌트, identity 잠금,
+감사, 캐시. 시크릿은 마스킹. 실행 중인 앱이 실제로 무엇을 로드했는지 확인용. (값 변경은
+`application.yml` 에서 — [설정](../reference/configuration.md) 참고.)
+
+### Config Sync (설정 동기화)
+정의성 설정(권한·역할·메뉴)을 환경 간 승격. **기본 off**, 운영 프로파일에선 거부됨([Config Sync
+가이드](config-sync.md) 참고).
+
+- **내보내기** — 이 환경을 코드 기준 JSON 번들로 스냅샷: 보기 / **다운로드** / **복사**. **사용자 포함** 토글로 사용자 추가(비밀번호 제외).
+- **가져오기** — 번들 붙여넣기·업로드, **병합**(추가/수정) 또는 **미러**(없는 항목 삭제) 선택, 선택적 **사용자 동기화**, **미리보기(dry-run)** 로 섹션별 diff(생성/수정/삭제/건너뜀) 확인. **적용**은 동일 번들의 dry-run 후에만 활성화.
+
+---
+
+## Observability
+
+### Dashboard (대시보드)
+랜딩 페이지: KPI 카드(사용자·테넌트·현재 테넌트·로그인 사용자)와 최근 감사 이벤트. **새로고침**으로 재조회.
+
+### Diagnostics (진단)
+사용자를 가장(impersonate)하지 않고 인가를 점검:
+
+- **로그인 테스트** — 테넌트/로그인/비밀번호 조합 확인.
+- **권한 체크** — **사용자**와 **권한**을 드롭다운으로 골라(UUID 타이핑 없음) 허용 여부·이유 확인.
+- **메뉴 가시성** — 사용자를 고르면 그 사용자가 볼 메뉴 **트리**(권한 필터링).
+
+### Audit Logs (감사 로그)
+모든 관리 작업을 비동기로 기록.
+
+- 테넌트·행위자·액션·대상 타입·결과·기간으로 **필터**; 결과는 **지연 페이지네이션**.
+- 행을 클릭하면 **JSON 페이로드**(전/후 메타데이터)를 확인.
+
+---
+
+## 더 보기
+
+- [튜토리얼: 0에서 실행까지](../getting-started/tutorial.md) — 위 작업 다수를 API + 콘솔로 수행.
+- [Access (RBAC + ABAC)](access.md) · [Menus](menus.md) · [Config Sync](config-sync.md)
+- [관리자 REST API](../reference/admin-api.md) — 모든 화면 뒤의 엔드포인트.

docs/guides/admin-console.md

@@ -0,0 +1,115 @@
+# Admin console — using every screen
+
+The [admin console](https://github.com/devslab-kr/devslab-kit-admin-ui) is a ready-made
+web UI for everything the kit manages. This guide walks through **every menu**, step by
+step. It pairs with the kit's REST API — anything here can also be done with the
+[Admin REST API](../reference/admin-api.md).
+
+!!! info "Open the console"
+    Run the admin-ui (`npm run dev` → `http://localhost:5173`); in dev it proxies
+    `/admin/api` to your app on `:8080`. Sign in with your platform account (e.g. the
+    bootstrap `admin`). The left sidebar groups the screens into **Identity & Access**,
+    **Platform**, and **Observability**. Each row's actions are the small icon buttons on
+    the right — **hover any icon for a tooltip**.
+
+---
+
+## Identity & Access
+
+### Users
+Platform accounts that can sign in and be granted access.
+
+- **Create** — top-right **Create**: login id, email (optional), password, provider (default `LOCAL`).
+- **Per-row actions** (hover for labels):
+    - **Lock / Unlock** (padlock) — block or restore sign-in.
+    - **Reset password** (key).
+    - **Manage roles** (id-card) — opens a two-pane picker (*Available* | *Assigned*); move roles across and **Save**. Roles assigned here apply directly to the user.
+    - **Manage groups** (people) — same picker for group membership.
+    - **Change status** (pencil) — `ACTIVE` / `LOCKED` / `DISABLED` / `PENDING_VERIFICATION`.
+    - **Delete** (trash).
+
+### Roles
+A named bundle of permissions.
+
+- **Create** — login id… **Create**: `code` (e.g. `LIBRARIAN`) + display name.
+- **Per-row**: **Manage permissions** (key) → the *Available | Assigned* picker of permission codes → **Save**; **Rename** (pencil); **Delete** (trash).
+- A user's effective permissions = the union of their direct roles + their groups' roles.
+
+### Permissions
+Fine-grained capabilities, coded as `resource.action` (e.g. `book.read`).
+
+- **Create** — you don't type the whole string: pick/type a **resource** (autocompletes from existing namespaces), pick an **action** (`read`/`write`/`delete`/`manage`/…, or type your own). The composed code (`book.read`) previews live. Add an optional description → **Create**.
+- **Edit** the description, or **Delete**. A new resource is created simply by typing a new name when you create the first permission under it.
+
+### Groups
+Collections of users that share roles — assign once instead of per-user.
+
+- **Create** — `code` + name.
+- **Per-row**: **Members** (people) → pick users; **Roles** (key) → pick roles that flow to all members; **Rename**; **Delete**.
+
+---
+
+## Platform
+
+### Menus
+A permission-gated navigation tree your product UI can render per user.
+
+- Shown as a **tree**. **Create** a root item, or use a node's **add-child** action.
+- Each item has a label, path, icon, **required permission** (a dropdown of existing permission codes — only users holding it see the item), and display order. **Edit** / **Delete** per node.
+- The kit serves the filtered tree to a signed-in user; your front end decides how to render it (see [Menus guide](menus.md)).
+
+### Tenants
+Isolated workspaces; all platform data is scoped to a tenant.
+
+- **Create** a tenant (`code` + name). **Change status** (`ACTIVE` / `SUSPENDED` / `ARCHIVED`). **Delete**.
+- In `single`-tenant mode you typically only have `default`.
+
+### Policies (ABAC)
+Attribute-based rules layered on top of roles. **Policies are code** (you implement
+`Policy` beans — see [Access guide](access.md#abac-policies)); this screen **lists** the
+registered policies and lets you **test** them.
+
+- Pick a policy, fill in a **subject** (user/tenant), a **resource** (type, id, attributes) and any **environment** attributes, then **Test**.
+- The result is the **decision** (`PERMIT` / `DENY` / `NOT_APPLICABLE`) with a **reason** and the **matched rules** — a dry-run with no side effects.
+
+### Settings
+A live, read-only view of the kit's **effective configuration** (`devslab.kit.*`) —
+JWT, tenant, identity lockout, audit, cache. Secrets are masked. Use it to confirm what
+the running app actually loaded. (To change values, edit your `application.yml` — see
+[Configuration](../reference/configuration.md).)
+
+### Config Sync
+Promote definitional config (permissions, roles, menus) between environments. **Off by
+default** and refused under a production profile (see [Config Sync guide](config-sync.md)).
+
+- **Export** — snapshot this environment as a code-keyed JSON bundle: view / **Download** / **Copy**. Toggle **Include users** to add users (no passwords).
+- **Import** — paste or upload a bundle, choose **merge** (add/update) or **mirror** (also delete extras), optionally **Sync users**, then **Preview (dry-run)** to see the per-section diff (created / updated / deleted / skipped). **Apply** unlocks only after a dry-run of the exact bundle.
+
+---
+
+## Observability
+
+### Dashboard
+Landing page: KPI cards (users, tenants, current tenant, signed-in user) and the most
+recent audit events. **Refresh** re-pulls.
+
+### Diagnostics
+Probe authorization for any user without impersonating them:
+
+- **Login test** — verify a tenant/login/password combination.
+- **Permission check** — pick a **user** and a **permission** (dropdowns, no UUID typing) → allowed or not, and why.
+- **Menu visibility** — pick a user → the menu **tree** they would see (permission-filtered).
+
+### Audit Logs
+Every administrative action, recorded asynchronously.
+
+- **Filter** by tenant, actor, action, target type, outcome, and time range; results are **lazily paginated**.
+- Click a row to inspect its **JSON payload** (the before/after metadata).
+
+---
+
+## See also
+
+- [Tutorial: from zero to a running app](../getting-started/tutorial.md) — does much of the above via API + console.
+- [Access (RBAC + ABAC)](access.md) · [Menus](menus.md) · [Config Sync](config-sync.md)
+- [Admin REST API](../reference/admin-api.md) — the endpoints behind every screen.

mkdocs.yml

@@ -79,6 +79,7 @@ plugins:
             Caching: 캐시
             First-admin Bootstrap: 최초 관리자 부트스트랩
             Config Sync: 설정 동기화
+            Admin Console: 관리자 콘솔
             Reference: 레퍼런스
             Configuration: 설정
             Admin REST API: 관리자 REST API
@@ -144,6 +145,7 @@ nav:
       - Caching: guides/cache.md
       - First-admin Bootstrap: guides/bootstrap.md
       - Config Sync: guides/config-sync.md
+      - Admin Console: guides/admin-console.md
   - Reference:
       - Configuration: reference/configuration.md
       - Admin REST API: reference/admin-api.md