文档优化总结

📝 变更说明

本次优化整理了项目文档,创建了经验教训总结文档,并优化了 CLAUDE.md 和 README.md。

✨ 新增文档

docs/lessons-learned.md

完整的 Taro + Vue 3 项目开发经验教训总结,包含:

核心章节

1. 组件抽取与复用

   • "第 3 次出现原则"（Rule of Three）
   • 何时抽取组件和 Composables
   • 实际案例分析（useSectionList、useFileOperation、useListItemClick）

2. NutUI 组件使用陷阱

   • textarea 样式无法覆盖 → 使用原生组件
   • IconFont 动态切换不响应 → 添加 :key="name"
   • 最佳实践建议

3. 静态资源加载问题

   • SVG 图标加载失败（500 错误）解决方案
   • 使用 import 导入静态资源

4. 样式处理策略

   • TailwindCSS vs Less 使用指南（80% vs 20%）
   • 双设计宽度系统详解
   • 使用场景对比表格

5. 性能优化

   • 响应式数据优化（shallowRef + markRaw）
   • 页面滚动优化（固定顶部 + 独立滚动）
   • 图片优化策略

6. 代码质量

   • JSDoc 注释规范
   • 命名规范
   • 错误处理模式

7. 架构设计

   • 统一的列表点击处理
   • 统一的文件操作
   • 分层架构原则

🔄 优化文档

CLAUDE.md

主要优化:

• ✅ 添加快速参考表格,常见问题一目了然
• ✅ 核心架构模式章节更清晰
• ✅ 添加样式处理策略和响应式优化章节
• ✅ 删除重复内容,精简文档结构
• ✅ 添加对经验教训文档的交叉引用
• ✅ 使用表情符号和表格提升可读性

关键改进:

• 新增"快速参考"部分,常见问题快速解决
• 重新组织"核心架构"章节,结构更清晰
• 突出"第 3 次出现原则"等核心经验
• 添加更多代码示例和最佳实践

README.md

主要优化:

• ✅ 添加项目文档索引（经验教训、CLAUDE.md）
• ✅ 新增"核心特性"章节
• ✅ 新增"常见问题"快速参考表格
• ✅ 精简项目结构,移除过时内容
• ✅ 优化开发规范说明
• ✅ 删除离线缓存等不再维护的功能说明

关键改进:

• 突出项目的核心特性
• 提供常见问题的快速解决方案
• 更清晰的项目结构说明
• 强调代码注释和开发规范

📊 文档对比

优化前

• ❌ CLAUDE.md 过于详细,缺乏结构化
• ❌ README.md 缺少项目亮点和常见问题
• ❌ 经验教训散落在 CHANGELOG 中,不便于查阅
• ❌ 缺少对 NutUI 陷阱、静态资源等问题的系统性总结

优化后

• ✅ 经验教训系统化整理,便于查阅
• ✅ 文档结构清晰,使用表格和表情符号提升可读性
• ✅ 添加交叉引用,相关文档相互链接
• ✅ 突出核心经验:"第 3 次出现原则"、样式策略、性能优化
• ✅ 提供常见问题的快速解决方案

🎯 使用指南

对于新开发者

1. 首先阅读: README.md

   • 了解项目概况
   • 查看快速开始指南
   • 阅读常见问题

2. 深入学习: docs/lessons-learned.md

   • 学习 Taro 项目开发的最佳实践
   • 了解常见陷阱和解决方案
   • 掌握组件抽取、样式处理、性能优化等核心技巧

3. 开发参考: CLAUDE.md

   • 查看项目架构和核心模式
   • 参考 API 层、认证流程、导航系统等实现
   • 使用快速参考表格解决常见问题

对于 Claude Code

• 主要参考: CLAUDE.md
• 辅助参考: docs/lessons-learned.md
• 遵循规范: ~/.claude/rules/code-commenting.md

📌 核心经验总结

1. "第 3 次出现原则"

当相同代码模式出现 3 次时,必须抽取为 Composable 或组件。

实际收益:

• 减少 60-290 行重复代码
• 提升可维护性
• 统一修改点

2. NutUI 组件陷阱

问题	解决方案
textarea 样式无法覆盖	使用原生 <textarea>
IconFont 动态切换不响应	添加 :key="name"

3. 静态资源加载

• ❌ 错误: 字符串路径 /assets/images/icon.svg
• ✅ 正确: import icon from '@/assets/images/icon.svg'

4. 样式策略

• TailwindCSS (80%): 布局、间距、颜色
• Less (20%): 组件样式、动画、伪元素

5. 性能优化

• 使用 shallowRef + markRaw 处理组件对象
• 固定顶部 + 列表独立滚动
• CDN 参数优化图片

🔄 持续改进

本文档会随着项目开发持续更新,记录新的经验教训。

下次更新建议:

• 添加更多实际案例
• 补充性能优化数据
• 添加架构图和流程图

---

优化日期: 2026-01-31 维护者: Claude Code 项目: Manulife WeApp