Skip to content
This repository was archived by the owner on May 13, 2026. It is now read-only.

ARCHITECTURE.md

Latest commit

 

History

History
312 lines (241 loc) · 8.05 KB

ARCHITECTURE.md

File metadata and controls

312 lines (241 loc) · 8.05 KB
Raw

架构说明

本文档介绍项目的整体架构设计和关键技术决策。

技术架构

┌─────────────────────────────────────────────────────────────┐
│                        微信小程序                            │
├─────────────────────────────────────────────────────────────┤
│                      Taro 4.1.2 (Vite)                      │
├─────────────────────────────────────────────────────────────┤
│  React 18  │  TypeScript 5  │  Redux Toolkit  │ Tailwind 4  │
├─────────────────────────────────────────────────────────────┤
│                       业务分包架构                           │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐           │
│  │  main   │ │cleaning │ │  hotel  │ │ wallet  │  ...      │
│  └─────────┘ └─────────┘ └─────────┘ └─────────┘           │
├─────────────────────────────────────────────────────────────┤
│  Components │  Hooks  │  Services  │  Utils  │  States     │
└─────────────────────────────────────────────────────────────┘

目录结构

分包架构

项目采用微信小程序分包机制，按业务模块划分:

src/
├── pages/                 # 主包页面 (首页路由入口)
│   └── index/            # 首页重定向
│
└── packages/             # 分包目录
    ├── main/             # 主功能分包
    │   └── pages/
    │       ├── home/     # 首页
    │       ├── orders/   # 订单列表
    │       └── profile/  # 个人中心
    │
    ├── cleaning/         # 清洁服务分包
    │   ├── pages/
    │   ├── hooks/        # 模块专用 Hooks
    │   └── components/   # 模块专用组件
    │
    ├── hotel/            # 酒店管理分包
    ├── wallet/           # 钱包分包
    ├── qualification/    # 资质认证分包
    ├── payment/          # 支付分包
    ├── profile/          # 个人信息分包
    └── common/           # 通用页面分包

组件分层

components/
├── ui/                   # 基础 UI 组件
│   ├── button.tsx       # 按钮
│   ├── card.tsx         # 卡片
│   ├── badge.tsx        # 徽章
│   ├── tabs.tsx         # 标签页
│   └── phone-button.tsx # 电话拨打组件
│
├── business/            # 业务组件
│   ├── date-picker/    # 日期选择器
│   └── region-selector/ # 区域选择器
│
└── layout/              # 布局组件
    ├── safe-view/       # 安全区域容器
    ├── tabbar/          # 底部导航栏
    └── auto-scroll-view/ # 自动滚动视图

状态管理

Redux Store 结构

interface RootState {
  user: UserState;      // 用户状态
  router: RouterState;  // 路由状态
  location: LocationState; // 位置状态
}

用户状态 (userSlice)

interface UserState {
  token: string | null;
  userInfo: UserInfo | null;
  permissions: string[];
  isLoggedIn: boolean;
}

路由状态 (routerSlice)

interface RouterState {
  currentRoute: string;
  currentTabBarGroup: string;
  selectedTabIndex: number;
}

Redux Persist

  • 自动持久化到本地存储
  • 版本管理: 基于 package.json 版本号
  • 版本不匹配时自动清空状态

数据流

API 请求流程

组件 → Hooks → API Service → Request 工具 → 后端
                    ↓
              OpenAPI 自动生成

请求处理

src/utils/core/request.ts 提供统一的请求处理:

  1. Token 注入: 自动添加 Authorization 头
  2. Token 刷新: 检测过期自动刷新
  3. 错误处理: 统一的错误提示
  4. 自动登录: Token 失效时尝试微信登录

API 生成

yarn openapi

从 OpenAPI 规范自动生成:

  • API 函数 (src/services/api/*Controller.ts)
  • 类型定义 (src/services/api/typings.d.ts)

路由系统

路由配置

src/constants/routes.ts 定义所有路由:

export const ROUTES = {
  MAIN: {
    HOME: '/packages/main/pages/home/index',
    ORDERS: '/packages/main/pages/orders/index',
    PROFILE: '/packages/main/pages/profile/index',
  },
  CLEANING: {
    INDEX: '/packages/cleaning/pages/index/index',
    ORDER: '/packages/cleaning/pages/order/index',
  },
  // ...
};

TabBar 配置

路由配置包含 TabBar 信息:

{
  path: '/packages/main/pages/home/index',
  tabbar: {
    group: 'main',
    index: 0,
    icon: 'i-lucide-home',
    title: '首页',
    permissions: ['user.view'],
  }
}

导航工具

使用封装的导航函数:

import { navigateTo, redirectTo, switchTab } from '@/utils/core/navigator';

// 页面跳转
navigateTo('/packages/cleaning/pages/order/index');

// 页面重定向
redirectTo('/packages/main/pages/home/index');

// TabBar 切换
switchTab('/packages/main/pages/profile/index');

权限系统

权限检查

import { useUserPermissions, useUserRole } from '@/hooks';

// 权限检查
const { hasPermission, hasAnyPermission } = useUserPermissions();
if (hasPermission('order.create')) {
  // ...
}

// 角色检查
const { hasRole, isHotelRole, isWorkerRole } = useUserRole();
if (isHotelRole()) {
  // 酒店角色逻辑
}

角色类型

角色 说明
admin 管理员
hotel 酒店用户
cleaning 清洁工人
user 普通用户

Hooks 体系

用户相关

Hook 用途
useUser() 用户状态管理
useUserRole() 角色检查
useUserPermissions() 权限检查
useRoleSwitch() 角色切换

路由相关

Hook 用途
useRouterActions() 路由状态操作
RouterActions 非组件中使用的路由工具类

数据加载

Hook 用途
useLoadData() 数据加载与下拉刷新
usePageRefresh() 页面刷新

模块专用

cleaning 模块专用 Hooks (src/packages/cleaning/hooks/):

Hook 用途
useCleaningOrderAPI() 根据角色自动选择 API
useOrderDetail() 订单详情状态
useOrderDetailActions() 订单操作处理

样式方案

Tailwind CSS

使用 Tailwind CSS 4.x + weapp-tailwindcss:

// 推荐: 内联样式
<View className="flex items-center p-4 bg-green-50 rounded-lg">
  <Text className="text-lg font-bold text-green-600">标题</Text>
</View>

图标

使用 Lucide 图标 (通过 Tailwind):

<View className="i-lucide-home text-2xl text-green-600" />
<View className="i-lucide-user text-xl text-gray-500" />

主题色

  • 主色: 绿色系 (green-500, green-600)
  • 圆角: 使用 rounded-lg, rounded-xl
  • 毛玻璃: backdrop-blur-sm bg-white/80

构建优化

分包预加载

// app.config.ts
export default {
  preloadRule: {
    'packages/main/pages/home/index': {
      network: 'all',
      packages: ['cleaning', 'hotel'],
    },
  },
};

代码压缩

生产构建自动启用:

  • Terser 代码压缩
  • CSS 压缩
  • 图片压缩