Hooke / manulife-weapp

Go to a project
Toggle navigation Toggle navigation pinning
hookehuyr
fc100dd6 1 parent b5592541

docs: 重构文档目录结构，提升组织清晰度 

删除重复文件：
- 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>
Inline Side-by-side
Showing 5 changed files with 108 additions and 156 deletions
# Docs 目录结构说明
## 📁 目录结构
```
docs/
├── README.md # 文档总索引（保留在顶层）
├── CHANGELOG.md # 变更日志（保留在顶层）
├── lessons-learned.md # 经验教训总结（保留在顶层）
│
├── PreDocs/ # 前期项目文档
│ └── 臻奇智荟圈小程序项目需求20260123a.docx
│
├── decisions/ # 技术决策记录
│ └── decisions.md
│
├── plan/ # 开发计划
│ ├── 项目开发计划.md
│ ├── 前端开发计划.md
│ └── 前端开发计划-调整版.md
│
├── guides/ # 指南文档
│ ├── START_HERE.md # 新人入门指南
│ ├── API_USAGE_EXAMPLES.md # API 使用示例
│ ├── API_DIFF_GUIDE.md # API 差异指南
│ ├── GET_VS_POST_GUIDE.md # GET vs POST 指南
│ ├── OPENAPI_TO_API_GUIDE.md # OpenAPI 转 API 指南
│ ├── JSDOC_GENERATION_GUIDE.md # JSDoc 生成指南
│ ├── apifox-integration-guide.md # Apifox 集成指南
│ ├── changelog-check-guide.md # CHANGELOG 检查指南
│ └── 腾讯元宝AI接入说明.md # 腾讯元宝 AI 接入说明
│
├── reports/ # 问题修复与实施报告
│ ├── COMPLETION_REPORT.md # 完成报告
│ ├── FINAL_FIX_REPORT.md # 最终修复报告
│ ├── IMPLEMENTATION_SUMMARY.md # 实施总结
│ ├── GET_POST_FIX.md # GET/POST 修复
│ ├── RENAME_TEST_REPORT.md # 重命名测试报告
│ ├── apifox-setup-summary.md # Apifox 设置总结
│ ├── changelog-check-report-20260201.md # CHANGELOG 检查报告
│ ├── changes-summary.md # 变更总结
│ ├── DOCUMENT_ICONS_UPDATE.md # 文档图标更新
│ ├── search-fix-summary.md # 搜索修复总结
│ └── search-problems-analysis.md # 搜索问题分析
│
├── design/ # UI/UX 设计文档
│ └── manulife-V1/
│ ├── done/ # 已完成的设计稿
│ │ ├── 首页/
│ │ ├── 入职相关/
│ │ ├── 签单相关/
│ │ ├── 资料知识库/
│ │ ├── 资料列表/
│ │ ├── 产品详情/
│ │ ├── 计划书/
│ │ ├── 我的/
│ │ ├── 我的收藏/
│ │ ├── 修改头像/
│ │ ├── 意见反馈/
│ │ └── 帮助中心/
│ └── 录入计划书/
│ ├── 方案A/
│ └── 方案B/
│
└── mcp/ # MCP 相关文档
├── MCP_配置测试指南.md
└── 如何切换到独立Apifox项目.md
```
## 📝 文档说明
### 顶层文档（核心文档）
| 文件 | 说明 |
|------|------|
| `README.md` | 文档总索引，快速了解项目文档结构 |
| `CHANGELOG.md` | 项目变更日志，记录所有功能、修复和优化 |
| `lessons-learned.md` | 开发经验教训，包含最佳实践和常见陷阱 |
### decisions/ - 技术决策记录
记录项目中的重要技术决策和设计权衡。
### plan/ - 开发计划
存放各种开发计划文档，包括整体计划和调整版计划。
### guides/ - 指南文档
开发过程中使用的各种指南文档，帮助开发者快速上手。
### reports/ - 问题修复与实施报告
记录问题修复过程、实施总结和测试报告。
### design/ - UI/UX 设计文档
存放 UI/UX 设计稿和生成的代码。
### mcp/ - MCP 相关文档
MCP (Model Context Protocol) 相关配置和测试指南。
## 🔍 快速查找
- **我是新开发者，想快速上手** → 阅读 `guides/START_HERE.md`
- **我想了解项目的历史变更** → 查看 `CHANGELOG.md`
- **我遇到了开发问题** → 查看 `lessons-learned.md` 和 `reports/`
- **我需要添加新功能** → 先查看 `decisions/` 了解技术决策
- **我需要修改 UI** → 查看 `design/` 中的设计稿
---
**整理日期**: 2026-02-02
......@@ -6,86 +6,152 @@
```
docs/
├── CHANGELOG.md # 项目更新日志（保持不变）
├── README.md # 本文件
├── CHANGELOG.md # 项目变更日志（核心文档）
├── README.md # 本文件（文档导航索引）
├── lessons-learned.md # 经验教训总结（核心文档）
├── api-integration-log.md # API 联调日志
│
├── guides/ # 📘 使用指南和教程
│ ├── START_HERE.md # 从这里开始
│ ├── OPENAPI_TO_API_GUIDE.md # OpenAPI 转 API 详细指南
│ ├── GET_VS_POST_GUIDE.md # GET vs POST 请求处理指南
│ ├── JSDOC_GENERATION_GUIDE.md # JSDoc 注释生成指南
│ └── API_USAGE_EXAMPLES.md # API 使用示例
├── guides/ # 📘 使用指南和教程
│ ├── START_HERE.md # 新人入门指南
│ ├── API_USAGE_EXAMPLES.md # API 使用示例
│ ├── API_DIFF_GUIDE.md # API 差异指南
│ ├── GET_VS_POST_GUIDE.md # GET vs POST 指南
│ ├── OPENAPI_TO_API_GUIDE.md # OpenAPI 转 API 指南
│ ├── JSDOC_GENERATION_GUIDE.md # JSDoc 生成指南
│ ├── SESSIONID_MANAGEMENT.md # SessionID 管理指南
│ ├── auth-debug-guide.md # 认证调试指南
│ ├── TARO_QUICK_REFERENCE.md # Taro 开发速查表
│ ├── apifox-integration-guide.md # Apifox 集成指南
│ ├── changelog-check-guide.md # CHANGELOG 检查指南
│ └── 腾讯元宝AI接入说明.md # 腾讯元宝 AI 接入说明
│
├── reports/ # 📊 实现报告和文档
│ ├── IMPLEMENTATION_SUMMARY.md # 技术实现总结
│ ├── COMPLETION_REPORT.md # 功能完成报告
│ ├── FINAL_FIX_REPORT.md # 修复完成报告
│ ├── GET_POST_FIX.md # 修复说明文档
│ └── UPDATE_LOG.md # 功能更新日志
├── reports/ # 📊 问题修复与实施报告
│ ├── IMPLEMENTATION_SUMMARY.md # 实施总结
│ ├── COMPLETION_REPORT.md # 完成报告
│ ├── FINAL_FIX_REPORT.md # 最终修复报告
│ ├── GET_POST_FIX.md # GET/POST 修复
│ ├── RENAME_TEST_REPORT.md # 重命名测试报告
│ ├── apifox-setup-summary.md # Apifox 设置总结
│ ├── changelog-check-report-20260201.md # CHANGELOG 检查报告
│ ├── changes-summary.md # 变更总结
│ ├── DOCUMENT_ICONS_UPDATE.md # 文档图标更新
│ ├── search-fix-summary.md # 搜索修复总结
│ └── search-problems-analysis.md # 搜索问题分析
│
├── api-specs/ # 📝 API 规范文档源文件
│ ├── user/ # 用户模块
│ └── order/ # 订单模块
├── api-specs/ # 📝 API 规范文档
│ ├── api-integration-log-template.md # API 联调日志模板
│ ├── user/ # 用户模块接口
│ ├── file/ # 文件模块接口
│ ├── get_product/ # 产品模块接口
│ ├── news/ # 新闻模块接口
│ └── wechat/ # 微信模块接口
│
├── Design/ # 🎨 设计文档
├── PLAN/ # 📋 项目计划
├── PreDocs/ # 📄 预留文档
└── TODO/ # ✅ 待办事项
├── decisions/ # 📋 技术决策记录
│ └── decisions.md
│
├── plan/ # 📋 开发计划
│ ├── 项目开发计划.md
│ ├── 前端开发计划.md
│ └── 前端开发计划-调整版.md
│
├── design/ # 🎨 UI/UX 设计文档
│ └── manulife-V1/
│ ├── done/ # 已完成的设计稿
│ └── 录入计划书/ # 计划书设计稿
│
├── features/ # ⭐ 功能文档
│ └── feedback-system/
│
├── specs/ # 📄 规范文档
│
├── mcp/ # 🤖 MCP 相关文档
│ ├── MCP_配置测试指南.md
│ └── 如何切换到独立Apifox项目.md
│
└── PreDocs/ # 📂 前期项目文档
└── 臻奇智荟圈小程序项目需求20260123a.docx
```
## 🚀 快速导航
### 核心文档
- 📖 [项目变更日志](CHANGELOG.md) - 所有功能、修复和优化的记录
- 📖 [经验教训总结](lessons-learned.md) - 开发中的最佳实践和常见陷阱
- 📖 [API 联调日志](api-integration-log.md) - 接口联调状态记录
### 新手入门
👉 **[guides/START_HERE.md](guides/START_HERE.md)** - 快速了解项目功能
### 使用指南
### 开发指南
- 📘 [Taro 开发速查表](guides/TARO_QUICK_REFERENCE.md) - Taro API 快速查阅
- 📘 [OpenAPI 转 API 详细指南](guides/OPENAPI_TO_API_GUIDE.md) - 完整功能说明
- 📘 [GET vs POST 请求处理指南](guides/GET_VS_POST_GUIDE.md) - 参数处理详解
- 📘 [JSDoc 注释生成指南](guides/JSDOC_GENERATION_GUIDE.md) - 注释生成规则
- 📘 [API 使用示例](guides/API_USAGE_EXAMPLES.md) - 实际使用案例
- 📘 [SessionID 管理指南](guides/SESSIONID_MANAGEMENT.md) - 认证会话管理
- 📘 [认证调试指南](guides/auth-debug-guide.md) - 授权流程调试
### 技术文档
- 📊 [技术实现总结](reports/IMPLEMENTATION_SUMMARY.md) - 实现细节
- 📊 [功能完成报告](reports/COMPLETION_REPORT.md) - 完成情况
- 📊 [修复完成报告](reports/FINAL_FIX_REPORT.md) - 问题修复
- 📊 [功能更新日志](reports/UPDATE_LOG.md) - 版本更新
### 设计文档
- 🎨 [UI/UX 设计稿](design/manulife-V1/done/) - 各页面设计稿
## 📖 文档分类说明
### 📘 guides/ - 使用指南
包含面向用户的使用教程和指南文档：
- 快速开始指南
- 功能详细说明
- 参数处理规则
- 代码使用示例
包含面向开发者的教程和指南文档：
- 新人入门指南
- Taro 开发速查
- API 使用指南
- 认证流程调试
- 工具使用说明
### 📊 reports/ - 技术报告
包含面向开发者的技术实现文档：
记录开发过程中的问题修复和实施总结：
- 实现总结
- 完成报告
- 修复说明
- 更新日志
- 测试报告
### 📝 api-specs/ - API 规范文档
OpenAPI 规范的 Markdown 文档和联调日志模板：
- 各模块接口定义
- 联调日志模板
### 📝 api-specs/ - API 规范文档源文件
OpenAPI 规范的 Markdown 文档，用于生成 API 代码：
- user/ - 用户模块接口
- order/ - 订单模块接口
### 🎨 design/ - 设计文档
UI/UX 设计稿和生成的代码：
- 已完成的设计稿
- 计划书设计稿
### 📋 decisions/ - 技术决策
记录项目中的重要技术决策和设计权衡。
### 📋 plan/ - 开发计划
存放各种开发计划文档。
## 🎯 使用建议
### 如果你是新手
### 如果你是新开发者
1. 先看 [guides/START_HERE.md](guides/START_HERE.md)
2. 阅读 [guides/OPENAPI_TO_API_GUIDE.md](guides/OPENAPI_TO_API_GUIDE.md)
3. 参考 [guides/API_USAGE_EXAMPLES.md](guides/API_USAGE_EXAMPLES.md)
2. 阅读 [lessons-learned.md](lessons-learned.md) 了解经验教训
3. 查看 [TARO_QUICK_REFERENCE.md](guides/TARO_QUICK_REFERENCE.md) 快速查阅 API
### 如果你想了解实现
1. 查看 [reports/IMPLEMENTATION_SUMMARY.md](reports/IMPLEMENTATION_SUMMARY.md)
2. 阅读 [reports/FINAL_FIX_REPORT.md](reports/FINAL_FIX_REPORT.md)
3. 浏览 [CHANGELOG.md](CHANGELOG.md) 了解历史变更
### 如果你想生成 API
1. 在 `api-specs/` 目录下创建文档
2. 运行 `pnpm api:generate`
3. 查看生成的文件
2. 参考 [api-integration-log-template.md](api-specs/api-integration-log-template.md) 记录联调日志
3. 运行 `pnpm api:generate`
### 如果你需要调试认证
1. 阅读 [guides/auth-debug-guide.md](guides/auth-debug-guide.md)
2. 参考 [guides/SESSIONID_MANAGEMENT.md](guides/SESSIONID_MANAGEMENT.md)
## 📝 维护说明
......@@ -96,9 +162,9 @@ OpenAPI 规范的 Markdown 文档，用于生成 API 代码：
放到 `reports/` 目录，并在本 README 中添加说明。
### 更新日志
- 项目级别的更新：修改根目录的 `CHANGELOG.md`
- 功能级别的更新：修改 `reports/UPDATE_LOG.md`
- 项目级别的更新：修改 `CHANGELOG.md`
- API 联调记录：修改 `api-integration-log.md`
---
**最后更新**: 2026-01-27
**最后更新**: 2026-02-05
......