WindowBird/OfficeSystem

Fork 0

WindowBird 34c6de002c 封装统一的url构建工具

2025-11-27 10:14:55 +08:00

12 KiB

Raw Permalink Blame History

OfficeSystem 项目架构与缺陷分析报告

📋 项目概述

项目名称: OfficeSystem（办公管理系统）
技术栈: uni-app + Vue 3 + Pinia + uv-ui
项目类型: 跨平台移动应用（支持H5、小程序、App）

🏗️ 项目架构分析

1. 整体架构层次

┌─────────────────────────────────────┐
│         页面层 (Pages)              │
│  - 任务管理、客户管理、项目管理等    │
└─────────────────────────────────────┘
           ↓
┌─────────────────────────────────────┐
│        组件层 (Components)          │
│  - 业务组件、UI组件                  │
└─────────────────────────────────────┘
           ↓
┌─────────────────────────────────────┐
│     状态管理层 (Store/Pinia)         │
│  - user, task, customer, dict       │
└─────────────────────────────────────┘
           ↓
┌─────────────────────────────────────┐
│        API层 (api/)                 │
│  - 统一接口封装                      │
└─────────────────────────────────────┘
           ↓
┌─────────────────────────────────────┐
│      工具层 (utils/)                │
│  - 请求封装、工具函数、指令          │
└─────────────────────────────────────┘

2. 目录结构分析

✅ 优点

模块化清晰: 按功能模块划分（task、customer、project等）
职责分离: API、Store、组件分离明确
工具函数集中: utils目录统一管理工具函数

⚠️ 问题

缺少类型定义: 无TypeScript或JSDoc类型定义
测试缺失: 无单元测试、集成测试
文档不足: 缺少API文档、组件文档

🔍 详细架构分析

1. API层 (`api/`)

架构设计

✅ 按业务模块划分（user、task、customer等）
✅ 统一使用 uni.$uv.http 封装
✅ 支持自定义配置（auth、toast、catch）

存在的问题

🔴 严重问题

硬编码的baseURL

// utils/request/index.js:13-14
config.baseURL = 'http://192.168.1.2:4001'; // 开发环境
config.baseURL = 'https://pm.ccttiot.com/prod-api'; // 生产环境

❌ 环境配置未分离，需要手动注释切换
❌ 应该使用环境变量或配置文件

URL构建方式不统一

// api/customer.js - 手动拼接URL
const queryString = queryParams.join('&');
const url = `bst/customer/list${queryString ? `?${queryString}` : ''}`;

// api/task.js - 也是手动拼接
queryParams.push(`pageNum=${params.pageNum}`);

❌ 应该使用URLSearchParams或统一工具函数
❌ 容易出错，维护困难

错误处理不一致

// 有些API使用 custom.catch: true
// 有些使用默认的Promise pending
// 导致错误处理方式不统一

🟡 中等问题

调试代码未清理

// api/customer.js:25,55
console.log('api params:', params);
console.log('最终请求URL:', url);

缺少请求重试机制
- 网络错误时无自动重试
- 无请求去重机制

2. 请求拦截器 (`utils/request/index.js`)

优点

✅ 统一的token管理
✅ 网络状态检测
✅ 401/403统一处理

存在的问题

🔴 严重问题

Promise pending导致内存泄漏风险
```
// 第112行
return new Promise(() => { }) // 永远pending的Promise
```
- ❌ 可能导致内存泄漏
- ❌ 无法正确追踪错误

重复的登录跳转逻辑

// 响应拦截和错误拦截都有401处理
// 代码重复，维护困难

网络检测逻辑重复
- 请求拦截和错误拦截都检测网络
- 可以提取为公共函数

🟡 中等问题

错误提示不够友好

uni.$uv.toast('请求失败') // 过于简单

缺少请求超时处理
- 无超时配置
- 无超时重试

3. 状态管理 (`store/`)

优点

✅ 使用Pinia，符合Vue 3最佳实践
✅ 模块化设计清晰
✅ 支持持久化（localStorage）

存在的问题

🟡 中等问题

Store职责不清晰

// store/task.js - 只存储taskDetailData
// 但很多页面直接调用API，不使用Store

缺少数据缓存策略
- 无缓存过期机制
- 无数据同步策略

权限数据格式不统一

// 需要处理数组、对象、字符串多种格式
// 应该在API层统一转换

4. 组件层 (`components/`)

优点

✅ 按业务模块组织
✅ 组件职责相对清晰

存在的问题

🟡 中等问题

组件复用性不足
- 很多业务逻辑写在页面中
- 缺少通用业务组件
样式管理混乱
- 部分使用scoped，部分未使用
- 缺少统一的样式变量

5. 工具层 (`utils/`)

优点

✅ 权限工具函数已提取（utils/permission.js）
✅ 请求封装统一

存在的问题

🟡 中等问题

工具函数分散
- textSolve/ 目录下只有少量文件
- 可以考虑合并到主utils目录
缺少常用工具函数
- 无日期格式化工具（多处重复实现）
- 无数据验证工具
- 无防抖节流工具

6. 指令系统 (`directives/`)

优点

✅ v-permission 指令设计良好
✅ 支持Vue 2和Vue 3
✅ 文档完善

存在的问题

🟢 轻微问题

Pinia实例获取逻辑复杂

// 尝试多个路径获取Pinia实例
// 可以简化

🐛 代码质量问题

1. 调试代码未清理

位置: 多处

// api/customer.js
console.log('api params:', params);
console.log('最终请求URL:', url);

// pages/task/detail/index.vue
console.log('任务详情数据:', res);

// composables/usePagination.js
console.log(`获取数据成功: 第${queryParams.value.pageNum}页`);

影响:

生产环境性能影响
可能泄露敏感信息

建议:

使用环境变量控制日志输出
或使用日志工具（如winston）

2. 硬编码值

位置:

App.vue:15 - 测试token硬编码
utils/request/index.js:13-14 - baseURL硬编码

建议:

使用环境变量或配置文件

3. 错误处理不完善

问题:

很多地方只有 console.error，无用户提示
错误信息不够详细
缺少错误上报机制

4. 代码重复

示例:

日期格式化函数在多处重复实现
权限判断逻辑在多个页面重复
网络检测逻辑重复

🔒 安全性问题

1. Token存储

✅ 使用uni.getStorageSync存储（相对安全）
⚠️ 但无token加密
⚠️ 无token刷新机制

2. 敏感信息

❌ App.vue 中硬编码测试token
❌ 生产环境可能泄露

3. 权限校验

✅ 前端有权限指令
⚠️ 但后端校验是最终保障（前端校验可被绕过）

📊 性能问题

1. 图片处理

⚠️ 无图片懒加载
⚠️ 无图片压缩
⚠️ 无CDN配置

2. 数据加载

⚠️ 部分页面无加载状态
⚠️ 无数据预加载
⚠️ 无虚拟列表（长列表性能问题）

3. 打包优化

⚠️ 无代码分割
⚠️ 无Tree Shaking配置检查

🧪 测试与质量保证

❌ 严重缺失

无单元测试
- 无测试文件（.test.js, .spec.js）
- 无测试框架配置
无集成测试
- 无E2E测试
- 无API测试
无代码检查工具
- 无ESLint配置
- 无Prettier配置
- 无Git hooks
无CI/CD
- 无自动化构建
- 无自动化部署

📝 文档问题

❌ 缺失的文档

API文档
- 无接口文档
- 无参数说明
组件文档
- 无组件使用说明
- 无Props文档
开发文档
- 无开发规范
- 无部署文档
- 无环境配置说明

🎯 改进建议

高优先级（立即修复）

环境配置分离

// config/env.js
export const config = {
  dev: { baseURL: 'http://192.168.1.2:4001' },
  prod: { baseURL: 'https://pm.ccttiot.com/prod-api' }
}

修复Promise pending问题

// 应该返回rejected Promise或统一错误格式
return Promise.reject(new Error(data.message || '请求失败'))

清理调试代码
- 移除所有console.log
- 移除硬编码的测试token

统一URL构建

// utils/request/buildUrl.js
export function buildUrl(path, params) {
  const url = new URL(path, baseURL)
  Object.entries(params).forEach(([key, value]) => {
    if (value != null) url.searchParams.append(key, value)
  })
  return url.toString()
}

中优先级（近期改进）

添加错误处理工具

// utils/errorHandler.js
export function handleError(error, showToast = true) {
  // 统一错误处理逻辑
}

添加常用工具函数库
- 日期格式化
- 数据验证
- 防抖节流
完善Store设计
- 统一数据缓存策略
- 添加数据同步机制
添加代码检查工具
- ESLint配置
- Prettier配置
- Git hooks

低优先级（长期优化）

引入TypeScript
- 类型安全
- 更好的IDE支持
添加单元测试
- Jest配置
- 核心功能测试
性能优化
- 图片懒加载
- 代码分割
- 虚拟列表
完善文档
- API文档
- 组件文档
- 开发规范

📈 架构评分

维度	评分	说明
代码组织	⭐⭐⭐⭐	模块化清晰，但缺少类型定义
错误处理	⭐⭐	有基础处理，但不完善
安全性	⭐⭐⭐	基础安全措施，但有硬编码问题
性能	⭐⭐⭐	基础优化，但缺少高级优化
可维护性	⭐⭐⭐	结构清晰，但代码重复较多
可测试性	⭐	无测试，难以保证质量
文档	⭐⭐	缺少完整文档

总体评分: ⭐⭐⭐ (3/5)

🎓 总结

优点

✅ 项目结构清晰，模块化设计良好
✅ 使用现代技术栈（Vue 3 + Pinia）
✅ 权限系统设计合理
✅ 请求拦截器功能完善

主要问题

❌ 环境配置硬编码
❌ 缺少测试和质量保证
❌ 代码重复和调试代码未清理
❌ 错误处理不完善
❌ 文档缺失

建议

优先解决高优先级问题（环境配置、Promise pending、调试代码），然后逐步完善测试、文档和性能优化。建议引入代码检查工具和CI/CD流程，提升代码质量和开发效率。

报告生成时间: 2024年
分析工具: 代码审查 + 架构分析

12 KiB Raw Permalink Blame History Unescape Escape

OfficeSystem 项目架构与缺陷分析报告

📋 项目概述

🏗️ 项目架构分析

1. 整体架构层次

2. 目录结构分析

✅ 优点

⚠️ 问题

🔍 详细架构分析

1. API层 (api/)

架构设计

存在的问题

2. 请求拦截器 (utils/request/index.js)

优点

存在的问题

3. 状态管理 (store/)

优点

存在的问题

4. 组件层 (components/)

优点

存在的问题

5. 工具层 (utils/)

优点

存在的问题

6. 指令系统 (directives/)

优点

存在的问题

🐛 代码质量问题

1. 调试代码未清理

2. 硬编码值

3. 错误处理不完善

4. 代码重复

🔒 安全性问题

1. Token存储

2. 敏感信息

3. 权限校验

📊 性能问题

1. 图片处理

2. 数据加载

3. 打包优化

🧪 测试与质量保证

❌ 严重缺失

📝 文档问题

❌ 缺失的文档

🎯 改进建议

高优先级（立即修复）

中优先级（近期改进）

低优先级（长期优化）

📈 架构评分

🎓 总结

优点

主要问题

建议

12 KiB

Raw Permalink Blame History

1. API层 (`api/`)

2. 请求拦截器 (`utils/request/index.js`)

3. 状态管理 (`store/`)

4. 组件层 (`components/`)

5. 工具层 (`utils/`)

6. 指令系统 (`directives/`)