# 日历记录API接口 - 前端开发指南

## 版本信息
- **版本**: v1.0.0
- **更新日期**: 2024-01-15
- **适用范围**: DataOps平台日历记录功能

## 概述

本文档提供日历记录相关API接口的详细说明，包括保存日历记录和获取日历记录功能。这些接口用于管理用户的月度日历内容，支持插入新记录和更新现有记录。

## 重要说明

1. **认证方式**: 使用微信用户的 `openid` 作为用户标识
2. **数据格式**: 所有请求和响应均使用 JSON 格式
3. **字符编码**: UTF-8
4. **时区**: 所有时间字段均为东八区时间 (UTC+8)
5. **月份格式**: 统一使用 `YYYY-MM` 格式（如：2024-01）

## API接口列表

| 接口名称 | 请求方法 | 路径 | 功能描述 |
|---------|---------|------|---------|
| 保存日历记录 | POST | `/api/parse/save-calendar-record` | 保存或更新用户日历记录 |
| 获取日历记录 | GET | `/api/parse/get-calendar-record` | 查询用户指定月份的日历记录 |

---

## 1. 保存日历记录接口

### 基本信息
- **接口路径**: `/api/parse/save-calendar-record`
- **请求方法**: `POST`
- **Content-Type**: `application/json`
- **功能**: 保存用户的日历内容记录，如果记录已存在则更新，不存在则创建新记录

### 请求参数

#### 请求头 (Headers)
```http
Content-Type: application/json
```

#### 请求体 (Request Body)
| 参数名 | 类型 | 必填 | 说明 | 示例值 |
|--------|------|------|------|--------|
| openid | string | 是 | 微信用户openid，28位字符串 | "wx_openid_abcd1234567890123456" |
| month_key | string | 是 | 月份标识，格式为YYYY-MM | "2024-01" |
| calendar_content | array | 是 | 日历内容，JSON数组格式 | 见下方示例 |

#### calendar_content 数组元素结构
| 字段名 | 类型 | 必填 | 说明 | 示例值 |
|--------|------|------|------|--------|
| date | string | 否 | 日期，格式为YYYY-MM-DD | "2024-01-01" |
| events | array | 否 | 事件列表，字符串数组 | ["会议", "约会"] |
| notes | string | 否 | 备注信息 | "重要日程" |

### 请求示例

#### JavaScript (Fetch API)
```javascript
async function saveCalendarRecord(openid, monthKey, calendarContent) {
    const url = '/api/parse/save-calendar-record';
    
    const requestData = {
        openid: openid,
        month_key: monthKey,
        calendar_content: calendarContent
    };
    
    try {
        const response = await fetch(url, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
            },
            body: JSON.stringify(requestData)
        });
        
        const result = await response.json();
        
        if (result.return_code === 200) {
            console.log('保存成功:', result.result);
            return { success: true, data: result.result };
        } else {
            console.error('保存失败:', result.error);
            return { success: false, error: result.error };
        }
    } catch (error) {
        console.error('请求异常:', error);
        return { success: false, error: '网络请求失败' };
    }
}

// 使用示例
const calendarData = [
    {
        date: "2024-01-01",
        events: ["元旦节"],
        notes: "新年快乐"
    },
    {
        date: "2024-01-15",
        events: ["会议", "约会"],
        notes: "重要日程"
    }
];

saveCalendarRecord("wx_openid_abcd1234567890123456", "2024-01", calendarData);
```

#### jQuery Ajax
```javascript
function saveCalendarRecord(openid, monthKey, calendarContent) {
    $.ajax({
        url: '/api/parse/save-calendar-record',
        type: 'POST',
        contentType: 'application/json',
        data: JSON.stringify({
            openid: openid,
            month_key: monthKey,
            calendar_content: calendarContent
        }),
        success: function(result) {
            if (result.return_code === 200) {
                console.log('保存成功:', result.result);
            } else {
                console.error('保存失败:', result.error);
            }
        },
        error: function(xhr, status, error) {
            console.error('请求失败:', error);
        }
    });
}
```

#### 微信小程序
```javascript
// 微信小程序保存日历记录
function saveCalendarRecord(openid, monthKey, calendarContent) {
    wx.request({
        url: 'https://your-domain.com/api/parse/save-calendar-record',
        method: 'POST',
        header: {
            'content-type': 'application/json'
        },
        data: {
            openid: openid,
            month_key: monthKey,
            calendar_content: calendarContent
        },
        success: function(res) {
            if (res.data.return_code === 200) {
                console.log('保存成功:', res.data.result);
                wx.showToast({
                    title: '保存成功',
                    icon: 'success'
                });
            } else {
                console.error('保存失败:', res.data.error);
                wx.showToast({
                    title: '保存失败',
                    icon: 'error'
                });
            }
        },
        fail: function(error) {
            console.error('请求失败:', error);
            wx.showToast({
                title: '网络错误',
                icon: 'error'
            });
        }
    });
}
```

### 响应结果

#### 成功响应 (HTTP 200)
```json
{
    "reason": "successed",
    "return_code": 200,
    "result": {
        "id": 1,
        "openid": "wx_openid_abcd1234567890123456",
        "month_key": "2024-01",
        "calendar_content": [
            {
                "date": "2024-01-01",
                "events": ["元旦节"],
                "notes": "新年快乐"
            },
            {
                "date": "2024-01-15",
                "events": ["会议", "约会"],
                "notes": "重要日程"
            }
        ],
        "created_at": "2024-01-15T10:30:00+08:00",
        "updated_at": "2024-01-15T14:30:00+08:00"
    }
}
```

#### 错误响应
```json
{
    "reason": "failed",
    "return_code": 400,
    "result": null,
    "error": "缺少必填参数: openid"
}
```

### 返回码说明
| 返回码 | 说明 | 处理建议 |
|--------|------|---------|
| 200 | 成功 | 继续后续操作 |
| 400 | 请求参数错误 | 检查请求参数格式和必填项 |
| 500 | 服务器内部错误 | 联系技术支持或稍后重试 |

---

## 2. 获取日历记录接口

### 基本信息
- **接口路径**: `/api/parse/get-calendar-record`
- **请求方法**: `GET`
- **功能**: 查询用户指定月份的日历记录

### 请求参数

#### 查询参数 (Query Parameters)
| 参数名 | 类型 | 必填 | 说明 | 示例值 |
|--------|------|------|------|--------|
| openid | string | 是 | 微信用户openid | wx_openid_abcd1234567890123456 |
| month_key | string | 是 | 月份标识，格式为YYYY-MM | 2024-01 |

### 请求示例

#### JavaScript (Fetch API)
```javascript
async function getCalendarRecord(openid, monthKey) {
    const url = `/api/parse/get-calendar-record?openid=${encodeURIComponent(openid)}&month_key=${encodeURIComponent(monthKey)}`;
    
    try {
        const response = await fetch(url, {
            method: 'GET',
            headers: {
                'Content-Type': 'application/json',
            }
        });
        
        const result = await response.json();
        
        if (result.return_code === 200) {
            console.log('查询成功:', result.result);
            return { success: true, data: result.result };
        } else {
            console.error('查询失败:', result.error);
            return { success: false, error: result.error };
        }
    } catch (error) {
        console.error('请求异常:', error);
        return { success: false, error: '网络请求失败' };
    }
}

// 使用示例
getCalendarRecord("wx_openid_abcd1234567890123456", "2024-01")
    .then(result => {
        if (result.success) {
            // 处理成功结果
            const calendarData = result.data;
            if (calendarData.id) {
                console.log('找到日历记录:', calendarData.calendar_content);
            } else {
                console.log('该月份暂无记录');
            }
        } else {
            // 处理错误
            console.error('获取失败:', result.error);
        }
    });
```

#### jQuery Ajax
```javascript
function getCalendarRecord(openid, monthKey) {
    $.ajax({
        url: '/api/parse/get-calendar-record',
        type: 'GET',
        data: {
            openid: openid,
            month_key: monthKey
        },
        success: function(result) {
            if (result.return_code === 200) {
                console.log('查询成功:', result.result);
                if (result.result.id) {
                    // 有记录
                    displayCalendarData(result.result.calendar_content);
                } else {
                    // 无记录
                    displayEmptyCalendar();
                }
            } else {
                console.error('查询失败:', result.error);
            }
        },
        error: function(xhr, status, error) {
            console.error('请求失败:', error);
        }
    });
}
```

#### 微信小程序
```javascript
// 微信小程序获取日历记录
function getCalendarRecord(openid, monthKey) {
    wx.request({
        url: 'https://your-domain.com/api/parse/get-calendar-record',
        method: 'GET',
        data: {
            openid: openid,
            month_key: monthKey
        },
        success: function(res) {
            if (res.data.return_code === 200) {
                console.log('查询成功:', res.data.result);
                const calendarData = res.data.result;
                
                if (calendarData.id) {
                    // 有记录，显示日历内容
                    this.setData({
                        calendarContent: calendarData.calendar_content,
                        hasRecord: true
                    });
                } else {
                    // 无记录，显示空日历
                    this.setData({
                        calendarContent: [],
                        hasRecord: false
                    });
                }
            } else {
                console.error('查询失败:', res.data.error);
                wx.showToast({
                    title: '查询失败',
                    icon: 'error'
                });
            }
        },
        fail: function(error) {
            console.error('请求失败:', error);
            wx.showToast({
                title: '网络错误',
                icon: 'error'
            });
        }
    });
}
```

### 响应结果

#### 有记录时的成功响应 (HTTP 200)
```json
{
    "reason": "successed",
    "return_code": 200,
    "result": {
        "id": 1,
        "openid": "wx_openid_abcd1234567890123456",
        "month_key": "2024-01",
        "calendar_content": [
            {
                "date": "2024-01-01",
                "events": ["元旦节"],
                "notes": "新年快乐"
            },
            {
                "date": "2024-01-15",
                "events": ["会议", "约会"],
                "notes": "重要日程"
            }
        ],
        "created_at": "2024-01-15T10:30:00+08:00",
        "updated_at": "2024-01-15T14:30:00+08:00"
    }
}
```

#### 无记录时的成功响应 (HTTP 200)
```json
{
    "reason": "successed",
    "return_code": 200,
    "result": {
        "id": null,
        "openid": "wx_openid_abcd1234567890123456",
        "month_key": "2024-01",
        "calendar_content": [],
        "created_at": null,
        "updated_at": null
    }
}
```

#### 错误响应
```json
{
    "reason": "failed",
    "return_code": 400,
    "result": null,
    "error": "缺少必填参数: month_key"
}
```

---

## 前端集成指南

### 1. 完整的日历管理类

```javascript
class CalendarRecordManager {
    constructor(baseUrl = '') {
        this.baseUrl = baseUrl;
    }
    
    /**
     * 保存日历记录
     * @param {string} openid - 微信用户openid
     * @param {string} monthKey - 月份标识 (YYYY-MM)
     * @param {Array} calendarContent - 日历内容数组
     * @returns {Promise<Object>} 返回操作结果
     */
    async saveRecord(openid, monthKey, calendarContent) {
        const url = `${this.baseUrl}/api/parse/save-calendar-record`;
        
        try {
            const response = await fetch(url, {
                method: 'POST',
                headers: {
                    'Content-Type': 'application/json',
                },
                body: JSON.stringify({
                    openid: openid,
                    month_key: monthKey,
                    calendar_content: calendarContent
                })
            });
            
            const result = await response.json();
            return {
                success: result.return_code === 200,
                data: result.result,
                error: result.error,
                code: result.return_code
            };
        } catch (error) {
            return {
                success: false,
                data: null,
                error: error.message,
                code: -1
            };
        }
    }
    
    /**
     * 获取日历记录
     * @param {string} openid - 微信用户openid
     * @param {string} monthKey - 月份标识 (YYYY-MM)
     * @returns {Promise<Object>} 返回查询结果
     */
    async getRecord(openid, monthKey) {
        const url = `${this.baseUrl}/api/parse/get-calendar-record?openid=${encodeURIComponent(openid)}&month_key=${encodeURIComponent(monthKey)}`;
        
        try {
            const response = await fetch(url, {
                method: 'GET',
                headers: {
                    'Content-Type': 'application/json',
                }
            });
            
            const result = await response.json();
            return {
                success: result.return_code === 200,
                data: result.result,
                error: result.error,
                code: result.return_code,
                hasRecord: result.result && result.result.id !== null
            };
        } catch (error) {
            return {
                success: false,
                data: null,
                error: error.message,
                code: -1,
                hasRecord: false
            };
        }
    }
    
    /**
     * 格式化月份键
     * @param {Date} date - 日期对象
     * @returns {string} 格式化的月份键 (YYYY-MM)
     */
    formatMonthKey(date = new Date()) {
        const year = date.getFullYear();
        const month = String(date.getMonth() + 1).padStart(2, '0');
        return `${year}-${month}`;
    }
    
    /**
     * 验证月份键格式
     * @param {string} monthKey - 月份键
     * @returns {boolean} 是否有效
     */
    validateMonthKey(monthKey) {
        const pattern = /^\d{4}-\d{2}$/;
        return pattern.test(monthKey);
    }
    
    /**
     * 验证openid格式
     * @param {string} openid - 微信openid
     * @returns {boolean} 是否有效
     */
    validateOpenid(openid) {
        return openid && typeof openid === 'string' && openid.length === 28;
    }
}

// 使用示例
const calendarManager = new CalendarRecordManager();

// 保存记录
async function saveCurrentMonthRecord(openid, events) {
    const monthKey = calendarManager.formatMonthKey(new Date());
    const result = await calendarManager.saveRecord(openid, monthKey, events);
    
    if (result.success) {
        console.log('保存成功:', result.data);
    } else {
        console.error('保存失败:', result.error);
    }
}

// 获取记录
async function loadCurrentMonthRecord(openid) {
    const monthKey = calendarManager.formatMonthKey(new Date());
    const result = await calendarManager.getRecord(openid, monthKey);
    
    if (result.success) {
        if (result.hasRecord) {
            console.log('找到记录:', result.data.calendar_content);
            return result.data.calendar_content;
        } else {
            console.log('暂无记录');
            return [];
        }
    } else {
        console.error('获取失败:', result.error);
        return null;
    }
}
```

### 2. Vue.js 集成示例

```vue
<template>
  <div class="calendar-container">
    <h2>{{ currentMonthText }}日历</h2>
    
    <!-- 日历内容显示 -->
    <div v-if="hasRecord" class="calendar-content">
      <div v-for="item in calendarContent" :key="item.date" class="calendar-item">
        <div class="date">{{ item.date }}</div>
        <div class="events">
          <span v-for="event in item.events" :key="event" class="event-tag">
            {{ event }}
          </span>
        </div>
        <div class="notes">{{ item.notes }}</div>
      </div>
    </div>
    
    <!-- 无记录提示 -->
    <div v-else class="no-record">
      <p>本月暂无日历记录</p>
    </div>
    
    <!-- 操作按钮 -->
    <div class="actions">
      <button @click="loadRecord" :disabled="loading">刷新</button>
      <button @click="saveRecord" :disabled="loading">保存</button>
    </div>
  </div>
</template>

<script>
export default {
  name: 'CalendarRecord',
  data() {
    return {
      openid: 'wx_openid_abcd1234567890123456', // 从登录状态获取
      currentMonth: new Date(),
      calendarContent: [],
      hasRecord: false,
      loading: false
    };
  },
  computed: {
    currentMonthText() {
      return `${this.currentMonth.getFullYear()}年${this.currentMonth.getMonth() + 1}月`;
    },
    monthKey() {
      const year = this.currentMonth.getFullYear();
      const month = String(this.currentMonth.getMonth() + 1).padStart(2, '0');
      return `${year}-${month}`;
    }
  },
  mounted() {
    this.loadRecord();
  },
  methods: {
    async loadRecord() {
      this.loading = true;
      
      try {
        const response = await fetch(`/api/parse/get-calendar-record?openid=${this.openid}&month_key=${this.monthKey}`);
        const result = await response.json();
        
        if (result.return_code === 200) {
          this.hasRecord = result.result.id !== null;
          this.calendarContent = result.result.calendar_content || [];
        } else {
          this.$message.error('获取日历记录失败: ' + result.error);
        }
      } catch (error) {
        this.$message.error('网络请求失败: ' + error.message);
      } finally {
        this.loading = false;
      }
    },
    
    async saveRecord() {
      // 这里应该从表单或编辑器获取要保存的数据
      const dataToSave = [
        {
          date: "2024-01-15",
          events: ["会议", "约会"],
          notes: "重要日程"
        }
      ];
      
      this.loading = true;
      
      try {
        const response = await fetch('/api/parse/save-calendar-record', {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({
            openid: this.openid,
            month_key: this.monthKey,
            calendar_content: dataToSave
          })
        });
        
        const result = await response.json();
        
        if (result.return_code === 200) {
          this.$message.success('保存成功');
          this.loadRecord(); // 重新加载数据
        } else {
          this.$message.error('保存失败: ' + result.error);
        }
      } catch (error) {
        this.$message.error('网络请求失败: ' + error.message);
      } finally {
        this.loading = false;
      }
    }
  }
};
</script>
```

### 3. React 集成示例

```jsx
import React, { useState, useEffect, useCallback } from 'react';

const CalendarRecord = ({ openid }) => {
    const [calendarContent, setCalendarContent] = useState([]);
    const [hasRecord, setHasRecord] = useState(false);
    const [loading, setLoading] = useState(false);
    const [currentMonth, setCurrentMonth] = useState(new Date());
    
    // 格式化月份键
    const formatMonthKey = useCallback((date) => {
        const year = date.getFullYear();
        const month = String(date.getMonth() + 1).padStart(2, '0');
        return `${year}-${month}`;
    }, []);
    
    const monthKey = formatMonthKey(currentMonth);
    
    // 加载日历记录
    const loadRecord = useCallback(async () => {
        setLoading(true);
        
        try {
            const response = await fetch(`/api/parse/get-calendar-record?openid=${openid}&month_key=${monthKey}`);
            const result = await response.json();
            
            if (result.return_code === 200) {
                setHasRecord(result.result.id !== null);
                setCalendarContent(result.result.calendar_content || []);
            } else {
                console.error('获取失败:', result.error);
            }
        } catch (error) {
            console.error('网络错误:', error);
        } finally {
            setLoading(false);
        }
    }, [openid, monthKey]);
    
    // 保存日历记录
    const saveRecord = async (dataToSave) => {
        setLoading(true);
        
        try {
            const response = await fetch('/api/parse/save-calendar-record', {
                method: 'POST',
                headers: {
                    'Content-Type': 'application/json',
                },
                body: JSON.stringify({
                    openid: openid,
                    month_key: monthKey,
                    calendar_content: dataToSave
                })
            });
            
            const result = await response.json();
            
            if (result.return_code === 200) {
                console.log('保存成功');
                loadRecord(); // 重新加载
            } else {
                console.error('保存失败:', result.error);
            }
        } catch (error) {
            console.error('网络错误:', error);
        } finally {
            setLoading(false);
        }
    };
    
    useEffect(() => {
        if (openid) {
            loadRecord();
        }
    }, [openid, loadRecord]);
    
    return (
        <div className="calendar-container">
            <h2>{currentMonth.getFullYear()}年{currentMonth.getMonth() + 1}月日历</h2>
            
            {hasRecord ? (
                <div className="calendar-content">
                    {calendarContent.map((item, index) => (
                        <div key={index} className="calendar-item">
                            <div className="date">{item.date}</div>
                            <div className="events">
                                {item.events?.map((event, idx) => (
                                    <span key={idx} className="event-tag">{event}</span>
                                ))}
                            </div>
                            <div className="notes">{item.notes}</div>
                        </div>
                    ))}
                </div>
            ) : (
                <div className="no-record">
                    <p>本月暂无日历记录</p>
                </div>
            )}
            
            <div className="actions">
                <button onClick={loadRecord} disabled={loading}>
                    {loading ? '加载中...' : '刷新'}
                </button>
            </div>
        </div>
    );
};

export default CalendarRecord;
```

---

## 错误处理指南

### 常见错误码及处理方案

| 错误码 | 错误信息 | 原因 | 解决方案 |
|--------|---------|------|---------|
| 400 | 请求体不能为空 | POST请求未提供请求体 | 检查请求体格式 |
| 400 | 缺少必填参数: openid | 未提供openid参数 | 确保传递有效的openid |
| 400 | 缺少必填参数: month_key | 未提供month_key参数 | 确保传递正确格式的月份键 |
| 400 | 缺少必填参数: calendar_content | 未提供calendar_content参数 | 确保传递日历内容数组 |
| 400 | 无效的openid格式 | openid格式不正确 | 检查openid是否为28位字符串 |
| 400 | 无效的月份格式 | month_key格式错误 | 确保使用YYYY-MM格式 |
| 500 | 数据库连接失败 | 服务器数据库问题 | 联系技术支持 |
| 500 | 服务器内部错误 | 其他服务器错误 | 稍后重试或联系技术支持 |

### 错误处理最佳实践

```javascript
async function handleApiCall(apiFunction) {
    try {
        const result = await apiFunction();
        
        switch (result.code) {
            case 200:
                return { success: true, data: result.data };
                
            case 400:
                // 参数错误，显示具体错误信息
                console.warn('参数错误:', result.error);
                return { success: false, error: result.error, needsRetry: false };
                
            case 500:
                // 服务器错误，可以重试
                console.error('服务器错误:', result.error);
                return { success: false, error: '服务器暂时不可用，请稍后重试', needsRetry: true };
                
            default:
                console.error('未知错误:', result.error);
                return { success: false, error: '操作失败，请重试', needsRetry: true };
        }
    } catch (error) {
        console.error('网络错误:', error);
        return { success: false, error: '网络连接失败，请检查网络', needsRetry: true };
    }
}

// 带重试的API调用
async function apiCallWithRetry(apiFunction, maxRetries = 3) {
    for (let attempt = 1; attempt <= maxRetries; attempt++) {
        const result = await handleApiCall(apiFunction);
        
        if (result.success || !result.needsRetry) {
            return result;
        }
        
        if (attempt < maxRetries) {
            console.log(`第${attempt}次尝试失败，${1000 * attempt}ms后重试...`);
            await new Promise(resolve => setTimeout(resolve, 1000 * attempt));
        }
    }
    
    return { success: false, error: '多次重试失败，请稍后再试' };
}
```

---

## 开发环境配置

### 环境变量配置

在开发环境中，需要配置以下环境变量：

```bash
# .env.development
REACT_APP_API_BASE_URL=http://localhost:5000
VUE_APP_API_BASE_URL=http://localhost:5000

# .env.production  
REACT_APP_API_BASE_URL=https://your-production-domain.com
VUE_APP_API_BASE_URL=https://your-production-domain.com
```

### 代理配置

#### Webpack Dev Server (React/Vue)
```javascript
// webpack.config.js 或 vue.config.js
module.exports = {
  devServer: {
    proxy: {
      '/api': {
        target: 'http://localhost:5000',
        changeOrigin: true,
        secure: false
      }
    }
  }
};
```

#### Create React App
```javascript
// package.json
{
  "name": "your-app",
  "proxy": "http://localhost:5000",
  // ...
}
```

---

## 测试用例

### 单元测试示例

```javascript
// calendar-api.test.js
import { CalendarRecordManager } from './calendar-manager';

describe('CalendarRecordManager', () => {
    let manager;
    const mockOpenid = 'wx_openid_test1234567890123456';
    const mockMonthKey = '2024-01';
    
    beforeEach(() => {
        manager = new CalendarRecordManager();
        // Mock fetch
        global.fetch = jest.fn();
    });
    
    afterEach(() => {
        jest.resetAllMocks();
    });
    
    test('保存日历记录 - 成功', async () => {
        const mockResponse = {
            reason: 'successed',
            return_code: 200,
            result: {
                id: 1,
                openid: mockOpenid,
                month_key: mockMonthKey,
                calendar_content: [
                    {
                        date: '2024-01-01',
                        events: ['测试事件'],
                        notes: '测试备注'
                    }
                ]
            }
        };
        
        fetch.mockResolvedValueOnce({
            json: async () => mockResponse
        });
        
        const result = await manager.saveRecord(mockOpenid, mockMonthKey, [
            {
                date: '2024-01-01',
                events: ['测试事件'],
                notes: '测试备注'
            }
        ]);
        
        expect(result.success).toBe(true);
        expect(result.data.id).toBe(1);
        expect(fetch).toHaveBeenCalledWith(
            '/api/parse/save-calendar-record',
            expect.objectContaining({
                method: 'POST',
                headers: {
                    'Content-Type': 'application/json',
                },
                body: JSON.stringify({
                    openid: mockOpenid,
                    month_key: mockMonthKey,
                    calendar_content: [
                        {
                            date: '2024-01-01',
                            events: ['测试事件'],
                            notes: '测试备注'
                        }
                    ]
                })
            })
        );
    });
    
    test('获取日历记录 - 有记录', async () => {
        const mockResponse = {
            reason: 'successed',
            return_code: 200,
            result: {
                id: 1,
                openid: mockOpenid,
                month_key: mockMonthKey,
                calendar_content: [
                    {
                        date: '2024-01-01',
                        events: ['测试事件'],
                        notes: '测试备注'
                    }
                ]
            }
        };
        
        fetch.mockResolvedValueOnce({
            json: async () => mockResponse
        });
        
        const result = await manager.getRecord(mockOpenid, mockMonthKey);
        
        expect(result.success).toBe(true);
        expect(result.hasRecord).toBe(true);
        expect(result.data.calendar_content).toHaveLength(1);
    });
    
    test('获取日历记录 - 无记录', async () => {
        const mockResponse = {
            reason: 'successed',
            return_code: 200,
            result: {
                id: null,
                openid: mockOpenid,
                month_key: mockMonthKey,
                calendar_content: [],
                created_at: null,
                updated_at: null
            }
        };
        
        fetch.mockResolvedValueOnce({
            json: async () => mockResponse
        });
        
        const result = await manager.getRecord(mockOpenid, mockMonthKey);
        
        expect(result.success).toBe(true);
        expect(result.hasRecord).toBe(false);
        expect(result.data.calendar_content).toEqual([]);
    });
    
    test('参数验证 - 无效的openid', async () => {
        const isValid = manager.validateOpenid('invalid_openid');
        expect(isValid).toBe(false);
    });
    
    test('参数验证 - 有效的openid', async () => {
        const isValid = manager.validateOpenid(mockOpenid);
        expect(isValid).toBe(true);
    });
    
    test('月份键格式化', () => {
        const date = new Date('2024-01-15');
        const monthKey = manager.formatMonthKey(date);
        expect(monthKey).toBe('2024-01');
    });
    
    test('月份键验证 - 有效格式', () => {
        expect(manager.validateMonthKey('2024-01')).toBe(true);
        expect(manager.validateMonthKey('2024-12')).toBe(true);
    });
    
    test('月份键验证 - 无效格式', () => {
        expect(manager.validateMonthKey('2024-1')).toBe(false);
        expect(manager.validateMonthKey('24-01')).toBe(false);
        expect(manager.validateMonthKey('2024/01')).toBe(false);
    });
});
```

---

## 性能优化建议

### 1. 请求优化
- 使用防抖（debounce）避免频繁保存
- 实现本地缓存减少重复请求
- 使用 Loading 状态提升用户体验

### 2. 数据处理优化
- 对大量日历数据进行分页处理
- 使用虚拟滚动处理长列表
- 实现增量更新而非全量替换

### 3. 缓存策略
```javascript
class CachedCalendarManager extends CalendarRecordManager {
    constructor(baseUrl = '', cacheTimeout = 5 * 60 * 1000) { // 5分钟缓存
        super(baseUrl);
        this.cache = new Map();
        this.cacheTimeout = cacheTimeout;
    }
    
    getCacheKey(openid, monthKey) {
        return `${openid}:${monthKey}`;
    }
    
    async getRecord(openid, monthKey) {
        const cacheKey = this.getCacheKey(openid, monthKey);
        const cached = this.cache.get(cacheKey);
        
        // 检查缓存是否有效
        if (cached && Date.now() - cached.timestamp < this.cacheTimeout) {
            return cached.data;
        }
        
        // 从服务器获取数据
        const result = await super.getRecord(openid, monthKey);
        
        // 缓存成功结果
        if (result.success) {
            this.cache.set(cacheKey, {
                data: result,
                timestamp: Date.now()
            });
        }
        
        return result;
    }
    
    async saveRecord(openid, monthKey, calendarContent) {
        const result = await super.saveRecord(openid, monthKey, calendarContent);
        
        // 保存成功后清除缓存
        if (result.success) {
            const cacheKey = this.getCacheKey(openid, monthKey);
            this.cache.delete(cacheKey);
        }
        
        return result;
    }
    
    clearCache(openid = null, monthKey = null) {
        if (openid && monthKey) {
            // 清除特定缓存
            const cacheKey = this.getCacheKey(openid, monthKey);
            this.cache.delete(cacheKey);
        } else {
            // 清除所有缓存
            this.cache.clear();
        }
    }
}
```

---

## 联系与支持

如有技术问题或需要支持，请联系：

- **技术支持邮箱**: support@dataops-platform.com
- **开发文档**: https://docs.dataops-platform.com
- **API更新日志**: https://docs.dataops-platform.com/changelog

---

## 更新日志

### v1.0.0 (2024-01-15)
- 初始版本发布
- 支持保存日历记录功能
- 支持获取日历记录功能
- 提供完整的前端集成示例
- 包含错误处理和性能优化建议