Hooke / manulife-weapp

Go to a project
Toggle navigation Toggle navigation pinning
hookehuyr
fda2fa22 1 parent 8f244d12

docs(auth): 完善认证调试指南和计划书文档 

- 更新认证调试指南，添加会话管理说明
- 完善计划书相关文档
- 更新项目 README 和快速开始文档
- 优化项目文档结构
Inline Side-by-side
Showing 10 changed files with 291 additions and 360 deletions
......@@ -76,7 +76,7 @@ export const submitFormAPI = (params) => {
export default {
pages: [
'pages/index/index', // 首页
'pages/auth/index', // 认证页（必须保留）
'pages/login/index', // 登录页（必须保留）
'pages/your-page/index', // 🔧 添加您的页面
],
tabBar: {
......@@ -120,9 +120,9 @@ pnpm dev:h5
- **静默认证**：应用启动时自动执行
- **401 自动刷新**：接口返回 401 时自动刷新会话
- **授权页回跳**：认证完成后自动返回原页面
- **登录页回跳**：登录完成后自动返回原页面
**重要**：后端需提供 `/srv/?a=openid_wxapp` 接口
**重要**：后端需提供 `/srv/?a=openid` 接口
### 🌐 网络请求
......@@ -203,7 +203,7 @@ export const useUserStore = defineStore('user', {
### Q: 认证流程不工作？
1. 检查后端 `/srv/?a=openid_wxapp` 接口是否正常
1. 检查后端 `/srv/?a=openid` 接口是否正常
2. 检查 `src/utils/config.js` 中的 `BASE_URL` 是否正确
3. 查看微信开发者工具控制台错误信息
......
......@@ -6,6 +6,7 @@
- **[经验教训总结](docs/lessons-learned.md)** - Taro 项目开发经验、最佳实践和常见陷阱
- **[CLAUDE.md](CLAUDE.md)** - 项目开发指南（供 Claude Code 使用）
- **[文档导航](docs/README.md)** - 项目文档索引与使用建议
## 🚀 快速开始
......@@ -44,6 +45,8 @@ pnpm lint
- ✅ **样式方案** - TailwindCSS(80%) + Less(20%) 混合使用
- ✅ **组件复用** - "第 3 次出现原则"抽取 Composables
- ✅ **可复用组件** - TabBar、NavHeader、IconFont
- ✅ **文档预览能力** - DocumentPreview 支持多格式文件预览
- ✅ **统一列表交互** - 搜索、收藏、资料列表统一点击与操作逻辑
## 🆕 最新更新（2026-02-14）
......@@ -52,6 +55,11 @@ pnpm lint
- ✅ **文档同步** - 更新提取计划相关文档字段示例
- ✅ **优化建议** - 提取计划相关字段命名保持“功能优先”的语义一致性
### 文档对齐
- ✅ **业务模块更新** - README 页面清单与业务模块对齐现有路由
- ✅ **新人指南更新** - 入口文档从工具生成器调整为业务上手流程
- ✅ **文档导航同步** - docs/README 快速导航修正与补充
## 🆕 最新更新（2026-02-13）
### 权限与测试
......@@ -130,46 +138,43 @@ pnpm lint
```
src/
├── api/ # API 接口层
│ ├── index.js # 业务接口定义
│ └── fn.js # HTTP 请求封装
├── assets/ # 静态资源
│ ├── images/ # 图片资源
│ └── styles/ # 全局样式
├── components/ # 通用组件
│ ├── IconFont.vue # 图标字体组件
│ ├── NavHeader.vue # 自定义导航头
│ ├── TabBar.vue # 底部导航栏
│ ├── SectionCard.vue # 分组卡片组件
│ ├── FilterTabs.vue # 筛选标签组件
│ ├── PosterBuilder/ # 海报生成器（可选）
│ └── PlanSchemes/ # 计划书方案组件
├── composables/ # Composition API hooks
│ ├── useSectionList.js # 分组列表管理
│ ├── useFileOperation.js # 文件操作（下载、预览）
│ └── useListItemClick.js # 列表点击处理
├── hooks/ # 自定义 hooks
│ └── useGo.js # 增强导航 hook
│ ├── cards/ # 卡片组件
│ ├── documents/ # 文档预览组件
│ ├── forms/ # 表单组件
│ ├── icons/ # 图标组件
│ ├── list/ # 列表组件
│ ├── navigation/ # 导航组件
│ └── plan/ # 计划书相关组件
├── composables/ # 组合式函数
├── config/ # 功能与权限配置
├── hooks/ # hooks
├── pages/ # 页面组件
│ ├── index/ # 首页
│ ├── auth/ # 认证页（必须保留）
│ ├── login/ # 登录页
│ ├── product-center/ # 产品中心
│ ├── product-detail/ # 产品详情
│ ├── category-list/ # 分类列表
│ ├── material-list/ # 资料列表
│ ├── knowledge-base/ # 知识库
│ ├── plan/ # 计划书
│ ├── week-hot-material/ # 周热门资料
│ ├── signing/ # 签单相关
│ ├── family-office/ # 家办业务
│ ├── plan/ # 计划书列表
│ ├── plan-submit-result/ # 计划书提交结果
│ ├── search/ # 搜索
│ ├── document-preview/ # 文档预览
│ ├── message/ # 消息列表
│ ├── message-detail/ # 消息详情
│ ├── feedback/ # 意见反馈
│ ├── feedback-list/ # 反馈列表
│ ├── favorites/ # 我的收藏
│ ├── mine/ # 我的
│ └── ...
├── stores/ # Pinia 状态管理
│ ├── router.js # 路由状态（认证回跳）
│ ├── main.js # 主 store
│ └── host.js # 配置 store
├── utils/ # 工具函数
│ ├── authRedirect.js # 认证流程核心（必须）
│ ├── request.js # HTTP 客户端核心（必须）
│ ├── config.js # 环境配置（⚠️ 需修改）
│ ├── tools.js # 通用工具
│ └── documentIcons.js # 文档图标工具
│ ├── avatar/ # 头像编辑
│ ├── help-center/ # 帮助中心
│ ├── login/ # 登录
│ ├── onboarding/ # 引导页
│ ├── video-player/ # 视频播放
│ └── webview/ # WebView 承载页
├── app.js # 应用入口
├── app.config.js # 页面路由配置
└── app.less # 全局样式
......@@ -177,17 +182,28 @@ src/
## 📄 页面说明
### 主要页面
- **首页** - 产品展示、热门资料、导航入口
- **产品详情** - 完整产品信息展示
- **资料列表** - 培训材料和文档管理
- **知识库** - 培训材料和案例知识库
- **计划书** - 计划书列表和管理
- **我的收藏** - 收藏内容管理
- **我的** - 个人资料、功能菜单
### 主要业务页面
- **首页** - 导航入口、产品与资料推荐
- **产品中心** - 产品聚合展示与筛选
- **产品详情** - 产品信息与附件预览入口
- **分类列表/资料列表** - 分类浏览与资料列表
- **周热门资料** - 热门资料聚合列表
- **签单相关** - 业务签单资料入口
- **家办业务** - 家办相关资料入口
- **计划书** - 计划书列表、状态展示
- **计划书提交结果** - 提交完成提示与下一步引导
- **搜索** - 全局搜索与结果分类
### 辅助与管理页面
- **消息列表/消息详情** - 消息通知与计划书状态查看
- **文档预览/视频播放** - 文件预览与播放
- **意见反馈/反馈列表** - 反馈提交与历史查看
- **我的/头像/帮助中心** - 个人信息与常用入口
- **登录/引导页** - 认证与首次引导
- **WebView** - 承载外部 H5 内容
### 页面特性
- ✅ 顶部筛选固定，列表独立滚动
- ✅ 列表页顶部筛选固定，列表独立滚动
- ✅ 统一的导航头（NavHeader）和底部导航（TabBar）
- ✅ 统一的文件操作逻辑（下载、预览）
- ✅ 统一的列表点击处理
......@@ -227,7 +243,7 @@ export const yourAPI = (params) => {
export default {
pages: [
'pages/index/index',
'pages/auth/index',
'pages/login/index',
'pages/your-page/index', // 添加您的页面
],
}
......@@ -246,13 +262,13 @@ export default {
1. **静默认证**：应用启动时自动执行
2. **401 自动刷新**：接口返回 401 时自动刷新会话
3. **授权页回跳**：认证完成后自动跳转回原页面
3. **登录页回跳**：登录完成后自动跳转回原页面
**核心文件**：
- `src/utils/authRedirect.js` - 认证流程管理
- `src/utils/request.js` - HTTP 请求拦截器
**重要**：后端需提供 `/srv/?a=openid_wxapp` 接口用于微信登录。
**重要**：后端需提供 `/srv/?a=openid` 接口用于微信登录。
## 📦 技术栈
......@@ -327,8 +343,15 @@ export default {
2. 请求超时默认 5 秒，可在 `src/utils/request.js` 中修改
3. NutUI 组件已配置自动导入，无需手动引入
4. TailwindCSS 已禁用 preflight，避免与小程序样式冲突
5. 认证失败会自动跳转到 `/pages/auth/index`
5. 认证失败会自动跳转到 `/pages/login/index`
6. **所有函数必须有 JSDoc 注释** - 详见 `~/.claude/rules/code-commenting.md`
7. 业务路由以 `src/app.config.js` 为准，计划类文档仅保留历史记录
## ✅ 优化建议
1. 持续维护 API 集成日志与页面模块对应关系
2. 文档预览与视频播放页面补充更多异常场景说明
3. 页面入口与权限策略保持同步，避免入口显示但权限不一致
## 📄 License
......
## [2026-02-14] - 文档对齐与业务说明更新
### 更新
- 同步 README 的业务模块与页面清单
- 修正文档导航中的 API 联调日志入口
- 重写新人入门指南为业务与路由上手文档
- 对齐登录页路径说明与认证调试文档
- 更新前端开发计划中的当前路由与模块概览
- 对齐鉴权重构文档的登录页说明
- 标记项目开发计划与调整版为历史版本并补充当前业务说明
- README 补充路由与计划文档对齐说明
---
**详细信息**：
- **影响文件**: README.md, QUICKSTART.md, docs/README.md, docs/guides/新人入门指南.md, docs/guides/认证调试指南.md, docs/plan/前端开发计划.md, docs/plan/项目开发计划.md, docs/plan/前端开发计划-调整版.md, docs/specs/2026-02-02-auth-refactoring.md
- **技术栈**: 文档维护
- **测试状态**: 不适用
- **备注**: 与现有路由与页面模块保持一致
---
## [2026-02-14] - 提取方式字段重命名
### 变更
......
# 臻奇智荟圈小程序 - 前端开发计划（调整版）
## ⚠️ 当前说明
本计划为历史版本，当前业务与路由以 `src/app.config.js` 为准，AI 模块已改为外部配置，不再内置页面。
## 📋 项目概览
### 项目信息
......
......@@ -9,7 +9,7 @@
- **设计宽度**: 750px（自定义组件）/ 375px（NutUI组件）
### 开发目标
基于现有 Taro 4 + Vue 3 模板，开发服务保险团队内部同事的微信小程序，实现计划书生成、资料库管理、AI问答三大核心功能。
基于现有 Taro 4 + Vue 3 模板，开发服务保险团队内部同事的微信小程序，实现产品与资料浏览、计划书管理、搜索与消息通知、反馈闭环等核心能力。
---
......@@ -19,65 +19,46 @@
```
src/
├── api/ # API接口定义
│ ├── index.js # API入口
│ ├── fn.js # 请求包装器
│ ├── order.js # 订单相关API
│ ├── material.js # 资料库相关API
│ ├── ai.js # AI问答相关API
│ └── user.js # 用户相关API
│
├── api/ # API 接口层
├── assets/ # 静态资源
│ └── images/ # 图片资源
│
├── components/ # 公共组件
│ ├── page-container/ # 页面容器组件
│ ├── order-card/ # 订单卡片组件
│ ├── material-item/ # 资料列表项组件
│ ├── file-preview/ # 文件预览组件（PDF/视频/图片）
│ └── chat-message/ # 聊天消息组件
│
├── components/ # 通用组件
│ ├── cards/ # 卡片组件
│ ├── documents/ # 文档预览组件
│ ├── forms/ # 表单组件
│ ├── icons/ # 图标组件
│ ├── list/ # 列表组件
│ ├── navigation/ # 导航组件
│ └── plan/ # 计划书相关组件
├── composables/ # 组合式函数
│ ├── useAuth.js # 认证相关
│ ├── useRequest.js # 请求封装
│ └── useUpload.js # 文件上传
│
├── pages/ # 页面
│ ├── index/ # 首页（工作台）
│ ├── order/
│ │ ├── submit/ # 提交计划书申请
│ │ ├── list/ # 我的订单列表
│ │ └── detail/ # 订单详情
│ ├── material/
│ │ ├── index/ # 资料库首页
│ │ ├── list/ # 资料列表
│ │ ├── detail/ # 资料详情（PDF/视频预览）
│ │ └── search/ # 资料搜索
│ ├── ai/
│ │ └── chat/ # AI问答对话页面
│ ├── notifications/ # 消息通知列表
│ ├── profile/ # 个人中心
│ └── auth/ # 授权登录（已有）
│
├── stores/ # 状态管理
│ ├── main.js # 主Store
│ ├── router.js # 路由Store（已有）
│ ├── user.js # 用户信息Store
│ ├── order.js # 订单Store
│ └── material.js # 资料库Store
│
├── utils/ # 工具函数
│ ├── authRedirect.js # 认证跳转（已有）
│ ├── request.js # 请求封装（已有）
│ ├── tools.js # 工具函数（已有）
│ ├── config.js # 配置文件（已有）
│ ├── validate.js # 表单验证
│ └── format.js # 格式化工具
│
├── hooks/ # Hooks
│ └── useGo.js # 导航Hook（已有）
│
├── app.config.js # 应用配置（路由、tabBar等）
├── config/ # 功能与权限配置
├── hooks/ # hooks
├── pages/ # 页面组件
│ ├── index/ # 首页
│ ├── product-center/ # 产品中心
│ ├── product-detail/ # 产品详情
│ ├── category-list/ # 分类列表
│ ├── material-list/ # 资料列表
│ ├── week-hot-material/ # 周热门资料
│ ├── signing/ # 签单相关
│ ├── family-office/ # 家办业务
│ ├── plan/ # 计划书列表
│ ├── plan-submit-result/ # 计划书提交结果
│ ├── search/ # 搜索
│ ├── document-preview/ # 文档预览
│ ├── document-demo/ # 文档演示
│ ├── message/ # 消息列表
│ ├── message-detail/ # 消息详情
│ ├── feedback/ # 意见反馈
│ ├── feedback-list/ # 反馈列表
│ ├── favorites/ # 我的收藏
│ ├── mine/ # 我的
│ ├── avatar/ # 头像编辑
│ ├── help-center/ # 帮助中心
│ ├── login/ # 登录
│ ├── onboarding/ # 引导页
│ ├── video-player/ # 视频播放
│ └── webview/ # WebView 承载页
├── app.config.js # 页面路由配置
└── app.js # 应用入口
```
......@@ -85,60 +66,63 @@ src/
| 页面路径 | 页面名称 | 需要登录 | 说明 |
|---------|---------|---------|------|
| /pages/index/index | 首页/工作台 | ✅ | 展示快捷入口、待处理订单、最新资料 |
| /pages/order/submit | 提交计划书申请 | ✅ | 表单提交页面 |
| /pages/order/list | 我的订单 | ✅ | 订单列表（按状态筛选） |
| /pages/order/detail | 订单详情 | ✅ | 查看订单详情、PDF预览、海报查看 |
| /pages/material/index | 资料库首页 | ✅ | 分类导航、热门资料 |
| /pages/material/list | 资料列表 | ✅ | 按分类查看资料 |
| /pages/material/detail | 资料详情 | ✅ | PDF/视频/图片预览（禁止下载） |
| /pages/material/search | 资料搜索 | ✅ | 搜索资料 |
| /pages/ai/chat | AI问答 | ✅ | 对话式AI交互 |
| /pages/notifications | 消息通知 | ✅ | 系统消息列表 |
| /pages/profile | 个人中心 | ✅ | 用户信息、设置 |
| /pages/auth/index | 授权登录 | ❌ | 微信登录（已有） |
| /pages/index/index | 首页 | ✅ | 导航入口、产品与资料推荐 |
| /pages/search/index | 搜索 | ✅ | 全局搜索与分类结果 |
| /pages/webview/index | WebView | ✅ | 承载外部 H5 |
| /pages/document-preview/index | 文档预览 | ✅ | PDF/Office 预览 |
| /pages/document-demo/index | 文档演示 | ✅ | 预览演示页面 |
| /pages/onboarding/index | 引导页 | ❌ | 首次引导 |
| /pages/family-office/index | 家办业务 | ✅ | 家办资料入口 |
| /pages/product-center/index | 产品中心 | ✅ | 产品聚合与筛选 |
| /pages/product-detail/index | 产品详情 | ✅ | 产品信息与附件 |
| /pages/category-list/index | 分类列表 | ✅ | 分类聚合列表 |
| /pages/material-list/index | 资料列表 | ✅ | 分类资料列表 |
| /pages/week-hot-material/index | 周热门资料 | ✅ | 热门资料聚合 |
| /pages/signing/index | 签单相关 | ✅ | 签单资料入口 |
| /pages/mine/index | 我的 | ✅ | 个人入口 |
| /pages/plan/index | 计划书 | ✅ | 计划书列表 |
| /pages/plan-submit-result/index | 计划书提交结果 | ✅ | 提交完成与引导 |
| /pages/favorites/index | 收藏 | ✅ | 收藏管理 |
| /pages/avatar/index | 头像编辑 | ✅ | 头像与信息编辑 |
| /pages/feedback-list/index | 反馈列表 | ✅ | 历史反馈 |
| /pages/feedback/index | 意见反馈 | ✅ | 反馈提交 |
| /pages/login/index | 登录 | ❌ | 登录与回跳 |
| /pages/help-center/index | 帮助中心 | ✅ | 常见问题与入口 |
| /pages/message/index | 消息列表 | ✅ | 消息通知 |
| /pages/message-detail/index | 消息详情 | ✅ | 消息详情与计划书状态 |
| /pages/video-player/index | 视频播放 | ✅ | 视频播放页面 |
### TabBar 配置
```javascript
// app.config.js
tabBar: {
color: '#999999',
selectedColor: '#007AFF',
backgroundColor: '#ffffff',
borderStyle: 'black',
list: [
{
pagePath: 'pages/index/index',
text: '工作台',
iconPath: 'assets/images/tab-home.png',
selectedIconPath: 'assets/images/tab-home-active.png'
},
{
pagePath: 'pages/material/index/index',
text: '资料库',
iconPath: 'assets/images/tab-material.png',
selectedIconPath: 'assets/images/tab-material-active.png'
},
{
pagePath: 'pages/ai/chat/index',
text: 'AI助手',
iconPath: 'assets/images/tab-ai.png',
selectedIconPath: 'assets/images/tab-ai-active.png'
},
{
pagePath: 'pages/profile/index',
text: '我的',
iconPath: 'assets/images/tab-profile.png',
selectedIconPath: 'assets/images/tab-profile-active.png'
}
]
}
```
当前采用自定义 TabBar 组件（`src/components/navigation/TabBar.vue`），原生 `tabBar` 未启用，路由以 `app.config.js` 为准。
---
## 📱 核心功能模块设计
## ✅ 当前功能模块概览
### 模块1：产品与资料
- 产品中心、产品详情、分类列表、资料列表、周热门资料、签单相关、家办业务
- 文档预览与视频播放作为统一内容承载页面
### 模块2：计划书流程
- 计划书列表与状态展示
- 提交结果页与消息详情联动
### 模块3：搜索与消息
- 搜索结果统一入口
- 消息列表与详情承载计划书状态更新
### 模块4：个人中心与反馈
- 我的、收藏、头像、帮助中心
- 反馈提交与反馈历史列表
---
---
## 🗃️ 历史规划（已停用）
以下内容为历史规划记录，已与当前业务实现不一致，阅读时请以“当前功能模块概览”和 `app.config.js` 为准。
### 模块1：计划书生成模块
......
......@@ -12,18 +12,31 @@
### 项目定位
服务保险团队内部同事的轻量化微信小程序，核心解决三大痛点：
1. 计划书快速生成+状态实时反馈
2. 沉淀内部培训、服务资料，打造专属知识库
3. AI智能问答功能
1. 计划书管理与状态实时反馈
2. 产品与资料沉淀、统一检索与消息通知
3. 反馈闭环与个人中心能力
### 核心技术决策
- **不对接保险公司官方API**：规避高成本、高门槛问题
- **采用半人工方式**：前端提交+后台人工协同的低成本落地方案
- **AI功能**：采用腾讯元宝AI，建立团队私有的知识库
- **AI能力**：采用腾讯元宝AI进行外部配置，不在小程序内置页面
---
## 🎯 需求分析
## ✅ 当前业务概览
### 核心模块
1. 产品与资料：产品中心、资料分类、周热门、签单与家办入口
2. 计划书：计划书列表、提交结果与消息联动
3. 搜索与消息：全局搜索、消息列表与详情
4. 个人中心与反馈：我的、收藏、头像、帮助中心、意见反馈
### 当前路由基准
以 `src/app.config.js` 为准，涉及页面包含首页、搜索、文档预览、文档演示、产品中心、计划书、消息、反馈、登录等。
---
## 🗃️ 历史需求分析（已停用）
### 一、核心功能模块
......@@ -108,7 +121,7 @@
| 数据库 | 存储订单、用户、资料数据 | MySQL / PostgreSQL |
| 文件存储 | PDF、培训资料、海报、视频 | 七牛云私有云存储 |
| CDN加速 | 视频、图片加速 | 七牛云CDN |
| AI服务 | 智能问答 | 腾讯元宝AI |
| AI服务 | 外部知识库配置 | 腾讯元宝AI（外部配置） |
| 即时通讯 | 消息推送 | 微信小程序订阅消息 |
### 系统架构图
......@@ -117,7 +130,7 @@
┌─────────────────────────────────────────────────────────────┐
│ 微信小程序前端 │
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ │
│ │计划书生成 │ │ 资料库 │ │ AI问答 │ │ 个人中心 │ │
│ │计划书流程 │ │ 资料中心 │ │ 搜索消息 │ │ 个人中心 │ │
│ └───────────┘ └───────────┘ └───────────┘ └───────────┘ │
└─────────────────────────────────────────────────────────────┘
↕ HTTPS
......@@ -252,7 +265,7 @@ CREATE TABLE operation_logs (
---
## 📅 开发计划与里程碑
## 🗓️ 历史开发计划与里程碑（已停用）
### 总体时间规划
- **项目启动**: 2026-01-20
......
......@@ -83,10 +83,10 @@ docs/
### 核心文档
- 📖 [项目变更日志](CHANGELOG.md) - 所有功能、修复和优化的记录
- 📖 [经验教训总结](lessons-learned.md) - 开发中的最佳实践和常见陷阱
- 📖 [API 联调日志](api-specs/API 集成日志.md) - 接口联调状态记录
- 📖 [API 联调日志](api-docs/API 集成日志.md) - 接口联调状态记录
### 新手入门
👉 **[guides/新人入门指南.md](guides/新人入门指南.md)** - 快速了解项目功能
👉 **[guides/新人入门指南.md](guides/新人入门指南.md)** - 快速了解业务与页面结构
### 开发指南
- 📘 [Taro 开发速查表](guides/Taro 开发速查表.md) - Taro API 快速查阅
......@@ -105,6 +105,9 @@ docs/
### 设计文档
- 🎨 [UI/UX 设计稿](design/manulife-V1/done/) - 各页面设计稿
### 业务规划
- 📋 [项目开发计划](plan/项目开发计划.md) - 业务规划与功能范围
## 📖 文档分类说明
### 📘 guides/ - 使用指南
......@@ -173,4 +176,4 @@ UI/UX 设计稿和生成的代码：
---
**最后更新**: 2026-02-05
**最后更新**: 2026-02-14
......
# 🎉 OpenAPI 转 API 文档生成器 - 完成报告
## ✅ 已完成的工作
### 1. 核心功能实现
- ✅ 自动化生成器脚本（`scripts/generateApiFromOpenAPI.js`）
- ✅ YAML 解析和验证
- ✅ 命名转换（驼峰命名、帕斯卡命名）
- ✅ 模块化组织生成
- ✅ 测试验证脚本
### 2. 示例和文档
- ✅ 3个 OpenAPI 文档示例（user、order 模块）
- ✅ 2个生成的 API 文件
- ✅ 完整的使用文档（4份指南）
- ✅ 演示页面（可直接访问查看效果）
### 3. 项目集成
- ✅ 添加到 `package.json` 的 npm 命令
- ✅ 添加路由配置
- ✅ 安装所需依赖（js-yaml）
## 🚀 立即开始使用
### 方式 1: 使用现有示例
# 新人入门指南
## 项目概览
Manulife WeApp（臻奇智荟圈）是面向内部同事的财富管理小程序，核心围绕产品信息、资料内容与计划书流程展开，支持文档预览、消息通知与反馈闭环。
## 业务模块
- **产品与资料**：产品中心、产品详情、分类列表、资料列表、周热门资料
- **业务场景**：签单相关、家办业务
- **计划书**：计划书列表、提交结果页
- **内容检索**：搜索页面统一入口
- **消息与反馈**：消息列表/详情、反馈提交/历史
- **个人中心**：我的、头像、帮助中心、收藏、登录/引导页
## 页面清单（与路由一致）
1. 首页：`pages/index/index`
2. 搜索：`pages/search/index`
3. WebView：`pages/webview/index`
4. 文档预览：`pages/document-preview/index`
5. 文档演示：`pages/document-demo/index`
6. 引导页：`pages/onboarding/index`
7. 家办业务：`pages/family-office/index`
8. 产品中心：`pages/product-center/index`
9. 产品详情：`pages/product-detail/index`
10. 分类列表：`pages/category-list/index`
11. 资料列表：`pages/material-list/index`
12. 周热门资料：`pages/week-hot-material/index`
13. 签单相关：`pages/signing/index`
14. 我的：`pages/mine/index`
15. 计划书：`pages/plan/index`
16. 计划书提交结果：`pages/plan-submit-result/index`
17. 收藏：`pages/favorites/index`
18. 头像编辑：`pages/avatar/index`
19. 反馈列表：`pages/feedback-list/index`
20. 意见反馈：`pages/feedback/index`
21. 登录：`pages/login/index`
22. 帮助中心：`pages/help-center/index`
23. 消息列表：`pages/message/index`
24. 消息详情：`pages/message-detail/index`
25. 视频播放：`pages/video-player/index`
## 本地开发
```bash
# 1. 查看生成的 API 文件
cat src/api/user.js
cat src/api/order.js
# 2. 启动开发服务器
pnpm install
pnpm dev:weapp
# 3. 访问演示页面
# 路径: pages/examples/api-demo/index
```
### 方式 2: 创建新的 API
```bash
# 1. 创建新模块
mkdir -p docs/api-specs/product
# 2. 创建接口文档
# 复制 docs/api-specs/user/getUserInfo.md 作为模板
# 修改其中的接口信息
# 3. 生成 API 文件
pnpm api:generate
# 4. 查看生成的文件
cat src/api/product.js
# 5. 在项目中使用
import { yourApiAPI } from '@/api/product';
```
## 📚 文档导航
### 快速开始
👉 **[README_API_GENERATOR.md](../README_API_GENERATOR.md)** - 项目总览和快速开始
### 详细指南
👉 **[QUICKSTART.md](../scripts/QUICKSTART.md)** - 5分钟快速上手
👉 **[OPENAPI_TO_API_GUIDE.md](./OPENAPI_TO_API_GUIDE.md)** - 完整功能说明
👉 **[API_USAGE_EXAMPLES.md](./API_USAGE_EXAMPLES.md)** - 实际使用案例
### 技术文档
👉 **[IMPLEMENTATION_SUMMARY.md](./IMPLEMENTATION_SUMMARY.md)** - 技术实现细节
## 🎯 核心命令
## 目录速览
```bash
# 生成 API 文件
pnpm api:generate
- `src/pages/`：业务页面
- `src/components/`：通用组件（文档预览、列表、导航、计划书组件等）
- `src/composables/`：组合式逻辑（权限、文件操作、列表、埋点等）
- `src/api/`：接口封装
- `docs/`：项目文档与流程说明
# 测试生成的文件
node scripts/test-generate.js
# 查看帮助
# 查看各文档文件
```
## 常用文档入口
## 📊 当前状态
- [文档导航](../README.md)
- [API 联调日志](../api-docs/API%20%E9%9B%86%E6%88%90%E6%97%A5%E5%BF%97.md)
- [经验教训总结](../lessons-learned.md)
- [DocumentPreview 组件文档](../../src/components/documents/DocumentPreview/README.md)
### 已测试的功能
- ✅ 单接口生成（user/getUserInfo）
- ✅ 批量接口生成（order/getList, order/getDetail）
- ✅ 多模块生成（user、order 两个模块）
- ✅ 文件格式验证
- ✅ 命名转换验证
## 常见任务
### 生成的文件统计
- **脚本**: 3个（生成器、测试、快速开始）
- **文档**: 4个（指南、示例、总结）
- **OpenAPI 示例**: 3个
- **生成的 API**: 2个模块
- **演示页面**: 1个
### 新增页面
## 💡 使用建议
### 1. 日常开发流程
```
修改接口 → 更新 OpenAPI 文档 → 运行生成命令 → 使用新 API
```
1. 在 `src/pages/` 新增页面目录与 `index.vue`
2. 在 `src/app.config.js` 添加路由
3. 如果需要复用布局，优先复用 `NavHeader` 与 `TabBar`
### 2. 团队协作
- 将 OpenAPI 文档作为单一数据源
- 定期运行 `pnpm api:generate` 同步
- 将生成的 API 文件提交到 Git
### 3. 版本管理
- OpenAPI 文档应该纳入版本控制
- 生成的 API 文件也应该提交
- 确保文档和代码同步更新
## 🔧 自定义和扩展
### 修改生成规则
编辑 `scripts/generateApiFromOpenAPI.js`:
```javascript
// 修改命名规则
function toCamelCase(str) { /* 你的规则 */ }
// 修改生成模板
function generateApiFileContent(moduleName, apis) { /* 你的模板 */ }
```
### 添加新功能
- TypeScript 类型定义生成
- Mock 数据生成
- Watch 模式自动重新生成
- 可视化配置界面
## 📞 遇到问题？
### 常见问题
1. **生成失败** → 检查 YAML 格式是否正确
2. **导入错误** → 确认文件路径是否正确
3. **命名不符合预期** → 修改 OpenAPI 文档文件名
### 调试技巧
```bash
# 运行测试脚本
node scripts/test-generate.js
# 查看生成的文件
cat src/api/your-module.js
# 查看错误日志
pnpm api:generate
```
## 🎉 下一步
### 推荐学习路径
1. **了解概览** → 阅读 README_API_GENERATOR.md
2. **快速上手** → 跟随 QUICKSTART.md 操作
3. **深入学习** → 查看 OPENAPI_TO_API_GUIDE.md
4. **实践应用** → 参考 API_USAGE_EXAMPLES.md
### 实际应用
- 在项目中创建新的 OpenAPI 文档
- 运行生成命令创建 API
- 在页面中使用生成的 API
- 享受自动化的便利！
## 📦 文件清单
```
✅ scripts/generateApiFromOpenAPI.js - 核心生成器
✅ scripts/test-generate.js - 测试脚本
✅ scripts/QUICKSTART.md - 快速开始
✅ docs/api-specs/user/getUserInfo.md - 用户接口示例
✅ docs/api-specs/order/getList.md - 订单列表示例
✅ docs/api-specs/order/getDetail.md - 订单详情示例
✅ docs/OPENAPI_TO_API_GUIDE.md - 详细指南
✅ docs/API_USAGE_EXAMPLES.md - 使用示例
✅ docs/IMPLEMENTATION_SUMMARY.md - 实现总结
✅ src/api/user.js - 用户 API（生成）
✅ src/api/order.js - 订单 API（生成）
✅ src/pages/examples/api-demo/index.vue - 演示页面
✅ package.json - 已添加 api:generate 命令
✅ src/app.config.js - 已添加演示页面路由
```
### 联调接口
## 🌟 总结
1. 在 `docs/api-specs/` 更新接口文档
2. 在 `docs/api-docs/API 集成日志.md` 记录联调状态
3. 在 `src/api/` 添加对应接口封装
你现在拥有一个完整的 OpenAPI 转 API 文档生成器！
## 新人第一天建议
**核心价值**：
- ⚡ **提高效率** - 自动化生成，节省时间
- ✅ **减少错误** - 避免手动编写的不一致
1. 先通读 [README](../../README.md) 与本指南
2. 阅读页面路由与业务模块对照表
3. 打开首页、产品中心、计划书、消息模块熟悉主流程
- 📦 **标准化** - 统一的代码格式
- 🔧 **易维护** - 单一数据源，易于更新
......
......@@ -102,24 +102,24 @@ pnpm dev:weapp
- [ ] 原始请求自动重放成功
- [ ] 新的 sessionid 已保存
#### 测试点 4: 授权页跳转（降级方案）
#### 测试点 4: 登录页跳转（降级方案）
**操作**：
1. 模拟授权失败（修改接口返回错误）
2. 观察是否跳转到授权页
2. 观察是否跳转到登录页
**预期结果**：
```
✅ 应该看到以下流程：
1. 授权失败
2. 保存当前页面路径
3. 跳转到 /pages/auth/index
4. 授权成功后回跳原页面
3. 跳转到 /pages/login/index
4. 登录成功后回跳原页面
```
**检查点**：
- [ ] 正确跳转到授权页
- [ ] 授权成功后回跳正确
- [ ] 正确跳转到登录页
- [ ] 登录成功后回跳正确
- [ ] 路径参数不丢失
## 📊 接口说明
......
......@@ -348,8 +348,6 @@ src/
│ └── wechat.js # 已存在：微信授权 API
│
├── pages/
│ ├── auth/
│ │ └── index.vue # 删除：不再需要单独的授权页
│ └── login/
│ └── index.vue # 保留：用户登录页（账号密码登录）
│
......@@ -736,7 +734,7 @@ function App(props) {
- 更新 401 响应处理
- [ ] 修改 `src/app.js` - 启动时检查登录状态
- [ ] 删除 `src/utils/authRedirect.js` - 移除旧的授权逻辑
- [ ] 删除 `src/pages/auth/index.vue` - 不再需要单独的授权页
- [ ] 确认不再需要单独的授权页（当前仅保留登录页）
### 第 3 步：更新登录页
......