Hooke / manulife-weapp

Go to a project
Toggle navigation Toggle navigation pinning
hookehuyr
f51d3f3f 1 parent 48eae832

docs: 文档模块接口字段确认 

- 更新 API 接口联调日志
  - 文档模块接口状态从"初稿"更新为"待联调"
  - weekHotAPI（本周热门资料）：字段已确认
  - fileListAPI（文档列表）：字段已确认，修正接口路径为 `/srv/?a=file&t=file_list`
  - 更新总体进度：26个接口（12个已完成，11个待联调，3个已废弃）
- 更新 CHANGELOG 记录本次文档更新
- 更新接口文档版本至 v2.4

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Inline Side-by-side
Showing 5 changed files with 338 additions and 206 deletions
......@@ -5,6 +5,30 @@
---
## [2026-02-04] - 文档模块接口字段确认
### 文档
- 更新 API 接口联调日志（`docs/api-integration-log.md`）
- 文档模块接口状态更新：从"初稿"更新为"待联调"
- weekHotAPI（本周热门资料）：字段已确认，更新接口文档
- fileListAPI（文档列表）：字段已确认，更新接口文档，修正接口路径
- 更新总体进度：26个接口（12个已完成，11个待联调，3个已废弃）
- 更新接口文档版本至 v2.4
---
**详细信息**：
- **影响文件**:
- `docs/api-integration-log.md` - API 联调日志更新
- `src/api/file.js` - 接口文档 JSDoc 注释已更新
- **技术栈**: 文档
- **测试状态**: ✅ 文档已更新，待联调
- **备注**:
- 文档模块的两个接口字段已确认，可以开始前端集成和联调工作
- fileListAPI 接口路径修正为 `/srv/?a=file&t=file_list`
---
## [2026-02-04] - 知识库页面新增搜索功能
### 新增
......
......@@ -8,26 +8,15 @@
- **已完成**: 12 (46.2%)
- **联调中**: 0 (0%)
- **已废弃**: 3 (11.5%)
- **待联调**: 9 (34.6%)
- **初稿（字段未确定）**: 2 (7.7%)
- **待联调**: 11 (42.3%)
- **有阻塞**: 0
---
**📝 最近更新** (2026-02-04):
- 🔧 **优化 OpenAPI 文档生成工具**：
- 添加 CLAUDE.md 文件过滤，避免将文档文件当作 API 文档处理
- 改进新增模块检测逻辑，显示新增模块包含的所有接口
- 优化变更检测报告，提升可读性
- 修复接口信息显示为 undefined 的问题
- 🗑️ **清理 Apifox API 依赖**：
- 删除不再工作的 Apifox API 相关脚本（apifox-to-openapi.js、apifox-sync.js 等）
- 删除 .env.apifox 配置文件
- 更新 package.json，移除 api:sync 和 api:test 命令
- 创建 API_GUIDE.md 使用指南，明确手动维护 OpenAPI 文档的工作流
- 📝 **新增文档模块接口（初稿）**：
- weekHotAPI（本周热门资料）：字段未最终确定，待联调确认
- fileListAPI（文档列表）：字段未最终确定，待联调确认
- 📝 **文档模块接口字段确认**：
- weekHotAPI（本周热门资料）：字段已确认，更新接口文档，待联调
- fileListAPI（文档列表）：字段已确认，更新接口文档，待联调
- ✅ **收藏模块后端完成**：3 个收藏接口（addAPI、delAPI、listAPI）后端已开发完成，前端待联调
- ✅ **埋点接口后端完成**：埋点接口（addAPI）后端已开发完成，前端待联调
- ✅ **产品模块联调完成**：产品列表接口（listAPI）联调成功
......@@ -830,7 +819,7 @@
### 文档模块
#### 接口 1: 本周热门资料（初稿）
#### 接口 1: 本周热门资料
**接口信息**
- **接口名称**: `weekHotAPI`
......@@ -843,22 +832,22 @@
| 日期 | 版本 | 变更内容 | 变更原因 | 文档链接 |
|------|------|---------|---------|---------|
| 2026-02-04 | v1.0 | 字段确认，更新接口文档 | 后端确认字段结构 | [查看](docs/api-specs/file/week_hot.md) |
| 2026-02-04 | v0.1 | 初稿版本 | 后端字段未确定，待联调确认 | [查看](docs/api-specs/file/week_hot.md) |
**页面调试情况**
| 日期 | 调试页面 | 问题记录 | 解决方案 | 状态 |
|------|---------|---------|---------|------|
| 2026-02-04 | - | 后端字段未确定 | 待后端确认后更新 | ⏳ 待联调 |
| 2026-02-04 | - | 后端字段已确认 | 待前端集成联调 | ⏳ 待联调 |
**接口状态**: ⏳ 初稿 - 后端字段未确定
**接口状态**: ⏳ 待联调
**备注**:
- ⚠️ **初稿状态**：当前接口文档为初稿，后端字段可能还有调整
- **参数**：
- `page`: 页码，从 0 开始
- `limit`: 每页数量
- **预期返回数据结构**：
- **返回数据结构**：
```javascript
{
code: 1,
......@@ -876,16 +865,16 @@
}
}
```
- **字段确认状态**：待后端确认最终字段结构
- **字段确认状态**：✅ 字段已确认
- 实现位置：`src/api/file.js:weekHotAPI`
---
#### 接口 2: 文档列表（初稿）
#### 接口 2: 文档列表
**接口信息**
- **接口名称**: `fileListAPI`
- **接口路径**: `/srv/?a=get_file_list&t=file_list`
- **接口路径**: `/srv/?a=file&t=file_list`
- **请求方法**: GET
- **负责页面**: 待确认
- **负责人**: 后端团队
......@@ -894,52 +883,62 @@
| 日期 | 版本 | 变更内容 | 变更原因 | 文档链接 |
|------|------|---------|---------|---------|
| 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) |
**页面调试情况**
| 日期 | 调试页面 | 问题记录 | 解决方案 | 状态 |
|------|---------|---------|---------|------|
| 2026-02-04 | - | 后端字段未确定 | 待后端确认后更新 | ⏳ 待联调 |
| 2026-02-04 | - | 后端字段已确认 | 待前端集成联调 | ⏳ 待联调 |
**接口状态**: ⏳ 初稿 - 后端字段未确定
**接口状态**: ⏳ 待联调
**备注**:
- ⚠️ **初稿状态**：当前接口文档为初稿，后端字段可能还有调整
- **参数**：
- `client_id`: 主体 ID（可选）
- `cid`: 分类 ID（可选）
- `page`: 页码（从 0 开始）
- `limit`: 每页数量
- **预期返回数据结构**：
- **返回数据结构**：
```javascript
{
code: 1,
data: {
categories: [
{ id: 2769851, name: "分类名称" }
cate: {
id: 2769851, // 分类id
category_name: "分类名称", // 分类名称
category_parent: 0, // 分类父级
icon: "https://..." // 分类图标
},
children: [
{
id: 2769852, // 二级分类id
category_name: "二级分类名",
category_parent: 2769851, // 二级分类父级id
icon: "https://...", // 二级分类图标
list: [...], // 二级分类的附件列表
children: [...] // 三级分类
}
],
list: [
{
id: 2769856, // 产品id
product_name: "产品名称", // 产品名
recommend: "hot", // 推荐位: normal-普通, hot-热卖
form_sn: "customize_jsj_pnzuky", // 产品编号
created_time: "2026-02-03 10:36:29",
categories: [ // 产品所属分类
{ id: "2769851", name: "分类名称" }
],
tags: [ // 产品标签
{ id: "2769847", name: "标签名", bg_color: "#3e5160", text_color: "#ffffff" }
]
name: "附件名称", // 附件名称
value: "https://...", // 附件地址
extension: "pdf", // 后缀名
post_date: "2026-02-04", // 发布时间
size: "2.5MB", // 附件大小
id: "12345" // 附件id
}
],
total: 3 // 产品总数
total: 100, // 主分类附件数量
max_level: "3" // 层级
}
}
```
- **字段确认状态**：待后端确认最终字段结构
- 实现位置：`src/api/get_file_list.js:fileListAPI`
- **字段确认状态**：✅ 字段已确认
- **接口路径更正**：`/srv/?a=file&t=file_list`（之前错误为 `/srv/?a=get_file_list&t=file_list`）
- 实现位置：`src/api/file.js:fileListAPI`
---
......@@ -1063,7 +1062,7 @@
- [❌ 已废弃](#通用模块) - 3个接口
- [⏳ 待联调](#收藏模块) - 3个接口
- [⏳ 待联调](#埋点模块) - 1个接口
- [⏳ 初稿 - 字段未确定](#文档模块) - 2个接口
- [⏳ 待联调](#文档模块) - 2个接口
- [⏳ 后端开发中](#消息模块) - 2个接口
### 按模块查看
......@@ -1073,7 +1072,7 @@
- [产品](#产品模块) - ✅ 1个已完成
- [收藏](#收藏模块) - ⏳ 3个待联调
- [埋点](#埋点模块) - ⏳ 1个待联调
- [文档](#文档模块) - ⏳ 2个初稿
- [文档](#文档模块) - ⏳ 2个待联调
- [消息](#消息模块) - ⏳ 2个后端开发中
- [知识库](#知识库模块) - ⏳ 未开始
- [家办](#家办模块) - ⏳ 未开始
......@@ -1111,20 +1110,14 @@
---
**最后更新时间**: 2026-02-04 15:30
**文档版本**: v2.3
**最后更新时间**: 2026-02-04 18:00
**文档版本**: v2.4
**更新内容**:
- 📝 **新增文档模块接口（初稿）**：
- weekHotAPI（本周热门资料）：字段未最终确定
- fileListAPI（文档列表）：字段未最终确定
- 🗑️ **移除 Apifox API 依赖**：
- 删除 apifox-to-openapi.js 等不再工作的脚本
- 更新 package.json，简化为 api:generate 单一命令
- 明确手动维护 OpenAPI 文档的工作流
- 🔧 **API 生成工具优化**：
- 修复新增模块接口信息显示为 undefined 的问题
- 改进接口信息提取逻辑
- 更新总体进度：26个接口（12个已完成，9个待联调，2个初稿，3个已废弃）
- 📝 **文档模块接口字段确认**：
- weekHotAPI（本周热门资料）：字段已确认，更新接口文档
- fileListAPI（文档列表）：字段已确认，更新接口文档，修正接口路径
- 更新总体进度：26个接口（12个已完成，11个待联调，3个已废弃）
- 文档模块从"初稿"状态更新为"待联调"状态
**历史版本**:
- v2.1 (2026-02-03 21:00): 产品模块联调完成
......
......@@ -27,7 +27,7 @@ paths:
in: query
description: ''
required: true
example: get_file_list
example: file
schema:
type: string
- name: t
......@@ -41,7 +41,7 @@ paths:
in: query
description: 主体id
required: false
example: '30901'
example: '2303465'
schema:
type: string
- name: limit
......@@ -62,6 +62,7 @@ paths:
in: query
description: 分类id
required: false
example: '2768724'
schema:
type: string
responses:
......@@ -79,114 +80,173 @@ paths:
data:
type: object
properties:
categories:
cate:
type: object
properties:
id:
type: integer
title: 分类id
category_name:
type: string
title: 分类名称
category_parent:
type: integer
title: 分类父级
icon:
type: string
required:
- id
- category_name
- category_parent
- icon
x-apifox-orders:
- id
- category_name
- category_parent
- icon
title: 当前分类
children:
type: array
items:
type: object
properties:
id:
type: integer
title: 分类id
name:
title: 二级分类id
category_name:
type: string
title: 分类名
x-apifox-orders:
- id
- name
title: 分类列表
list:
type: array
items:
type: object
properties:
id:
title: 二级分类名
category_parent:
type: integer
title: 产品id
product_name:
type: string
title: 产品名
recommend:
type: string
title: '推荐位: normal-普通, hot-热卖'
form_sn:
type: string
created_time:
title: 二级分类名父级id
icon:
type: string
title: 创建时间
categories:
title: 二级分类图标
list:
type: array
items:
type: object
properties:
id:
type: string
title: 分类id
name:
type: string
title: 分类名
title: 附件名称
value:
type: string
title: 附件地址
extension:
type: string
title: 后缀名
post_date:
type: string
title: 发布时间
size:
type: string
title: 附件大小
id:
type: string
title: 附件id
required:
- id
- name
- value
- extension
- post_date
- size
- id
x-apifox-orders:
- id
- name
title: 产品所属分类
tags:
- value
- extension
- post_date
- size
title: 二级分类的附件列表
children:
type: array
items:
type: object
properties:
id:
type: integer
title: 三级分类id
category_name:
type: string
title: 标签id
name:
type: string
title: 标签名
bg_color:
type: string
title: 标签背景色
text_color:
type: string
title: 标签文字色
required:
- id
- name
- bg_color
- text_color
title: 三级分类名
category_parent:
type: integer
title: 三级分类名父级id
icon:
type: 'null'
title: 三级分类图标
x-apifox-orders:
- id
- name
- bg_color
- text_color
title: 产品标签
- category_name
- category_parent
- icon
title: 三级分类
x-apifox-orders:
- id
- category_name
- category_parent
- icon
- children
- list
title: 二级分类列表
list:
type: array
items:
type: object
properties:
name:
type: string
title: 附件名称
value:
type: string
title: 附件地址
extension:
type: string
title: 后缀名
post_date:
type: string
title: 发布时间
size:
type: string
title: 附件大小
id:
type: string
title: 附件id
required:
- name
- value
- extension
- post_date
- size
- id
- product_name
- recommend
- form_sn
- created_time
- categories
- tags
x-apifox-orders:
- id
- product_name
- recommend
- form_sn
- created_time
- categories
- tags
title: 产品列表
- name
- value
- extension
- post_date
- size
title: 主分类的附件列表
total:
type: integer
title: 产品总数
title: 主分类附件数量
max_level:
type: string
title: 层级
required:
- categories
- cate
- children
- list
- total
- max_level
x-apifox-orders:
- categories
- cate
- children
- list
- total
- max_level
required:
- code
- msg
......@@ -199,48 +259,95 @@ paths:
code: 1
msg: 0
data:
categories:
- id: 2769851
name: '11'
cate:
id: 2768724
category_name: 入职相关
category_parent: 0
children:
- id: 2768748
category_name: 入职前
category_parent: 2768724
level: 1
icon: >-
https://cdn.ipadbiz.cn/space_35697/chenggong@2x_Fv8frv6yLpjv_-udOjNbrqWjf7Ro.png
list:
- name: icon-gongfo@2x.png
value: >-
https://cdn.ipadbiz.cn/space_2303465/icon-gongfo@2x_FupcW54dbCtf8Os3VR8-uPxBPZKJ.png
extension: png
post_date: '2025-11-18 09:56:10'
size: 3.08 KB
- name: tit01.1715066891.png
value: >-
https://cdn.ipadbiz.cn/space_2303465/tit01.1715066891_FkZth0fslVSIpN3_sH1QQLCvYG3I.png
extension: png
post_date: '2025-11-06 16:32:45'
size: 23.06 KB
- name: 警告1.png
value: >-
https://cdn.ipadbiz.cn/space_35697/警告_FgcO1_v6jMprMXk8GvWwvAS96Q0b.png
extension: png
post_date: '2025-11-06 16:32:12'
size: 8.16 KB
children:
- id: 2769731
category_name: 考试报名
category_parent: 2768748
level: 2
icon: null
max_depth: 2
- id: 2769881
category_name: 考试资料
category_parent: 2768748
level: 2
icon: null
max_depth: 2
max_depth: 2
- id: 2769882
category_name: 入职中
category_parent: 2768724
level: 1
icon: null
list: []
children:
- id: 2769883
category_name: 各个进度
category_parent: 2769882
level: 2
icon: null
max_depth: 2
max_depth: 2
list:
- id: 2769856
product_name: '22'
recommend: hot
form_sn: customize_jsj_pnzuky
created_time: '2026-02-03 10:36:29'
categories:
- id: '2769851'
name: '11'
tags:
- id: '2769847'
name: '111'
bg_color: '#3e5160'
text_color: '#ffffff'
- id: 2769848
product_name: '1111'
recommend: normal
form_sn: customize_jsj_ivleuz
created_time: '2026-02-02 16:33:01'
categories:
- id: '2769851'
name: '11'
tags:
- id: '2769846'
name: 测试1
bg_color: '#1e9fff'
text_color: '#ffffff'
- id: '2769847'
name: '111'
bg_color: '#3e5160'
text_color: '#ffffff'
- id: 2769845
product_name: '1'
recommend: normal
form_sn: customize_jsj_pnzuky
created_time: '2026-02-02 16:22:26'
categories: []
tags: []
total: 3
- id: 2768730
name: no_banner1.jpg
value: >-
https://cdn.ipadbiz.cn/xiyuan_35697/no_banner1_Ft2CHoVnGHpiT3KNAHkyjTRObgQ1.jpg
extension: jpg
post_date: '2025-11-05 18:30:38'
size: 48.76 KB
- id: 2768729
name: '4444'
value: >-
https://cdn.ipadbiz.cn/xiyuan_35697/no_banner1_Ft2CHoVnGHpiT3KNAHkyjTRObgQ1.jpg
extension: jpg
post_date: '2025-11-05 16:02:07'
size: 48.76 KB
- id: 2768723
name: '1235'
value: >-
https://cdn.ipadbiz.cn/xiyuan_35697/no_banner_FuQDBojRddPWEv0A9hM_ffoddnNC.jpg
extension: jpg
post_date: '2025-11-05 15:10:27'
size: 78.55 KB
- id: 2768711
name: chenggong@2x.png
value: >-
https://cdn.ipadbiz.cn/space_35697/chenggong@2x_Fv8frv6yLpjv_-udOjNbrqWjf7Ro.png
extension: png
post_date: '2025-11-03 13:59:04'
size: 23.08 KB
total: 4
max_level: 2
headers: {}
x-apifox-name: 成功
x-apifox-ordering: 0
......@@ -252,7 +359,9 @@ components:
schemas: {}
responses: {}
securitySchemes: {}
servers: []
servers:
- url: https://manulife.onwall.cn
description: 正式环境
security: []
```
......
import { fn, fetch } from '@/api/fn';
const Api = {
FileList: '/srv/?a=file&t=file_list',
WeekHot: '/srv/?a=file&t=week_hot',
}
/**
* @description 文档列表
* @remark
* @param {Object} params 请求参数
* @param {string} params.client_id (可选) 主体id
* @param {string} params.limit (可选)
* @param {string} params.page (可选)
* @param {string} params.cid (可选) 分类id
* @returns {Promise<{
* code: number; // 状态码
* msg: string; // 消息
* data: {
* cate: {
* id: integer; // 分类id
* category_name: string; // 分类名称
* category_parent: integer; // 分类父级
* icon: string; //
* };
* children: Array<{
* id: integer; // 二级分类id
* category_name: string; // 二级分类名
* category_parent: integer; // 二级分类名父级id
* icon: string; // 二级分类图标
* list: array; // 二级分类的附件列表
* children: array; // 三级分类
* }>;
* list: Array<{
* name: string; // 附件名称
* value: string; // 附件地址
* extension: string; // 后缀名
* post_date: string; // 发布时间
* size: string; // 附件大小
* id: string; // 附件id
* }>;
* total: integer; // 主分类附件数量
* max_level: string; // 层级
* };
* }>}
*/
export const fileListAPI = (params) => fn(fetch.get(Api.FileList, params));
/**
* @description 本周热门资料
* @remark
* @param {Object} params 请求参数
......
import { fn, fetch } from '@/api/fn';
const Api = {
FileList: '/srv/?a=get_file_list&t=file_list',
}
/**
* @description 文档列表
* @remark
* @param {Object} params 请求参数
* @param {string} params.client_id (可选) 主体id
* @param {string} params.limit (可选)
* @param {string} params.page (可选)
* @param {string} params.cid (可选) 分类id
* @returns {Promise<{
* code: number; // 状态码
* msg: string; // 消息
* data: {
* categories: Array<{
* id: integer; // 分类id
* name: string; // 分类名
* }>;
* list: Array<{
* id: integer; // 产品id
* product_name: string; // 产品名
* recommend: string; // 推荐位: normal-普通, hot-热卖
* form_sn: string; //
* created_time: string; // 创建时间
* categories: array; // 产品所属分类
* tags: array; // 产品标签
* }>;
* total: integer; // 产品总数
* };
* }>}
*/
export const fileListAPI = (params) => fn(fetch.get(Api.FileList, params));