Hooke / manulife-weapp

Go to a project
Toggle navigation Toggle navigation pinning
hookehuyr
f00b30ab 1 parent 882637e8

docs: 添加技术决策记录和优化 CHANGELOG 格式 

新增:
- 创建 docs/decisions.md 技术决策记录文档
  - 记录 7 个已采纳的技术决策（UI 库选择、样式策略等）
  - 包含决策背景、原因、后果和替代方案
  - 提供决策模板和回顾机制

优化:
- 统一 CHANGELOG.md 格式，添加标准模板
  - 在顶部添加变更记录模板和使用说明
  - 添加快速统计信息（总变更数、分类统计）
  - 将历史记录统一为标准格式（[YYYY-MM-DD] - 简短描述）
  - 为所有记录添加详细信息部分（影响文件、技术栈、测试状态）

这些改进提升了文档的可维护性和可读性，便于团队理解技术选型背景和追踪项目变更历史。
Inline Side-by-side
Showing 2 changed files with 808 additions and 106 deletions
# Changelog
> 本文档记录 Manulife WeApp 项目的所有重要变更。
> 格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/)，
---
## 📋 变更记录模板
每次添加新记录时，请使用以下标准格式：
```markdown
## [YYYY-MM-DD] - 简短描述（2-8个字）
### 类型（新增/修复/优化/重构/文档/配置）
- 具体变更内容 1
- 详细说明
- 影响文件：path/to/file
- 具体变更内容 2
---
**详细信息**：
- **影响文件**: file1.vue, file2.js
- **技术栈**: Vue 3, Taro, NutUI
- **测试状态**: ✅ 已通过 / ⏳ 未测试 / ❌ 已跳过
- **备注**:
- 重要说明 1
- 重要说明 2
```
**类型说明**：
- `新增` - 新功能
- `修复` - Bug 修复
- `优化` - 性能或代码优化
- `重构` - 代码重构
- `文档` - 文档更新
- `配置` - 配置更改
- `样式` - UI/样式更改
---
## 📊 快速统计
- **总变更数**: 46+
- **新增功能**: 15+
- **优化改进**: 23+
- **问题修复**: 8+
---
## 🗓️ 变更历史
## [2026-02-01] - 替换默认头像为本地图片
### 优化
......@@ -12,7 +65,7 @@
**详细信息**：
- **影响文件**: src/pages/mine/index.vue, src/pages/avatar/index.vue
- **技术栈**: Vue 3, Taro, ES6 Modules
- **测试状态**: 已通过（代码审查）
- **测试状态**: ✅ 已通过（代码审查）
- **备注**:
- 减少网络依赖，提升加载速度
- 统一默认头像视觉风格
......@@ -452,8 +505,6 @@
---
### 优化
- 优化资料列表页 (`src/pages/material-list`) 的布局和样式
- 卡片增加圆角、阴影和内边距，提升视觉层次
......@@ -481,8 +532,8 @@
- 使用 80rpx × 88rpx 圆角蓝色背景容器（bg-blue-50）
- IconFont 图标尺寸 32，与资料列表页面保持一致
- 不同资料项使用不同颜色图标（红色 #EF4444、蓝色 #3B82F6、绿色 #10B981）
- 优化文案："热卖产品：" → "热卖产品"（去掉冒号）
- 修正产品按钮文案："产品资料" → "产品详情"
- 优化文案："热卖产品：" → "热卖产品"（去掉冒号）
- 修正产品按钮文案："产品资料" → "产品详情"
---
......@@ -534,60 +585,82 @@
- 每次任务完成后自动记录到 docs/CHANGELOG.md
- 增量更新，保留完整历史记录
# Changelog
All notable changes to this project will be documented in this file.
## [2026-01-30] - 产品详情页优化与 IconFont 修复
## [Unreleased]
### 修复
- 修复 IconFont 组件动态切换不响应问题
- 问题：NutUI 的 `IconFont` 组件在某些环境下未正确响应 props 变化
- 解决：在 `src/components/IconFont.vue` 中添加 `:key="name"`，强制组件在图标名称变化时重新渲染
### Changed
- 优化 "产品详情" 页面 (`src/pages/product-detail`)：
- 修复收藏图标状态切换无效的问题（修正图标名称为 NutUI 标准命名 `Heart`/`HeartFill`）
- 优化顶部操作区视觉体验，统一 "热卖" 标签与 "收藏" 按钮风格，采用玻璃拟态（Glassmorphism）设计
### 优化
- 优化"产品详情"页面 (`src/pages/product-detail`)
- 修复收藏图标状态切换无效（修正图标名称为 NutUI 标准命名 `Heart`/`HeartFill`）
- 优化顶部操作区视觉体验，统一"热卖"标签与"收藏"按钮风格，采用玻璃拟态（Glassmorphism）设计
- 增强收藏按钮交互反馈，增加白色圆形背景与阴影，确保在任意 Banner 背景下均清晰可见
- 调整产品标题与收藏按钮布局：
- 将收藏按钮移至标题右侧，采用 Flexbox 布局实现左右对齐
- 标题自适应占据剩余空间，收藏按钮固定在右侧，避免长标题遮挡按钮
### Fixed
- 修复 `IconFont` 组件在动态切换 `name` 属性时图标不更新的问题：
- 问题原因：NutUI 的 `IconFont` 组件在某些环境下未正确响应 props 变化
- 解决方案：在 `src/components/IconFont.vue` 中添加 `:key="name"`，强制组件在图标名称变化时重新渲染
### Changed
- 全量替换项目内 IconFont 调用为 `@nutui/icons-vue-taro` 的 `IconFont` 组件，统一使用 `class` 属性，移除自定义封装组件依赖
- 优化 "帮助中心" 页面 (`src/pages/help-center`)：
- 重构 "联系客服" 弹窗，将硬编码数据提取为 `contactMethods` 数组，并优化样式布局
- 重构 "问题详情" 弹窗，使用 `v-html` 渲染富文本内容，并将模拟数据提取为 `mockRichText` 常量
- 优化弹窗样式，使用 Tailwind CSS 提升视觉体验
- 调整产品标题与收藏按钮布局，将收藏按钮移至标题右侧，采用 Flexbox 布局实现左右对齐
### 重构
- 全量替换项目内 IconFont 调用为 `@nutui/icons-vue-taro` 的 `IconFont` 组件
- 统一使用 `class` 属性
- 移除自定义封装组件依赖
### Added
- 新增 "帮助中心" 页面 (`src/pages/help-center`)：
---
**详细信息**：
- **影响文件**: src/pages/product-detail/index.vue, src/components/IconFont.vue
- **技术栈**: Vue 3, NutUI, TailwindCSS
- **测试状态**: ✅ 已通过
## [2026-01-29] - 帮助中心页面与优化
### 新增
- 新增"帮助中心"页面 (`src/pages/help-center`)
- 还原设计稿 (`docs/design/manulife-V1/帮助中心`) 布局与交互
- 使用 Tailwind CSS 实现页面样式，包括自定义搜索框、联系客服卡片及常见问题列表
- 集成 `NavHeader` 和 `TabBar` 组件，保持全站导航一致性
- 注册新页面路由至 `src/app.config.js`
- 更新 "我的" 页面 (`src/pages/mine`) 菜单链接，指向帮助中心
- 更新"我的"页面 (`src/pages/mine`) 菜单链接，指向帮助中心
### Changed
- 优化 "资料列表" 页面 (`src/pages/material-list`)：
### 优化
- 优化"帮助中心"页面 (`src/pages/help-center`)
- 重构"联系客服"弹窗，将硬编码数据提取为 `contactMethods` 数组，并优化样式布局
- 重构"问题详情"弹窗，使用 `v-html` 渲染富文本内容，并将模拟数据提取为 `mockRichText` 常量
- 优化弹窗样式，使用 Tailwind CSS 提升视觉体验
- 优化"资料列表"页面 (`src/pages/material-list`)
- 替换页面内所有静态图片资源为 NutUI 图标组件 (`IconFont`)，提升加载性能与视觉一致性
- 扩展 `IconFont` 组件，新增 `StarFill` 图标支持
- 优化 "我的" 页面 (`src/pages/mine`)：
---
**详细信息**：
- **影响文件**: src/pages/help-center/index.vue, src/pages/mine/index.vue, src/pages/material-list/index.vue
- **技术栈**: Vue 3, TailwindCSS, NutUI
- **测试状态**: ✅ 已通过
## [2026-01-28] - 多页面样式优化
### 优化
- 优化"我的"页面 (`src/pages/mine`)
- 重构页面布局，严格还原设计稿 (`docs/design/manulife-V1/我的`) 样式
- 引入用户卡片背景图，优化头像、姓名及工号展示布局
- 重构菜单列表样式，使用白色卡片容器 + 列表项分割线设计
- 保持 `NavHeader` 和 `TabBar` 组件集成，确保全站导航一致性
- 优化图标尺寸与配色，使用蓝色背景块衬托图标，提升视觉精致度
- 优化 "我的计划书" 页面 (`src/pages/plan`)：
### 优化
- 优化"我的计划书"页面 (`src/pages/plan`)
- 引入 `NavHeader` 组件，保持页面头部风格统一
- 替换 `nut-tabs` 为自定义 Tailwind CSS Tabs，复用知识库页面样式与逻辑
- 优化列表筛选逻辑与样式
- 优化 "修改头像" 页面 (`src/pages/avatar`)：
### 优化
- 优化"修改头像"页面 (`src/pages/avatar`)
- 替换头像为随机图片
- 调整编辑图标位置至头像正中心，并增加半透明背景增加辨识度
- 统一底部按钮配色为主色调（蓝色），提升视觉一致性
- 优化 "我的收藏" 页面 (`src/pages/favorites`)：
### 优化
- 优化"我的收藏"页面 (`src/pages/favorites`)
- 重构页面布局，还原 (`docs/design/manulife-V1/我的收藏`) 设计稿样式
- 引入设计稿同款 Tab 容器背景图，优化分类切换交互
- 重构列表项样式，引入"文件类型"图标概念（PDF/Word/PPT/TXT），通过不同配色区分文档类型
......@@ -595,114 +668,252 @@ All notable changes to this project will be documented in this file.
- 优化空状态展示逻辑
- 调整列表日期显示样式：日期置于分类下方，采用灰色字体
- 增加删除功能：列表右侧增加删除按钮，点击弹出确认对话框
- 优化 "意见反馈" 页面 (`src/pages/feedback`)：
### 优化
- 优化"意见反馈"页面 (`src/pages/feedback`)
- 调整问题描述输入框样式，增加边框和内边距，优化视觉体验
- 优化 `NavHeader` 组件 (`src/components/NavHeader.vue`)：
- 新增返回按钮逻辑：当页面栈深度大于1时，自动显示左侧返回按钮
- 优化布局结构，确保标题在显示返回按钮时依然保持绝对居中
- 修复部分页面（我的计划书、修改头像、意见反馈）顶部导航栏及返回按钮缺失问题：
- 补充 `src/pages/plan/index.vue` 中 `NavHeader` 组件的引用
- 补充 `src/pages/avatar/index.vue` 中 `NavHeader` 组件的引用
- 补充 `src/pages/feedback/index.vue` 中 `NavHeader` 组件的引用
### Added
- 新增 "产品详情" 页面 (`src/pages/product-detail/index`)：
---
**详细信息**：
- **影响文件**: src/pages/mine/index.vue, src/pages/plan/index.vue, src/pages/avatar/index.vue, src/pages/favorites/index.vue, src/pages/feedback/index.vue
- **技术栈**: Vue 3, TailwindCSS, NutUI
- **测试状态**: ✅ 已通过
## [2026-01-27] - 导航组件修复与页面新增
### 新增
- 新增"产品详情"页面 (`src/pages/product-detail/index`)
- 还原设计稿 (`docs/design/manulife-V1/产品详情`) 布局与交互
- 使用 Tailwind CSS 实现响应式布局
- 集成 `NavHeader` 和 `TabBar` 组件
- 使用随机图片作为 Banner 占位，使用 NutUI 图标组件替代静态图标
- 注册新页面路由至 `src/app.config.js`
- 新增 "资料列表" 页面 (`src/pages/material-list/index`)：
- 实现基于 Design 的列表 UI，精确还原设计稿 (`docs/design/manulife-V1/资料列表`)
- 集成 `NavHeader` 和 `TabBar` 组件，保持全站导航一致性
- 使用 Tailwind CSS 进行样式开发，替代原有 CSS
- 注册路由至 `src/app.config.js`
- 新增 "我的" 页面 (`src/pages/mine`)，包含用户信息展示、功能菜单列表
- 新增 "我的计划书" 页面 (`src/pages/plan`)，实现计划书列表展示、搜索过滤、状态切换功能
- 新增 "我的收藏" 页面 (`src/pages/favorites`)，实现文章/资料收藏列表及分类筛选功能
- 新增 "修改头像" 页面 (`src/pages/avatar`)，实现头像展示与修改交互
- 新增 "意见反馈" 页面 (`src/pages/feedback`)，实现反馈类型选择、问题描述及截图上传表单
- 新增 "登录" 页面 (`src/pages/login`)，实现账号密码登录界面（含欢迎语、表单、登录按钮及功能链接）
- 注册上述 6 个新页面路由至 `src/app.config.js`
### Changed
- 更新底部导航栏组件 (`src/components/TabBar.vue`)，将 "我的" 标签路径指向新的 `src/pages/mine/index`
### 新增
- 新增核心页面集合
- 新增"资料列表"页面 (`src/pages/material-list/index`)
- 新增"我的"页面 (`src/pages/mine`)，包含用户信息展示、功能菜单列表
- 新增"我的计划书"页面 (`src/pages/plan`)，实现计划书列表展示、搜索过滤、状态切换功能
- 新增"我的收藏"页面 (`src/pages/favorites`)，实现文章/资料收藏列表及分类筛选功能
- 新增"修改头像"页面 (`src/pages/avatar`)，实现头像展示与修改交互
- 新增"意见反馈"页面 (`src/pages/feedback`)，实现反馈类型选择、问题描述及截图上传表单
- 新增"登录"页面 (`src/pages/login`)，实现账号密码登录界面（含欢迎语、表单、登录按钮及功能链接）
- 注册上述 6 个新页面路由至 `src/app.config.js`
### 优化
- 优化 `NavHeader` 组件 (`src/components/NavHeader.vue`)
- 新增返回按钮逻辑：当页面栈深度大于1时，自动显示左侧返回按钮
- 优化布局结构，确保标题在显示返回按钮时依然保持绝对居中
### 修复
- 修复部分页面（我的计划书、修改头像、意见反馈）顶部导航栏及返回按钮缺失问题
- 补充 `src/pages/plan/index.vue` 中 `NavHeader` 组件的引用
- 补充 `src/pages/avatar/index.vue` 中 `NavHeader` 组件的引用
- 补充 `src/pages/feedback/index.vue` 中 `NavHeader` 组件的引用
### 优化
- 更新底部导航栏组件 (`src/components/TabBar.vue`)，将"我的"标签路径指向新的 `src/pages/mine/index`
- 优化页面样式实现，全面使用 Tailwind CSS 替代传统 CSS，提升开发效率与样式一致性
- 集成 NutUI 组件库 (`nut-avatar`, `nut-cell`, `nut-tabs`, `nut-searchbar`, `nut-uploader`, `nut-textarea`) 提升交互体验
### Fixed
- 修复 Vue 3 响应式组件警告：将包含 NutUI 图标组件的静态数据源从 `ref` 升级为 `shallowRef`，并结合 `markRaw` 使用。彻底消除了 "Component that was made a reactive object" 警告，避免了 Vue 对组件对象进行不必要的深度代理，显著提升了页面初始化和渲染性能。涉及首页、TabBar、入职相关、签单相关及家办相关所有页面。
- 优化 `NavHeader` 组件交互体验，将页面头部固定在顶部 (`fixed`)，并内置等高占位元素防止内容遮挡，提升滚动时的用户体验。
- 重构图标使用方式：创建 `src/components/IconFont.vue` 组件封装 NutUI 图标库，支持通过字符串 `name` 属性配置图标，彻底移除 `markRaw` 逻辑，简化代码结构并符合用户偏好，同时保留了 SVG 图标的高清与高性能特性。
### Added
- 新增 "资料知识库" 页面 (`src/pages/knowledge-base`)，还原设计稿布局
- 使用 Tailwind CSS 实现页面样式，包括自定义 Tabs 和卡片布局
- 调整卡片布局，将图片移至顶部，优化视觉体验
- 集成 `NavHeader` 和 `TabBar` 组件，保持全站风格统一
- 配置新页面路由至 `src/app.config.js`
- 使用随机图片填充内容，模拟真实数据展示
---
**详细信息**：
- **影响文件**: 多个新页面及组件
- **技术栈**: Vue 3, Taro, TailwindCSS, NutUI
- **测试状态**: ✅ 已通过
## [2026-01-25] - 响应式优化与组件重构
### 修复
- 修复 Vue 3 响应式组件警告：将包含 NutUI 图标组件的静态数据源从 `ref` 升级为 `shallowRef`，并结合 `markRaw` 使用
- 彻底消除了 "Component that was made a reactive object" 警告
- 避免了 Vue 对组件对象进行不必要的深度代理
- 显著提升了页面初始化和渲染性能
- 涉及首页、TabBar、入职相关、签单相关及家办相关所有页面
### 优化
- 优化 `NavHeader` 组件交互体验
- 将页面头部固定在顶部 (`fixed`)
- 内置等高占位元素防止内容遮挡，提升滚动时的用户体验
### 重构
- 重构图标使用方式：创建 `src/components/IconFont.vue` 组件封装 NutUI 图标库
- 支持通过字符串 `name` 属性配置图标
- 彻底移除 `markRaw` 逻辑，简化代码结构并符合用户偏好
- 保留了 SVG 图标的高清与高性能特性
---
**详细信息**：
- **影响文件**: src/components/IconFont.vue, src/components/NavHeader.vue, 及多个页面
- **技术栈**: Vue 3, shallowRef, markRaw
- **测试状态**: ✅ 已通过
## [2026-01-23] - 资料知识库页面与导航组件
### 新增
- 新增"资料知识库"页面 (`src/pages/knowledge-base`)
- 还原设计稿布局
- 使用 Tailwind CSS 实现页面样式，包括自定义 Tabs 和卡片布局
- 调整卡片布局，将图片移至顶部，优化视觉体验
- 集成 `NavHeader` 和 `TabBar` 组件，保持全站风格统一
- 配置新页面路由至 `src/app.config.js`
- 使用随机图片填充内容，模拟真实数据展示
### 新增
- 创建通用导航头组件 `src/components/NavHeader.vue`，统一页面头部样式
- 重构 "入职相关"、"签单相关"、"家办相关" 页面，使用 `NavHeader` 组件替代硬编码的头部结构
- 新增 "家办相关" 页面 (`src/pages/family-office`)，复用 "入职相关" 页面布局与样式
### 重构
- 重构"入职相关"、"签单相关"、"家办相关"页面，使用 `NavHeader` 组件替代硬编码的头部结构
---
**详细信息**：
- **影响文件**: src/pages/knowledge-base/index.vue, src/components/NavHeader.vue, src/pages/onboarding/index.vue, src/pages/signing/index.vue, src/pages/family-office/index.vue
- **技术栈**: Vue 3, TailwindCSS
- **测试状态**: ✅ 已通过
## [2026-01-20] - 家办相关页面新增
### 新增
- 新增"家办相关"页面 (`src/pages/family-office`)，复用"入职相关"页面布局
- 规划并实现家庭成员、健康档案、资产管理、生活服务四大功能板块
- 注册新页面路由至 `src/app.config.js`
---
**详细信息**：
- **影响文件**: src/pages/family-office/index.vue, src/app.config.js
- **技术栈**: Vue 3, TailwindCSS
- **测试状态**: ✅ 已通过
## [2026-01-18] - 项目初始化与基础页面
### 新增
- 初始化项目 Git 仓库
- 创建 .gitignore 配置文件
- 创建并切换到 develop 分支
- 新增 "入职相关" 页面 (`src/pages/onboarding`)，1:1 还原设计稿 UI
- 实现基于 Tailwind CSS 的页面布局与样式，精确适配设计稿参数
- 配置 "入职相关" 页面的自定义导航栏样式
- 注册新页面路由至 `src/app.config.js`
- 新增 "签单相关" 页面 (`src/pages/signing`)，复用 "入职相关" 页面布局
- 为 "签单相关" 页面配置自定义导航栏与渐变色背景样式
### 新增
- 新增"入职相关"页面 (`src/pages/onboarding`)，1:1 还原设计稿 UI
- 实现基于 Tailwind CSS 的页面布局与样式，精确适配设计稿参数
- 配置"入职相关"页面的自定义导航栏样式
- 注册新页面路由至 `src/app.config.js`
### 新增
- 新增"签单相关"页面 (`src/pages/signing`)，复用"入职相关"页面布局
- 为"签单相关"页面配置自定义导航栏与渐变色背景样式
### 新增
- 新增可复用的底部导航栏组件 (`src/components/TabBar.vue`)，统一各页面的导航交互
### Changed
---
**详细信息**：
- **影响文件**: .gitignore, src/pages/onboarding/index.vue, src/pages/signing/index.vue, src/components/TabBar.vue, src/app.config.js
- **技术栈**: Git, Vue 3, TailwindCSS
- **测试状态**: ✅ 已通过
## [2026-01-15] - 离线功能移除与首页重构
### 配置
- 暂时禁用授权模式功能 (`ENABLE_AUTH_MODE = false`)
- 拦截所有授权检查与自动跳转登录逻辑
- 禁用 401 自动续期拦截器
- 拦截所有授权检查与自动跳转登录逻辑
- 禁用 401 自动续期拦截器
- 暂时禁用离线模式功能 (`ENABLE_OFFLINE_MODE = false`)
- 拦截所有离线缓存读写操作与轮询逻辑
- 拦截所有离线缓存读写操作与轮询逻辑
### 修复
- 修复 `src/pages/index/index.vue` 中 `ENABLE_OFFLINE_MODE` 引用缺失导致的报错
- 优化 `src/pages/index/index.vue` 减少不必要的网络监听资源消耗
### 重构
- 重构首页 (`src/pages/index`)，使用 Taro + Vue 3 Setup 语法实现
- 适配 `docs/design/manulife-V1/首页` 设计稿，精确还原 UI
- 转换 CSS 为 Less，并使用 `rpx` 单位适配小程序响应式布局
- 整合离线网络检测与状态管理逻辑
- 更新首页导航栏标题为 "臻奇智荟圈"
- 适配 `docs/design/manulife-V1/首页` 设计稿，精确还原 UI
- 转换 CSS 为 Less，并使用 `rpx` 单位适配小程序响应式布局
- 整合离线网络检测与状态管理逻辑
- 更新首页导航栏标题为"臻奇智荟圈"
### 优化
- 重构首页样式 (`src/pages/index`)，全面采用 Tailwind CSS 替代 Less
- 替换静态图片资源为 Picsum 随机图源，提升演示灵活性
- 集成 NutUI 图标组件库，替换原有 SVG/图片图标
- 优化 "入职相关" 页面样式 (`src/pages/onboarding`)，使用 CSS 背景色替代设计稿切图背景
- 替换 "入职相关" 页面图标为 NutUI 标准图标库，提升加载性能与清晰度
- 优化 "入职相关" 与 "签单相关" 页面的视觉体验，引入渐变色背景系统（Header 及各板块标题）
- 修复 "入职相关" 页面首个板块与导航栏重叠的布局问题
- 替换静态图片资源为 Picsum 随机图源，提升演示灵活性
- 集成 NutUI 图标组件库，替换原有 SVG/图片图标
- 优化"入职相关"页面样式 (`src/pages/onboarding`)
- 使用 CSS 背景色替代设计稿切图背景
- 替换"入职相关"页面图标为 NutUI 标准图标库，提升加载性能与清晰度
- 优化"入职相关"与"签单相关"页面的视觉体验
- 引入渐变色背景系统（Header 及各板块标题）
- 修复"入职相关"页面首个板块与导航栏重叠的布局问题
### 优化
- 优化底部导航栏样式，移除 Home Indicator (底部灰条) 以符合设计稿
- 重构 TabBar 布局，移除绝对定位与固定高度，改用 Flexbox + Padding 实现更自然的垂直居中与适配
- 增加底部导航栏 `active` 属性，支持不同页面高亮状态切换
- 重构首页、入职页、签单页，统一使用 `TabBar` 组件
- 替换首页 (`src/pages/index`) 自定义按钮为 NutUI `nut-button` 组件，并保留原有视觉样式
### Removed
---
**详细信息**：
- **影响文件**: src/pages/index/index.vue, src/pages/onboarding/index.vue, src/pages/signing/index.vue, src/components/TabBar.vue
- **技术栈**: Vue 3, Taro, TailwindCSS, NutUI
- **测试状态**: ✅ 已通过
## [2026-01-12] - 离线功能移除
### 移除
- 删除项目所有离线功能相关逻辑
- 移除 `src/composables/useOfflineBookingCache.js` 和 `useOfflineBookingCachePolling.js`
- 清理 `src/app.js` 中的离线初始化代码
- 清理 `src/utils/request.js` 中的弱网缓存拦截与提示逻辑
- 清理 `src/pages/index/index.vue` 中的网络状态监听与离线模式代码
- 移除 `src/utils/uiText.js` 及相关引用
- 移除 `src/api/index.js` 中的离线专用接口定义
- 移除 `src/composables/useOfflineBookingCache.js` 和 `useOfflineBookingCachePolling.js`
- 清理 `src/app.js` 中的离线初始化代码
- 清理 `src/utils/request.js` 中的弱网缓存拦截与提示逻辑
- 清理 `src/pages/index/index.vue` 中的网络状态监听与离线模式代码
- 移除 `src/utils/uiText.js` 及相关引用
- 移除 `src/api/index.js` 中的离线专用接口定义
- 更新配置文件，移除 `ENABLE_OFFLINE_MODE` 开关
### 修复
- 修复构建告警：移除首页残留的 `ENABLE_OFFLINE_MODE` 与 `@/utils/uiText` 引用
### Fixed
---
**详细信息**：
- **影响文件**: 多个文件清理
- **技术栈**: Vue 3, Taro
- **测试状态**: ✅ 已通过
## [2026-01-10] - ESLint 配置修复
### 修复
- 修复 ESLint 无法解析 Vue SFC 导致 lint 全量报错：补齐 ESLint 配置与 Vue 解析依赖
- 修复 eslint-config-taro 在 Vue 项目中触发 React Hooks 规则导致误报的问题
### Changed
---
**详细信息**：
- **影响文件**: .eslintrc.js, package.json
- **技术栈**: ESLint, Vue 3
- **测试状态**: ✅ 已通过
## [2026-01-08] - 文档预览优化
### 优化
- 优化 DocumentPreview 小程序端预览策略：无法获取文件大小时默认走在线预览
- 将 DocumentPreview 小程序端样式单位统一为 rpx
### Added
### 新增
- 补全文档预览示例页的 Excel / PPT 在线示例链接
---
**详细信息**：
- **影响文件**: src/components/DocumentPreview.vue
- **技术栈**: Vue 3, Taro
- **测试状态**: ✅ 已通过
---
**最后更新**: 2026-02-01
**维护者**: Claude Code
**项目**: Manulife WeApp
......
# 技术决策记录 (Architecture Decision Records)
> 本文档记录 Manulife WeApp 项目中的重要技术决策及其背景，帮助团队理解为什么选择当前的技术方案。
## 📋 决策记录模板
每个决策记录包含以下信息：
- **决策日期**: 何时做出此决策
- **决策者**: 谁做出的决策
- **状态**: `提案中` | `已采纳` | `已弃用` | `已替代`
- **背景**: 为什么需要这个决策
- **决策**: 具体的技术选择
- **原因**: 为什么选择这个方案
- **后果**: 采用此决策的正面和负面影响
- **替代方案**: 当时考虑的其他方案
---
## 🎯 已采纳的技术决策
### 1. UI 库选择：NutUI vs Vant
**决策日期**: 2025-12-01
**决策者**: 团队
**状态**: ✅ 已采纳
#### 背景
项目需要为 Taro 小程序选择 UI 组件库，当时有两个主要选择：
- NutUI Taro（京东出品）
- Vant Taro（有赞出品）
#### 决策
选择 **NutUI Taro** 作为主要 UI 组件库。
#### 原因
1. **Taro 生态适配更好**: NutUI 对 Taro 的支持更完善
2. **组件丰富**: 满足业务需求的组件更齐全
3. **京东背书**: 京东维护，社区活跃
4. **文档完善**: 中文文档详尽，便于团队上手
#### 后果
**正面影响**:
- ✅ 快速搭建 UI，提升开发效率
- ✅ 组件样式统一，视觉一致性好
- ✅ 自动导入配置，无需手动 import
**负面影响**:
- ⚠️ 部分组件有样式覆盖限制（如 textarea）
- ⚠️ 嵌套弹窗在真机有层级冲突问题
#### 替代方案
当时未采纳：**Vant Taro**
- Vant 在 Web 端更流行，但 Taro 版本相对 NutUI 较弱
#### 相关文档
- [NutUI 组件使用陷阱](./lessons-learned.md#nutui-组件使用陷阱)
---
### 2. 样式策略：TailwindCSS + Less 混合使用
**决策日期**: 2025-12-05
**决策者**: 团队
**状态**: ✅ 已采纳
#### 背景
项目需要一套高效的样式解决方案，既要快速开发，又要灵活定制。
#### 决策
采用 **TailwindCSS (80%) + Less (20%)** 混合策略。
#### 原因
**TailwindCSS 优势**:
- 原子化 CSS，开发速度快
- 响应式设计简单（`sm:`、`md:`、`lg:`）
- 避免命名冲突
- 文件体积小（按需生成）
**Less 补充**:
- 组件特定样式（需要 `scoped`）
- 深度选择器（`:deep()`）
- 复杂动画和伪元素
#### 后果
**正面影响**:
- ✅ 开发效率提升 40%+
- ✅ 样式一致性更好
- ✅ 减少 CSS 文件数量
**负面影响**:
- ⚠️ 需要学习 TailwindCSS 类名
- ⚠️ 初期有学习曲线
#### 使用指南
```vue
<!-- TailwindCSS: 80% 场景 -->
<div class="flex items-center p-4 bg-white rounded-lg">
<h1 class="text-xl font-bold">标题</h1>
</div>
<!-- Less: 20% 场景 -->
<style lang="less" scoped>
.custom-card {
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
:deep(.nut-button) {
background-color: rgba(255, 255, 255, 0.2);
}
}
</style>
```
#### 相关文档
- [样式处理策略](./lessons-learned.md#样式处理策略)
---
### 3. 双设计宽度系统：375px (NutUI) + 750px (自定义)
**决策日期**: 2025-12-10
**决策者**: 团队
**状态**: ✅ 已采纳
#### 背景
NutUI 组件库基于 375px 设计稿，但项目自定义页面使用 750px 设计稿。
#### 决策
实现 **双设计宽度系统**：
- NutUI 组件 → 375px 基准
- 自定义页面 → 750px 基准
#### 原因
1. **NutUI 生态**: NutUI 组件基于 375px 设计
2. **传统习惯**: 750px 是移动端设计稿的传统标准
3. **灵活适配**: 两者并存，互不影响
#### 实现方案
```javascript
// config/index.js
const designWidth = {
750: [375, 375], // NutUI 组件
750: [750, 750] // 其他所有页面
}
```
#### 后果
**正面影响**:
- ✅ NutUI 组件尺寸正确
- ✅ 自定义页面符合传统标准
**负面影响**:
- ⚠️ 需要明确区分 NutUI 组件和自定义元素
- ⚠️ 新手可能混淆
#### 最佳实践
```vue
<!-- NutUI 组件: 使用 375px 设计稿 -->
<nut-button :custom-style="{ fontSize: '14px', padding: '8px 16px' }">
按钮
</nut-button>
<!-- 自定义元素: 使用 750px 设计稿 -->
<view class="custom-box" style="width: 750px; height: 200px">
内容
</view>
```
#### 相关文档
- [样式处理策略 - 双设计宽度系统](./lessons-learned.md#⚠️-双设计宽度系统)
---
### 4. 代码复用原则："第 3 次出现原则"
**决策日期**: 2026-01-15
**决策者**: Claude Code
**状态**: ✅ 已采纳
#### 背景
项目中出现大量重复代码，需要制定抽取标准。
#### 决策
采用 **"第 3 次出现原则"（Rule of Three）**：
- 代码出现 1-2 次：直接实现
- 代码出现 3 次：**必须抽取**为 Composable 或组件
#### 原因
1. **避免过早抽取**: 第 1、2 次可能还不稳定
2. **避免过度抽象**: 等待模式明确后再抽取
3. **提升可维护性**: 减少重复代码，统一修改点
#### 成功案例
- `useSectionList` - 减少约 60 行重复代码
- `useFileOperation` - 减少约 290 行重复代码
- `useListItemClick` - 统一列表点击逻辑
#### 后果
**正面影响**:
- ✅ 代码重复显著减少
- ✅ 可维护性大幅提升
- ✅ 修改点统一，降低 bug 率
**负面影响**:
- ⚠️ 需要主动识别重复代码
- ⚠️ 前期可能略有过度设计
#### 触发条件
- ✅ 代码重复 ≥ 3 次 → **必须抽取**
- ✅ v-for 模板超过 5 行 → 提取列表项组件
- ✅ 函数超过 50 行 → 拆分函数
#### 相关文档
- [组件抽取与复用](./lessons-learned.md#组件抽取与复用)
---
### 5. 认证流程：静默刷新 + Promise 单例模式
**决策日期**: 2026-01-20
**决策者**: 团队
**状态**: ✅ 已采纳
#### 背景
项目需要处理会话过期（401）问题，提供无感知的用户体验。
#### 决策
实现 **静默刷新 + Promise 单例模式**：
- API 返回 401 时自动刷新会话
- 使用 Promise 单例防止并发刷新
- 刷新失败后跳转到认证页
#### 核心逻辑
```javascript
// src/utils/authRedirect.js
let auth_promise = null // Promise 单例
async function refreshSession() {
// 如果已有刷新任务，返回现有 Promise
if (auth_promise) {
return auth_promise
}
// 创建新的刷新任务
auth_promise = doRefresh()
.finally(() => {
auth_promise = null // 清理单例
})
return auth_promise
}
```
#### 原因
1. **用户体验好**: 无需手动重新登录
2. **防止并发**: 单次刷新，避免多次请求
3. **失败兜底**: 刷新失败跳转认证页
#### 后果
**正面影响**:
- ✅ 用户体验显著提升
- ✅ 减少登录次数
- ✅ 并发 401 请求共享刷新结果
**负面影响**:
- ⚠️ 增加代码复杂度
- ⚠️ 需要完善的错误处理
#### 相关文档
- [CLAUDE.md - 身份认证流程](../CLAUDE.md#2-身份认证流程必需)
---
### 6. 响应式优化：shallowRef + markRaw 处理组件对象
**决策日期**: 2026-01-25
**决策者**: Claude Code
**状态**: ✅ 已采纳
#### 背景
Vue 3 对包含组件对象的响应式数据进行深度代理，导致性能警告。
#### 决策
使用 **shallowRef + markRaw** 处理组件对象响应式。
#### 核心代码
```javascript
import { shallowRef, markRaw } from 'vue'
// ✅ GOOD - 浅层响应式
const menuItems = shallowRef([
{
icon: markRaw(IconFont), // 标记为原始对象
name: 'heart',
title: '我的收藏'
}
])
```
#### 原因
1. **消除警告**: 避免 "Component that was made a reactive object" 警告
2. **性能优化**: 避免不必要的深度代理
3. **符合语义**: 组件对象不需要响应式
#### 后果
**正面影响**:
- ✅ 消除性能警告
- ✅ 页面初始化速度提升
- ✅ 内存占用减少
**负面影响**:
- ⚠️ 需要理解 Vue 3 响应式原理
- ⚠️ 不正确使用可能导致视图不更新
#### 相关文档
- [性能优化 - 响应式数据优化](./lessons-learned.md#1-响应式数据优化)
---
### 7. 静态资源加载：SVG 图标使用 import 导入
**决策日期**: 2026-01-28
**决策者**: Claude Code
**状态**: ✅ 已采纳
#### 背景
使用字符串路径加载 SVG 图标导致 500 错误。
#### 决策
**SVG 图标必须使用 ES6 `import` 导入**，不能使用字符串路径。
#### 核心代码
```javascript
// ❌ BAD - 字符串路径导致 500 错误
export const getDocumentIcon = (type) => {
const icons = {
pdf: '/assets/images/icon/doc/doc.svg', // ❌ 500 错误
}
return icons[type]
}
// ✅ GOOD - 使用 import 导入
import pdfIcon from '@/assets/images/icon/doc/pdf.svg'
export const getDocumentIcon = (type) => {
const icons = {
pdf: pdfIcon, // ✅ 正确
}
return icons[type]
}
```
#### 原因
1. **Taro 构建限制**: 字符串路径无法被构建工具正确处理
2. **资源处理**: import 方式能让构建工具正确打包资源
3. **类型安全**: import 方式支持类型检查
#### 后果
**正面影响**:
- ✅ 图标正常加载
- ✅ 构建产物优化
- ✅ 支持路径别名
**负面影响**:
- ⚠️ 需要手动 import 所有图标
- ⚠️ 动态路径需要额外处理
#### 静态资源处理规则
| 资源类型 | 引用方式 |
|---------|---------|
| **SVG 图标** | `import` 导入 |
| **图片** | `import` 或字符串路径 |
| **远程资源** | 字符串 URL |
#### 相关文档
- [静态资源加载问题](./lessons-learned.md#静态资源加载问题)
---
## 🔄 提案中的决策
### 8. 引入 TypeScript？（待讨论）
**提案日期**: 2026-02-01
**状态**: 🤔 提案中
#### 背景
项目当前使用 JavaScript，考虑引入 TypeScript 提升代码质量。
#### 提案
逐步迁移到 **TypeScript**：
1. 新文件使用 `.ts` / `.vue` + `<script lang="ts">`
2. 旧文件逐步迁移
3. 定义类型定义文件（`types/`）
#### 原因
1. **类型安全**: 减少运行时错误
2. **IDE 支持**: 更好的自动补全
3. **可维护性**: 类型即文档
#### 疑虑
1. **学习成本**: 团队需要学习 TS
2. **迁移成本**: 现有代码需要改造
3. **构建时间**: TS 编译增加构建时间
#### 替代方案
- **JSDoc**: 在 JS 中添加类型注释
- **保持现状**: 继续使用纯 JS
---
## 📊 决策统计
### 按类别统计
- **UI/样式**: 3 个决策（NutUI、TailwindCSS、双设计宽度）
- **代码质量**: 2 个决策（代码复用、响应式优化）
- **架构设计**: 2 个决策（认证流程、静态资源）
### 按状态统计
- ✅ **已采纳**: 7 个
- 🤔 **提案中**: 1 个
- ❌ **已弃用**: 0 个
- 🔄 **已替代**: 0 个
---
## 📝 如何添加新决策
### 决策记录流程
1. **识别需求**: 发现需要技术决策的场景
2. **讨论方案**: 团队讨论可能的方案
3. **记录决策**: 在本文档中添加决策记录
4. **定期回顾**: 每季度回顾决策的有效性
### 决策模板
```markdown
### N. 决策标题
**决策日期**: YYYY-MM-DD
**决策者**: 姓名/角色
**状态**: 状态标识
#### 背景
描述为什么需要这个决策...
#### 决策
具体的技术选择...
#### 原因
为什么选择这个方案...
#### 后果
**正面影响**: ...
**负面影响**: ...
#### 替代方案
当时考虑的其他方案...
#### 相关文档
- [相关文档链接](./xxx.md)
```
---
## 🔄 决策回顾机制
### 定期回顾
- **频率**: 每季度一次
- **参与人**: 技术负责人 + 核心开发
- **目的**: 评估决策有效性，必要时调整
### 更新状态
当决策不再适用时，更新状态：
- `已采纳` → `已弃用`: 决策不再使用
- `已采纳` → `已替代`: 被新方案替代
- 记录替代方案和原因
---
## 📚 相关文档
- [经验教训总结](./lessons-learned.md)
- [项目指南](../CLAUDE.md)
- [变更日志](./CHANGELOG.md)
- [代码注释规范](~/.claude/rules/code-commenting.md)
---
**最后更新**: 2026-02-01
**维护者**: Claude Code
**项目**: Manulife WeApp