# 书嗨 (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) 分层架构：

```text
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 命令清单
```bash
# 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` 规范，开发新功能时需遵循以下标准：

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