From 864ef9a1fa9672a7b5ffb87b450970f6ba058388 Mon Sep 17 00:00:00 2001 From: dzq Date: Wed, 15 Oct 2025 10:14:53 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E9=A1=B9=E7=9B=AE?= =?UTF-8?q?=E6=96=87=E6=A1=A3=E5=92=8C=E9=85=8D=E7=BD=AE=E6=96=87=E4=BB=B6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增项目说明文档，包含技术架构和核心功能 - 添加开发指南文档，规范开发流程 - 创建API接口文档，详细描述各模块接口 - 编写部署和维护指南，提供生产环境配置 - 添加.claude配置文件，设置权限规则 --- .claude/settings.local.json | 9 + doc/API接口文档.md | 594 +++++++++++++++++++++++++++++++++ doc/README.md | 69 ++++ doc/开发指南.md | 639 ++++++++++++++++++++++++++++++++++++ doc/部署和维护指南.md | 482 +++++++++++++++++++++++++++ doc/项目说明文档.md | 330 +++++++++++++++++++ 6 files changed, 2123 insertions(+) create mode 100644 .claude/settings.local.json create mode 100644 doc/API接口文档.md create mode 100644 doc/README.md create mode 100644 doc/开发指南.md create mode 100644 doc/部署和维护指南.md create mode 100644 doc/项目说明文档.md diff --git a/.claude/settings.local.json b/.claude/settings.local.json new file mode 100644 index 0000000..c14d84d --- /dev/null +++ b/.claude/settings.local.json @@ -0,0 +1,9 @@ +{ + "permissions": { + "allow": [ + "Bash(mkdir:*)" + ], + "deny": [], + "ask": [] + } +} diff --git a/doc/API接口文档.md b/doc/API接口文档.md new file mode 100644 index 0000000..fabd6ef --- /dev/null +++ b/doc/API接口文档.md @@ -0,0 +1,594 @@ +# API 接口文档 + +## 概述 + +本文档详细描述了智能柜管理系统前端项目的所有 API 接口，按业务模块分类。 + +## 通用接口 + +### 登录认证 + +#### 1. 获取配置信息 +- **接口**: `GET /api/common/login/config` +- **描述**: 获取系统配置信息 +- **返回**: +```typescript +{ + serverHost: string + // 其他配置信息 +} +``` + +#### 2. 密码登录 +- **接口**: `POST /api/common/login/password` +- **描述**: 使用用户名密码登录 +- **参数**: +```typescript +{ + username: string + password: string +} +``` +- **返回**: +```typescript +{ + token: string + userInfo: User +} +``` + +#### 3. 企业微信登录 +- **接口**: `POST /api/common/login/wechat` +- **描述**: 企业微信扫码登录 +- **参数**: +```typescript +{ + corpid: string + code: string + state?: string +} +``` + +## 智能柜管理模块 + +### 智能柜设备管理 + +#### 1. 获取智能柜列表 +- **接口**: `GET /api/cabinet/smart-cabinet/list` +- **描述**: 获取智能柜设备列表 +- **参数**: +```typescript +{ + page?: number + size?: number + keyword?: string + status?: string +} +``` +- **返回**: +```typescript +{ + list: SmartCabinet[] + total: number +} +``` + +#### 2. 创建智能柜 +- **接口**: `POST /api/cabinet/smart-cabinet` +- **描述**: 创建新的智能柜设备 +- **参数**: `SmartCabinet` +- **返回**: `SmartCabinet` + +#### 3. 更新智能柜 +- **接口**: `PUT /api/cabinet/smart-cabinet/{id}` +- **描述**: 更新智能柜信息 +- **参数**: `Partial` +- **返回**: `SmartCabinet` + +#### 4. 删除智能柜 +- **接口**: `DELETE /api/cabinet/smart-cabinet/{id}` +- **描述**: 删除智能柜设备 + +### 柜体格口管理 + +#### 1. 获取格口列表 +- **接口**: `GET /api/cabinet/cabinet-cell/list` +- **描述**: 获取柜体格口列表 +- **参数**: +```typescript +{ + cabinetId?: number + page?: number + size?: number + status?: string +} +``` +- **返回**: +```typescript +{ + list: CabinetCell[] + total: number +} +``` + +#### 2. 格口操作 +- **接口**: `POST /api/cabinet/cell-operation/{operation}` +- **描述**: 执行格口操作（开门、关门等） +- **参数**: +```typescript +{ + cellId: number + operation: 'open' | 'close' | 'reset' +} +``` + +### MQTT 服务器管理 + +#### 1. 获取 MQTT 服务器列表 +- **接口**: `GET /api/cabinet/mqtt-server/list` +- **描述**: 获取 MQTT 服务器配置列表 +- **返回**: `MqttServer[]` + +#### 2. 测试 MQTT 连接 +- **接口**: `POST /api/cabinet/mqtt-server/test` +- **描述**: 测试 MQTT 服务器连接 +- **参数**: `MqttServer` + +## 店铺管理模块 + +### 店铺管理 + +#### 1. 获取店铺列表 +- **接口**: `GET /api/shop/shop/list` +- **描述**: 获取店铺列表 +- **参数**: +```typescript +{ + page?: number + size?: number + keyword?: string +} +``` +- **返回**: +```typescript +{ + list: Shop[] + total: number +} +``` + +#### 2. 创建店铺 +- **接口**: `POST /api/shop/shop` +- **描述**: 创建新店铺 +- **参数**: `Shop` +- **返回**: `Shop` + +#### 3. 更新店铺 +- **接口**: `PUT /api/shop/shop/{id}` +- **描述**: 更新店铺信息 +- **参数**: `Partial` +- **返回**: `Shop` + +#### 4. 删除店铺 +- **接口**: `DELETE /api/shop/shop/{id}` +- **描述**: 删除店铺 + +### 商品管理 + +#### 1. 获取商品列表 +- **接口**: `GET /api/shop/goods/list` +- **描述**: 获取商品列表 +- **参数**: +```typescript +{ + page?: number + size?: number + keyword?: string + categoryId?: number + status?: string +} +``` +- **返回**: +```typescript +{ + list: Goods[] + total: number +} +``` + +#### 2. 获取商品详情 +- **接口**: `GET /api/shop/goods/{id}` +- **描述**: 获取商品详细信息 +- **返回**: `Goods` + +#### 3. 创建商品 +- **接口**: `POST /api/shop/goods` +- **描述**: 创建新商品 +- **参数**: `Goods` +- **返回**: `Goods` + +#### 4. 更新商品 +- **接口**: `PUT /api/shop/goods/{id}` +- **描述**: 更新商品信息 +- **参数**: `Partial` +- **返回**: `Goods` + +#### 5. 删除商品 +- **接口**: `DELETE /api/shop/goods/{id}` +- **描述**: 删除商品 + +### 分类管理 + +#### 1. 获取分类列表 +- **接口**: `GET /api/shop/category/list` +- **描述**: 获取商品分类列表 +- **返回**: `Category[]` + +#### 2. 创建分类 +- **接口**: `POST /api/shop/category` +- **描述**: 创建新分类 +- **参数**: `Category` +- **返回**: `Category` + +#### 3. 更新分类 +- **接口**: `PUT /api/shop/category/{id}` +- **描述**: 更新分类信息 +- **参数**: `Partial` +- **返回**: `Category` + +#### 4. 删除分类 +- **接口**: `DELETE /api/shop/category/{id}` +- **描述**: 删除分类 + +### 订单管理 + +#### 1. 获取订单列表 +- **接口**: `GET /api/shop/order/list` +- **描述**: 获取订单列表 +- **参数**: +```typescript +{ + page?: number + size?: number + keyword?: string + status?: string + startTime?: string + endTime?: string +} +``` +- **返回**: +```typescript +{ + list: Order[] + total: number +} +``` + +#### 2. 获取订单详情 +- **接口**: `GET /api/shop/order/{id}` +- **描述**: 获取订单详细信息 +- **返回**: `Order` + +#### 3. 创建订单 +- **接口**: `POST /api/shop/order` +- **描述**: 创建新订单 +- **参数**: `Order` +- **返回**: `Order` + +#### 4. 更新订单状态 +- **接口**: `PUT /api/shop/order/{id}/status` +- **描述**: 更新订单状态 +- **参数**: +```typescript +{ + status: string +} +``` + +### 审批管理 + +#### 1. 获取审批列表 +- **接口**: `GET /api/shop/approval/list` +- **描述**: 获取审批列表 +- **参数**: +```typescript +{ + page?: number + size?: number + type?: string + status?: string +} +``` +- **返回**: +```typescript +{ + list: Approval[] + total: number +} +``` + +#### 2. 审批操作 +- **接口**: `POST /api/shop/approval/{id}/action` +- **描述**: 执行审批操作 +- **参数**: +```typescript +{ + action: 'approve' | 'reject' + remark?: string +} +``` + +### 数据统计 + +#### 1. 获取统计数据 +- **接口**: `GET /api/shop/stats` +- **描述**: 获取系统统计数据 +- **参数**: +```typescript +{ + corpid: string +} +``` +- **返回**: +```typescript +{ + shopCount: number + goodsCount: number + orderCount: number + goodsTotalAmount: number + unReturnedGoodsCount: number + unReturnedOrderCount: number + unReturnedAmount: number + cabinetCount: number + cellCount: number + linkedCellCount: number + unmanagedCellCount: number + gatewayCount: number + topGoods: TopGoodsDTO[] + todayLatestOrderGoods: TodayLatestOrderGoodsDTO[] +} +``` + +## 企业管理模块 + +### 企业用户管理 + +#### 1. 获取企业用户列表 +- **接口**: `GET /api/qy/qy-user/list` +- **描述**: 获取企业用户列表 +- **参数**: +```typescript +{ + page?: number + size?: number + keyword?: string +} +``` +- **返回**: +```typescript +{ + list: QyUser[] + total: number +} +``` + +#### 2. 获取企业用户详情 +- **接口**: `GET /api/qy/qy-user/{id}` +- **描述**: 获取企业用户详细信息 +- **返回**: `QyUser` + +#### 3. 更新企业用户 +- **接口**: `PUT /api/qy/qy-user/{id}` +- **描述**: 更新企业用户信息 +- **参数**: `Partial` +- **返回**: `QyUser` + +#### 4. 绑定汇邦云账号 +- **接口**: `POST /api/ab98/user/bind` +- **描述**: 绑定汇邦云会员账号 +- **参数**: +```typescript +{ + qyUserId: number + name: string + idNum: string +} +``` + +## 系统管理模块 + +### 用户管理 + +#### 1. 获取用户列表 +- **接口**: `GET /api/system/user/list` +- **描述**: 获取系统用户列表 +- **参数**: +```typescript +{ + page?: number + size?: number + keyword?: string +} +``` +- **返回**: +```typescript +{ + list: SystemUser[] + total: number +} +``` + +#### 2. 创建用户 +- **接口**: `POST /api/system/user` +- **描述**: 创建新用户 +- **参数**: `SystemUser` +- **返回**: `SystemUser` + +#### 3. 更新用户 +- **接口**: `PUT /api/system/user/{id}` +- **描述**: 更新用户信息 +- **参数**: `Partial` +- **返回**: `SystemUser` + +#### 4. 删除用户 +- **接口**: `DELETE /api/system/user/{id}` +- **描述**: 删除用户 + +## 数据类型定义 + +### 通用类型 + +```typescript +// 分页响应 +type PaginationResponse = { + list: T[] + total: number +} + +// 基础实体 +interface BaseEntity { + id: number + createTime: string + updateTime: string +} +``` + +### 智能柜相关 + +```typescript +interface SmartCabinet extends BaseEntity { + name: string + code: string + status: 'online' | 'offline' | 'maintenance' + location: string + ipAddress: string + mqttServerId: number +} + +interface CabinetCell extends BaseEntity { + cabinetId: number + cellNo: string + status: 'empty' | 'occupied' | 'fault' + goodsId?: number +} + +interface MqttServer extends BaseEntity { + name: string + host: string + port: number + username?: string + password?: string +} +``` + +### 店铺相关 + +```typescript +interface Shop extends BaseEntity { + name: string + code: string + address: string + contact: string + phone: string + status: 'active' | 'inactive' +} + +interface Goods extends BaseEntity { + name: string + code: string + categoryId: number + price: number + stock: number + coverImg: string + description?: string + status: 'available' | 'sold_out' | 'disabled' +} + +interface Category extends BaseEntity { + name: string + parentId?: number + sort: number +} + +interface Order extends BaseEntity { + orderNo: string + userId: number + totalAmount: number + status: 'pending' | 'processing' | 'completed' | 'cancelled' + goodsList: OrderGoods[] +} + +interface OrderGoods extends BaseEntity { + orderId: number + goodsId: number + quantity: number + price: number + totalAmount: number +} + +interface Approval extends BaseEntity { + type: string + applicantId: number + targetId: number + status: 'pending' | 'approved' | 'rejected' + remark?: string +} +``` + +### 统计相关 + +```typescript +interface TopGoodsDTO { + goodsId: number + goodsName: string + coverImg: string + occurrenceCount: number +} + +interface TodayLatestOrderGoodsDTO { + orderGoodsId: number + goodsName: string + coverImg: string + quantity: number + totalAmount: number + buyerName: string + createTimeStr: string +} +``` + +### 企业用户相关 + +```typescript +interface QyUser extends BaseEntity { + name: string + userId: string + department?: string + position?: string + mobile?: string + email?: string + avatar?: string + ab98UserId?: number +} +``` + +## 错误码说明 + +| 错误码 | 说明 | 处理建议 | +|--------|------|----------| +| 401 | 未授权 | 检查 token 是否有效 | +| 403 | 禁止访问 | 检查用户权限 | +| 404 | 资源不存在 | 检查请求路径 | +| 500 | 服务器内部错误 | 联系系统管理员 | + +## 注意事项 + +1. 所有接口都需要在请求头中携带 token +2. 分页参数 page 从 1 开始 +3. 时间参数使用 ISO 8601 格式 +4. 文件上传使用 multipart/form-data +5. 接口返回统一使用 JSON 格式 + +--- + +**文档版本**: 1.0 +**最后更新**: 2025-10-15 \ No newline at end of file diff --git a/doc/README.md b/doc/README.md new file mode 100644 index 0000000..bfc3ac7 --- /dev/null +++ b/doc/README.md @@ -0,0 +1,69 @@ +# 项目文档目录 + +本目录包含智能柜管理系统前端项目的完整技术文档。 + +## 文档列表 + +### 📋 核心文档 + +1. **[项目说明文档.md](./项目说明文档.md)** + - 项目概述和技术架构 + - 项目结构和核心功能 + - 技术栈和开发环境 + +2. **[开发指南.md](./开发指南.md)** + - 开发环境搭建 + - 代码规范和最佳实践 + - API 开发规范 + - 组件开发指南 + +3. **[API接口文档.md](./API接口文档.md)** + - 完整的 API 接口说明 + - 按业务模块分类 + - 数据类型定义 + - 错误码说明 + +4. **[部署和维护指南.md](./部署和维护指南.md)** + - 生产环境部署流程 + - 系统维护操作 + - 故障排除指南 + - 性能优化配置 + +## 快速开始 + +### 开发人员 + +1. 阅读 **[项目说明文档.md](./项目说明文档.md)** 了解项目概况 +2. 按照 **[开发指南.md](./开发指南.md)** 搭建开发环境 +3. 参考 **[API接口文档.md](./API接口文档.md)** 进行接口开发 + +### 运维人员 + +1. 阅读 **[部署和维护指南.md](./部署和维护指南.md)** +2. 按照文档进行生产环境部署 +3. 了解日常维护操作和故障排除方法 + +## 文档维护 + +### 更新流程 + +1. 项目有重大变更时，及时更新相关文档 +2. 新增功能模块时，补充相应的 API 文档 +3. 技术栈升级时，更新开发指南 + +### 版本控制 + +- 文档版本与项目版本保持一致 +- 每次更新记录变更内容和日期 +- 重要变更需要在文档中标注 + +## 联系我们 + +如有文档相关问题，请联系： +- 项目维护团队 +- 技术负责人 + +--- + +**最后更新**: 2025-10-15 +**文档版本**: 1.0 \ No newline at end of file diff --git a/doc/开发指南.md b/doc/开发指南.md new file mode 100644 index 0000000..0c36f90 --- /dev/null +++ b/doc/开发指南.md @@ -0,0 +1,639 @@ +# 开发指南 + +## 开发环境搭建 + +### 1. 环境准备 + +```bash +# 安装 Node.js (版本 16.0+) +# 下载地址: https://nodejs.org/ + +# 安装 pnpm +npm install -g pnpm + +# 验证安装 +node --version +pnpm --version +``` + +### 2. 项目初始化 + +```bash +# 克隆项目 +git clone +cd shop-front-end + +# 安装依赖 +pnpm install + +# 启动开发服务器 +pnpm dev +``` + +### 3. 开发工具配置 + +推荐使用 VSCode 并安装以下插件： +- Vue Language Features (Volar) +- TypeScript Vue Plugin (Volar) +- ESLint +- Prettier +- Stylelint + +## 代码规范 + +### 1. 命名规范 + +#### 文件命名 +- 组件文件: `PascalCase.vue` +- 工具文件: `camelCase.ts` +- 配置文件: `kebab-case.ts` +- 样式文件: `kebab-case.scss` + +#### 变量命名 +```typescript +// 正确 +const userName = '张三' +const MAX_COUNT = 100 +const userList = [] + +// 避免 +const username = '张三' // 驼峰 +const max_count = 100 // 下划线 +``` + +#### 组件命名 +```vue + + + + + +``` + +### 2. 代码结构 + +#### Vue 组件结构 +```vue + + + + + +``` + +### 3. TypeScript 规范 + +#### 类型定义 +```typescript +// 接口定义 +interface Goods { + id: number + name: string + price: number + stock: number +} + +// 类型别名 +type GoodsStatus = 'available' | 'sold_out' | 'disabled' + +// 枚举 +enum OrderStatus { + PENDING = 1, + PROCESSING = 2, + COMPLETED = 3 +} +``` + +#### 函数定义 +```typescript +// 带类型的函数 +const formatPrice = (price: number): string => { + return `¥${price.toFixed(2)}` +} + +// 异步函数 +const fetchGoodsList = async (params: SearchParams): Promise => { + const { data } = await getGoodsList(params) + return data +} +``` + +## API 开发规范 + +### 1. API 文件结构 + +```typescript +// src/api/shop/goods.ts +import request from '@/utils/request' + +export interface Goods { + id: number + name: string + price: number + stock: number +} + +export interface GoodsParams { + page?: number + size?: number + keyword?: string +} + +export interface GoodsListResponse { + list: Goods[] + total: number +} + +// 获取商品列表 +export const getGoodsList = (params: GoodsParams) => { + return request.get('/api/goods/list', { params }) +} + +// 创建商品 +export const createGoods = (data: Partial) => { + return request.post('/api/goods', data) +} + +// 更新商品 +export const updateGoods = (id: number, data: Partial) => { + return request.put(`/api/goods/${id}`, data) +} + +// 删除商品 +export const deleteGoods = (id: number) => { + return request.delete(`/api/goods/${id}`) +} +``` + +### 2. 请求封装 + +```typescript +// src/utils/request.ts +import axios from 'axios' +import { ElMessage } from 'element-plus' + +const request = axios.create({ + baseURL: import.meta.env.VITE_API_BASE_URL, + timeout: 10000 +}) + +// 请求拦截器 +request.interceptors.request.use( + config => { + // 添加 token + const token = localStorage.getItem('token') + if (token) { + config.headers.Authorization = `Bearer ${token}` + } + return config + }, + error => { + return Promise.reject(error) + } +) + +// 响应拦截器 +request.interceptors.response.use( + response => { + return response.data + }, + error => { + // 统一错误处理 + ElMessage.error(error.response?.data?.message || '请求失败') + return Promise.reject(error) + } +) + +export default request +``` + +## 组件开发规范 + +### 1. 组件设计原则 + +#### 单一职责 +每个组件只负责一个特定的功能。 + +#### 可复用性 +组件应该设计为可复用的，通过 props 接收配置。 + +#### 组合优于继承 +通过组合多个小组件来构建复杂功能。 + +### 2. Props 定义 + +```vue + +``` + +### 3. Emits 定义 + +```vue + +``` + +## 状态管理规范 + +### 1. Store 定义 + +```typescript +// src/store/modules/user.ts +import { defineStore } from 'pinia' + +export interface UserState { + userInfo: User | null + token: string | null +} + +export const useUserStore = defineStore('user', { + state: (): UserState => ({ + userInfo: null, + token: null + }), + + getters: { + isLogin: state => !!state.token, + userName: state => state.userInfo?.name || '' + }, + + actions: { + setUserInfo(userInfo: User) { + this.userInfo = userInfo + }, + + setToken(token: string) { + this.token = token + }, + + async login(credentials: LoginParams) { + const { data } = await loginApi(credentials) + this.setToken(data.token) + this.setUserInfo(data.user) + }, + + logout() { + this.userInfo = null + this.token = null + } + }, + + persist: { + enabled: true, + strategies: [ + { + key: 'user', + storage: localStorage + } + ] + } +}) +``` + +### 2. Store 使用 + +```vue + +``` + +## 路由开发规范 + +### 1. 路由定义 + +```typescript +// src/router/modules/shop.ts +export default { + path: '/shop', + name: 'Shop', + redirect: '/shop/goods', + meta: { + title: '店铺管理', + icon: 'shop', + rank: 10 + }, + children: [ + { + path: '/shop/goods', + name: 'Goods', + component: () => import('@/views/shop/goods/index.vue'), + meta: { + title: '商品管理', + roles: ['admin', 'shop_manager'] + } + }, + { + path: '/shop/orders', + name: 'Orders', + component: () => import('@/views/shop/orders/index.vue'), + meta: { + title: '订单管理', + roles: ['admin', 'shop_manager'] + } + } + ] +} as RouteConfigsTable +``` + +### 2. 路由守卫 + +```typescript +// 在路由守卫中检查权限 +router.beforeEach((to, from, next) => { + const userStore = useUserStore() + + // 检查登录状态 + if (!userStore.isLogin && to.path !== '/login') { + next('/login') + return + } + + // 检查页面权限 + if (to.meta.roles && !hasPermission(to.meta.roles)) { + next('/error/403') + return + } + + next() +}) +``` + +## 样式开发规范 + +### 1. SCSS 规范 + +```scss +// 变量定义 +$primary-color: #409eff; +$success-color: #67c23a; +$warning-color: #e6a23c; +$danger-color: #f56c6c; + +// 混入 +@mixin flex-center { + display: flex; + align-items: center; + justify-content: center; +} + +// 组件样式 +.goods-card { + border: 1px solid #ebeef5; + border-radius: 4px; + padding: 20px; + + &__header { + @include flex-center; + margin-bottom: 16px; + } + + &__title { + font-size: 16px; + font-weight: bold; + color: $primary-color; + } +} +``` + +### 2. CSS 类命名 + +使用 BEM 命名规范： +```scss +.block {} +.block__element {} +.block--modifier {} +``` + +## 测试规范 + +### 1. 单元测试 + +```typescript +// tests/unit/utils/format.spec.ts +import { formatPrice } from '@/utils/format' + +describe('formatPrice', () => { + it('should format price correctly', () => { + expect(formatPrice(100)).toBe('¥100.00') + expect(formatPrice(99.9)).toBe('¥99.90') + }) +}) +``` + +### 2. 组件测试 + +```typescript +// tests/unit/components/GoodsCard.spec.ts +import { mount } from '@vue/test-utils' +import GoodsCard from '@/components/GoodsCard.vue' + +describe('GoodsCard', () => { + it('should render goods info', () => { + const wrapper = mount(GoodsCard, { + props: { + goods: { + id: 1, + name: '测试商品', + price: 100 + } + } + }) + + expect(wrapper.text()).toContain('测试商品') + expect(wrapper.text()).toContain('¥100.00') + }) +}) +``` + +## 提交规范 + +### 1. Commit Message 格式 + +``` +(): + + + +