# 智助小程序 - 开发文档

## 项目简介

智助是一款基于 uni-app 开发的图书管理小程序，主要面向图书经销商，提供图书上传、商品管理、仓库管理等功能。项目集成了孔夫子旧书网 API，支持多端发布（微信小程序、支付宝小程序、H5、App）。

## 目录

- [技术栈](#技术栈)
- [项目结构](#项目结构)
- [环境配置](#环境配置)
- [开发指南](#开发指南)
- [核心功能](#核心功能)
- [API 接口](#api-接口)
- [组件说明](#组件说明)
- [部署发布](#部署发布)
- [常见问题](#常见问题)

---

## 技术栈

### 前端框架
- **Vue.js 2.x** - 核心框架
- **uni-app** - 跨端开发框架
- **Vuex** - 状态管理

### UI 组件库
- **uView UI 2.0.38** - 主要 UI 组件库
- **uni-ui** - DCloud 官方组件库

### 工具库
- **crypto-js 4.2.0** - 加密算法库
- **SCSS** - 样式预处理

### 开发工具
- **HBuilderX** - 官方推荐 IDE
- **微信开发者工具** - 小程序调试

---

## 项目结构

```
zhizhu/
├── api/                          # API 接口定义
│   └── kongfz.js                 # 孔夫子旧书网 API 服务
│
├── components/                   # 自定义组件
│   ├── BookConditionSelect.vue  # 图书成色选择器
│   ├── BookFilterDisplay.vue    # 图书筛选展示
│   ├── BookProductList.vue      # 图书产品列表
│   ├── CameraUpload.vue         # 相机上传组件
│   ├── CategoryDropdown.vue     # 分类下拉选择
│   ├── FormInput.vue            # 表单输入组件
│   ├── LocationPicker.vue       # 位置选择器
│   ├── PriceComparison.vue      # 价格比较组件
│   ├── PriceStockControl.vue    # 价格库存控制
│   ├── StoragePicker.vue        # 存储选择器
│   ├── TabBar.vue               # 底部导航栏
│   └── WarehouserSelector.vue   # 仓库选择器
│
├── pages/                        # 页面文件
│   ├── clone-tool/               # 商品克隆工具
│   │   └── index.vue
│   ├── entry/                    # 功能入口
│   │   └── index.vue
│   ├── goods/                    # 商品管理
│   │   └── index.vue
│   ├── index/                    # 首页
│   │   └── index.vue
│   ├── isbn-upload/              # ISBN 上传
│   │   └── index.vue
│   ├── login/                    # 登录
│   │   └── index.vue
│   ├── photo-upload/             # 照片上传
│   │   └── index.vue
│   ├── register/                 # 注册（子包）
│   │   └── index.vue
│   ├── scan/                     # 扫码相关
│   │   ├── book-records.vue     # 上书记录
│   │   └── history.vue          # 设置
│   ├── shelf/                    # 货架管理
│   │   └── management.vue
│   ├── title-upload/             # 书名上传
│   │   └── index.vue
│   ├── user/                     # 用户中心
│   │   ├── index.vue            # 个人中心
│   │   ├── memberSelect.vue     # 会员等级选择
│   │   └── dispatch-management.vue  # 下发管理
│   ├── warehouse/                # 仓库管理（子包）
│   │   ├── warehouse-select.vue  # 选择仓库
│   │   ├── create-warehouse.vue  # 创建仓库
│	│	├── order-query.vue		  # 订单查询
│	│	└── warehouse-select.vue  # 闪上书员工选择
│   └── wave/
│		├──wave.json              # 禁止刷新
│		└──wave.vue				  # 闪上书页面
│
├── static/                       # 静态资源
│   └── tabbar/                   # 底部导航图标
│
├── store/                        # Vuex 状态管理
│   └── index.js
│
├── uni_modules/                  # uni-app 插件模块
│   ├── bcode-camera/            # 条码扫描相机
│   ├── uni-fab/                 # 悬浮按钮
│   ├── uni-icons/               # 图标组件
│   ├── uni-scss/                # SCSS 预处理
│   └── uview-ui/                # uView UI 组件库
│
├── utils/                        # 工具函数
│   ├── clone-tool.js            # 克隆工具
│   ├── config.js                # 配置文件
│   ├── request.js               # 请求封装
│   └── upload.js                # 上传功能
│
├── App.vue                       # 应用根组件
├── main.js                       # 应用入口
├── pages.json                    # 页面配置
├── manifest.json                 # 应用配置
├── package.json                  # 项目依赖
├── uni.scss                      # 全局样式
└── README.md                     # 项目文档
```

---

## 环境配置

### 1. 安装依赖

```bash
npm install
```

### 2. 修改配置

编辑 [utils/config.js](utils/config.js)，配置以下参数：

```javascript
{
  // API 基础 URL
  baseURL: 'https://api.buzhiyushu.cn',

  // 客户端 ID
  clientId: '1400a724f627ddc73d8f4dd344f80a5e',

  // 授权类型（xcx: 小程序）
  grantType: 'xcx',

  // 请求超时时间（毫秒）
  timeout: 10000
}
```

### 3. 小程序配置

编辑 [manifest.json](manifest.json)，配置微信小程序 AppID：

```json
{
  "mp-weixin": {
    "appid": "wx703b8fb6c3da692a",
    "setting": {
      "urlCheck": false,
      "es6": true,
      "postcss": true,
      "minified": true
    }
  }
}
```

### 4. 开发工具

1. 下载并安装 [HBuilderX](https://www.dcloud.io/hbuilderx.html)
2. 下载并安装 [微信开发者工具](https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html)
3. 在 HBuilderX 中导入项目
4. 运行 → 运行到小程序模拟器 → 微信开发者工具

---

## 开发指南

### 页面开发规范

1. **页面命名**：使用 kebab-case 命名法，如 `isbn-upload/index.vue`
2. **组件命名**：使用 PascalCase 命名法，如 `BookProductList.vue`
3. **样式编写**：使用 SCSS，统一使用 `uni.scss` 中的变量

### 请求封装

使用 [utils/request.js](utils/request.js) 发起网络请求：

```javascript
import request from '@/utils/request.js'

// GET 请求
request({
  url: '/api/endpoint',
  method: 'GET',
  data: { key: 'value' },
  loading: true  // 显示加载提示
}).then(res => {
  console.log(res.data)
}).catch(err => {
  console.error(err)
})

// POST 请求
request({
  url: '/api/endpoint',
  method: 'POST',
  data: { key: 'value' }
})
```

### 状态管理

在 [store/index.js](store/index.js) 中使用 Vuex：

```javascript
import { mapState, mapActions } from 'vuex'

export default {
  computed: {
    ...mapState(['userInfo', 'token'])
  },
  methods: {
    ...mapActions(['setUserInfo', 'setToken'])
  }
}
```

### 组件使用

项目使用了 easycom 自动引入组件，无需手动引入：

```vue
<template>
  <u-button type="primary">按钮</u-button>
  <u-input v-model="value" placeholder="请输入内容" />
  <uni-popup ref="popup">弹窗内容</uni-popup>
</template>
```

---

## 核心功能

### 1. 用户认证

- **登录**：[pages/login/index.vue](pages/login/index.vue)
  - 支持微信授权登录
  - 支持账号密码登录

- **注册**：[pages/register/index.vue](pages/register/index.vue)
  - 新用户注册流程

### 2. 图书上传

提供两种图书上传方式：

- **ISBN 扫码上传**：[pages/isbn-upload/index.vue](pages/isbn-upload/index.vue)
  - 扫描 ISBN 码自动识别图书信息
  - 支持手动输入 ISBN

- **照片上传**：[pages/photo-upload/index.vue](pages/photo-upload/index.vue)
  - 拍照上传图书封面
  - AI 识别图书信息

### 3. 商品管理

- **商品列表**：[pages/goods/index.vue](pages/goods/index.vue)
  - 查看所有商品
  - 支持搜索和筛选
  - 支持下拉刷新

- **商品克隆工具**：[pages/clone-tool/index.vue](pages/clone-tool/index.vue)
  - 从孔夫子旧书网克隆商品
  - 批量处理商品信息
  - 自动价格调整

### 4. 仓库管理

- **仓库选择**：[pages/warehouse/warehouse-select.vue](pages/warehouse/warehouse-select.vue)
  - 选择当前使用的仓库
  - 支持多仓库切换

- **创建仓库**：[pages/warehouse/create-warehouse.vue](pages/warehouse/create-warehouse.vue)
  - 创建新仓库
  - 配置仓库信息

- **货架管理**：[pages/shelf/management.vue](pages/shelf/management.vue)
  - 管理仓库货架
  - 商品位置分配

### 5. 用户中心

- **个人中心**：[pages/user/index.vue](pages/user/index.vue)
  - 查看用户信息
  - 会员等级选择
  - 下发管理

---

## API 接口

### 后端 API

**基础 URL**：`https://api.buzhiyushu.cn`

| 接口 | 方法 | 说明 |
|------|------|------|
| `/auth/login` | POST | 用户登录 |
| `/auth/code` | GET | 获取验证码 |
| `/auth/tenant/list` | GET | 获取租户列表 |
| `/zhishu/shopGoods/xcx` | GET | 获取商品列表 |
| `/zhishu/shopGoodsPublished/batchUpdateKfzPlatformId` | POST | 批量更新平台 ID |

### 孔夫子旧书网 API

详见 [api/kongfz.js](api/kongfz.js)：

| 函数 | 说明 |
|------|------|
| `login(username, password)` | 登录孔夫子账号 |
| `fetchItems(token, params)` | 获取商品列表 |
| `getItemTplFields(token, itemId)` | 获取商品模板字段 |
| `submitItemForm(token, itemData, priceConfig)` | 提交商品表单 |
| `deleteItem(token, itemId)` | 删除商品 |
| `batchUpdatePddPlatformId(items)` | 批量更新平台 ID |

---

## 组件说明

### BookConditionSelect.vue
图书成色选择器，用于选择图书的新旧程度。

### BookProductList.vue
图书产品列表组件，展示图书信息。

### CameraUpload.vue
相机上传组件，调用相机拍照上传。

### PriceStockControl.vue
价格库存控制组件，管理商品价格和库存。

### WarehouserSelector.vue
仓库选择器，选择和管理仓库。

---

## 部署发布

### 微信小程序

1. 在 HBuilderX 中点击 **发行** → **小程序-微信**
2. 填写版本号和备注
3. 点击 **发行** 按钮
4. 在微信开发者工具中打开生成的目录
5. 上传代码到微信后台
6. 在微信公众平台提交审核

### H5

1. 在 HBuilderX 中点击 **发行** → **H5**
2. 填写网站标题和域名
3. 点击 **发行** 按钮
4. 将生成的文件部署到服务器

### App

1. 在 HBuilderX 中点击 **发行** → **原生App-云打包**
2. 选择平台（Android/iOS）
3. 填写应用信息
4. 点击 **打包** 按钮

---

## 常见问题

### 1. 如何添加新页面？

1. 在 `pages/` 目录下创建页面文件
2. 在 `pages.json` 中注册页面路径
3. 在 `pages.json` 中配置页面样式

### 2. 如何修改主题颜色？

编辑 `uni.scss`，修改全局样式变量：

```scss
$uni-color-primary: #2979ff;
$uni-color-success: #4cd964;
$uni-color-warning: #f0ad4e;
$uni-color-error: #dd524d;
```

### 3. 如何处理跨域问题？

在 `manifest.json` 中配置白名单域名：

```json
{
  "mp-weixin": {
    "setting": {
      "urlCheck": false
    }
  }
}
```

### 4. 如何调试网络请求？

在 `utils/request.js` 中添加日志：

```javascript
success: (res) => {
  console.log('请求成功:', res)
  // ...
}
```

### 5. 页面白屏怎么办？

1. 检查控制台是否有错误
2. 确认所有依赖是否正确安装
3. 清除缓存重新编译
4. 检查页面路径是否正确

---

## 版本历史

- **v1.0.0** (2024) - 初始版本发布
  - 用户登录注册
  - 图书上传功能
  - 商品管理
  - 仓库管理

---

## 开发团队

本项目由知书团队开发维护。

---

## 许可证

本项目为商业项目，版权归知书团队所有。
