Hooke / manulife-weapp

Go to a project
Toggle navigation Toggle navigation pinning
hookehuyr
63ed4e5d 1 parent 94d2c3f3

feat: 优化 OpenAPI 文档生成工具并更新接口联调日志 

- 优化 API 文档生成脚本
  - 添加 CLAUDE.md 文件过滤，避免将文档文件当作 API 文档处理
  - 改进新增模块检测逻辑，显示新增模块包含的所有接口
  - 优化变更检测报告，提升可读性

- 更新 API 接口联调日志
  - 收藏模块：3个接口后端已完成，标记为待联调
  - 埋点模块：1个接口后端已完成，标记为待联调
  - 更新总体进度：24个接口（12已完成，9待联调，3已废弃）

- 新增埋点模块
  - 添加埋点接口（addAPI）
  - 生成 API 文档和接口代码

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Inline Side-by-side
Showing 5 changed files with 248 additions and 35 deletions
......@@ -5,6 +5,36 @@
---
## [2026-02-04] - 优化 OpenAPI 文档生成工具
### 优化
- API 文档生成脚本（`scripts/generateApiFromOpenAPI.js`）
- 添加 CLAUDE.md 文件过滤，避免将文档文件当作 API 文档处理
- 改进新增模块检测逻辑，显示新增模块包含的所有接口
- 优化变更检测报告，提升可读性
- 在 3 处添加了 `.md` 文件过滤（扫描模块、对比变更、文件列表）
### 文档
- 更新 API 接口联调日志（`docs/api-integration-log.md`）
- 收藏模块：3个接口后端已完成，标记为待联调
- 埋点模块：1个接口后端已完成，标记为待联调
- 更新总体进度统计：24个接口（12已完成，9待联调，3已废弃）
---
**详细信息**：
- **影响文件**:
- `scripts/generateApiFromOpenAPI.js` - API 文档生成脚本优化
- `docs/api-integration-log.md` - API 联调日志更新
- **技术栈**: Node.js, fs 模块
- **测试状态**: ✅ 已测试通过
- **备注**:
- 扫描目录时自动忽略 `CLAUDE.md` 文件
- 新增模块时会显示该模块包含的所有接口信息（方法、路径、描述）
- 变更检测报告更加准确和详细
---
## [2026-02-04] - 优化视频播放用户体验
### 优化
......
......@@ -4,28 +4,27 @@
## 📊 总体进度
- **总接口数**: 20
- **已完成**: 12 (60.0%)
- **总接口数**: 24
- **已完成**: 12 (50.0%)
- **联调中**: 0 (0%)
- **已废弃**: 3 (15.0%)
- **后端开发中**: 5 (25.0%)
- **已废弃**: 3 (12.5%)
- **待联调**: 9 (37.5%)
- **有阻塞**: 0
---
**📝 最近更新** (2026-02-03):
**📝 最近更新** (2026-02-04):
- 🔧 **优化 OpenAPI 文档生成工具**：
- 添加 CLAUDE.md 文件过滤，避免将文档文件当作 API 文档处理
- 改进新增模块检测逻辑，显示新增模块包含的所有接口
- 优化变更检测报告，提升可读性
- ✅ **收藏模块后端完成**：3 个收藏接口（addAPI、delAPI、listAPI）后端已开发完成，前端待联调
- ✅ **埋点接口后端完成**：埋点接口（addAPI）后端已开发完成，前端待联调
- ✅ **产品模块联调完成**：产品列表接口（listAPI）联调成功
- 知识库页面：动态标签栏、分类筛选、滚动加载功能正常
- 首页热卖产品：产品列表正常显示
- 🆕 **新增产品模块**：添加产品列表接口（listAPI），前端集成完成，待联调
- 🆕 **知识库页面 API 集成**：动态标签栏、分类筛选、滚动加载功能
- ✅ **修复空状态文字居中**：为 text 元素添加 `w-full text-center` 类
- ✅ **修复获取个人信息接口字段访问错误**：修正 avatar 字段结构（对象而非字符串）
- ✅ **修复更新个人资料接口参数结构错误**：传递完整 avatar 对象而非 avatar_meta_id
- ✅ **修复头像上传接口数据映射错误**：根据实际返回结构正确映射字段
- ✅ **新增头像设置页面加载时获取用户当前头像功能**：提升用户体验
- ✅ **更新 API 文档**：完善 get_profile 和 update_profile 接口文档
- 🆕 **新增收藏模块**：添加 3 个收藏接口（addAPI、delAPI、listAPI），后端开发中
---
......@@ -714,20 +713,22 @@
| 日期 | 版本 | 变更内容 | 变更原因 | 文档链接 |
|------|------|---------|---------|---------|
| 2026-02-04 | v1.1 | 更新状态：后端已完成，前端待联调 | 后端开发完成 | [查看](#) |
| 2026-02-03 | v1.0 | 初始版本 | - | [查看](#) |
**页面调试情况**
| 日期 | 调试页面 | 问题记录 | 解决方案 | 状态 |
|------|---------|---------|---------|------|
| 2026-02-04 | - | 后端已完成，前端待联调 | - | ⏳ 待联调 |
| 2026-02-03 | - | 后端开发中 | - | ⏳ 后端开发中 |
**接口状态**: ⏳ 后端开发中
**接口状态**: ⏳ 待联调
**备注**:
- 参数：`meta_id`（文件ID）
- 用于收藏产品或资料
- 后端接口开发中
- 后端接口已完成
- 实现位置：`src/api/favorite.js:addAPI`
---
......@@ -745,20 +746,22 @@
| 日期 | 版本 | 变更内容 | 变更原因 | 文档链接 |
|------|------|---------|---------|---------|
| 2026-02-04 | v1.1 | 更新状态：后端已完成，前端待联调 | 后端开发完成 | [查看](#) |
| 2026-02-03 | v1.0 | 初始版本 | - | [查看](#) |
**页面调试情况**
| 日期 | 调试页面 | 问题记录 | 解决方案 | 状态 |
|------|---------|---------|---------|------|
| 2026-02-04 | - | 后端已完成，前端待联调 | - | ⏳ 待联调 |
| 2026-02-03 | - | 后端开发中 | - | ⏳ 后端开发中 |
**接口状态**: ⏳ 后端开发中
**接口状态**: ⏳ 待联调
**备注**:
- 参数：`meta_id`（文件ID）
- 用于取消收藏的产品或资料
- 后端接口开发中
- 后端接口已完成
- 实现位置：`src/api/favorite.js:delAPI`
---
......@@ -776,15 +779,17 @@
| 日期 | 版本 | 变更内容 | 变更原因 | 文档链接 |
|------|------|---------|---------|---------|
| 2026-02-04 | v1.1 | 更新状态：后端已完成，前端待联调 | 后端开发完成 | [查看](#) |
| 2026-02-03 | v1.0 | 初始版本 | - | [查看](#) |
**页面调试情况**
| 日期 | 调试页面 | 问题记录 | 解决方案 | 状态 |
|------|---------|---------|---------|------|
| 2026-02-04 | - | 后端已完成，前端待联调 | - | ⏳ 待联调 |
| 2026-02-03 | - | 后端开发中 | - | ⏳ 后端开发中 |
**接口状态**: ⏳ 后端开发中
**接口状态**: ⏳ 待联调
**备注**:
- 参数：
......@@ -808,11 +813,46 @@
}
}
```
- 后端接口开发中
- 后端接口已完成
- 实现位置：`src/api/favorite.js:listAPI`
---
### 埋点模块
#### 接口 1: 添加埋点
**接口信息**
- **接口名称**: `addAPI`
- **接口路径**: `/srv/?a=event&t=add`
- **请求方法**: POST
- **负责页面**: 待确认
- **负责人**: 后端团队
**接口文档更新记录**
| 日期 | 版本 | 变更内容 | 变更原因 | 文档链接 |
|------|------|---------|---------|---------|
| 2026-02-04 | v1.0 | 初始版本 | 后端已完成，前端待联调 | [查看](#) |
**页面调试情况**
| 日期 | 调试页面 | 问题记录 | 解决方案 | 状态 |
|------|---------|---------|---------|------|
| 2026-02-04 | - | 后端已完成，前端待联调 | - | ⏳ 待联调 |
**接口状态**: ⏳ 待联调
**备注**:
- 参数：
- `type`（类型）：READ_FILE=阅读素材
- `object_id`（文件ID）
- 用于记录用户行为埋点
- 后端接口已完成
- 实现位置：`src/api/event.js:addAPI`
---
### 模块模板
复制下方模板添加新接口：
......@@ -871,12 +911,12 @@
## 📈 进度追踪
### 本周进度 (2026-01-27 ~ 2026-02-03)
### 本周进度 (2026-01-27 ~ 2026-02-04)
- **新增接口**: 16
- **完成联调**: 11
- **新增接口**: 17
- **完成联调**: 12
- **已废弃**: 3
- **联调中**: 0
- **待联调**: 9
- **后端开发中**: 2
- **发现问题**: 6
- **解决问题**: 6
......@@ -885,7 +925,7 @@
| 周 | 完成数 | 新增数 | 废弃数 | 问题数 |
|----|--------|--------|--------|--------|
| 2026-01-27 ~ 2026-02-03 | 9 | 16 | 3 | 0 |
| 2026-01-27 ~ 2026-02-04 | 12 | 17 | 3 | 0 |
---
......@@ -896,16 +936,18 @@
- [✅ 已完成](#意见反馈模块) - 2个接口
- [✅ 已完成](#产品模块) - 1个接口
- [❌ 已废弃](#通用模块) - 3个接口
- [⏳ 待联调](#收藏模块) - 3个接口
- [⏳ 待联调](#埋点模块) - 1个接口
- [⏳ 后端开发中](#消息模块) - 2个接口
- [⏳ 后端开发中](#收藏模块) - 3个接口
### 按模块查看
- [用户中心](#用户中心模块) - ✅ 6个已完成
- [通用](#通用模块) - ❌ 3个已废弃
- [意见反馈](#意见反馈模块) - ✅ 2个已完成
- [产品](#产品模块) - ✅ 1个已完成
- [收藏](#收藏模块) - ⏳ 3个待联调
- [埋点](#埋点模块) - ⏳ 1个待联调
- [消息](#消息模块) - ⏳ 2个后端开发中
- [收藏](#收藏模块) - ⏳ 3个后端开发中
- [知识库](#知识库模块) - ⏳ 未开始
- [家办](#家办模块) - ⏳ 未开始
- [签单](#签单模块) - ⏳ 未开始
......@@ -942,15 +984,23 @@
---
**最后更新时间**: 2026-02-03 21:00
**文档版本**: v2.1
**最后更新时间**: 2026-02-04 13:00
**文档版本**: v2.2
**更新内容**:
- 产品模块联调完成：产品列表接口（listAPI）✅ 已完成
- 知识库页面：动态标签栏、分类筛选、滚动加载功能正常
- 首页热卖产品：产品列表正常显示
- 更新总体进度：20个接口（12个已完成，0个联调中，3个已废弃，5个后端开发中）
- 收藏模块：3个接口后端已完成，前端待联调
- addAPI（添加收藏）
- delAPI（取消收藏）
- listAPI（收藏列表）
- 埋点模块：1个接口后端已完成，前端待联调
- addAPI（添加埋点）
- OpenAPI 文档生成工具优化：
- 添加 CLAUDE.md 文件过滤
- 改进新增模块检测逻辑
- 优化变更检测报告
- 更新总体进度：24个接口（12个已完成，9个待联调，3个已废弃）
**历史版本**:
- v2.1 (2026-02-03 21:00): 产品模块联调完成
- v2.0 (2026-02-03 20:40): 新增产品模块
- v1.9 (2026-02-03 20:30): 新增收藏模块
- v1.8 (2026-02-03 20:00): 用户中心模块头像接口修复
......
# 埋点
## OpenAPI Specification
```yaml
openapi: 3.0.1
info:
title: ''
version: 1.0.0
paths:
/srv/:
post:
summary: 埋点
deprecated: false
description: ''
tags:
- 埋点
parameters:
- name: f
in: query
description: ''
required: true
example: jiangedianlv
schema:
type: string
- name: a
in: query
description: ''
required: true
example: common
schema:
type: string
- name: t
in: query
description: ''
required: true
example: submit_feedback
schema:
type: string
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
f:
example: manulife
type: string
a:
example: event
type: string
t:
example: add
type: string
type:
description: 类型。READ_FILE=阅读素材
example: READ_FILE
type: string
object_id:
description: 文件ID
example: '834965'
type: string
required:
- f
- a
- t
- type
- object_id
examples: {}
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
code:
type: integer
msg:
type: string
required:
- code
- msg
x-apifox-orders:
- code
- msg
headers: {}
x-apifox-name: 成功
x-apifox-ordering: 0
security: []
x-apifox-folder: 埋点
x-apifox-status: testing
x-run-in-apifox: https://app.apifox.com/web/project/7792797/apis/api-415042878-run
components:
schemas: {}
responses: {}
securitySchemes: {}
servers: []
security: []
```
......@@ -571,7 +571,7 @@ function scanAndGenerate(openAPIDir, outputDir) {
modules.forEach((moduleName) => {
const moduleDir = path.join(openAPIDir, moduleName);
const apiFiles = fs.readdirSync(moduleDir)
.filter(file => file.endsWith('.md'));
.filter(file => file.endsWith('.md') && file !== 'CLAUDE.md');
if (apiFiles.length === 0) {
console.log(`模块 ${moduleName} 中没有找到 .md 文件`);
......@@ -704,14 +704,26 @@ function compareAPIChanges(openAPIDir) {
// 如果临时备份中不存在该模块，说明是新增模块
if (!fs.existsSync(tempModuleDir)) {
console.log(`📦 新增模块: ${moduleName}`);
console.log(`\n📦 新增模块: ${moduleName}`);
// 解析新增模块的接口
try {
const newDocs = parseOpenAPIPath(moduleDir);
if (newDocs && newDocs.length > 0) {
console.log(` 包含 ${newDocs.length} 个新增接口:`);
newDocs.forEach(doc => {
console.log(` • ${doc.method} ${doc.path} - ${doc.summary}`);
});
}
} catch (error) {
console.error(` ⚠️ 解析模块失败: ${error.message}`);
}
hasChanges = true;
return;
}
// 读取当前和临时备份的文档
const currentFiles = fs.readdirSync(moduleDir).filter(f => f.endsWith('.md'));
const tempFiles = fs.readdirSync(tempModuleDir).filter(f => f.endsWith('.md'));
const currentFiles = fs.readdirSync(moduleDir).filter(f => f.endsWith('.md') && f !== 'CLAUDE.md');
const tempFiles = fs.readdirSync(tempModuleDir).filter(f => f.endsWith('.md') && f !== 'CLAUDE.md');
// 检查是否有文件变更
const hasNewFiles = currentFiles.some(f => !tempFiles.includes(f));
......
import { fn, fetch } from '@/api/fn';
const Api = {
Add: '/srv/?a=event&t=add',
}
/**
* @description 埋点
* @remark
* @param {Object} params 请求参数
* @param {string} params.type 类型。READ_FILE=阅读素材
* @param {string} params.object_id 文件ID
* @returns {Promise<{
* code: number; // 状态码
* msg: string; // 消息
* data: any;
* }>}
*/
export const addAPI = (params) => fn(fetch.post(Api.Add, params));