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 @@ ...@@ -5,6 +5,8 @@
5 ## 📚 项目文档索引 5 ## 📚 项目文档索引
6 6
7 - **[经验教训总结](docs/lessons-learned.md)** - Taro 项目开发经验、最佳实践和常见陷阱 7 - **[经验教训总结](docs/lessons-learned.md)** - Taro 项目开发经验、最佳实践和常见陷阱
8 +- **[接口联调日志](docs/api-integration-log.md)** - API 集成状态和联调记录
9 +- **[变更日志](docs/CHANGELOG.md)** - 项目版本更新历史
8 - **[项目 README](README.md)** - 项目概述和快速开始指南 10 - **[项目 README](README.md)** - 项目概述和快速开始指南
9 11
10 ## 🚀 开发命令 12 ## 🚀 开发命令
...@@ -84,22 +86,32 @@ pnpm dev:tt # 字节跳动小程序开发 ...@@ -84,22 +86,32 @@ pnpm dev:tt # 字节跳动小程序开发
84 86
85 ### 2. 身份认证流程(必需) 87 ### 2. 身份认证流程(必需)
86 88
87 -项目具有完善的身份认证系统,支持自动会话管理。 89 +项目具有完善的身份认证系统,支持静默认证和会话管理。
88 90
89 **核心文件** 91 **核心文件**
90 -- `src/utils/authRedirect.js` - 所有认证逻辑(静默刷新、导航、状态) 92 +- `src/utils/openid.js` - 微信授权和会话管理
91 - `src/utils/request.js` - 带 401 自动刷新拦截器的 HTTP 客户端 93 - `src/utils/request.js` - 带 401 自动刷新拦截器的 HTTP 客户端
92 -- `src/pages/auth/index.vue` - 认证页(必须保留)
93 - `src/pages/login/index.vue` - 登录页 94 - `src/pages/login/index.vue` - 登录页
94 95
95 -**401 自动刷新流程** 96 +**认证流程**
96 -1. API 返回 401 97 +1. **静默认证**`miniProgramAuth()`):
97 -2. 拦截器保存当前页面路径 98 + - 调用 `wx.login()` 获取 code
98 -3. 调用 `refreshSession()` 通过微信登录获取新会话 99 + - 调用后端 `/srv/?a=openid` 接口换取 sessionid
99 -4. 使用新会话重试原始请求 100 + - 自动将 sessionid 写入 localStorage
100 -5. 如果刷新失败,跳转到认证页 101 + - 尝试调用 `loginStatusAPI` 获取用户信息(如已登录)
101 - 102 +
102 -**重要**:后端必须提供 `/srv/?a=openid_wxapp` 端点用于微信登录。 103 +2. **401 自动刷新**
104 + - API 返回 401 时触发
105 + - 拦截器保存当前页面路径
106 + - 调用 `miniProgramAuth()` 重新获取会话
107 + - 使用新会话重试原始请求
108 + - 如果刷新失败,跳转到登录页
109 +
110 +**重要**
111 +- 后端必须提供 `/srv/?a=openid` 端点用于微信登录
112 +- 后端必须提供 `loginStatusAPI` 接口用于检查登录状态
113 +- sessionid 存储在 `localStorage.sessionid`
114 +- sessionid 由请求拦截器自动注入到请求头的 `cookie` 字段
103 115
104 ### 3. API 层架构 116 ### 3. API 层架构
105 117
...@@ -193,50 +205,75 @@ src/pages/your-page/ ...@@ -193,50 +205,75 @@ src/pages/your-page/
193 205
194 ### 当前页面 206 ### 当前页面
195 207
208 +所有页面按 `src/app.config.js` 注册顺序排列:
209 +
196 **核心页面** 210 **核心页面**
197 1. `pages/index/index` - 首页(产品展示、搜索、网格导航) 211 1. `pages/index/index` - 首页(产品展示、搜索、网格导航)
198 - 热门产品的"产品资料"按钮跳转到 `product-detail` 页面,带产品 ID 212 - 热门产品的"产品资料"按钮跳转到 `product-detail` 页面,带产品 ID
199 - 热门资料的"查看更多"跳转到 `material-list` 页面 213 - 热门资料的"查看更多"跳转到 `material-list` 页面
200 - 网格导航图标跳转到各个业务页面 214 - 网格导航图标跳转到各个业务页面
201 -2. `pages/auth/index` - 认证页 215 +2. `pages/search/index` - 产品和资料搜索页
202 -3. `pages/login/index` - 登录页 216 +3. `pages/webview/index` - 外部 URL 的 WebView 包装器
217 +4. `pages/document-preview/index` - 文档预览页
218 +5. `pages/document-demo/index` - 文档预览演示页
219 +6. `pages/onboarding/index` - 新用户引导
203 220
204 **业务页面** 221 **业务页面**
205 -4. `pages/family-office/index` - 家族办公室服务 222 +7. `pages/family-office/index` - 家族办公室服务
206 -5. `pages/knowledge-base/index` - 知识库(培训材料、案例) 223 +8. `pages/knowledge-base/index` - 知识库(培训材料、案例)
207 -6. `pages/signing/index` - 签约 224 +9. `pages/product-detail/index` - 产品详情页
208 -7. `pages/plan/index` - 业务计划管理
209 -8. `pages/favorites/index` - 用户收藏
210 -9. `pages/feedback/index` - 用户反馈
211 -10. `pages/avatar/index` - 头像设置
212 -11. `pages/mine/index` - 用户资料
213 -
214 -**产品与内容页面**
215 -12. `pages/product-detail/index` - 产品详情页
216 - 通过 Taro 的 `useLoad` hook 接收 `id` 参数 225 - 通过 Taro 的 `useLoad` hook 接收 `id` 参数
217 - 导航示例:`go('/pages/product-detail/index', { id: 1 })` 226 - 导航示例:`go('/pages/product-detail/index', { id: 1 })`
218 - 参数可用于从 API 获取产品详情 227 - 参数可用于从 API 获取产品详情
219 -13. `pages/material-list/index` - 资料/文档列表页 228 +10. `pages/material-list/index` - 资料/文档列表页
220 -14. `pages/help-center/index` - 帮助中心和常见问题页 229 +11. `pages/signing/index` - 签约
221 -15. `pages/search/index` - 产品和资料搜索页 230 +12. `pages/mine/index` - 用户资料
222 - 231 +13. `pages/plan/index` - 业务计划管理
223 -**工具页面** 232 +14. `pages/plan-submit-result/index` - 计划提交结果页
224 -16. `pages/onboarding/index` - 新用户引导 233 +
225 -17. `pages/webview/index` - 外部 URL 的 WebView 包装器 234 +**用户相关页面**
226 -18. `pages/document-demo/index` - 文档预览演示页 235 +15. `pages/favorites/index` - 用户收藏
227 -19. `pages/document-preview/index` - 文档预览页 236 +16. `pages/avatar/index` - 头像设置
237 +17. `pages/feedback-list/index` - 反馈列表
238 +18. `pages/feedback/index` - 用户反馈
239 +19. `pages/login/index` - 登录页
240 +20. `pages/help-center/index` - 帮助中心和常见问题页
241 +
242 +**开发测试页面**(仅开发环境):
243 +- `pages/test-tabs/index` - 标签页测试
228 244
229 ### 组件库 245 ### 组件库
230 246
231 -**可复用组件** 247 +**导航与布局组件**
232 - `TabBar.vue` - 底部导航栏 248 - `TabBar.vue` - 底部导航栏
233 - `NavHeader.vue` - 自定义导航头 249 - `NavHeader.vue` - 自定义导航头
234 -- `IconFont.vue` - 图标字体包装器 250 +- `indexNav.vue` - 首页网格导航
235 251
236 -**功能组件** 252 +**图标与媒体组件**
253 +- `IconFont.vue` - 图标字体包装器
237 - `qrCode.vue` - 二维码显示 254 - `qrCode.vue` - 二维码显示
238 - `qrCodeSearch.vue` - 二维码扫描 255 - `qrCodeSearch.vue` - 二维码扫描
239 -- `PosterBuilder/` - 海报生成 256 +
257 +**列表与展示组件**
258 +- `SectionCard.vue` - 分组卡片组件
259 +- `SectionItem.vue` - 分组列表项组件
260 +- `ListItemActions/` - 列表项操作按钮
261 +
262 +**表单与输入组件**
263 +- `FilterTabs.vue` - 过滤标签组件
264 +- `SearchBar.vue` - 搜索栏组件
265 +
266 +**文档预览组件**
267 +- `DocumentPreview/` - 文档预览组件
268 +- `PdfPreview.vue` - PDF 预览组件
269 +- `OfficeViewer.vue` - Office 文档查看器
270 +
271 +**业务组件**
272 +- `PlanSchemes/` - 计划方案组件(SchemeA, SchemeB)
273 +- `PlanPopup/` - 计划弹窗组件
274 +
275 +**工具组件**
276 +- `PosterBuilder/` - 海报生成器
240 - `time-picker-data/` - 时间选择器数据 277 - `time-picker-data/` - 时间选择器数据
241 278
242 ### 路径别名 279 ### 路径别名
...@@ -275,16 +312,14 @@ src/pages/your-page/ ...@@ -275,16 +312,14 @@ src/pages/your-page/
275 ## 🔧 重要实现细节 312 ## 🔧 重要实现细节
276 313
277 ### 会话管理 314 ### 会话管理
278 -- 会话 ID 存储在 `localStorage` 中,键名为 `sessionid` 315 +- **会话 ID 存储**`localStorage.sessionid`
279 -- 微信登录成功后由 `authRedirect.refreshSession()` 设置 316 +- **静默登录**`openid.js``miniProgramAuth()` 函数
280 --`request.js` 拦截器自动注入到请求头中 317 + - 调用 `wx.login()` 获取 code
281 -- 登出或显式手动操作时清除 318 + - 调用 `/srv/?a=openid` 接口换取 sessionid
282 - 319 + - 自动写入 localStorage
283 -### Promise 单例模式 320 +- **请求注入**`request.js` 拦截器自动读取并注入到请求头的 `cookie` 字段
284 -认证系统使用 Promise 单例防止并发登录尝试: 321 +- **会话清除**:登出或 401 失败时清除
285 -- `authRedirect.js` 中的 `auth_promise` 确保一次只刷新一个 322 +- **401 刷新**:拦截器捕获 401 → 调用 `miniProgramAuth()` → 重试原始请求
286 -- 所有并发的 401 共享同一个刷新 Promise
287 -- `.finally()` 确保无论成功/失败都执行清理
288 323
289 ### 请求超时处理 324 ### 请求超时处理
290 - 默认超时:5 秒(`src/utils/request.js:79` 325 - 默认超时:5 秒(`src/utils/request.js:79`
...@@ -479,7 +514,7 @@ store.setState('新值') ...@@ -479,7 +514,7 @@ store.setState('新值')
479 ## 关键文件总结 514 ## 关键文件总结
480 515
481 ### 修改前必须理解 516 ### 修改前必须理解
482 -1. **`src/utils/authRedirect.js`** - 完整的认证流程逻辑 517 +1. **`src/utils/openid.js`** - 微信授权和会话管理逻辑
483 2. **`src/utils/request.js`** - 带拦截器的 HTTP 客户端 518 2. **`src/utils/request.js`** - 带拦截器的 HTTP 客户端
484 3. **`src/app.js`** - 应用启动序列和网络处理 519 3. **`src/app.js`** - 应用启动序列和网络处理
485 4. **`src/utils/config.js`** - 服务器配置(需要修改) 520 4. **`src/utils/config.js`** - 服务器配置(需要修改)
...@@ -488,17 +523,30 @@ store.setState('新值') ...@@ -488,17 +523,30 @@ store.setState('新值')
488 1. **`src/api/index.js`** - API 定义 523 1. **`src/api/index.js`** - API 定义
489 2. **`src/api/fn.js`** - 请求包装器 524 2. **`src/api/fn.js`** - 请求包装器
490 3. **`src/stores/main.js`** - 主要状态管理 525 3. **`src/stores/main.js`** - 主要状态管理
491 -4. **`src/stores/router.js`** - 认证回调的路由状态 526 +4. **`src/stores/user.js`** - 用户状态管理
527 +5. **`src/stores/router.js`** - 路由状态管理
528 +
529 +### 认证与会话
530 +1. **`src/utils/openid.js`** - `miniProgramAuth()` 静默登录
531 +2. **`src/utils/request.js`** - 401 拦截器和 sessionid 管理
532 +3. **`src/pages/login/index.vue`** - 登录页
492 533
493 ### 可复用组件 534 ### 可复用组件
494 1. **`src/components/TabBar.vue`** - 底部导航栏 535 1. **`src/components/TabBar.vue`** - 底部导航栏
495 2. **`src/components/NavHeader.vue`** - 自定义导航头 536 2. **`src/components/NavHeader.vue`** - 自定义导航头
496 -3. **`src/components/IconFont.vue`** - 图标包装器 537 +3. **`src/components/SectionCard.vue`** - 分组卡片
497 - 538 +4. **`src/components/DocumentPreview/`** - 文档预览
498 -### UI/UX 工具 539 +
499 -1. **`src/utils/uiText.js`** - 集中式文案管理 540 +### Composables
500 -2. **`src/utils/network.js`** - 网络状态工具 541 +1. **`src/composables/useSectionList.js`** - 分组列表管理
501 -3. **`src/hooks/useGo.js`** - 增强导航 hook 542 +2. **`src/composables/useFileOperation.js`** - 文件操作
543 +3. **`src/composables/useListItemClick.js`** - 列表点击处理
544 +
545 +### 工具函数
546 +1. **`src/utils/documentIcons.js`** - 文档类型图标识别
547 +2. **`src/utils/tools.js`** - 通用工具函数集合
548 +3. **`src/utils/network.js`** - 网络状态工具
549 +4. **`src/hooks/useGo.js`** - 增强导航 hook
502 550
503 ## 调试技巧 551 ## 调试技巧
504 552
......