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 | ... | ... |
-
Please register or login to post a comment