# quick-ai-script-admin

**Repository Path**: yooyeLearning/quick-ai-script-admin

## Basic Information

- **Project Name**: quick-ai-script-admin
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-08-12
- **Last Updated**: 2026-08-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# QuickScript AI 管理平台

> 面向运营人员的剧本/用户/类型/权限一体化管理后台 —— 基于 React 19 + TypeScript + Ant Design 6 构建

[![React](https://img.shields.io/badge/React-19.x-61dafb?logo=react)](https://react.dev)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178c6?logo=typescript)](https://www.typescriptlang.org)
[![Ant Design](https://img.shields.io/badge/Ant_Design-6.x-0170fe?logo=antdesign)](https://ant.design)
[![Vite](https://img.shields.io/badge/Vite-7.x-646cff?logo=vite)](https://vitejs.dev)
[![Zustand](https://img.shields.io/badge/Zustand-5.x-orange)](https://zustand-demo.pmnd.rs)
[![License](https://img.shields.io/badge/license-Private-red)](#许可证)

---

## 目录

- [项目简介](#项目简介)
- [核心特性](#核心特性)
- [技术栈](#技术栈)
- [快速开始](#快速开始)
- [常用命令](#常用命令)
- [环境变量](#环境变量)
- [项目结构](#项目结构)
- [架构与模块边界](#架构与模块边界)
- [开发规范](#开发规范)
- [浏览器兼容性](#浏览器兼容性)
- [常见问题](#常见问题)
- [路线图](#路线图)
- [许可证](#许可证)

---

## 项目简介

**QuickScript AI 管理平台** 是面向运营人员的 Web 管理后台，用于管理 AI 剧本生成平台的内容、用户、权限和分类体系。运营人员通过此平台完成剧本审核、用户管理、角色权限分配、分类维护、运营数据查看等日常工作。

本平台为单页应用（SPA），采用前后端分离架构，所有数据通过 RESTful API 获取；开发期使用 [json-server](https://github.com/typicode/json-server) 模拟后端接口。

---

## 核心特性

- 📜 **剧本管理** —— 剧本列表、审核、批量处理
- 👥 **账号与角色** —— 管理员账号、角色权限的完整 RBAC 管理
- 🏷️ **类型管理** —— 作品分类体系的增删改查
- 📊 **数据仪表盘** —— 基于 ECharts 的运营数据可视化
- 🌗 **主题配置** —— 明暗模式、6 种主题色、紧凑度，支持「跟随系统」
- 🔐 **权限控制** —— 基于 `permissions` 键位的细粒度菜单/按钮级权限
- 🛣️ **路由守卫** —— `AuthGuard` + `GuestGuard` 双层守卫
- 🌐 **中文优先** —— Ant Design 国际化 + 全中文 UI

---

## 技术栈

| 类别 | 技术 | 版本 | 说明 |
|------|------|------|------|
| 前端框架 | React | 19.x | 函数组件 + Hooks |
| 开发语言 | TypeScript | 5.x+ | `strict: true` 严格模式 |
| UI 组件库 | Ant Design | 6.x | 唯一 UI 库 |
| 状态管理 | Zustand | 5.x | 配合 `persist` 中间件 |
| 路由 | React Router | v7+ | `createBrowserRouter` |
| 构建工具 | Vite | 7.x+ | `@vitejs/plugin-react` |
| 包管理器 | pnpm | 最新 | 严禁使用 npm / yarn |
| Mock 服务 | json-server | 最新 | 仅开发环境 |
| 代码规范 | oxlint | 最新 | 基于 Oxc 的 Rust 实现 |
| 图表库 | ECharts | 6.x | 仪表盘可视化 |

---

## 快速开始

### 环境要求

| 工具 | 版本 | 说明 |
|------|------|------|
| Node.js | ≥ 18.0 | 推荐 20 LTS |
| pnpm | ≥ 8.0 | `npm i -g pnpm` |

### 安装

```bash
# 1. 克隆仓库
git clone <repository-url>
cd quick-ai-script-admin

# 2. 安装依赖
pnpm install
```

### 启动开发服务器

```bash
# 仅启动前端（需自行启动 mock 服务）
pnpm dev

# 同时启动前端 + mock 后端（推荐）
pnpm dev:mock
```

启动后访问 [http://localhost:5173](http://localhost:5173)，默认登录任意账号即可进入（mock 模式未做鉴权校验）。

### 生产构建

```bash
# 1. 类型检查 + 构建
pnpm build

# 2. 本地预览生产包
pnpm preview
```

构建产物输出至 `dist/` 目录。

---

## 常用命令

| 命令 | 说明 |
|------|------|
| `pnpm dev` | 启动 Vite 开发服务器（仅前端） |
| `pnpm build` | 类型检查并构建生产包 |
| `pnpm preview` | 本地预览生产包 |
| `pnpm lint` | 运行 oxlint 代码检查 |
| `pnpm mock` | 启动 json-server mock 服务（端口 3003） |
| `pnpm dev:mock` | 并行启动前端 + mock 服务 |

---

## 环境变量

项目根目录维护两个环境文件，Vite 会根据 `npm run` 的模式自动加载：

- **`.env.development`** —— `pnpm dev` 时生效
- **`.env.production`** —— `pnpm build` 时生效

| 变量名 | 用途 | 开发环境示例 | 生产环境示例 |
|--------|------|--------------|--------------|
| `VITE_BASE_URL` | API 请求基础路径 | `http://localhost:3003/api/v1` | `https://api.example.com/api/v1` |

> 所有自定义环境变量**必须**以 `VITE_` 开头才能被前端访问。

---

## 项目结构

```
quick-ai-script-admin/
├── mock/                          # json-server 数据模拟
│   ├── db.json                    # Mock 数据
│   ├── routes.json                # 自定义路由
│   └── middleware.cjs             # 中间件
├── public/                        # 不经过构建的静态资源
├── src/
│   ├── app/                       # 应用装配层
│   │   ├── layouts/               # 布局组件
│   │   │   ├── RootLayout.tsx     # 主布局（侧边栏 + 头部）
│   │   │   └── AuthLayout.tsx     # 登录页布局
│   │   ├── router/                # 路由配置
│   │   │   ├── index.tsx          # 路由定义
│   │   │   ├── routes.tsx         # 业务路由元数据
│   │   │   └── guards.tsx         # 路由守卫
│   │   ├── providers/             # 全局 Context 聚合
│   │   │   ├── index.tsx          # Provider 入口
│   │   │   └── ThemeProvider.tsx  # 主题 Provider
│   │   └── utils/                 # 路由/菜单辅助函数
│   ├── features/                  # 核心业务功能（按领域划分）
│   │   ├── auth/                  # 认证
│   │   ├── dashboard/             # 仪表盘
│   │   ├── genres/                # 类型管理
│   │   ├── account/               # 账号/角色/权限
│   │   ├── script/                # 剧本管理
│   │   └── result/                # 结果页（403/404）
│   ├── shared/                    # 通用基础设施（不可依赖 features）
│   │   ├── ui/                    # 通用 UI 组件
│   │   │   └── ThemeSwitcher/     # 主题切换面板
│   │   ├── hooks/                 # 通用 Hooks
│   │   │   ├── usePermission.ts   # 权限校验
│   │   │   ├── useTheme.ts        # 主题应用
│   │   │   └── index.ts
│   │   ├── utils/                 # 通用工具
│   │   │   └── theme.ts           # antd token 生成
│   │   ├── stores/                # 全局 Store
│   │   │   ├── permission.ts      # 权限 Store
│   │   │   └── useThemeStore.ts   # 主题 Store
│   │   ├── api/                   # API 客户端
│   │   │   └── client.ts          # Axios 实例
│   │   ├── types/                 # 全局类型
│   │   │   └── theme.ts           # 主题类型
│   │   └── constants/             # 全局常量
│   │       └── permissions.ts     # 权限键位 + 模块元数据
│   ├── App.tsx                    # 根组件
│   └── main.tsx                   # 入口文件
├── .env.development               # 开发环境变量
├── .env.production                # 生产环境变量
├── index.html                     # HTML 模板
├── package.json
├── tsconfig.json
├── vite.config.ts
├── oxlint.config.json             # oxlint 配置（如有）
└── README.md
```

---

## 架构与模块边界

本项目严格执行三层依赖方向：

```
app/       →  可依赖 features 和 shared
features/  →  可依赖 shared，❌ 不可依赖其他 features
shared/    →  ❌ 不可依赖 features 或 app
```

### 命名规范

| 类型 | 命名规则 | 示例 |
|------|----------|------|
| 页面级组件 | `{领域}Page` | `ScriptsPage`、`GenresPage` |
| 子组件 | `{领域}{功能}` | `ScriptsTable`、`GenreFormModal` |
| 通用组件 | `{功能}` | `SearchInput`、`ThemeSwitcher` |
| Hook | `use{领域}` 或 `use{功能}` | `useScripts`、`useTheme` |
| Store | `use{领域}Store` | `useScriptStore`、`useThemeStore` |
| API 函数 | `{操作}{领域}` | `fetchScripts`、`createGenre` |
| 样式 | PascalCase + `.module.less` | `ThemeSwitcher/index.module.less` |

### 路径别名

统一使用 `@/` 指向 `src/`，**禁止**使用相对路径引用 `src/` 下的文件。

```ts
// ✅ 正确
import { client } from '@/shared/api/client'

// ❌ 错误
import { client } from '../../../shared/api/client'
```

### 权限系统

权限以字符串键位定义在 [`src/shared/constants/permissions.ts`](src/shared/constants/permissions.ts)，包含：

- **`PERMISSIONS`** —— 所有权限键位常量（如 `scripts.view`、`users.ban`）
- **`PERMISSION_MODULES`** —— 按模块组织的权限元数据（用于角色编辑页）
- **`usePermission`** —— Hook 形式消费，支持 `can('users.ban')` 校验

在路由 `handle` 中通过 `permission` 字段声明所需权限，菜单和守卫会自动过滤。

---

## 开发规范

### 导入顺序

```ts
// 1. React 相关
import React, { useState } from 'react'

// 2. 第三方库
import { Button } from 'antd'
import { useNavigate } from 'react-router'

// 3. 项目内部模块（@/ 别名）
import type { Script } from '@/features/script/types'
import { useScriptStore } from '@/features/script/stores'

// 4. 样式文件
import styles from './index.module.less'
```

### 错误处理

所有异步操作**必须**使用 `try-catch`，`catch` 中**必须**记录 `console.error`，用户可见错误**必须**使用 `message.error()`。

### 类型约束

- 开启 `strict: true` / `noImplicitAny: true` / `strictNullChecks: true`
- 优先使用 `type` 而非 `interface`（需要声明合并时除外）
- 类型导入**必须**使用 `import type`
- **禁止**使用 `any`（特殊情况需注释说明）

### Git 提交规范

遵循 [Conventional Commits](https://www.conventionalcommits.org/)：

```bash
feat(scripts): add review button
fix(theme): sider not following dark mode
docs(readme): update installation steps
refactor(auth): extract login API to service
```

### 分支策略

| 分支 | 用途 |
|------|------|
| `main` | 稳定发布分支 |
| `feature/*` | 新功能开发 |
| `fix/*` | 问题修复 |
| `docs/*` | 文档更新 |

---

## 浏览器兼容性

| 浏览器 | 支持版本 |
|--------|----------|
| Chrome | 最新版 |
| Edge | 最新版 |
| Firefox | 最新版 |
| Safari | 最新版 |

- **不要求**兼容 IE 11 或任何老旧浏览器
- **不要求**兼容移动端浏览器（仅桌面端使用）
- 生产环境建议使用最新 2 个大版本的现代浏览器

---

## 常见问题

### Q1: 启动后接口 404？
确认 mock 服务是否已启动。可通过 `pnpm dev:mock` 同时启动前后端。检查 `.env.development` 中的 `VITE_BASE_URL` 是否与 json-server 端口（默认 3003）一致。

### Q2: 登录后菜单为空？
当前账号未配置权限。进入 `账号管理 → 角色管理`，为角色勾选对应权限即可。`usePermission.can()` 返回 false 的菜单会被自动隐藏。

### Q3: 主题切换不生效？
确认 `AppProviders` 已包裹 `RouterProvider`（在 `src/main.tsx`）。主题配置会持久化到 `localStorage` 的 `quick-ai-script-theme` 键。

### Q4: 添加新模块应该放哪？
业务功能放 `src/features/{领域名}/`，目录结构遵循 `components/hooks/services/stores/types` 五件套。通用工具放 `src/shared/`。

---

## 路线图

- [x] 基础架构与权限系统
- [x] 仪表盘、剧本、类型、账号/角色管理
- [x] 主题配置（明暗模式 / 主题色 / 紧凑度）
- [ ] 评论管理模块
- [ ] 财务对账模块
- [ ] 单元测试覆盖（Vitest）
- [ ] E2E 测试（Playwright）
- [ ] CI/CD 流水线

---

## 许可证

本项目为内部使用项目，**保留所有权利**。未经授权，禁止复制、修改、分发或用于商业用途。

Copyright © 2026 QuickScript AI. All Rights Reserved.