456 lines
12 KiB
Markdown
456 lines
12 KiB
Markdown
# 智助小程序 - 开发文档
|
||
|
||
## 项目简介
|
||
|
||
智助是一款基于 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) - 初始版本发布
|
||
- 用户登录注册
|
||
- 图书上传功能
|
||
- 商品管理
|
||
- 仓库管理
|
||
|
||
---
|
||
|
||
## 开发团队
|
||
|
||
本项目由知书团队开发维护。
|
||
|
||
---
|
||
|
||
## 许可证
|
||
|
||
本项目为商业项目，版权归知书团队所有。
|