hookehuyr

docs: 更新 CLAUDE.md 与项目实际结构保持一致

主要更新:
- 新增接口联调日志和变更日志的文档索引
- 更正身份认证流程说明(openid.js 替代不存在的 authRedirect.js)
- 删除不存在的 auth/index 页面
- 新增 3 个页面:plan-submit-result、feedback-list、test-tabs
- 新增 11 个组件:DocumentPreview、PdfPreview、OfficeViewer 等
- 新增 3 个工具函数:documentIcons.js、tools.js、openid.js
- 更新关键文件总结和会话管理说明

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Showing 1 changed file with 103 additions and 55 deletions
......@@ -5,6 +5,8 @@
## 📚 项目文档索引
- **[经验教训总结](docs/lessons-learned.md)** - Taro 项目开发经验、最佳实践和常见陷阱
- **[接口联调日志](docs/api-integration-log.md)** - API 集成状态和联调记录
- **[变更日志](docs/CHANGELOG.md)** - 项目版本更新历史
- **[项目 README](README.md)** - 项目概述和快速开始指南
## 🚀 开发命令
......@@ -84,22 +86,32 @@ pnpm dev:tt # 字节跳动小程序开发
### 2. 身份认证流程(必需)
项目具有完善的身份认证系统,支持自动会话管理。
项目具有完善的身份认证系统,支持静默认证和会话管理。
**核心文件**
- `src/utils/authRedirect.js` - 所有认证逻辑(静默刷新、导航、状态)
- `src/utils/openid.js` - 微信授权和会话管理
- `src/utils/request.js` - 带 401 自动刷新拦截器的 HTTP 客户端
- `src/pages/auth/index.vue` - 认证页(必须保留)
- `src/pages/login/index.vue` - 登录页
**401 自动刷新流程**
1. API 返回 401
2. 拦截器保存当前页面路径
3. 调用 `refreshSession()` 通过微信登录获取新会话
4. 使用新会话重试原始请求
5. 如果刷新失败,跳转到认证页
**重要**:后端必须提供 `/srv/?a=openid_wxapp` 端点用于微信登录。
**认证流程**
1. **静默认证**`miniProgramAuth()`):
- 调用 `wx.login()` 获取 code
- 调用后端 `/srv/?a=openid` 接口换取 sessionid
- 自动将 sessionid 写入 localStorage
- 尝试调用 `loginStatusAPI` 获取用户信息(如已登录)
2. **401 自动刷新**
- API 返回 401 时触发
- 拦截器保存当前页面路径
- 调用 `miniProgramAuth()` 重新获取会话
- 使用新会话重试原始请求
- 如果刷新失败,跳转到登录页
**重要**
- 后端必须提供 `/srv/?a=openid` 端点用于微信登录
- 后端必须提供 `loginStatusAPI` 接口用于检查登录状态
- sessionid 存储在 `localStorage.sessionid`
- sessionid 由请求拦截器自动注入到请求头的 `cookie` 字段
### 3. API 层架构
......@@ -193,50 +205,75 @@ src/pages/your-page/
### 当前页面
所有页面按 `src/app.config.js` 注册顺序排列:
**核心页面**
1. `pages/index/index` - 首页(产品展示、搜索、网格导航)
- 热门产品的"产品资料"按钮跳转到 `product-detail` 页面,带产品 ID
- 热门资料的"查看更多"跳转到 `material-list` 页面
- 网格导航图标跳转到各个业务页面
2. `pages/auth/index` - 认证页
3. `pages/login/index` - 登录页
2. `pages/search/index` - 产品和资料搜索页
3. `pages/webview/index` - 外部 URL 的 WebView 包装器
4. `pages/document-preview/index` - 文档预览页
5. `pages/document-demo/index` - 文档预览演示页
6. `pages/onboarding/index` - 新用户引导
**业务页面**
4. `pages/family-office/index` - 家族办公室服务
5. `pages/knowledge-base/index` - 知识库(培训材料、案例)
6. `pages/signing/index` - 签约
7. `pages/plan/index` - 业务计划管理
8. `pages/favorites/index` - 用户收藏
9. `pages/feedback/index` - 用户反馈
10. `pages/avatar/index` - 头像设置
11. `pages/mine/index` - 用户资料
**产品与内容页面**
12. `pages/product-detail/index` - 产品详情页
7. `pages/family-office/index` - 家族办公室服务
8. `pages/knowledge-base/index` - 知识库(培训材料、案例)
9. `pages/product-detail/index` - 产品详情页
- 通过 Taro 的 `useLoad` hook 接收 `id` 参数
- 导航示例:`go('/pages/product-detail/index', { id: 1 })`
- 参数可用于从 API 获取产品详情
13. `pages/material-list/index` - 资料/文档列表页
14. `pages/help-center/index` - 帮助中心和常见问题页
15. `pages/search/index` - 产品和资料搜索页
**工具页面**
16. `pages/onboarding/index` - 新用户引导
17. `pages/webview/index` - 外部 URL 的 WebView 包装器
18. `pages/document-demo/index` - 文档预览演示页
19. `pages/document-preview/index` - 文档预览页
10. `pages/material-list/index` - 资料/文档列表页
11. `pages/signing/index` - 签约
12. `pages/mine/index` - 用户资料
13. `pages/plan/index` - 业务计划管理
14. `pages/plan-submit-result/index` - 计划提交结果页
**用户相关页面**
15. `pages/favorites/index` - 用户收藏
16. `pages/avatar/index` - 头像设置
17. `pages/feedback-list/index` - 反馈列表
18. `pages/feedback/index` - 用户反馈
19. `pages/login/index` - 登录页
20. `pages/help-center/index` - 帮助中心和常见问题页
**开发测试页面**(仅开发环境):
- `pages/test-tabs/index` - 标签页测试
### 组件库
**可复用组件**
**导航与布局组件**
- `TabBar.vue` - 底部导航栏
- `NavHeader.vue` - 自定义导航头
- `IconFont.vue` - 图标字体包装器
- `indexNav.vue` - 首页网格导航
**功能组件**
**图标与媒体组件**
- `IconFont.vue` - 图标字体包装器
- `qrCode.vue` - 二维码显示
- `qrCodeSearch.vue` - 二维码扫描
- `PosterBuilder/` - 海报生成
**列表与展示组件**
- `SectionCard.vue` - 分组卡片组件
- `SectionItem.vue` - 分组列表项组件
- `ListItemActions/` - 列表项操作按钮
**表单与输入组件**
- `FilterTabs.vue` - 过滤标签组件
- `SearchBar.vue` - 搜索栏组件
**文档预览组件**
- `DocumentPreview/` - 文档预览组件
- `PdfPreview.vue` - PDF 预览组件
- `OfficeViewer.vue` - Office 文档查看器
**业务组件**
- `PlanSchemes/` - 计划方案组件(SchemeA, SchemeB)
- `PlanPopup/` - 计划弹窗组件
**工具组件**
- `PosterBuilder/` - 海报生成器
- `time-picker-data/` - 时间选择器数据
### 路径别名
......@@ -275,16 +312,14 @@ src/pages/your-page/
## 🔧 重要实现细节
### 会话管理
- 会话 ID 存储在 `localStorage` 中,键名为 `sessionid`
- 微信登录成功后由 `authRedirect.refreshSession()` 设置
-`request.js` 拦截器自动注入到请求头中
- 登出或显式手动操作时清除
### Promise 单例模式
认证系统使用 Promise 单例防止并发登录尝试:
- `authRedirect.js` 中的 `auth_promise` 确保一次只刷新一个
- 所有并发的 401 共享同一个刷新 Promise
- `.finally()` 确保无论成功/失败都执行清理
- **会话 ID 存储**`localStorage.sessionid`
- **静默登录**`openid.js``miniProgramAuth()` 函数
- 调用 `wx.login()` 获取 code
- 调用 `/srv/?a=openid` 接口换取 sessionid
- 自动写入 localStorage
- **请求注入**`request.js` 拦截器自动读取并注入到请求头的 `cookie` 字段
- **会话清除**:登出或 401 失败时清除
- **401 刷新**:拦截器捕获 401 → 调用 `miniProgramAuth()` → 重试原始请求
### 请求超时处理
- 默认超时:5 秒(`src/utils/request.js:79`
......@@ -479,7 +514,7 @@ store.setState('新值')
## 关键文件总结
### 修改前必须理解
1. **`src/utils/authRedirect.js`** - 完整的认证流程逻辑
1. **`src/utils/openid.js`** - 微信授权和会话管理逻辑
2. **`src/utils/request.js`** - 带拦截器的 HTTP 客户端
3. **`src/app.js`** - 应用启动序列和网络处理
4. **`src/utils/config.js`** - 服务器配置(需要修改)
......@@ -488,17 +523,30 @@ store.setState('新值')
1. **`src/api/index.js`** - API 定义
2. **`src/api/fn.js`** - 请求包装器
3. **`src/stores/main.js`** - 主要状态管理
4. **`src/stores/router.js`** - 认证回调的路由状态
4. **`src/stores/user.js`** - 用户状态管理
5. **`src/stores/router.js`** - 路由状态管理
### 认证与会话
1. **`src/utils/openid.js`** - `miniProgramAuth()` 静默登录
2. **`src/utils/request.js`** - 401 拦截器和 sessionid 管理
3. **`src/pages/login/index.vue`** - 登录页
### 可复用组件
1. **`src/components/TabBar.vue`** - 底部导航栏
2. **`src/components/NavHeader.vue`** - 自定义导航头
3. **`src/components/IconFont.vue`** - 图标包装器
### UI/UX 工具
1. **`src/utils/uiText.js`** - 集中式文案管理
2. **`src/utils/network.js`** - 网络状态工具
3. **`src/hooks/useGo.js`** - 增强导航 hook
3. **`src/components/SectionCard.vue`** - 分组卡片
4. **`src/components/DocumentPreview/`** - 文档预览
### Composables
1. **`src/composables/useSectionList.js`** - 分组列表管理
2. **`src/composables/useFileOperation.js`** - 文件操作
3. **`src/composables/useListItemClick.js`** - 列表点击处理
### 工具函数
1. **`src/utils/documentIcons.js`** - 文档类型图标识别
2. **`src/utils/tools.js`** - 通用工具函数集合
3. **`src/utils/network.js`** - 网络状态工具
4. **`src/hooks/useGo.js`** - 增强导航 hook
## 调试技巧
......