书嗨 (Book Hi) Admin - Code Wiki

1. 项目概述 (Project Overview)

书嗨后台管理系统 是一个面向二手书交易、回收、商城零售及运营管理的综合性中后台业务系统。项目前端基于 Vue 3 (Composition API) + Vite 构建，UI 层深度集成了 Element Plus 与 Ele Admin Plus，并使用 Tailwind CSS 作为原子化 CSS 引擎。项目整体架构基于经典的 RuoYi (若依) Vue3 权限管理系统 进行了二次开发与业务深度定制，支持细粒度的按钮级权限控制和动态菜单路由。

2. 整体架构与目录结构 (Architecture & Directory Structure)

项目采用标准的 Vue 3 单页应用 (SPA) 分层架构：

book-hi-admin/
├── .env.*                 # 环境变量配置 (开发、测试、生产)
├── package.json           # 项目依赖与脚本配置
├── vite.config.js         # Vite 构建与插件配置 (基于环境可能隐式配置或封装)
├── docs/                  # 项目文档库 (包含 TRAE_CODING_GUIDELINES.md 等)
└── src/                   # 源码主目录
    ├── api/               # 网络请求 API 声明，按业务模块划分
    ├── assets/            # 静态资源 (图片、Logo、SVG)
    ├── components/        # 全局通用组件 (高频业务组件、基础组件封装)
    ├── config/            # 全局系统配置 (setting.js 包含 API_BASE_URL 等)
    ├── layout/            # 页面整体布局组件 (Header, Sidebar, 框架)
    ├── router/            # 路由配置 (动态路由加载、路由守卫)
    ├── store/             # Pinia 状态管理 (用户态、字典、主题)
    ├── styles/            # 全局样式 (Tailwind 引入、Element Plus 主题覆盖、深色模式)
    ├── utils/             # 全局工具函数、Hooks (request.js, 权限校验等)
    └── views/             # 页面视图级组件，按业务模块划分

3. 主要业务模块职责 (Main Module Responsibilities)

项目的业务域主要集中在 src/views/ 目录下，拆分为以下几个核心模块：

3.1 核心交易与物流 (Trade & Logistics)

recycle / recycleOrder / recycleService / recycleAffairs: 回收业务全生命周期管理。涵盖书籍回收定价参数、库存监控、回收订单审核、物流入库出库、待处理异常等。
mallOrder / mallLogistics: C端商城零售订单管理。包含订单全流程（待付款、待发货、退款、客诉）以及运费模板、发货地址管理。
goods: 平台商品库。管理商城上架的书籍、书籍规格定义、高投诉书籍预警及价格调整工作台 (priceWorkbench)。

3.2 财务与结算 (Finance)

finance: 财务对账与出纳。包括书款支付流水、佣金结算、平台现金流、提现审核及资金概览。

3.3 营销与客户 (Marketing & Customer)

marketing: 增长与促销工具。包含红包、优惠券、裂变分销规则、满减/件折规则、活动弹窗配置以及消息推送。
customer: 客户关系管理。包含用户列表、黑名单管理、用户标签定义及用户数据统计。

3.4 数据、监控与系统 (Data & System)

data: 核心数据大盘。包含书籍库基础数据、到货率统计、商品推送日志及搜索词反馈分析。
optimization: 运营优化模块。包括订单分析、服务客诉、兜底逻辑及分析报告。
monitor / system: (若依原生核心模块) 系统监控（缓存、定时任务、登录日志、操作日志）以及系统管理（用户、角色、菜单、部门、字典配置）。

5. 关键组件、类与函数说明 (Key Components & Functions)

5.1 核心通用组件 (`src/components/`)

CommonPage/CommonTable.vue: 深度封装的列表组件。支持高度自适应 (flex-table)，内置分页、请求加载、列渲染插槽等逻辑。
CommonPage/ProSearch.vue / ProSearch2.vue: 高级搜索栏组件。基于配置化 JSON 渲染查询条件。
ProForm/index.vue: 高级表单封装。支持配置化渲染表单项、联动校验。
DictData/index.vue: 若依字典数据下拉选择等通用渲染组件。
编辑器组件: MonacoEditor, TinymceEditor, ByteMdEditor 分别应对代码、富文本、Markdown 渲染需求。

5.2 状态管理与路由 (`src/store/` & `src/router/`)

useUserStore (store/modules/user.js): 管理用户会话信息、权限 (authorities)、角色 (roles)、动态菜单树 (menus) 以及字典缓存 (dicts)。内部集成 fetchUserInfo 行为，用于初始化若依鉴权体系。
router/index.js: 全局路由守卫。拦截未登录请求，判断 getToken()，并在用户首次登录后通过 userStore.fetchUserInfo 动态拉取并挂载权限路由。

5.3 网络请求与拦截 (`src/utils/request.js`)

axios 实例拦截器: 统一在 Request Header 中注入 Authorization: token。
响应拦截: 统一处理全局错误提示，针对 HTTP 401 状态码（登录过期）进行强拦截，唤起重新登录的 Dialog 或重定向到 /login。

5.4 关键 Hooks 与工具函数 (`src/utils/`)

use-dict-data.js: 提供 useDictData(['dict_code']) Hook，自动从 Store 或接口拉取并缓存字典配置，供页面渲染下拉列表。
permission.js: 注册全局自定义指令 v-permission。例如 <el-button v-permission="'module:add'">，用于控制按钮的显示/隐藏。

6. 项目依赖关系 (Dependencies)

项目 package.json 中的核心依赖概览：

框架底座: vue (~3.4), vue-router, pinia
UI 与样式体系:
- element-plus (核心组件库)
- ele-admin-plus (高级后台组件套件)
- tailwindcss (原子化 CSS)
图表与多媒体:
- echarts / vue-echarts (数据可视化)
- xgplayer (视频/音频播放)
富交互工具:
- vuedraggable / sortablejs (拖拽)
- monaco-editor / tinymce / bytemd (多形态编辑器)
- exceljs / jszip (前端导出与解析)

7. 项目运行与部署方式 (Project Execution & Deployment)

7.1 环境准备

Node.js (推荐 18.x 或更高版本)
pnpm (推荐使用 pnpm 作为包管理器，因项目存在 pnpm-lock.yaml)

7.2 环境变量

.env.development: 开发环境变量（包含 VITE_API_URL 指向后端接口，如 https://bk.shuhi.com）。
.env.staging / .env.production: 预发与正式生产环境配置。

7.3 命令清单

# 1. 安装依赖
pnpm install

# 2. 启动开发服务器
pnpm run dev

# 3. 执行 ESLint 代码检查与修复
pnpm run lint:eslint

# 4. 构建生产环境产物
pnpm run build

# 5. 构建并预览本地打包产物
pnpm run serve

8. 开发规范与约定 (Development Conventions)

根据项目 TRAE_CODING_GUIDELINES.md 规范，开发新功能时需遵循以下标准：

列表页结构 (List Page):
- 采用 <ele-page flex-table> 作为根容器。
- 结构固定为：搜索区 (page-search.vue) + 表格区 (common-table) + 弹窗区 (edit-dialog.vue)。
组件拆分:
- 页面特有组件必须存放在 views/模块名/components/ 目录下，并采用 kebab-case 命名（如 page-search.vue）。
- 全局通用组件存放在 src/components/ 目录下，采用 PascalCase 命名。
样式开发:
- 优先使用 Tailwind CSS 控制间距、布局、颜色等原子样式，减少手写 <style scoped> 块的频率。
字典规范:
- 绝不允许在前端代码中硬编码状态枚举，必须通过若依后台配置数据字典，并在 Vue 组件中引入 useDictData 进行渲染。

Code_Wiki.md 7.8 KB Histórico Em bruto