Hooke / manulife-weapp

Go to a project
Toggle navigation Toggle navigation pinning
hookehuyr
1368fa96 1 parent 298f7c8a

docs: 将 CLAUDE.md 翻译成中文 

- 将项目开发文档从英文翻译成中文
- 保留所有代码示例、文件路径和技术配置
- 使用清晰易懂的中文表达
Inline Side-by-side
Showing 1 changed file with 355 additions and 355 deletions
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Development Commands
### Core Commands
- `pnpm dev:weapp` - Start WeChat mini-program development server
- `pnpm dev:h5` - Start H5 development server
- `pnpm build:weapp` - Build for production (WeChat mini-program)
- `pnpm lint` - Run ESLint
### Other Platform Builds
- `pnpm dev:alipay` - Alipay mini-program development
- `pnpm dev:swan` - Baidu mini-program development
- `pnpm dev:tt` - ByteDance mini-program development
## Project Overview
**Manulife WeApp** (臻奇智荟圈) is a wealth management WeChat mini-program built with Taro 4 + Vue 3 + NutUI.
### Business Modules
The app currently includes the following main features:
- **Product Showcase** - Hot products display with detail pages
- Home page shows hot products with "产品资料" (Product Materials) buttons
- Product detail page displays comprehensive product information
- **Material Library** - Training materials and document management
- Knowledge base for training materials and case studies
- Material list page with document preview capabilities
- **Family Office** (家办) - Family office services
- **Contract Signing** (签单) - Contract signing workflow
- **User Center** - Personal profile, favorites, feedback, help center
## Project Architecture
This is a **Taro 4 + Vue 3 + NutUI** WeChat mini-program with built-in authentication and reusable navigation components.
### Technology Stack
- **Framework**: Taro 4.1.9 + Vue 3.3.0 + Composition API
- **UI Library**: NutUI 4.3.13 (JD.com's UI library for Taro)
- **State Management**: Pinia 3.0.3 + taro-plugin-pinia
- **HTTP Client**: axios-miniprogram
- **Styling**: Less + TailwindCSS 3.x (dual design width system)
- **Build Tool**: Webpack 5
- **Navigation**: Custom TabBar + enhanced navigation hooks
### Dual Design Width System
The project uses **two different design widths** configured in `config/index.js:16-23`:
- **NutUI components**: 375px base width
- **All other pages**: 750px base width
When working with styles:
- Check if you're using NutUI components → reference 375px designs
- Custom page layouts → reference 750px designs
### Key Architectural Patterns
#### 1. Reusable Navigation Components
**TabBar Component** (`src/components/TabBar.vue`):
- Fixed bottom navigation bar
- Auto-adapts to safe areas (notch/home indicator)
- Supports icon + text layout
- Active state highlighting
- Used across: Index, Mine, Family Office, Knowledge Base, Signing pages
**NavHeader Component** (`src/components/NavHeader.vue`):
- Custom navigation header with back button
- Transparent/background variants
- Safe area padding for notch devices
- Replaces default Taro navigation bar
**IconFont Component** (`src/components/IconFont.vue`):
- Icon font wrapper for custom icons
- Supports size and color customization
#### 2. Authentication Flow (Required)
The project has a sophisticated authentication system with automatic session management:
**Startup Flow** (`src/app.js:26-214`):
1. App saves launch path for auth callback
2. Checks network status and handles weak network scenarios
3. Attempts silent auth if not authenticated
4. On auth success, enables offline features
**Core Files**:
- `src/utils/authRedirect.js` - All auth logic (silent refresh, navigation, state)
- `src/utils/request.js` - HTTP client with 401 auto-refresh interceptor
- `src/pages/auth/index.vue` - Auth page (must be preserved)
- `src/pages/login/index.vue` - Login page
**How 401 Auto-Refresh Works** (`src/utils/request.js:241-276`):
1. API returns 401
2. Interceptor saves current page path
3. Calls `refreshSession()` to get new session via WeChat login
4. Retries original request with new session
5. If refresh fails, redirects to auth page
**Important**: The backend MUST provide `/srv/?a=openid_wxapp` endpoint for WeChat login.
#### 3. API Layer Architecture
**API Definition Pattern** (`src/api/index.js`):
本文件为 Claude Code (claude.ai/code) 在处理此仓库代码时提供指导。
## 开发命令
### 核心命令
- `pnpm dev:weapp` - 启动微信小程序开发服务器
- `pnpm dev:h5` - 启动 H5 开发服务器
- `pnpm build:weapp` - 构建生产版本（微信小程序）
- `pnpm lint` - 运行 ESLint
### 其他平台构建
- `pnpm dev:alipay` - 支付宝小程序开发
- `pnpm dev:swan` - 百度小程序开发
- `pnpm dev:tt` - 字节跳动小程序开发
## 项目概述
**Manulife WeApp**（臻奇智荟圈）是一个基于 Taro 4 + Vue 3 + NutUI 构建的财富管理微信小程序。
### 业务模块
应用目前包含以下主要功能：
- **产品展示** - 热门产品展示及详情页
- 首页显示热门产品，带"产品资料"按钮
- 产品详情页展示完整产品信息
- **资料库** - 培训材料和文档管理
- 培训材料和案例的知识库
- 资料列表页支持文档预览
- **家办** - 家族办公室服务
- **签单** - 签约流程
- **用户中心** - 个人资料、收藏、反馈、帮助中心
## 项目架构
这是一个基于 **Taro 4 + Vue 3 + NutUI** 的微信小程序，内置身份认证和可复用的导航组件。
### 技术栈
- **框架**：Taro 4.1.9 + Vue 3.3.0 + Composition API
- **UI 库**：NutUI 4.3.13（京东推出的 Taro UI 库）
- **状态管理**：Pinia 3.0.3 + taro-plugin-pinia
- **HTTP 客户端**：axios-miniprogram
- **样式**：Less + TailwindCSS 3.x（双设计宽度系统）
- **构建工具**：Webpack 5
- **导航**：自定义 TabBar + 增强导航 hooks
### 双设计宽度系统
项目在 `config/index.js:16-23` 中配置了**两种不同的设计宽度**：
- **NutUI 组件**：375px 基准宽度
- **所有其他页面**：750px 基准宽度
处理样式时：
- 使用 NutUI 组件 → 参考 375px 设计稿
- 自定义页面布局 → 参考 750px 设计稿
### 核心架构模式
#### 1. 可复用的导航组件
**TabBar 组件**（`src/components/TabBar.vue`）：
- 固定底部导航栏
- 自动适配安全区域（刘海屏/底部指示器）
- 支持图标 + 文字布局
- 激活状态高亮
- 使用于：首页、我的、家办、知识库、签单页面
**NavHeader 组件**（`src/components/NavHeader.vue`）：
- 带返回按钮的自定义导航头
- 透明/背景变体
- 刘海屏设备的安全区域内边距
- 替代默认的 Taro 导航栏
**IconFont 组件**（`src/components/IconFont.vue`）：
- 自定义图标的图标字体包装器
- 支持大小和颜色自定义
#### 2. 身份认证流程（必需）
项目具有完善的身份认证系统，支持自动会话管理：
**启动流程**（`src/app.js:26-214`）：
1. 应用保存启动路径用于认证回调
2. 检查网络状态并处理弱网络场景
3. 如果未认证，尝试静默认证
4. 认证成功后，启用离线功能
**核心文件**：
- `src/utils/authRedirect.js` - 所有认证逻辑（静默刷新、导航、状态）
- `src/utils/request.js` - 带 401 自动刷新拦截器的 HTTP 客户端
- `src/pages/auth/index.vue` - 认证页（必须保留）
- `src/pages/login/index.vue` - 登录页
**401 自动刷新工作原理**（`src/utils/request.js:241-276`）：
1. API 返回 401
2. 拦截器保存当前页面路径
3. 调用 `refreshSession()` 通过微信登录获取新会话
4. 使用新会话重试原始请求
5. 如果刷新失败，跳转到认证页
**重要**：后端必须提供 `/srv/?a=openid_wxapp` 端点用于微信登录。
#### 3. API 层架构
**API 定义模式**（`src/api/index.js`）：
```javascript
export const yourAPI = (params) => {
return buildApiUrl('your_action', params)
}
```
**Request Wrapper** (`src/api/fn.js`):
- All API calls should go through this wrapper
- Handles common error scenarios
- Provides consistent interface
**请求包装器**（`src/api/fn.js`）：
- 所有 API 调用都应通过此包装器
- 处理常见错误场景
- 提供一致的接口
**URL Building** (`src/utils/tools.js`):
- `buildApiUrl(action, params)` - Constructs full API URL
- Automatically merges default parameters from `src/utils/config.js`
**URL 构建**（`src/utils/tools.js`）：
- `buildApiUrl(action, params)` - 构建完整的 API URL
- 自动合并来自 `src/utils/config.js` 的默认参数
#### 4. Enhanced Navigation System
#### 4. 增强导航系统
**useGo Hook** (`src/hooks/useGo.js`):
**useGo Hook**（`src/hooks/useGo.js`）：
```javascript
import { useGo } from '@/hooks/useGo'
const go = useGo()
go('/page-name') // Auto-completes path
go('/page', { id: 123 }) // With query params
go('/page-name') // 自动补全路径
go('/page', { id: 123 }) // 带查询参数
```
**Route Storage** (`src/stores/router.js`):
- Maintains stack of visited routes
- Used for auth callback navigation
- Automatically managed by auth flow
**路由存储**（`src/stores/router.js`）：
- 维护已访问路由的栈
- 用于认证回调导航
- 由认证流程自动管理
### Page Structure
### 页面结构
All pages follow this directory structure:
所有页面遵循以下目录结构：
```
src/pages/your-page/
├── index.vue # Page component (must use <script setup>)
├── index.config.js # Page configuration (navigationBarTitleText, etc.)
└── assets/ # Page-specific assets (optional)
├── index.vue # 页面组件（必须使用 <script setup>）
├── index.config.js # 页面配置（navigationBarTitleText 等）
└── assets/ # 页面特定资源（可选）
```
### Current Pages
**Core Pages**:
1. `pages/index/index` - Home page (product showcase, search, grid navigation)
- Hot products "产品资料" buttons navigate to `product-detail` page with product ID
- Hot materials "查看更多" navigates to `material-list` page
- Grid navigation icons navigate to various business pages
2. `pages/auth/index` - Authentication page
3. `pages/login/index` - Login page
**Business Pages**:
4. `pages/family-office/index` - Family office services
5. `pages/knowledge-base/index` - Knowledge base (training materials, cases)
6. `pages/signing/index` - Contract signing
7. `pages/plan/index` - Business plan management
8. `pages/favorites/index` - User favorites
9. `pages/feedback/index` - User feedback
10. `pages/avatar/index` - Avatar settings
11. `pages/mine/index` - User profile
**Product & Content Pages**:
12. `pages/product-detail/index` - Product detail page
- Receives `id` parameter via Taro's `useLoad` hook
- Example navigation: `go('/pages/product-detail/index', { id: 1 })`
- Parameters can be used to fetch product details from API
13. `pages/material-list/index` - Material/Document list page
14. `pages/help-center/index` - Help center and FAQ page
15. `pages/search/index` - Search page for products and materials
**Utility Pages**:
16. `pages/onboarding/index` - New user onboarding
17. `pages/webview/index` - WebView wrapper for external URLs
18. `pages/document-demo/index` - Document preview demo page
19. `pages/document-preview/index` - Document preview page
### Component Library
**Reusable Components**:
- `TabBar.vue` - Bottom navigation bar
- `NavHeader.vue` - Custom navigation header
- `IconFont.vue` - Icon font wrapper
**Feature Components**:
- `qrCode.vue` - QR code display
- `qrCodeSearch.vue` - QR code scanner
- `PosterBuilder/` - Poster generation
- `time-picker-data/` - Time picker data
### Path Aliases
All configured in `config/index.js:30-38`:
### 当前页面
**核心页面**：
1. `pages/index/index` - 首页（产品展示、搜索、网格导航）
- 热门产品的"产品资料"按钮跳转到 `product-detail` 页面，带产品 ID
- 热门资料的"查看更多"跳转到 `material-list` 页面
- 网格导航图标跳转到各个业务页面
2. `pages/auth/index` - 认证页
3. `pages/login/index` - 登录页
**业务页面**：
4. `pages/family-office/index` - 家族办公室服务
5. `pages/knowledge-base/index` - 知识库（培训材料、案例）
6. `pages/signing/index` - 签约
7. `pages/plan/index` - 业务计划管理
8. `pages/favorites/index` - 用户收藏
9. `pages/feedback/index` - 用户反馈
10. `pages/avatar/index` - 头像设置
11. `pages/mine/index` - 用户资料
**产品与内容页面**：
12. `pages/product-detail/index` - 产品详情页
- 通过 Taro 的 `useLoad` hook 接收 `id` 参数
- 导航示例：`go('/pages/product-detail/index', { id: 1 })`
- 参数可用于从 API 获取产品详情
13. `pages/material-list/index` - 资料/文档列表页
14. `pages/help-center/index` - 帮助中心和常见问题页
15. `pages/search/index` - 产品和资料搜索页
**工具页面**：
16. `pages/onboarding/index` - 新用户引导
17. `pages/webview/index` - 外部 URL 的 WebView 包装器
18. `pages/document-demo/index` - 文档预览演示页
19. `pages/document-preview/index` - 文档预览页
### 组件库
**可复用组件**：
- `TabBar.vue` - 底部导航栏
- `NavHeader.vue` - 自定义导航头
- `IconFont.vue` - 图标字体包装器
**功能组件**：
- `qrCode.vue` - 二维码显示
- `qrCodeSearch.vue` - 二维码扫描
- `PosterBuilder/` - 海报生成
- `time-picker-data/` - 时间选择器数据
### 路径别名
全部配置在 `config/index.js:30-38`：
```javascript
@/utils → src/utils
@/components → src/components
......@@ -204,71 +204,71 @@ All configured in `config/index.js:30-38`:
@/hooks → src/hooks
```
### Configuration Management
**Environment Config** (`src/utils/config.js`):
**⚠️ MUST BE MODIFIED before use**:
- `BASE_URL` - Set development/production domain
- `REQUEST_DEFAULT_PARAMS.f` - Set business module identifier
- `REQUEST_DEFAULT_PARAMS.client_name` - Set application name
**Build Config** (`config/index.js`):
- Path aliases
- Design width rules
- NutUI auto-import
- Platform-specific settings
**App Config** (`src/app.config.js`):
- Page routes registration
- Window configuration
- Tab bar configuration (optional)
- Subpackages (if needed)
## Important Implementation Details
### Session Management
- Session ID stored in `localStorage` with key `sessionid`
- Set by `authRedirect.refreshSession()` after successful WeChat login
- Automatically injected into request headers by `request.js` interceptor
- Cleared on logout or explicit manual intervention
### Promise Single-Pattern
The auth system uses Promise singletons to prevent concurrent login attempts:
- `auth_promise` in `authRedirect.js` ensures only one refresh at a time
- All concurrent 401s share the same refresh Promise
- `.finally()` ensures cleanup regardless of success/failure
### Request Timeout Handling
- Default timeout: 5 seconds (`src/utils/request.js:79`)
- Timeout detection via `is_timeout_error()` helper
- Network error detection via `is_network_error()` helper
- Both trigger weak network fallback flow
### NutUI Auto-Import
NutUI components are auto-imported via unplugin-vue-components (`config/index.js:91-93`).
**No manual imports needed** - just use components directly in templates.
### TailwindCSS Integration
- Preflight disabled for mini-program compatibility
- `rem2rpx` conversion enabled
- Content paths configured in `tailwind.config.js`
- Use Tailwind for layout, spacing, colors
- Use Less for component-specific styles, animations, pseudo-elements
### Styling Guidelines
**When to use TailwindCSS** (80% of cases):
### 配置管理
**环境配置**（`src/utils/config.js`）：
**⚠️ 使用前必须修改**：
- `BASE_URL` - 设置开发/生产域名
- `REQUEST_DEFAULT_PARAMS.f` - 设置业务模块标识符
- `REQUEST_DEFAULT_PARAMS.client_name` - 设置应用名称
**构建配置**（`config/index.js`）：
- 路径别名
- 设计宽度规则
- NutUI 自动导入
- 平台特定设置
**应用配置**（`src/app.config.js`）：
- 页面路由注册
- 窗口配置
- 标签栏配置（可选）
- 分包（如需要）
## 重要实现细节
### 会话管理
- 会话 ID 存储在 `localStorage` 中，键名为 `sessionid`
- 微信登录成功后由 `authRedirect.refreshSession()` 设置
- 由 `request.js` 拦截器自动注入到请求头中
- 登出或显式手动操作时清除
### Promise 单例模式
认证系统使用 Promise 单例防止并发登录尝试：
- `authRedirect.js` 中的 `auth_promise` 确保一次只刷新一个
- 所有并发的 401 共享同一个刷新 Promise
- `.finally()` 确保无论成功/失败都执行清理
### 请求超时处理
- 默认超时：5 秒（`src/utils/request.js:79`）
- 通过 `is_timeout_error()` 辅助函数检测超时
- 通过 `is_network_error()` 辅助函数检测网络错误
- 两者都会触发弱网络降级流程
### NutUI 自动导入
NutUI 组件通过 unplugin-vue-components 自动导入（`config/index.js:91-93`）。
**无需手动导入** - 直接在模板中使用组件即可。
### TailwindCSS 集成
- 为小程序兼容性禁用了 Preflight
- 启用了 `rem2rpx` 转换
- 内容路径配置在 `tailwind.config.js` 中
- 使用 Tailwind 处理布局、间距、颜色
- 使用 Less 处理组件特定样式、动画、伪元素
### 样式指南
**何时使用 TailwindCSS**（80% 的情况）：
```vue
<div class="flex items-center justify-between p-4 bg-white">
<h1 class="text-xl font-bold text-gray-900">Title</h1>
<h1 class="text-xl font-bold text-gray-900">标题</h1>
</div>
```
**When to use Less** (20% of cases):
- Component-specific styles
- Deep selectors (`:deep()`)
- Animations and transitions
- Pseudo-elements (`::before`, `::after`)
**何时使用 Less**（20% 的情况）：
- 组件特定样式
- 深度选择器（`:deep()`）
- 动画和过渡
- 伪元素（`::before`、`::after`）
```less
<style lang="less" scoped>
.custom-card {
......@@ -282,36 +282,36 @@ NutUI components are auto-imported via unplugin-vue-components (`config/index.js
</style>
```
## Optional Features
## 可选功能
These features can be removed if not needed:
- **WeChat Pay**: `src/utils/wechatPay.js`, `src/api/wx/pay.js`
- **QR Code**: `src/components/qrCode.vue`, `src/components/qrCodeSearch.vue`
- **Poster Builder**: `src/components/PosterBuilder/`
- **Time Picker**: `src/components/time-picker-data/`
- **Offline Cache**: Entire offline booking cache system (if not used)
如果不需要，可以移除以下功能：
- **微信支付**：`src/utils/wechatPay.js`、`src/api/wx/pay.js`
- **二维码**：`src/components/qrCode.vue`、`src/components/qrCodeSearch.vue`
- **海报生成器**：`src/components/PosterBuilder/`
- **时间选择器**：`src/components/time-picker-data/`
- **离线缓存**：整个离线预约缓存系统（如果不使用）
## Development Workflow
## 开发工作流
### Adding New Pages
### 添加新页面
1. **Create page directory**:
1. **创建页面目录**：
```bash
src/pages/your-page/
├── index.vue
└── index.config.js
```
2. **Configure page** (`index.config.js`):
2. **配置页面**（`index.config.js`）：
```javascript
export default {
navigationBarTitleText: 'Your Page Title',
navigationBarTitleText: '您的页面标题',
enablePullDownRefresh: true,
backgroundColor: '#f5f5f5'
}
```
3. **Register route** in `src/app.config.js`:
3. **在 `src/app.config.js` 中注册路由**：
```javascript
pages: [
'pages/your-page/index',
......@@ -319,7 +319,7 @@ These features can be removed if not needed:
]
```
4. **Use composition API** in `index.vue`:
4. **在 `index.vue` 中使用 composition API**：
```vue
<script setup>
import { ref } from 'vue'
......@@ -328,46 +328,46 @@ These features can be removed if not needed:
const pageId = ref(null)
useLoad((options) => {
console.log('Page loaded with options:', options)
// Receive navigation parameters
console.log('页面加载，参数：', options)
// 接收导航参数
if (options.id) {
pageId.value = options.id
// Fetch data based on ID
// 根据 ID 获取数据
}
})
useShow(() => {
console.log('Page shown')
console.log('页面显示')
})
// Your component logic
// 您的组件逻辑
</script>
```
**Navigation with Parameters**:
**带参数导航**：
```javascript
// From another page
// 从另一个页面
import { useGo } from '@/hooks/useGo'
const go = useGo()
// Navigate with query params
// 带查询参数导航
go('/pages/product-detail/index', { id: 123, type: 'insurance' })
```
5. **Add navigation** (optional TabBar integration):
- Import and use `TabBar` component
- Configure active state based on route
5. **添加导航**（可选的 TabBar 集成）：
- 导入并使用 `TabBar` 组件
- 根据路由配置激活状态
### Adding API Calls
### 添加 API 调用
1. **Define API** in `src/api/index.js`:
1. **在 `src/api/index.js` 中定义 API**：
```javascript
export const getProductListAPI = (params) => {
return buildApiUrl('product_list', params)
}
```
2. **Use in page**:
2. **在页面中使用**：
```javascript
import { getProductListAPI } from '@/api'
import { fn } from '@/api/fn'
......@@ -379,33 +379,33 @@ These features can be removed if not needed:
products.value = res.data
}
} catch (err) {
console.error('Failed to fetch products:', err)
console.error('获取产品失败：', err)
}
}
```
### Using Navigation
### 使用导航
**Recommended**: Use `useGo` hook for enhanced navigation:
**推荐**：使用 `useGo` hook 进行增强导航：
```javascript
import { useGo } from '@/hooks/useGo'
const go = useGo()
// Navigate to page
// 导航到页面
go('/pages/detail/index')
// Navigate with params (e.g., product ID)
// 带参数导航（例如产品 ID）
go('/pages/product-detail/index', { id: 123 })
// Navigate with multiple params
// 带多个参数导航
go('/pages/material-list/index', { category: 'insurance', page: 1 })
// Go back
// 返回
go.back()
```
**Receiving Parameters in Target Page**:
**在目标页面接收参数**：
```javascript
import { useLoad } from '@tarojs/taro'
import { ref } from 'vue'
......@@ -413,16 +413,16 @@ import { ref } from 'vue'
const productId = ref(null)
useLoad((options) => {
// Access navigation parameters
console.log('Received params:', options)
// 访问导航参数
console.log('接收到的参数：', options)
productId.value = options.id
// Fetch data based on parameters
// 根据参数获取数据
fetchProductDetail(options.id)
})
```
**Alternative**: Use Taro's built-in navigation:
**替代方案**：使用 Taro 内置导航：
```javascript
import Taro from '@tarojs/taro'
......@@ -431,9 +431,9 @@ Taro.navigateTo({
})
```
### State Management with Pinia
### 使用 Pinia 状态管理
**Create store** (`src/stores/yourStore.js`):
**创建 store**（`src/stores/yourStore.js`）：
```javascript
import { defineStore } from 'pinia'
import { ref } from 'vue'
......@@ -449,90 +449,90 @@ export const useYourStore = defineStore('yourStore', () => {
})
```
**Use in component**:
**在组件中使用**：
```javascript
import { useYourStore } from '@/stores/yourStore'
const store = useYourStore()
store.setState('new value')
store.setState('新值')
```
## Critical Files Summary
### Must Understand Before Modifying
1. **`src/utils/authRedirect.js`** - Complete auth flow logic
2. **`src/utils/request.js`** - HTTP client with interceptors
3. **`src/app.js`** - App startup sequence and network handling
4. **`src/utils/config.js`** - Server configuration (requires modification)
### Key Business Logic
1. **`src/api/index.js`** - API definitions
2. **`src/api/fn.js`** - Request wrapper
3. **`src/stores/main.js`** - Primary state management
4. **`src/stores/router.js`** - Route state for auth callbacks
### Reusable Components
1. **`src/components/TabBar.vue`** - Bottom navigation bar
2. **`src/components/NavHeader.vue`** - Custom navigation header
3. **`src/components/IconFont.vue`** - Icon wrapper
### UI/UX Utilities
1. **`src/utils/uiText.js`** - Centralized copy management
2. **`src/utils/network.js`** - Network status utilities
3. **`src/hooks/useGo.js`** - Enhanced navigation hook
## Debugging Tips
When debugging issues:
1. **Check environment config**:
- Verify `BASE_URL` in `src/utils/config.js`
- Check business module identifier `f` and `client_name`
2. **Verify authentication**:
- Check `sessionid` in localStorage
- Enable verbose logging in `src/utils/request.js` interceptor
- Test 401 refresh flow
3. **Network issues**:
- Use Taro's built-in network status monitoring
- Check weak network fallback scenarios
- Verify offline cache interactions
4. **Styling problems**:
- Confirm design width (375px vs 750px)
- Check if NutUI component or custom component
- Verify TailwindCSS classes are applied
5. **Navigation issues**:
- Check route is registered in `src/app.config.js`
- Verify page directory structure matches route
- Use `useGo` hook for consistent navigation
## Best Practices
### Component Development
- Use `<script setup>` syntax
- Composables for reusable logic
- Props should have type definitions
- Use `emit` for child-to-parent communication
- Prefer TailwindCSS for styling
### API Integration
- Always check `res.code === 1` for success
- Use `try/catch` for error handling
- Show loading states during requests
- Handle network errors gracefully
### Performance
- Use page lazy loading (subpackages)
- Optimize images with CDN parameters
- Avoid large data sets without pagination
- Clean up timers and listeners in `onUnmounted`
### Code Style
- Follow Vue 3 Composition API patterns
- Use descriptive variable names
- Keep functions focused and small (< 50 lines)
- Add JSDoc comments for complex functions
- Run `pnpm lint` before committing
## 关键文件总结
### 修改前必须理解
1. **`src/utils/authRedirect.js`** - 完整的认证流程逻辑
2. **`src/utils/request.js`** - 带拦截器的 HTTP 客户端
3. **`src/app.js`** - 应用启动序列和网络处理
4. **`src/utils/config.js`** - 服务器配置（需要修改）
### 核心业务逻辑
1. **`src/api/index.js`** - API 定义
2. **`src/api/fn.js`** - 请求包装器
3. **`src/stores/main.js`** - 主要状态管理
4. **`src/stores/router.js`** - 认证回调的路由状态
### 可复用组件
1. **`src/components/TabBar.vue`** - 底部导航栏
2. **`src/components/NavHeader.vue`** - 自定义导航头
3. **`src/components/IconFont.vue`** - 图标包装器
### UI/UX 工具
1. **`src/utils/uiText.js`** - 集中式文案管理
2. **`src/utils/network.js`** - 网络状态工具
3. **`src/hooks/useGo.js`** - 增强导航 hook
## 调试技巧
调试问题时：
1. **检查环境配置**：
- 验证 `src/utils/config.js` 中的 `BASE_URL`
- 检查业务模块标识符 `f` 和 `client_name`
2. **验证身份认证**：
- 检查 localStorage 中的 `sessionid`
- 在 `src/utils/request.js` 拦截器中启用详细日志
- 测试 401 刷新流程
3. **网络问题**：
- 使用 Taro 内置的网络状态监控
- 检查弱网络降级场景
- 验证离线缓存交互
4. **样式问题**：
- 确认设计宽度（375px vs 750px）
- 检查是 NutUI 组件还是自定义组件
- 验证 TailwindCSS 类是否已应用
5. **导航问题**：
- 检查路由是否在 `src/app.config.js` 中注册
- 验证页面目录结构与路由匹配
- 使用 `useGo` hook 进行一致的导航
## 最佳实践
### 组件开发
- 使用 `<script setup>` 语法
- 使用 Composables 处理可复用逻辑
- Props 应该有类型定义
- 使用 `emit` 进行子到父通信
- 优先使用 TailwindCSS 进行样式设计
### API 集成
- 始终检查 `res.code === 1` 判断成功
- 使用 `try/catch` 进行错误处理
- 请求期间显示加载状态
- 优雅地处理网络错误
### 性能
- 使用页面懒加载（分包）
- 使用 CDN 参数优化图片
- 避免无分页的大数据集
- 在 `onUnmounted` 中清理定时器和监听器
### 代码风格
- 遵循 Vue 3 Composition API 模式
- 使用描述性变量名
- 保持函数聚焦且简短（< 50 行）
- 为复杂函数添加 JSDoc 注释
- 提交前运行 `pnpm lint`
......