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>

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>
hookehuyr
Commit 63ed4e5d98c9ad004ff2ef67c1c390175c2abd0a 63ed4e5d 1 parent 94d2c3f3
Showing 5 changed files with 248 additions and 35 deletions
docs/CHANGELOG.md
docs/api-integration-log.md
docs/api-specs/event/add.md
scripts/generateApiFromOpenAPI.js
src/api/event.js
--- a/docs/CHANGELOG.md
View file @63ed4e5
+++ b/docs/CHANGELOG.md
View file @63ed4e5
@@ -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] - 优化视频播放用户体验
 ### 优化
--- a/docs/api-integration-log.md
View file @63ed4e5
+++ b/docs/api-integration-log.md
View file @63ed4e5
@@ -4,28 +4,27 @@
 ## 📊 总体进度
-- **总接口数**: 20
+- **总接口数**: 24
-- **已完成**: 12 (60.0%)
+- **已完成**: 12 (50.0%)
 - **联调中**: 0 (0%)
-- **已废弃**: 3 (15.0%)
+- **已废弃**: 3 (12.5%)
-- **后端开发中**: 5 (25.0%)
+- **待联调**: 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
+- **新增接口**: 17
-- **完成联调**: 11
+- **完成联调**: 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
+**最后更新时间**: 2026-02-04 13:00
-**文档版本**: v2.1
+**文档版本**: v2.2
 **更新内容**:
-- 产品模块联调完成：产品列表接口（listAPI）✅ 已完成
+- 收藏模块：3个接口后端已完成，前端待联调
-  - 知识库页面：动态标签栏、分类筛选、滚动加载功能正常
+  - addAPI（添加收藏）
-  - 首页热卖产品：产品列表正常显示
+  - delAPI（取消收藏）
-- 更新总体进度：20个接口（12个已完成，0个联调中，3个已废弃，5个后端开发中）
+  - 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): 用户中心模块头像接口修复
--- a/docs/api-specs/event/add.md 0 → 100644
View file @63ed4e5
+++ b/docs/api-specs/event/add.md 0 → 100644
View file @63ed4e5
+# 埋点
+
+## 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: []
+
+```
--- a/scripts/generateApiFromOpenAPI.js
View file @63ed4e5
+++ b/scripts/generateApiFromOpenAPI.js
View file @63ed4e5
@@ -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 currentFiles = fs.readdirSync(moduleDir).filter(f => f.endsWith('.md') && f !== 'CLAUDE.md');
-    const tempFiles = fs.readdirSync(tempModuleDir).filter(f => f.endsWith('.md'));
+    const tempFiles = fs.readdirSync(tempModuleDir).filter(f => f.endsWith('.md') && f !== 'CLAUDE.md');
     // 检查是否有文件变更
     const hasNewFiles = currentFiles.some(f => !tempFiles.includes(f));
--- a/src/api/event.js 0 → 100644
View file @63ed4e5
+++ b/src/api/event.js 0 → 100644
View file @63ed4e5
+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));