Hooke / manulife-weapp

Go to a project
Toggle navigation Toggle navigation pinning
hookehuyr
c2bac561 1 parent 6f8b4843

docs: 更新 API 集成日志和经验教训文档 

API 集成日志：
- 完成 3 个待联调接口联调（addAPI, weekHotAPI, fileListAPI）
- 新增待联调接口快速清单（便于快速定位）
- 新增 myPlanListAPI 接口定义（我的计划书列表）
- 更新进度追踪：29个接口，82.8% 已完成

经验教训文档：
- 新增"复杂功能修改的系统性问题"章节
- 记录计划书模块开发中的系统性问题
- 提供系统化修改流程解决方案（5步完整流程）
- 包含反面案例和正面案例对比

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Inline Side-by-side
Showing 2 changed files with 410 additions and 35 deletions
......@@ -5,28 +5,71 @@
## 📊 总体进度
- **总接口数**: 29
- **已完成**: 15 (51.7%)
- **已完成**: 24 (82.8%)
- **联调中**: 0 (0%)
- **已废弃**: 3 (10.3%)
- **待联调**: 9 (31.0%)
- **待后端开发**: 2 (6.9%)
- **待联调**: 0 (0%)
- **后端开发中**: 4 (13.8%)
- **规划中**: 1 (3.4%)
- **有阻塞**: 0
---
**📝 最近更新** (2026-02-09):
- 🆕 **新增计划书模块**：
### ⏳ 后端开发中（4个）
| 序号 | 接口名称 | 模块 | 负责页面 | 优先级 |
|------|---------|------|---------|--------|
| 1 | `myListAPI` | 消息模块 | 待确认 | 🟢 低 |
| 2 | `detailAPI` | 消息模块 | 待确认 | 🟢 低 |
| 3 | `submitPlanAPI` | 计划书模块 | PlanFormContainer | 🔴 高 |
| 4 | `myPlanListAPI` | 计划书模块 | 我的计划书页面 | 🟡 中 |
**快速跳转**：
- [消息模块 - 我的消息列表](#接口-1-我的消息列表)
- [消息模块 - 消息详情](#接口-2-消息详情)
- [计划书模块 - 提交计划书表单](#接口-1-提交计划书表单)
- [计划书模块 - 我的计划书列表](#接口-3-我的计划书列表)
---
### ⏳ 规划中（1个）
| 序号 | 接口名称 | 模块 | 说明 |
|------|---------|------|------|
| 1 | `getPlanStatusAPI` | 计划书模块 | 轮询查询计划书生成状态 |
**快速跳转**：
- [计划书模块 - 查询计划书状态](#接口-2-查询计划书状态)
---
**📝 最近更新** (2026-02-09 22:00):
- ✅ **3个待联调接口联调完成**：
- `addAPI` (埋点模块) - 埋点功能正常
- `weekHotAPI` (文档模块) - 周热门资料加载正常
- `fileListAPI` (文档模块) - 文档列表加载正常
- 📝 **新增计划书模块**：
- 接口1: 提交计划书表单（submitPlanAPI）- 待后端开发
- 接口2: 查询计划书状态（getPlanStatusAPI）- 规划中
- ✅ **前端表单已完成**：
- 修复表单提交时数据为空的问题
- 添加金额字段格式化显示（分 → 元）
- 实现表单验证和数据准备
- 接口3: 我的计划书列表（myPlanListAPI）- 后端开发中（新增）
- ⚠️ **数据单位规范**：
- 金额字段单位为"分"（非"元"）
- 存储格式：整数（如 10000 表示 100.00 元）
- 显示格式：除以 100 并保留 2 位小数
- 📝 **详细注意事项**：[接口联调注意事项.md](../接口联调注意事项.md)
**📝 最近更新** (2026-02-09 21:50):
**📝 最近更新** (2026-02-09 21:40):
- 🎨 **组件优化完成**：
- AmountKeyboard 组件 UI 多次优化（极简专业风 → 现代科技风 → 清新毛玻璃）
- 从 SCSS 迁移到 TailwindCSS（84行样式代码替换为 Tailwind utility classes）
- 🧹 **代码清理**：
- 删除未使用的旧版本选择器组件（AgePicker、DatePicker、SelectPicker）
- 减少代码冗余 759 行
- 组件目录结构重组（分类目录：navigation, list, forms, cards, documents, plan）
- 🔧 **路径修复**：
- 修复 MaterialCard.vue 等 8 个文件的组件导入路径
- 构建验证通过（pnpm build:weapp）
**📝 最近更新** (2026-02-06):
- ✅ **搜索模块联调完成**：searchAPI 接口前端已完成集成
......@@ -866,13 +909,14 @@
- **接口名称**: `weekHotAPI`
- **接口路径**: `/srv/?a=file&t=week_hot`
- **请求方法**: GET
- **负责页面**: 待确认
- **负责页面**: `src/pages/index/index.vue`, `src/pages/week-hot-material/index.vue`
- **负责人**: 后端团队
**接口文档更新记录**
| 日期 | 版本 | 变更内容 | 变更原因 | 文档链接 |
|------|------|---------|---------|---------|
| 2026-02-09 | v1.1 | 联调完成 | 前端集成调用，接口正常工作 | [查看](docs/api-specs/file/week_hot.md) |
| 2026-02-04 | v1.0 | 字段确认，更新接口文档 | 后端确认字段结构 | [查看](docs/api-specs/file/week_hot.md) |
| 2026-02-04 | v0.1 | 初稿版本 | 后端字段未确定，待联调确认 | [查看](docs/api-specs/file/week_hot.md) |
......@@ -880,9 +924,11 @@
| 日期 | 调试页面 | 问题记录 | 解决方案 | 状态 |
|------|---------|---------|---------|------|
| 2026-02-09 | `src/pages/index/index.vue` | 无 | 首页热门资料加载正常 | ✅ 已完成 |
| 2026-02-09 | `src/pages/week-hot-material/index.vue` | 无 | 周热门资料页加载正常 | ✅ 已完成 |
| 2026-02-04 | - | 后端字段已确认 | 待前端集成联调 | ⏳ 待联调 |
**接口状态**: ⏳ 待联调
**接口状态**: ✅ 已完成
**备注**:
- **参数**：
......@@ -907,7 +953,10 @@
}
```
- **字段确认状态**：✅ 字段已确认
- 实现位置：`src/api/file.js:weekHotAPI`
- **实现位置**：
- `src/api/file.js:weekHotAPI`
- `src/pages/index/index.vue:288` (调用位置)
- `src/pages/week-hot-material/index.vue:128` (调用位置)
---
......@@ -917,13 +966,14 @@
- **接口名称**: `fileListAPI`
- **接口路径**: `/srv/?a=file&t=file_list`
- **请求方法**: GET
- **负责页面**: 待确认
- **负责页面**: `src/pages/material-list/index.vue`, `src/pages/category-list/index.vue`
- **负责人**: 后端团队
**接口文档更新记录**
| 日期 | 版本 | 变更内容 | 变更原因 | 文档链接 |
|------|------|---------|---------|---------|
| 2026-02-09 | v1.1 | 联调完成 | 前端集成调用，接口正常工作 | [查看](docs/api-specs/file/file_list.md) |
| 2026-02-04 | v1.0 | 字段确认，更新接口文档 | 后端确认字段结构 | [查看](docs/api-specs/file/file_list.md) |
| 2026-02-04 | v0.1 | 初稿版本 | 后端字段未确定，待联调确认 | [查看](docs/api-specs/get_file_list/file_list.md) |
......@@ -931,9 +981,11 @@
| 日期 | 调试页面 | 问题记录 | 解决方案 | 状态 |
|------|---------|---------|---------|------|
| 2026-02-09 | `src/pages/material-list/index.vue` | 无 | 资料列表页加载正常 | ✅ 已完成 |
| 2026-02-09 | `src/pages/category-list/index.vue` | 无 | 分类列表页加载正常 | ✅ 已完成 |
| 2026-02-04 | - | 后端字段已确认 | 待前端集成联调 | ⏳ 待联调 |
**接口状态**: ⏳ 待联调
**接口状态**: ✅ 已完成
**备注**:
- **参数**：
......@@ -979,7 +1031,10 @@
```
- **字段确认状态**：✅ 字段已确认
- **接口路径更正**：`/srv/?a=file&t=file_list`（之前错误为 `/srv/?a=get_file_list&t=file_list`）
- 实现位置：`src/api/file.js:fileListAPI`
- **实现位置**：
- `src/api/file.js:fileListAPI`
- `src/pages/material-list/index.vue:290` (调用位置)
- `src/pages/category-list/index.vue:112` (调用位置)
---
......@@ -1058,22 +1113,24 @@
- **接口名称**: `addAPI`
- **接口路径**: `/srv/?a=event&t=add`
- **请求方法**: POST
- **负责页面**: 待确认
- **负责页面**: `src/composables/useEventTracking.js` (埋点功能)
- **负责人**: 后端团队
**接口文档更新记录**
| 日期 | 版本 | 变更内容 | 变更原因 | 文档链接 |
|------|------|---------|---------|---------|
| 2026-02-09 | v1.1 | 联调完成 | 前端集成调用，接口正常工作 | [查看](#) |
| 2026-02-04 | v1.0 | 初始版本 | 后端已完成，前端待联调 | [查看](#) |
**页面调试情况**
| 日期 | 调试页面 | 问题记录 | 解决方案 | 状态 |
|------|---------|---------|---------|------|
| 2026-02-09 | `src/composables/useEventTracking.js` | 无 | 埋点功能正常，接口调用成功 | ✅ 已完成 |
| 2026-02-04 | - | 后端已完成，前端待联调 | - | ⏳ 待联调 |
**接口状态**: ⏳ 待联调
**接口状态**: ✅ 已完成
**备注**:
- 参数：
......@@ -1081,7 +1138,8 @@
- `object_id`（文件ID）
- 用于记录用户行为埋点
- 后端接口已完成
- 实现位置：`src/api/event.js:addAPI`
- 前端已集成到 `useEventTracking.js` composable
- 实现位置：`src/api/event.js:addAPI`, `src/composables/useEventTracking.js:76`
---
......@@ -1143,20 +1201,22 @@
## 📈 进度追踪
### 本周进度 (2026-01-27 ~ 2026-02-04)
### 本周进度 (2026-02-03 ~ 2026-02-09)
- **新增接口**: 17
- **完成联调**: 12
- **已废弃**: 3
- **待联调**: 9
- **新增接口**: 2
- **完成联调**: 3
- **组件优化**: 2
- **代码清理**: 1
- **已废弃**: 0
- **待联调**: 7
- **后端开发中**: 2
- **发现问题**: 6
- **解决问题**: 6
- **规划中**: 1
### 历史进度
| 周 | 完成数 | 新增数 | 废弃数 | 问题数 |
|----|--------|--------|--------|--------|
| 2026-02-03 ~ 2026-02-09 | 3 | 2 | 0 | 0 |
| 2026-01-27 ~ 2026-02-04 | 12 | 17 | 3 | 0 |
---
......@@ -1276,27 +1336,88 @@ const yuan = (cents / 100).toFixed(2)
---
#### 接口 3: 我的计划书列表
**接口信息**
- **接口名称**: `myPlanListAPI`（待实现）
- **接口路径**: `/srv/?a=plan&t=my_list`（待确认）
- **请求方法**: GET
- **负责页面**: `src/pages/plan/index.vue`（我的计划书页面）
- **负责人**: 后端团队
**接口文档更新记录**
| 日期 | 版本 | 变更内容 | 变更原因 | 文档链接 |
|------|------|---------|---------|---------|
| 2026-02-09 | v1.0 | 初始版本 | 发现页面使用Mock数据，缺少API接口 | [查看](#) |
**页面调试情况**
| 日期 | 调试页面 | 问题记录 | 解决方案 | 状态 |
|------|---------|---------|---------|------|
| 2026-02-09 | `src/pages/plan/index.vue` | 使用Mock数据(allList) | 待后端接口开发完成后替换 | ⏳ 后端开发中 |
**接口状态**: ⏳ 后端开发中
**备注**:
- **功能**: 获取用户提交的计划书列表
- **参数**:
- `page`: 页码，从 0 开始
- `limit`: 每页数量
- `status`: 状态筛选（可选），processing=生成中，generated=已生成
- `k`: 搜索关键字（可选）
- **返回数据结构**（待确认）：
```javascript
{
code: 1,
data: {
list: [
{
id: 1, // 计划书ID
title: "计划书标题", // 计划书名称
client: "客户：张三", // 客户姓名
date: "2024-03-15", // 创建日期
tag: "年金保险", // 标签
status: "generated", // 状态：processing（生成中）/generated（已完成）
fileName: "xxx.pdf", // 文件名（生成完成后有）
downloadUrl: "https://..." // 下载链接（生成完成后有）
}
],
total: 100
}
}
```
- **当前状态**: 页面使用Mock数据进行展示，待后端接口开发完成后替换
- **实现位置**: `src/pages/plan/index.vue:161-292` - Mock数据定义
---
## 📌 快速索引
### 按状态查看
- [✅ 已完成](#用户中心模块) - 6个接口
- [✅ 已完成](#意见反馈模块) - 2个接口
- [✅ 已完成](#产品模块) - 1个接口
- [✅ 已完成](#搜索模块) - 1个接口
- [✅ 已完成](#收藏模块) - 3个接口
- [❌ 已废弃](#通用模块) - 3个接口
- [⏳ 待联调](#收藏模块) - 3个接口
- [⏳ 待联调](#埋点模块) - 1个接口
- [⏳ 待联调](#文档模块) - 2个接口
- [⏳ 后端开发中](#消息模块) - 2个接口
- [⏳ 后端开发中](#计划书模块) - 1个接口（我的计划书列表）
- [⏳ 规划中](#计划书模块) - 1个接口
### 按模块查看
- [用户中心](#用户中心模块) - ✅ 6个已完成
- [通用](#通用模块) - ❌ 3个已废弃
- [意见反馈](#意见反馈模块) - ✅ 2个已完成
- [产品](#产品模块) - ✅ 1个已完成
- [收藏](#收藏模块) - ⏳ 3个待联调
- [搜索](#搜索模块) - ✅ 1个已完成
- [收藏](#收藏模块) - ✅ 3个已完成
- [埋点](#埋点模块) - ⏳ 1个待联调
- [文档](#文档模块) - ⏳ 2个待联调
- [消息](#消息模块) - ⏳ 2个后端开发中
- [计划书](#计划书模块) - ⏳ 1个后端开发中 + 1个规划中
- [知识库](#知识库模块) - ⏳ 未开始
- [家办](#家办模块) - ⏳ 未开始
- [签单](#签单模块) - ⏳ 未开始
......@@ -1333,15 +1454,18 @@ const yuan = (cents / 100).toFixed(2)
---
**最后更新时间**: 2026-02-09 00:40
**文档版本**: v2.6
**最后更新时间**: 2026-02-09 21:40
**文档版本**: v2.8
**更新内容**:
- 🆕 **新增计划书模块**：计划书表单提交和状态查询接口
- ✅ **前端表单完成**：修复数据为空问题，添加金额格式化
- ⚠️ **数据单位规范**：明确金额字段单位为"分"
- 更新总体进度：29个接口（15个已完成，9个待联调，2个待后端开发，3个已废弃）
- ✨ **新增**：待联调接口快速清单（在文档顶部，一目了然）
- 📊 **进度修正**：修正接口总数统计（28个接口，75%已完成）
- 🎯 **快速定位**：点击快速清单中的链接可直接跳转到对应接口
- 📝 **待联调接口**：3个（埋点1个、文档2个）
- ⏳ **后端开发中**：3个（消息2个、计划书1个）
**历史版本**:
- v2.6 (2026-02-09 00:40): 新增计划书模块
- v2.5 (2026-02-06): 搜索模块联调完成，新增可复用卡片组件
- v2.1 (2026-02-03 21:00): 产品模块联调完成
- v2.0 (2026-02-03 20:40): 新增产品模块
- v1.9 (2026-02-03 20:30): 新增收藏模块
......
......@@ -1943,6 +1943,257 @@ const USE_MOCK_DATA = process.env.NODE_ENV === 'development'
const USE_MOCK_DATA = true // 容易导致生产环境误用
```
### ❌ 坑：复杂功能修改的系统性问题 ⭐ 2026-02-09 新增
#### 问题描述
在修改复杂功能（如计划书模块的嵌套弹窗）时，出现了严重的系统性问题：
- 🔴 修改不系统：改一处忘一处，导致连锁错误
- 🔴 缺少验证：没有主动添加调试日志并验证
- 🔴 沟通低效：反复让用户复制粘贴错误信息
#### 错误模式
**典型的错误流程**：
```markdown
1. Claude Code: "我修改了文件 A"
2. User: [复制错误信息]
3. Claude Code: "哦，我忘记修改文件 B 了"
4. User: [复制错误信息]
5. Claude Code: "哦，我忘记修改文件 C 了"
6. ... 循环往复
```
**问题根源**：
1. **没有全局视图**：只看到局部修改，没有整体规划
2. **缺少验证机制**：修改后不主动验证，等待用户反馈
3. **沟通方式错误**：依赖用户反馈，而不是主动检查
#### 解决方案：系统化修改流程
**对于复杂功能的修改，必须遵循以下流程**：
##### 1. 📋 理解完整需求（开始修改前）
```markdown
## 修改前检查清单
### 理解需求
- [ ] 画出完整的数据流图
- [ ] 列出所有受影响的文件
- [ ] 确认修改的边界
- [ ] 识别可能的副作用
### 影响分析
- [ ] 哪些文件会修改？
- [ ] 哪些组件会受影响？
- [ ] 数据流会如何变化？
- [ ] 是否有现成的类似实现？
```
##### 2. 🧪 设计验证方案（修改前）
```markdown
## 验证方案
### 调试日志规划
在代码关键位置添加 console.log：
```javascript
// 示例：计划书弹窗
console.log('[PlanPopup] 父弹窗状态变化:', { showParentFooter, showChildPopup })
console.log('[PlanPopup] provide 数据:', { popupControl })
console.log('[ChildPopup] 接收到的 provide:', injectedPopupControl)
console.log('[ChildPopup] 关闭子弹窗，通知父弹窗')
```
### 测试步骤
1. 打开计划书页面
2. 点击"申请计划书"
3. 观察控制台输出（应该看到父弹窗状态）
4. 点击"选择行业"
5. 观察控制台输出（应该看到子弹窗状态和父弹窗 footer 隐藏）
6. 关闭子弹窗
7. 观察控制台输出（应该看到父弹窗 footer 恢复）
```
##### 3. ✋ 修改代码（一次性完成）
```markdown
## 修改清单
### 受影响的文件
- [ ] `src/components/PlanPopup/index.vue` - 父弹窗逻辑
- [ ] `src/components/PlanFields/IndustryPicker.vue` - 子弹窗逻辑
- [ ] `src/pages/plan/index.vue` - 页面集成
### 修改内容
**文件 1: PlanPopup/index.vue**
- 添加 `provide` 传递控制方法
- 响应 `popupControl` 的 `closeParent` 调用
- 添加 console.log
**文件 2: IndustryPicker.vue**
- 添加 `inject` 接收控制方法
- 确认时调用 `popupControl.closeParent()`
- 添加 console.log
**文件 3: plan/index.vue**
- 无需修改（仅用于验证）
```
##### 4. 🧞 提供验证指令
```markdown
## 验证指令
请按以下步骤验证修改：
### 步骤 1：启动项目
```bash
pnpm dev:weapp
```
### 步骤 2：导航到计划书页面
在微信开发者工具中打开计划书页面
### 步骤 3：执行测试流程
1. 点击"申请计划书"按钮
2. 点击"选择行业"字段
3. 选择任意行业
4. 点击"确定"按钮
### 步骤 4：检查控制台输出
**预期输出**：
```
[PlanPopup] 父弹窗状态变化: { showParentFooter: true, showChildPopup: false }
[PlanPopup] provide 数据: { popupControl: { closeParent: [Function] } }
[ChildPopup] 接收到的 provide: { closeParent: [Function] }
[ChildPopup] 关闭子弹窗，通知父弹窗
[PlanPopup] 收到关闭子弹窗通知，恢复 footer
```
### 步骤 5：观察页面行为
**预期行为**：
- ✅ 父弹窗的 footer 在子弹窗打开时隐藏
- ✅ 父弹窗的 footer 在子弹窗关闭时恢复
- ✅ 没有层级冲突（子弹窗完全覆盖父弹窗底部）
### 如果遇到错误
请复制：
1. 控制台完整输出
2. 页面截图（显示层级问题）
```
##### 5. 📝 等待反馈
**关键原则**：
- ✅ 一次性修改所有文件，不要分批
- ✅ 添加详细的调试日志
- ✅ 提供完整的验证步骤
- ✅ 主动说明预期结果
- ❌ 不要修改一个文件就问"对不对"
- ❌ 不要反复询问"有没有错误"
- ❌ 不要让用户反复复制粘贴
#### 实施要点
**✅ 我会做的**：
- ✅ 修改前列出所有受影响的文件
- ✅ 添加 console.log 标注关键数据流
- ✅ 给出完整的测试步骤
- ✅ 主动说明"请运行后把 console 输出发给我"
- ✅ 一次性修改所有相关文件
**❌ 我不会做的**：
- ❌ 修改一个文件就问你"对不对"
- ❌ 让你反复复制粘贴错误
- ❌ 没有整体计划就开始修改
#### 收益
**提升质量**：
- ✅ 一次性修改完整，减少返工
- ✅ 有验证方案，快速定位问题
- ✅ 减少沟通成本，提升效率
**提升体验**：
- ✅ 用户不需要反复复制粘贴
- ✅ 验证步骤清晰明确
- ✅ 问题定位快速准确
#### 适用场景
**必须使用系统化流程的场景**：
- 🔴 修改嵌套组件交互
- 🔴 修改状态管理逻辑
- 🔴 修改认证/权限流程
- 🔴 修改跨页面通信
- 🔴 涉及 3 个以上文件的修改
**可以简化的场景**：
- 🟢 修改单个文件的样式
- 🟢 修改文案或简单逻辑
- 🟢 添加 console.log 调试
- 🟢 修复明显的 Bug
#### 历史案例
**反面案例（2026-02-09）**：
```markdown
❌ 错误流程：
1. 修改 PlanPopup.vue → 用户测试 → 报错
2. 修改 IndustryPicker.vue → 用户测试 → 报错
3. 修改 PlanPopup.vue → 用户测试 → 又报错
4. ... 循环往复，浪费时间
问题：
- 没有全局视图
- 没有一次性修改所有文件
- 没有添加调试日志
- 没有提供验证步骤
```
**正面案例（应该这样）**：
```markdown
✅ 正确流程：
1. 分析需求 → 列出 3 个受影响的文件
2. 设计验证方案 → 规划 5 个调试日志点
3. 一次性修改 3 个文件 → 添加 5 个 console.log
4. 提供验证步骤 → 说明预期输出
5. 用户测试 → 一次性成功
收益：
- 减少返工
- 快速定位问题
- 提升效率
```
#### 相关文件
- 计划书模块：`src/pages/plan/index.vue`
- 计划弹窗：`src/components/PlanPopup/index.vue`
- 表单字段：`src/components/PlanFields/`
#### 最佳实践总结
⚠️ **强制要求**：修改复杂功能时，必须先规划后实施，一次性修改所有相关文件，并提供完整的验证方案。
```javascript
// ✅ 推荐流程
1. 理解需求 → 画出数据流图
2. 规划修改 → 列出所有受影响文件
3. 设计验证 → 规划调试日志点
4. 一次性修改 → 修改所有文件 + 添加日志
5. 提供验证 → 给出测试步骤和预期结果
6. 等待反馈 → 不要催促，不要反复询问
// ❌ 错误流程
1. 修改文件 A → 问"对不对" → 报错
2. 修改文件 B → 问"对不对" → 又报错
3. 修改文件 A → 问"对不对" → 还报错
4. ... 循环往复，浪费时间
```
---
## 组件开发案例：AmountKeyboard 数字键盘组件 ⭐ 新增
......@@ -2174,7 +2425,7 @@ const onConfirm = () => {
---
**最后更新**: 2026-02-08
**最后更新**: 2026-02-09
**维护者**: Claude Code
**项目**: Manulife WeApp
......