wenzi/docs/plans/2026-02-04-admin-production-plan.md

# Admin Production-Grade (Demo + RBAC) Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

**Goal:** 在 admin 端实现生产级功能框架与演示登录/数据，同时预留真实鉴权接入。
**Architecture:** 前端引入 AuthAdapter + RBAC + DemoDataService，未登录默认演示管理员视图，真实鉴权仅需替换 Adapter 与数据源。
**Tech Stack:** Vue 3, Pinia, Vue Router, Vite, TypeScript, Tailwind

---

## Decisions / Constraints
- 不新增依赖（如 Vitest）除非你确认。
- 不执行 git commit（如需提交请明确指示）。

---

### Task 1: 建立 auth 目录结构

**Files:**
- Create: `frontend/admin/src/auth/types.ts`
- Create: `frontend/admin/src/auth/roles.ts`
- Create: `frontend/admin/src/auth/adapters/AuthAdapter.ts`
- Create: `frontend/admin/src/auth/adapters/DemoAuthAdapter.ts`

**Step 1: 定义角色与权限枚举**
- File: `frontend/admin/src/auth/roles.ts`
- 内容：`AdminRole`、`Permission`、`RolePermissions` 映射

**Step 2: 定义认证类型与接口**
- File: `frontend/admin/src/auth/types.ts`
- 内容：`AuthUser`、`AuthState`、`LoginResult`、`AuthAdapter` 类型

**Step 3: 实现 DemoAuthAdapter**
- File: `frontend/admin/src/auth/adapters/DemoAuthAdapter.ts`
- 行为：返回演示管理员账号 + 支持“切换角色”

---

### Task 2: 新增 auth store

**Files:**
- Create: `frontend/admin/src/stores/auth.ts`

**Step 1: 定义 state/actions**
- 初始状态为 demo admin
- actions: `loginDemo()`, `logout()`, `setRole(role)`

**Step 2: 暴露 getters**
- `isAuthenticated`, `role`, `hasPermission(permission)`

---

### Task 3: 路由与权限守卫

**Files:**
- Modify: `frontend/admin/src/router/index.ts`

**Step 1: 给 routes 增加 meta.roles**
- 所有页面默认 `['admin','operator','viewer']`
- 敏感页面（用户/配置/审计）限制为 `['admin']`

**Step 2: 添加 global beforeEach**
- 未登录自动 `auth.loginDemo()`
- role 不满足则跳转到 `/403`

**Step 3: 添加 403 页面**
- Create: `frontend/admin/src/views/ForbiddenView.vue`
- Route: `/403`

---

### Task 4: 登录页 + 演示一键登录

**Files:**
- Create: `frontend/admin/src/views/LoginView.vue`
- Modify: `frontend/admin/src/router/index.ts`

**Step 1: 登录页 UI**
- 表单（用户名/密码）显示但禁用
- 一键登录按钮调用 `auth.loginDemo()` 并跳转首页

**Step 2: 路由接入**
- `/login` route

---

### Task 5: 统一演示数据层

**Files:**
- Create: `frontend/admin/src/services/demo/DemoDataService.ts`
- Create: `frontend/admin/src/services/api/ApiDataService.ts`
- Create: `frontend/admin/src/services/index.ts`

**Step 1: 定义服务接口**
- `getDashboard()`, `getActivities()`, `getUsers()`, `getRewards()`, `getAlerts()`, `getAuditLogs()`, `getConfig()`

**Step 2: Demo 实现**
- 返回结构稳定的 mock 数据
- 支持分页/筛选参数但本地处理

**Step 3: Api 实现占位**
- 使用现有 `useMosquito()` 封装（暂不调用后端登录）

---

### Task 6: 页面完善（运营/用户/奖励/风控/审计/通知）

**Files:**
- Create: `frontend/admin/src/views/UsersView.vue`
- Create: `frontend/admin/src/views/RewardsView.vue`
- Create: `frontend/admin/src/views/RiskView.vue`
- Create: `frontend/admin/src/views/AuditLogView.vue`
- Create: `frontend/admin/src/views/NotificationsView.vue`
- Modify: `frontend/admin/src/router/index.ts`
- Modify: `frontend/admin/src/App.vue`

**Step 1: UsersView**
- 用户列表 + 角色标签 + 搜索框

**Step 2: RewardsView**
- 奖励发放列表 + 状态筛选

**Step 3: RiskView**
- 黑名单/风控规则列表 + 占位操作

**Step 4: AuditLogView**
- 审计日志表格 + 时间筛选

**Step 5: NotificationsView**
- 通知列表 + 未读标记

**Step 6: 导航接入**
- App header 新增导航项，按角色控制可见

---

### Task 7: 现有页面接入新数据服务

**Files:**
- Modify: `frontend/admin/src/views/DashboardView.vue`
- Modify: `frontend/admin/src/views/ActivityListView.vue`

**Step 1: 替换为统一服务调用**
- 用 `services/index.ts` 中的 `dataService`

**Step 2: 演示模式标识**
- header 显示“演示模式”badge

---

### Task 8: 权限与演示状态的 UI 反馈

**Files:**
- Modify: `frontend/admin/src/App.vue`
- Modify: `frontend/admin/src/styles/index.css`

**Step 1: 顶部状态条**
- 显示当前角色/是否演示

**Step 2: 非授权页面提示**
- 403 页面完善

---

### Task 9: 文档

**Files:**
- Create: `docs/admin-demo-auth.md`

**Step 1: 说明演示模式**
- 如何进入演示
- 未来如何替换为真实鉴权

---

### Task 10: 手工验证清单

**Steps:**
1. 启动 admin：`npm --prefix "frontend/admin" run dev -- --host 127.0.0.1 --port 5174 --strictPort`
2. 访问 `/login`，点击“一键登录”进入首页
3. 切换角色（admin/operator/viewer），观察菜单变化
4. 访问 `/403` 验证无权限提示
5. 各页面可渲染且无控制台错误

---

## Execution Handoff

Plan complete and saved to `docs/plans/2026-02-04-admin-production-plan.md`. Two execution options:

1. Subagent-Driven (this session) - I dispatch fresh subagent per task, review between tasks, fast iteration
2. Parallel Session (separate) - Open new session with executing-plans, batch execution with checkpoints

Which approach?