Hooke / manulife-weapp

记录本次修复的内容：
- 问题描述、根本原因
- 技术方案和实现细节

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

问题描述：
- 提交成功后，有时表单会保留上次的数据
- 表现不稳定：大部分时候正常，偶尔会有残留数据
- 影响用户体验，需要手动清除数据

根本原因：
- 依赖 watch 监听器重置表单存在竞态条件
- watch(visible) 只在弹窗打开时重置，关闭时不重置
- 组件可能被缓存（v-show），状态未清理
- 响应式更新时序问题导致残留

解决方案：
1. 在 submit() 成功后立即调用 resetForm()
2. 在 close() 关闭弹窗前调用 resetForm()
3. 优化 watch(visible) 作为安全网，检测残留数据
4. 为所有模板组件添加 clearErrors() 方法

技术改进：
- 新增 resetForm() 函数：重置表单和错误状态
- submit() 中调用 resetForm()，确保提交后立即清空
- close() 中调用 resetForm()，确保关闭时清空
- watch(visible) 仅在检测到残留数据时才重置
- 统一模板组件接口：validate + clearErrors

影响文件:
- src/components/PlanFormContainer.vue
- src/components/PlanTemplates/SavingsTemplate.vue
- src/components/PlanTemplates/LifeInsuranceTemplate.vue
- src/components/PlanTemplates/CriticalIllnessTemplate.vue

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

- 为计划书表单添加完整验证机制
- 更新重疾险产品货币为 USD
- 各个 PlanFields 组件支持错误提示
- CriticalIllnessTemplate 和 LifeInsuranceTemplate 实现验证逻辑
- PlanFormContainer 添加提交前验证流程

技术细节：
- PlanFormContainer 通过 ref 调用子组件 validate 方法
- 各个表单字段组件添加 error 状态显示
- 使用 usePlanFormValidation composable 管理验证逻辑
- 验证失败时阻止提交并显示错误信息

影响文件:
- src/components/PlanFormContainer.vue
- src/components/PlanFields/*.vue
- src/components/PlanTemplates/CriticalIllnessTemplate.vue
- src/components/PlanTemplates/LifeInsuranceTemplate.vue
- src/config/plan-templates.js
- docs/CHANGELOG.md

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

- 创建 form-sn-mapping.md 文档，提供完整的 form_sn 到模版组件的映射关系
- 创建 form-sn-mapping.json 文件，提供机器可读的映射数据
- 包含 8 个产品的映射（人寿保险 2 个、重疾保险 3 个、储蓄保险 4 个）
- 提供后端集成指南，包括 API 返回示例、命名规范、新产品接入流程
- 明确职责分工：后端只负责返回 form_sn 字段，前端处理具体配置

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

- 创建计划书模块架构和经验教训总结文档
- 创建快速使用指南（5分钟快速集成）
- 更新架构文档，明确提取计划三层结构
- 添加 SavingsTemplate 组件（储蓄型产品模板）
- 修复 PlanFormContainer 中的模板导入路径

影响文件：
- docs/lessons-learned/plan-entry-module-summary.md (新增)
- docs/plan/plan-entry-quick-guide.md (新增)
- docs/CHANGELOG.md (更新)
- docs/plan/plan-entry-architecture.md (更新)
- src/components/PlanTemplates/SavingsTemplate.vue (新增)
- src/components/PlanFormContainer.vue (修复)

根据客户需求，移除计划书模版中的保险期间显示字段。
配置文件中的 insurance_period 配置保留，以备未来需要。

- 移除 LifeInsuranceTemplate 中的保险期间显示
- 移除 CriticalIllnessTemplate 中的保险期间显示
- 保留配置文件中的 insurance_period 配置

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

- 修复 AmountInput 组件键盘输入报错问题
- 修复快速输入时显示 [object Object] 的异常
- 优化输入体验，引入内部状态分离显示值与模型值
- 修复标签和币种提示分两行显示的样式问题
- 统一计划书模版组件间距，增强视觉一致性
- 为重疾保险模版添加配置缺失提示

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

- 在 commit-msg hook 中添加 plan 到允许的 scope 列表
- 更新帮助文档，说明 plan 为计划书模块

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

- 添加 JSDoc 注释提升代码可读性
- 修复 ESLint 错误：isNaN 改为 Number.isNaN
- 优化 AgePicker 和 DatePicker 组件逻辑
- 统一组件代码风格和结构
- 更新 CHANGELOG 记录变更

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

- 添加递归函数支持任意深度嵌套
- 修复 list 字段无法展开的问题
- 支持四层嵌套结构
- 重新生成所有 API 文档
- 修复 AmountInput ESLint 错误

为 SearchBar 组件添加 variant='rounded' 属性，统一知识库页面
与搜索页面的搜索栏高度表现

影响文件:
- src/pages/knowledge-base/index.vue

- 移除废弃的 shebang 和 husky.sh 导入
- 修复 pre-commit hook 中的 ESLint 文件列表传递问题
- 移除所有交互式确认，改为提示信息
- 添加 husky 和 chore 到允许的 commit scope 列表
- 优化 hooks 以兼容 husky v10

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

- 删除资料列表和本周热门资料中的预览 Toast 提示
- 简化用户体验流程，减少干扰
- 同步更新 components.d.ts

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

- 实现滚动到底部自动加载更多功能
- 支持搜索框失焦触发搜索（@blur 事件）
- 添加清除搜索回调，重新请求最新数据
- 自定义 CSS 加载动画（替换 NutUI loading）
- 分页状态缓存，各分类独立维护页码
- 禁用 category-list 页面的 console.log

影响文件:
- src/pages/material-list/index.vue（无限滚动、搜索增强）
- docs/CHANGELOG.md（更新变更记录）
- src/pages/category-list/index.vue（禁用 console.log）

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

## 主要变更

### 优化
- 移除硬编码的 CATEGORY_IDS 和 loopNav 配置
- 新增 fetchHomeIcons 函数，从 API 动态获取导航数据
- 实现智能参数解析，自动提取 link 字段中的路由和查询参数
- 支持任意数量的查询参数（如 cid, category_id 等）
- API 失败时自动降级到默认配置，保证可用性

### 导航跳转逻辑优化
- 重构 handleGridNav 函数，使用通用的参数提取逻辑
- 自动添加 title 参数到目标页面
- 移除硬编码的路由判断，提升可维护性

### 代码质量提升
- 性能优化：使用 shallowRef 存储导航数据
- 错误处理：完善的 try-catch 和降级方案
- 代码注释：添加完整的 JSDoc 注释

## 影响文件
- src/pages/index/index.vue
- docs/CHANGELOG.md

## 技术细节
- link 字段格式：/pages/category-list/index?cid=3129684
- 自动解析路由和查询参数
- 参数值自动 URL 解码
- 灵活支持后台配置，无需发版

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

## 主要修改

### 1. 修复 OpenAPI 生成器 (scripts/generateApiFromOpenAPI.js)
- 修复 extractAPIInfo is not defined 错误
- 增强 generateReturnJSDoc 函数，支持正确解析数组类型的 data 字段
- 新增对 Array<{...}> 类型的完整字段描述生成

### 2. 优化 API 文档 JSDoc 注释
- news.js: data 字段从 any 改为详细的 Array<{...}> 类型
- home.js: 新增 home 模块 API（首页图标列表）

### 3. 添加无限滚动功能 (src/pages/material-list/index.vue)
- 实现 useReachBottom 触底加载更多
- 添加分页状态管理（currentPage, hasMore, loadingMore）
- 支持各分类独立的分页缓存
- 优化加载状态显示（加载中/没有更多了）
- 添加自定义加载动画

## 技术细节
- 使用防抖（300ms）避免频繁触发加载
- 区分首次加载和加载更多的状态
- 正确处理搜索、子分类、全部列表的分页逻辑
- 保存并恢复各分类的分页状态

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

新增功能：
- 创建本周热门资料详情页面，复用资料列表样式
- 学习人数和热度标签统一显示样式
- 添加文件大小显示

样式优化：
- 统一 tag 样式（padding、圆角、字体大小）
- 加强卡片阴影效果（shadow-sm → shadow-md）
- 添加多行文本省略样式支持（index、week-hot-material、knowledge-base）

Bug 修复：
- 修复收藏状态判断逻辑，支持布尔值 true
- 移除学习人数标签中的火焰图标（避免重复）

页面路由：
- 注册 week-hot-material 页面路由
- 首页"查看更多"链接指向新页面

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Document the extraction of duplicate collection logic into a reusable composable.

- Created useCollectOperation composable with optimistic UI updates
- Refactored index and material-list pages (removed 89 lines of duplicate code)
- Fixed runtime module resolution issue
- Net reduction: 82 lines of code

Extracted 89 lines of duplicate collection/favorite operation code from index and material-list pages into a reusable composable.

Changes:
- Created src/composables/useCollectOperation.js with unified collection logic
- Refactored src/pages/index/index.vue to use the composable (-44 lines)
- Refactored src/pages/material-list/index.vue to use the composable (-45 lines)
- Fixed runtime import issue by using relative path in composable

Features:
- Optimistic UI updates with automatic rollback on error
- Consistent error handling and user feedback
- JSDoc documentation with usage examples
- Supports both meta_id and id fields

Impact:
- Net reduction: 82 lines of code eliminated
- Improved maintainability and DRY compliance
- Enhanced code reusability across pages

Co-Authored-By: Claude Code <noreply@anthropic.com>

- 新增分类列表页,支持二级分类展示和跳转
- 资料列表页实现动态 Tab 切换和搜索功能
- 首页接入热门产品和热门资料 API
- 收藏页接入列表和删除 API
- fileListAPI 新增 child_id 和 keyword 参数
- 修复 fn.js 类型检查逻辑 (String → number)

影响文件:
- src/pages/category-list/ (新建)
- src/pages/material-list/index.vue
- src/pages/index/index.vue
- src/pages/favorites/index.vue
- src/api/file.js
- src/api/fn.js
- src/app.config.js

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

新增功能：
- 创建通用埋点 Composable (useEventTracking)
  - 支持 READ_FILE 等事件类型追踪
  - 静默处理错误，不影响用户体验
  - 提供便捷方法 trackFileRead()

- ListItemActions 组件集成埋点
  - 新增 itemId prop，自动发送埋点数据
  - 向后兼容，不破坏现有代码

- 图片预览支持
  - useFileOperation 添加 isImageFile() 判断
  - 图片文件使用 Taro.previewImage 直接预览
  - 支持 jpg, jpeg, png, gif, webp, bmp, svg 格式

- 产品详情页文件预览
  - 集成 useFileOperation
  - 自动判断文件类型并选择最优预览方式

文档：
- 更新 CHANGELOG 记录变更
- 新增埋点功能使用指南

技术栈：Vue 3, Taro 4, Composition API

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

- 接入收藏列表API (listAPI) 和取消收藏API (delAPI)
- 移除分类Tabs逻辑，简化为统一列表展示
- 添加自定义loading spinner，替代NutUI组件
- 完善错误处理和用户提示
- 更新API联调日志和CHANGELOG

注意：实际联调需等有数据后验证

🤖 Generated with Claude Code
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

- 添加 2026-02-05 条目，记录文档整理变更
- 说明删除重复文件、文档归类优化的具体内容
- 记录整理收益和影响范围

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

删除重复文件：
- DOCS_STRUCTURE.md（与 README.md 内容重复）

文档归类优化：
- auth-debug-guide.md → guides/auth-debug-guide.md（认证调试指南）
- TARO_QUICK_REFERENCE.md → guides/TARO_QUICK_REFERENCE.md（Taro 速查表）
- api-integration-log-template.md → api-specs/api-integration-log-template.md（API 联调模板）

更新文档：
- README.md：更新目录结构说明，添加新归类文档的导航

收益：
- 文档结构更清晰，按功能分类组织
- 减少顶层文件数量，保留核心文档
- 便于开发者快速查找所需文档

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

- 创建 docs/reports/ 目录用于存放审核和分析报告
- 按日期组织子目录结构: YYYY-MM-DD
- 移动已有的两个文档到 reports/2026-02-05/
- 更新 CHANGELOG 中的文档路径引用

- 删除未定义的 store.changeUserInfo(null) 调用
- userStore.logout() 已经清除了所有用户信息
- mainStore 在项目中未被使用
- 修复 ESLint 错误: 'store' is not defined

相关文档: docs/code-review-2026-02-05.md

- 安装 husky 和 lint-staged 依赖
- 创建 pre-commit hook（代码检查、改动规模评估、CHANGELOG 检查）
- 创建 commit-msg hook（提交信息格式验证）
- 创建 pre-push hook（推送前检查）
- 创建 post-commit hook（提交成功反馈）
- 修复 src/pages/mine/index.vue 中的 ESLint 错误（删除未定义的 store 引用）

相关文档：
- docs/code-review-2026-02-05.md（代码审核报告）
- docs/userinfo-storage-logic-analysis.md（用户信息存储逻辑分析）

- 更新 API 接口联调日志
  - 文档模块接口状态从"初稿"更新为"待联调"
  - weekHotAPI（本周热门资料）：字段已确认
  - fileListAPI（文档列表）：字段已确认，修正接口路径为 `/srv/?a=file&t=file_list`
  - 更新总体进度：26个接口（12个已完成，11个待联调，3个已废弃）
- 更新 CHANGELOG 记录本次文档更新
- 更新接口文档版本至 v2.4

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

新增功能：
- 添加 SearchBar 搜索组件
- 实现实时搜索功能（带 500ms 防抖优化）
- 支持按回车键立即搜索
- 支持一键清空搜索内容
- 搜索与分类筛选联动（可组合使用）

优化体验：
- 输入时实时搜索（防抖延迟 500ms）
- 按回车键立即搜索（取消防抖定时器）
- 清空搜索时恢复当前分类的所有产品
- 切换分类时保持搜索状态

技术实现：
- API 接口：使用 listAPI 的 keyword 参数
- 防抖逻辑：使用 setTimeout 实现搜索防抖
- 状态管理：新增 searchValue 搜索状态
- 样式布局：参考 plan 页面的搜索栏布局

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

- 将状态判断从严格相等(===)改为宽松相等(==)
- 提高对数字/字符串类型混用的兼容性

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

将“Manulife 臻奇智荟圈”更新为“Manulife 臻奇荟”，以匹配最新的品牌命名规范。

- 将 .claude/ 目录添加到 .gitignore 以避免提交 IDE 配置文件
- 更新首页显示的应用名称为“臻奇荟”
- 在 Claude IDE 配置中移除不再使用的 Apifox 相关脚本
- 修正 PlanPopup 组件的类型声明文件路径

- 删除 7 个不再工作的 Apifox API 相关脚本
- 删除 .env.apifox 配置文件
- 简化 package.json 命令（移除 api:sync 和 api:test）
- 修复 API 生成工具：新增模块接口信息显示为 undefined
- 新增文档模块接口（初稿）：weekHotAPI、fileListAPI
- 创建 API_GUIDE.md 使用指南
- 更新 API 联调日志（v2.3）和 CHANGELOG

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

- 优化 API 文档生成脚本
  - 添加 CLAUDE.md 文件过滤，避免将文档文件当作 API 文档处理
  - 改进新增模块检测逻辑，显示新增模块包含的所有接口
  - 优化变更检测报告，提升可读性

- 更新 API 接口联调日志
  - 收藏模块：3个接口后端已完成，标记为待联调
  - 埋点模块：1个接口后端已完成，标记为待联调
  - 更新总体进度：24个接口（12已完成，9待联调，3已废弃）

- 新增埋点模块
  - 添加埋点接口（addAPI）
  - 生成 API 文档和接口代码

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

- 移除视频中央的播放/暂停按钮，避免遮挡画面
- 将播放控制集成到底部进度条区域（play-btn-position='bottom'）
- 优化播放结束提示为弱提示（移除图标，缩短显示时间）

优化用户观看体验，提供更沉浸式的视频播放效果。

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

新增功能：
- 添加视频文件类型判断（MP4、M4V、MOV）
- 创建视频播放页面，支持全屏播放、进度控制等功能
- 文件操作支持视频，点击查看自动跳转播放页面

优化体验：
- 移除页面初始加载状态，直接展示视频播放器
- 移除加载状态遮罩层，使用播放器自带指示器
- 修复页面高度问题，使用 flex 布局
- 更新测试视频 URL 为 CDN 地址

文档更新：
- 更新 CHANGELOG 记录所有变更

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>