iChangzuo/webend

Fork 0

Files

T

alex_q 612a567f2f 添加AGENTS.md，重写README.md

2026-06-12 13:54:20 +08:00

9.1 KiB

Raw Permalink Blame History

唱作网 (ichangzuo)

基于 Vue3 + Vite6 + TypeScript5 + Element-Plus + Pinia 等主流技术栈构建的中后台管理前端应用。

技术栈

层级	技术	版本
框架	Vue	^3.5.13
构建	Vite	^6.0.2
语言	TypeScript	^5.7.2
UI	Element Plus	^2.9.0
状态管理	Pinia	^2.2.8
路由	Vue Router	^4.5.0
国际化	Vue I18n	10.0.5
CSS	UnoCSS + SCSS	^0.65.0 / sass ^1.82.0
HTTP	Axios	^1.7.8
富文本	WangEditor	^5.1.23

环境准备

环境	要求
运行环境	Node.js ≥18（注意：20.6.0 版本不可用）
包管理器	pnpm（项目强制，npm/yarn 无法安装）
开发工具	VSCode（推荐）

开发指南

安装与启动

# 安装依赖
pnpm install

# 启动开发服务器（默认端口 3000）
pnpm dev

常用命令

命令	说明
`pnpm dev`	启动开发服务器
`pnpm build`	类型检查 + 生产构建
`pnpm build-only`	仅生产构建（不做类型检查）
`pnpm type-check`	TypeScript 类型检查
`pnpm lint:eslint`	ESLint 检查并自动修复
`pnpm lint:prettier`	Prettier 格式化
`pnpm lint:stylelint`	Stylelint 检查并自动修复
`pnpm commit`	交互式 Git 提交（必须使用，不要直接 `git commit`）

环境变量

环境变量定义在 .env.development 和 .env.production 中：

变量	开发环境	生产环境	说明
`VITE_APP_PORT`	3000	—	开发服务器端口
`VITE_APP_BASE_API`	`/dev-api`	`/prod-api`	API 代理前缀
`VITE_APP_API_URL`	`http://localhost:8989`	—	后端接口地址
`VITE_MOCK_DEV_SERVER`	false	—	是否启用 Mock 服务

注意：VITE_APP_BASE_API 是代理前缀，不是后端的真实路径。Vite 开发服务器会自动将 /dev-api 前缀剥离后再转发请求到 VITE_APP_API_URL。例如请求 /dev-api/api/v1/auth/login，实际转发到 http://localhost:8989/api/v1/auth/login。

项目结构

src/
├── api/                # API 模块（每个文件对应一个业务域，导出静态类和类型）
├── assets/icons/       # SVG 图标（通过 vite-plugin-svg-icons 加载）
├── components/         # 通用组件（自动注册，无需手动导入）
├── directive/          # 自定义指令（v-permission 按钮权限）
├── enums/              # 常量枚举（ResultEnum, CacheEnum, LayoutEnum, ThemeEnum 等）
├── lang/               # 国际化资源（zh-CN + en）
├── layout/             # 应用布局框架（侧边栏、顶栏、标签导航）
├── plugins/            # 应用插件注册（图标、路由守卫）
├── router/             # Vue Router 配置（静态路由 + 动态路由）
├── store/modules/      # Pinia 状态模块（app, permission, settings, tagsView, user）
├── styles/             # 全局样式（SCSS 变量、重置、登录样式）
├── types/              # 全局类型声明（env, auto-imports, components, router）
├── utils/              # 工具函数（request.ts = axios 封装, i18n, format, nprogress）
└── views/              # 页面组件
    ├── software/       # 软件产品页（默认首页）
    ├── helper/         # 帮助/助手页
    ├── dashboard/      # 账号信息
    ├── account/        # 用户账户（笔记、消息、VIP、安全、修改密码）
    ├── system/        # 系统管理（用户、角色、菜单、字典、配置、日志）
    ├── website/        # 网站管理
    ├── autoLogin/     # 自动登录
    ├── resetPassword/ # 重置密码
    └── error-page/    # 错误页面（401、404）

核心功能

权限系统

路由权限：基于角色的动态路由，登录后从后端获取菜单并动态注入路由
按钮权限：通过 v-permission 指令和 hasAuth() 函数控制按钮级权限
白名单路由：/software、/helper、/autoLogin、/resetPassword 无需登录即可访问
ROOT 角色：超级管理员拥有所有按钮权限，自动放行

认证流程

用户登录 → 后端返回 Token → 存储到 localStorage（key: accessToken）
路由守卫检测 Token → 获取用户信息（角色、权限） → 生成动态路由
Token 过期（后端返回 A0230） → 自动清除 Token → 重定向到登录页

API 层

API 模块位于 src/api/，每个文件导出一个静态类和对应的请求/响应类型：

auth.ts — 登录、注册、验证码
user.ts — 用户信息、账户信息
role.ts — 角色管理
menu.ts — 菜单管理
dict.ts — 字典管理
software.ts — 软件产品
helper.ts — 帮助内容
order.ts — 订单管理
integral.ts — 积分系统
message.ts — 消息通知
notice.ts — 公告管理
bank.ts — 银行信息
file.ts — 文件上传
config.ts — 系统配置
log.ts — 日志管理
statistics.ts — 数据统计
style.ts — 样式管理
codegen.ts — 代码生成

状态管理

Pinia Store 采用 Composition API 风格（defineStore("name", () => { ... })）：

模块	文件	职责
app	`store/modules/app.ts`	应用全局状态（侧边栏、设备类型等）
permission	`store/modules/permission.ts`	动态路由生成
settings	`store/modules/settings.ts`	应用设置（主题、布局、语言等）
tagsView	`store/modules/tagsView.ts`	标签导航管理
user	`store/modules/user.ts`	用户认证与信息

在组件外（如路由守卫、拦截器）使用 Store 时，用 useUserStoreHook()、useAppStoreHook() 等包装函数。

开发约定

路径别名

@ 映射到 src/，跨模块引用统一使用 @/ 前缀：

// 正确
import { useUserStore } from "@/store/modules/user";
import AuthAPI from "@/api/auth";

// 错误
import { useUserStore } from "../../store/modules/user";

自动导入

项目配置了 unplugin-auto-import 和 unplugin-vue-components，以下无需手动导入：

Vue API：ref、reactive、computed、watch、onMounted 等
Pinia：defineStore
Vue Router：useRouter、useRoute
Vue I18n：createI18n
@vueuse/core：所有导出
Element Plus：ElMessage、ElNotification、ElMessageBox 及所有组件

// 错误 — 不要添加这些导入
import { ref } from "vue";
import { ElMessage } from "element-plus";

// 正确 — 直接使用，编译时自动注入
const count = ref(0);
ElMessage.success("操作成功");

图标使用

Element Plus 图标：<i-ep-xxx />（如 <i-ep-edit />、<i-ep-delete />）
自定义 SVG 图标：将 SVG 文件放入 src/assets/icons/，使用 <SvgIcon icon-class="name" />

UnoCSS 快捷类

快捷类	等效
`flex-center`	`flex justify-center items-center`
`flex-x-center`	`flex justify-center`
`flex-y-center`	`flex items-center`
`wh-full`	`w-full h-full`
`flex-x-between`	`flex items-center justify-between`
`flex-x-end`	`flex items-center justify-end`

主题色使用 UnoCSS 的 primary（等价于 var(--el-color-primary)），不要硬编码色值。

SCSS 全局变量

src/styles/variables.scss 中的变量通过 Vite 全局注入，所有 .vue 和 .scss 文件可直接使用，无需 @use。

Git 提交规范

使用 pnpm commit 交互式提交，支持以下类型：

类型	说明
`feat`	新增功能
`fix`	修复缺陷
`docs`	文档变更
`style`	代码格式（不影响功能）
`refactor`	代码重构
`perf`	性能优化
`test`	测试相关
`build`	构建流程、外部依赖变更
`ci`	CI 配置变更
`revert`	回滚提交
`chore`	构建过程或辅助工具变更
`wip`	开发阶段临时提交

Pre-commit 钩子会自动对暂存文件执行 ESLint + Prettier + Stylelint 检查。

部署

# 生产构建
pnpm build

# 构建产物在 dist/ 目录，部署到服务器即可

Nginx 配置参考：

server {
    listen     80;
    server_name  localhost;
    location / {
        root /usr/share/nginx/html;
        index index.html index.htm;
        try_files $uri $uri/ /index.html;
    }
    # 后端 API 反向代理
    location /prod-api/ {
        proxy_pass http://localhost:8989/;
    }
}

注意：try_files 配置确保 Vue Router 的 HTML5 History 模式正常工作，刷新页面不会 404。

注意事项

自动导入插件 DTS 生成已关闭：组件类型声明已预生成。如需添加新组件，临时开启 vite.config.ts 中 AutoImport/Components 的 dts 选项，运行一次开发服务器后重新关闭。
Node 20.6.0 不可用：该版本存在已知问题，请使用其他 18+ 版本。
IDE 爆红：如遇组件、函数或引用标红，尝试重启 VSCode 或重新执行 pnpm install。

9.1 KiB Raw Permalink Blame History Unescape Escape