📅 Ralendar - Roamio 生态智能日历

Ralendar = Roamio + Calendar
让每一个时刻都有意义，让每一次旅行都有计划。

Ralendar 是一个现代化的智能日历应用，集成了日程管理、AI助手、地图定位、天气查询等丰富功能，支持 Android、Web、AcWing 三端同步，是 Roamio 生态系统的核心组件之一。

📋 目录

核心功能
技术架构
快速开始
在线演示
项目结构
API 文档
部署指南
开发文档
项目进度
贡献指南

✨ 核心功能

📅 日历视图

月视图：整月日历网格，支持日期标记、节日显示、日程预览
周视图：横向7天选择器 + 24小时时间线，便于查看一周安排
日视图：详细时间线视图，精确到小时级别
流畅切换：三种视图模式一键切换，动画过渡自然

✏️ 日程管理

完整 CRUD：添加、编辑、查看、删除日程
丰富信息：标题、描述、日期时间、提醒设置、地点位置
智能提醒：基于 AlarmManager 的系统级提醒，支持自定义提前时间（5分钟/15分钟/30分钟/1小时/1天）
地图集成：支持地点搜索、地图选点、经纬度定位、一键导航
重复事件：支持重复日程设置

🤖 AI 智能助手

自然语言解析：支持自然语言输入创建日程
- 示例："明天下午3点开会" → 自动解析为结构化日程
智能日程总结：AI 自动总结日程安排，提供时间管理建议
对话式管理：支持与 AI 对话查询日程、创建日程、获取建议
节日问答：向 AI 提问节日相关问题，获取节日历史、习俗、美食等信息

🌐 多端同步

Android 原生应用：Kotlin + Room 数据库，Material Design 3 设计
Web 管理界面：Vue 3 + Element Plus，现代化响应式设计
AcWing 平台集成：Vue 3 + Vuex，无缝集成 AcWing 生态
数据同步：本地优先策略，云端自动备份，离线可用

🔐 多种登录方式

普通账号：邮箱注册登录
AcWing 一键登录：OAuth 2.0 集成
QQ 互联登录：UnionID 跨应用识别
账号绑定管理：支持绑定/解绑多个账号

🏮 特色功能

农历显示：支持中国传统节日、农历日期转换
网络订阅：公共日历订阅、节日订阅、订阅管理
天气查询：实时天气信息、自动定位、体感温度
运势查询：每日运势（综合/爱情/事业/财运/健康）
个人中心：用户信息管理、账号绑定、统计数据
生态融合：与 Roamio 旅行平台深度集成，旅行计划自动同步为日程

🏗️ 技术架构

系统架构图

┌─────────────────────────────────────────────────────────┐
│                     Ralendar 架构                        │
└─────────────────────────────────────────────────────────┘

    ┌──────────┐  ┌──────────┐  ┌──────────┐
    │ Web 端   │  │ AcApp端  │  │Android端 │
    │ (Vue 3)  │  │ (Vue 3)  │  │ (Kotlin) │
    └────┬─────┘  └────┬─────┘  └────┬─────┘
         │             │             │
         └─────────────┼─────────────┘
                       │ HTTPS / REST API
                       │ (app7626.acapp.acwing.com.cn)
                       ▼
    ┌─────────────────────────────────────────────────────┐
    │            ☁️ 阿里云 ECS 服务器                      │
    │         (47.121.137.60 / Ubuntu 20.04)             │
    ├─────────────────────────────────────────────────────┤
    │  ┌──────────────────────────────────────────────┐   │
    │  │         Nginx (反向代理 + SSL)               │   │
    │  └──────────────────┬───────────────────────────┘   │
    │                     ▼                               │
    │  ┌──────────────────────────────────────────────┐   │
    │  │         Docker 容器化部署                     │   │
    │  │  ┌────────────────────────────────────────┐  │   │
    │  │  │  Django REST Framework + uWSGI         │  │   │
    │  │  │  ┌────────────────────────────────────┐│  │   │
    │  │  │  │ Events │ Auth │ OAuth │ Lunar │ API││  │   │
    │  │  │  └──────────────┬─────────────────────┘│  │   │
    │  │  └──────────────────┼───────────────────────┘  │   │
    │  └──────────────────────┼───────────────────────────┘   │
    │                         ▼                               │
    │  ┌──────────────────────────────────────────────┐   │
    │  │    SQLite (生产) / PostgreSQL (可选)          │   │
    │  └──────────────────────────────────────────────┘   │
    └─────────────────────────────────────────────────────┘
                       ▲
                       │ 数据同步
                       │
    ┌─────────────────────────────────────────────────────┐
    │              Android 本地存储                        │
    │  ┌──────────────────────────────────────────────┐   │
    │  │         Room Database (SQLite)                │   │
    │  │  - 离线优先策略                               │   │
    │  │  - 自动云端同步                               │   │
    │  └──────────────────────────────────────────────┘   │
    └─────────────────────────────────────────────────────┘

    ┌─────────────────────────────────────────────────────┐
    │               ☁️ 其他云服务                         │
    │  - 腾讯云 COS (文件存储，可选)                      │
    │  - AcWing 云平台 (域名 + HTTPS + CDN)              │
    │  - 阿里云通义千问 (AI 服务)                         │
    │  - 百度地图 / 高德地图 (地图服务)                   │
    └─────────────────────────────────────────────────────┘

技术栈

后端技术栈

框架：Django 4.2 + Django REST Framework 3.15
认证：JWT (Simple JWT) + OAuth 2.0
数据库：SQLite (生产) / PostgreSQL (可选)
异步任务：Celery 5.2 + Redis 4.3
API 文档：Django REST Framework 自动生成
部署：Docker + Nginx + uWSGI

Android 技术栈

语言：Kotlin 1.9+
架构：MVVM + Repository 模式
数据库：Room Database (SQLite)
网络：Retrofit 2 + OkHttp
UI：Material Design 3
异步：Kotlin Coroutines + Flow
地图：百度地图 SDK

Web 前端技术栈

框架：Vue 3 + Vite
UI 组件：Element Plus
日历组件：FullCalendar
HTTP 客户端：Axios
状态管理：Vuex (AcApp) / Pinia (Web)

AcApp 前端技术栈

框架：Vue 3 + Vue CLI
状态管理：Vuex
平台集成：AcWing SDK

设计模式

Repository 模式：统一数据访问接口，支持本地/云端切换
Manager 模式：业务逻辑封装，职责清晰
Facade 模式：统一 API 接口，简化调用
MVVM 架构：UI 与业务逻辑分离

🚀 快速开始

前置要求

Python 3.8+
Node.js 20+
Android Studio (Android 开发)
Git

1. 克隆项目

git clone https://github.com/ppshuX/Ralendar.git
cd Ralendar

2. 后端设置

cd backend

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 安装依赖
pip install -r requirements.txt

# 配置环境变量
cp .env.example .env
# 编辑 .env 文件，填入你的配置（见下方环境变量说明）

# 数据库迁移
python manage.py migrate

# 创建超级用户（可选）
python manage.py createsuperuser

# 启动开发服务器
python manage.py runserver

后端将运行在 http://localhost:8000

环境变量配置 (.env)

# ==================== Django 基础配置 ====================
SECRET_KEY=your-secret-key-here
DEBUG=True
ENVIRONMENT=development  # development 或 production

# ==================== 数据库配置 ====================
# 开发环境使用 SQLite（默认），生产环境使用 MySQL
DB_ENGINE=mysql  # 或 sqlite3
DB_NAME=ralendar_db
DB_USER=ralendar_user
DB_PASSWORD=your-password
DB_HOST=localhost
DB_PORT=3306

# ==================== OAuth 配置 ====================
# AcWing OAuth
ACWING_APPID=7626
ACWING_SECRET=your-acwing-secret

# QQ OAuth
QQ_APPID=your-qq-appid
QQ_APPKEY=your-qq-appkey

# ==================== Celery 配置 ====================
CELERY_BROKER_URL=redis://localhost:6379/0
CELERY_RESULT_BACKEND=redis://localhost:6379/0

# ==================== 邮件配置 ====================
EMAIL_HOST=smtp.qq.com
EMAIL_PORT=587
EMAIL_USE_TLS=True
EMAIL_HOST_USER=your-email@qq.com
EMAIL_HOST_PASSWORD=your-smtp-password
DEFAULT_FROM_EMAIL=Ralendar <your-email@qq.com>

# ==================== 第三方服务 API Key ====================
# 百度地图
BAIDU_MAP_AK=your-baidu-map-api-key

# 高德地图（天气服务）
AMAP_API_KEY=your-amap-api-key

# 阿里云通义千问（AI 助手）
QWEN_API_KEY=your-qwen-api-key

启动 Celery（邮件提醒需要）

# 启动 Celery Worker（处理异步任务）
celery -A calendar_backend worker --loglevel=info

# 启动 Celery Beat（定时任务调度）
celery -A calendar_backend beat --loglevel=info

注意：邮件提醒功能需要 Celery 服务运行。

3. Web 前端设置

cd web_frontend

# 安装依赖
npm install

# 配置环境变量（可选）
# 创建 .env 文件，配置 API 地址等

# 启动开发服务器
npm run dev

Web 前端将运行在 http://localhost:5173

4. AcApp 前端设置

cd acapp_frontend

# 安装依赖
npm install

# 启动开发服务器
npm run serve

5. Android 应用设置

使用 Android Studio 打开 adapp 目录
配置 local.properties，设置 SDK 路径
同步 Gradle 依赖
运行应用

注意：Android 应用需要配置百度地图 API Key（可选，用于地图功能）

🌐 在线演示

Web 端: https://app7626.acapp.acwing.com.cn
AcApp: 在 AcWing 平台搜索 "Ralendar" 或 App ID: 7626
API 地址: https://app7626.acapp.acwing.com.cn/api
API 文档: https://app7626.acapp.acwing.com.cn/api/docs/ (如果配置了 DRF 文档)

部署信息

服务器：阿里云 ECS (Ubuntu 20.04)
部署方式：Docker 容器化部署
域名：AcWing 云应用平台托管
数据库：SQLite (生产环境) / PostgreSQL (可选)
反向代理：Nginx + uWSGI
SSL 证书：AcWing 平台自动配置

📁 项目结构

Ralendar/
├── adapp/                    # Android 应用
│   ├── app/                  # 应用主模块
│   │   └── src/main/
│   │       ├── java/         # Kotlin 源代码
│   │       │   └── com/ncu/kotlincalendar/
│   │       │       ├── data/          # 数据层
│   │       │       │   ├── managers/  # Manager 类
│   │       │       │   ├── repository/# Repository 类
│   │       │       │   └── database/  # Room 数据库
│   │       │       ├── ui/            # UI 层
│   │       │       │   └── dialogs/   # 对话框组件
│   │       │       ├── api/           # 网络层
│   │       │       │   └── services/  # API 服务接口
│   │       │       └── utils/          # 工具类
│   │       └── res/          # 资源文件
│   └── 产品报告/             # 产品报告文档
│
├── backend/                  # Django 后端
│   ├── api/                  # API 应用
│   │   ├── models/          # 数据模型
│   │   │   ├── event.py     # Event 模型（日程事件）
│   │   │   ├── user.py      # User 扩展模型（AcWingUser, QQUser, UserMapping）
│   │   │   └── calendar_data.py  # 节假日、黄历、运势模型
│   │   ├── views/           # 视图层（按功能模块组织）
│   │   │   ├── auth/        # 认证相关（注册、登录、OAuth）
│   │   │   ├── calendar/    # 日历核心（Events, Calendars）
│   │   │   ├── external/    # 外部服务（农历、节假日、天气、运势）
│   │   │   ├── ai/          # AI 助手（通义千问集成）
│   │   │   ├── integration/ # 第三方集成（Roamio Fusion API）
│   │   │   └── oauth/       # OAuth 2.0 服务器（授权、令牌、用户信息）
│   │   ├── url_patterns/    # URL 路由（模块化）
│   │   │   ├── auth.py      # 认证路由
│   │   │   ├── user.py      # 用户中心路由
│   │   │   ├── fusion.py    # 融合功能路由
│   │   │   ├── oauth.py     # OAuth 路由
│   │   │   └── utils.py     # 工具类路由
│   │   ├── serializers.py   # 序列化器
│   │   ├── tasks.py         # Celery 异步任务（邮件提醒）
│   │   ├── middleware/      # 中间件
│   │   └── utils/           # 工具模块
│   ├── calendar_backend/    # Django 项目配置
│   │   ├── settings.py      # 配置文件
│   │   ├── urls.py          # 主路由
│   │   ├── celery.py        # Celery 配置
│   │   ├── wsgi.py          # WSGI 配置
│   │   └── asgi.py          # ASGI 配置
│   ├── templates/           # 模板文件（OAuth 回调页面等）
│   ├── static/              # 静态文件（collectstatic 生成）
│   ├── requirements.txt     # Python 依赖
│   ├── manage.py            # Django 管理脚本
│   ├── uwsgi.ini            # uWSGI 配置
│   ├── nginx.conf            # Nginx 配置示例
│   └── start_celery.sh      # Celery 启动脚本
│
├── web_frontend/            # Web 前端
│   ├── src/
│   │   ├── components/      # Vue 组件（按功能分类）
│   │   │   ├── auth/        # 认证组件（LoginForm, RegisterForm, OAuthButtons）
│   │   │   ├── profile/     # 个人中心组件（UserHeader, UserStats, AccountBindings）
│   │   │   ├── calendar/    # 日历组件（Toolbar, EventDialog, EventDetail）
│   │   │   ├── NavBar.vue   # 导航栏
│   │   │   └── ContentField.vue  # 内容容器
│   │   ├── views/           # 页面视图
│   │   │   ├── account/     # 账号相关（LoginView, ProfileView, OAuth 回调）
│   │   │   └── CalendarView.vue  # 日历主页
│   │   ├── router/          # 路由配置
│   │   ├── api/             # API 调用封装
│   │   ├── store/           # Pinia 状态管理
│   │   └── main.js          # 入口文件
│   ├── package.json
│   └── vite.config.js       # Vite 构建配置
│
├── acapp_frontend/          # AcApp 前端
│   ├── src/
│   │   ├── components/      # Vue 组件
│   │   ├── views/           # 页面视图
│   │   ├── store/           # Vuex 状态管理
│   │   └── App.vue          # 根组件
│   ├── package.json
│   └── vue.config.js        # Vue CLI 配置
│
├── docs/                    # 项目文档
│   ├── api/                 # API 文档
│   │   └── ROAMIO_ECOSYSTEM_API_DOCUMENTATION.md  # 完整 API 文档
│   ├── guides/              # 开发指南
│   │   ├── QUICK_START.md   # 快速开始
│   │   ├── DEPLOYMENT_GUIDE.md  # 部署指南
│   │   ├── ACWING_LOGIN_GUIDE.md  # AcWing 登录指南
│   │   ├── BAIDU_MAP_SETUP.md  # 百度地图配置
│   │   └── EMAIL_REMINDER_GUIDE.md  # 邮件提醒配置
│   ├── architecture/        # 架构文档
│   │   ├── ARCHITECTURE.md  # 系统架构
│   │   └── Component_Structure.md  # 组件结构
│   ├── integration/         # 集成文档
│   │   ├── ROAMIO_INTEGRATION_GUIDE.md  # Roamio 集成指南
│   │   └── ROAMIO_QUICKSTART.md  # 快速集成
│   ├── features/            # 功能文档
│   │   ├── HOLIDAY_SYNC_GUIDE.md  # 节假日同步
│   │   └── DJANGO_ADMIN_GUIDE.md  # Django Admin 使用
│   └── INDEX.md             # 文档索引
│
└── README.md                # 项目说明（本文档）

📚 API 文档

主要 API 端点

认证相关

POST /api/auth/register/ - 用户注册
- 请求体: {username, password, email?}
- 响应: {id, username, email, access, refresh}
POST /api/auth/login/ - 用户登录
- 请求体: {username, password}
- 响应: {access, refresh, user}
POST /api/auth/refresh/ - 刷新 Token
- 请求体: {refresh}
- 响应: {access}
GET /api/auth/me/ - 获取当前用户信息（需要认证）
POST /api/auth/acwing/login/ - AcWing OAuth 登录
- 请求体: {code, state?}
POST /api/auth/qq/login/ - QQ OAuth 登录
- 请求体: {code, state?}
- 支持 UnionID 跨应用识别

日程管理

GET /api/events/ - 获取日程列表
- 查询参数: start_date?, end_date?, page?, page_size?
- 响应: [{id, title, start_time, end_time, location, ...}]
POST /api/events/ - 创建日程
- 请求体: {title, start_time, end_time?, description?, location?, latitude?, longitude?, reminder_minutes?, email_reminder?}
- 响应: {id, title, start_time, ...}
GET /api/events/{id}/ - 获取日程详情
PUT /api/events/{id}/ - 更新日程（完整更新）
PATCH /api/events/{id}/ - 更新日程（部分更新）
DELETE /api/events/{id}/ - 删除日程

用户中心

GET /api/user/stats/ - 获取用户统计（需要认证）
- 响应: {total_events, today_events, upcoming_events}
GET /api/user/bindings/ - 获取账号绑定状态
- 响应: {has_acwing, has_qq, has_password, ...}
PATCH /api/user/profile/ - 更新个人信息
POST /api/user/change-password/ - 修改密码
DELETE /api/user/unbind/acwing/ - 解绑 AcWing
DELETE /api/user/unbind/qq/ - 解绑 QQ

AI 助手

POST /api/ai/parse-event/ - 自然语言解析日程
- 请求体: {text: "明天下午3点开会"}
- 响应: {title, start_time, location?, ...}
POST /api/ai/summarize/ - 智能总结日程
- 请求体: {start_date?, end_date?}
- 响应: {summary, suggestions}
POST /api/ai/chat/ - AI 对话
- 请求体: {message, context?}

外部服务

GET /api/lunar/ - 获取农历信息
- 查询参数: year, month, day 或 date=YYYY-MM-DD
- 响应: {lunarDate, year, month, day, isleap}
GET /api/holidays/check/ - 检查节假日
- 查询参数: date=YYYY-MM-DD 或 year=YYYY
GET /api/fortune/ - 获取每日运势
- 查询参数: date?（可选，默认为今天）
GET /api/weather/ - 获取天气信息
- 查询参数: city?, latitude?, longitude?

融合功能 (Roamio)

POST /api/fusion/events/batch/ - 批量创建日程（用于 Roamio 同步）
- 请求体: {source_app: "roamio", source_id, related_trip_slug, events: [...]}
- 支持跨应用 Token 认证（通过 UnionID 匹配用户）
GET /api/fusion/events/by-trip/{slug}/ - 按旅行查询日程
- 响应: {count, trip_slug, events: [...]}
POST /api/fusion/sync/from-roamio/ - 从 Roamio 同步
- 请求体: {trip_slug, activities: [...]}

OAuth 2.0 服务器端点

GET /api/oauth2/receive_code/ - AcWing OAuth 回调（特殊端点）
- 返回纯 JSON（不是 HTML），供 AcWingOS API 调用

API 认证方式

所有需要认证的端点使用 JWT Bearer Token：

Authorization: Bearer <access_token>

Token 生命周期：

Access Token: 5 分钟（短期，安全）
Refresh Token: 15 天（长期，便利）

API 响应格式

成功响应：

{
  "id": 1,
  "title": "会议",
  "start_time": "2025-11-07T14:00:00Z",
  ...
}

错误响应：

{
  "error": "错误描述",
  "error_code": "ERROR_CODE",
  "details": {...}
}

完整 API 文档请查看：API 文档

🗄️ 数据模型

Event（日程事件）

核心字段：

user - 所属用户（ForeignKey）
title - 标题（CharField, max_length=200）
description - 描述（TextField）
start_time - 开始时间（DateTimeField）
end_time - 结束时间（DateTimeField, 可选）
location - 地点名称（CharField）
latitude / longitude - 经纬度坐标（FloatField）
map_provider - 地图服务商（baidu/amap/tencent）
reminder_minutes - 提前提醒分钟数（IntegerField, 默认15）
email_reminder - 是否邮件提醒（BooleanField）
notification_sent - 提醒已发送标记（BooleanField）

Roamio 融合字段：

source_app - 来源应用（ralendar/roamio）
source_id - 来源对象ID（用于追踪原始数据）
related_trip_slug - 关联旅行计划Slug

属性方法：

map_url - 生成地图导航链接（根据 map_provider）
has_location - 是否有地理位置
is_from_roamio - 是否来自 Roamio

User（用户）

Django 内置 User 模型，扩展：

AcWingUser（一对一）：

openid - AcWing OpenID（唯一）
access_token / refresh_token - OAuth 令牌
photo_url - 头像URL

QQUser（一对一）：

openid - QQ OpenID（唯一）
unionid - QQ UnionID（跨应用识别，已索引）
nickname - QQ昵称
photo_url - 头像URL

UserMapping（用户映射表，用于 Roamio 融合）：

ralendar_user - Ralendar 用户（一对一）
roamio_user_id - Roamio 用户ID
qq_unionid - QQ UnionID（统一标识）
sync_enabled - 是否启用同步

数据库索引

优化查询性能的索引：

event_user_start_idx - (user, start_time)
event_source_idx - (source_app, source_id)
event_trip_idx - (related_trip_slug)
qquser_unionid_idx - (unionid)

☁️ 云资源使用

本项目使用了以下云服务资源：

云服务器

阿里云 ECS - 后端 API 服务部署
- 服务器 IP: 47.121.137.60
- 操作系统: Ubuntu 20.04
- 部署方式: Docker 容器化部署
- 用途: Django 后端服务、Nginx 反向代理

云数据库

SQLite - 本地数据库（开发/测试环境，当前生产环境使用）
MySQL - 云端数据库（生产环境，可选）
- 支持数据持久化和高并发访问
- 可配置为与 Roamio 共享数据库（深度集成方案）

云存储

腾讯云 COS - 对象存储服务（可选）
- 用于存储用户上传的文件、图片等静态资源

云平台

AcWing 云应用平台 - 应用托管和域名服务
- 域名: https://app7626.acapp.acwing.com.cn
- 提供 HTTPS 证书和 CDN 加速

第三方服务

阿里云通义千问 - AI 智能助手服务
- 自然语言解析、日程总结、对话功能
百度地图 / 高德地图 - 地图定位和导航服务
- 地点搜索、坐标转换、导航链接生成
高德天气 API - 天气查询服务
- 实时天气、体感温度、未来预报

数据同步策略

本地优先 - Android 端使用 Room 数据库本地存储
云端备份 - 通过 REST API 同步到云端服务器
离线支持 - 本地数据可离线访问，联网时自动同步
冲突解决 - 以服务器数据为准（可扩展为时间戳比较）

📖 开发文档

完整文档位于 docs/ 目录：

快速开始

📖 文档入口
🚀 快速开始指南

API 文档

🌐 完整 API 文档
🔗 融合 API 指南

开发指南

集成文档

🔗 Roamio 集成指南
🔐 OAuth 集成

产品报告

📊 项目进度

当前版本: v1.0.0
完成度: 约 88%

模块	状态	完成度
基础架构	✅ 完成	100%
用户认证	✅ 完成	98%
日程管理	✅ 完成	90%
多端适配	✅ 完成	85%
个人中心	✅ 完成	95%
地图功能	✅ 完成	85%
AI 助手	✅ 完成	80%
生态融合	🚧 进行中	40%

已完成功能 ✅

✅ 日历视图（月/周/日三种视图）
✅ 日程 CRUD（增删改查）
✅ 提醒功能（AlarmManager）
✅ 网络订阅（公共日历、节日订阅）
✅ 农历显示
✅ AI 智能助手（自然语言解析、日程总结、对话）
✅ 地图定位（地点搜索、地图选点、导航）
✅ 天气查询
✅ 运势查询
✅ 多端同步（Android/Web/AcApp）
✅ OAuth 登录（AcWing/QQ）
✅ 云端部署

进行中 🚧

🚧 Roamio 生态融合（部分完成）
- ✅ Fusion API 已实现（批量创建、按旅行查询）
- ✅ UnionID 跨应用用户识别
- 🚧 共享数据库方案（待 Roamio 团队提供配置）
🚧 ICS 格式导入导出（规划中）
🚧 黄历功能（待实现）
🚧 每日运势（待实现）

技术特性

认证系统

JWT Token 认证：Access Token（5分钟）+ Refresh Token（15天）
OAuth 2.0 支持：AcWing、QQ 一键登录
UnionID 跨应用识别：QQ 登录支持 UnionID，实现 Roamio 和 Ralendar 账号互通
账号绑定管理：支持绑定/解绑多个第三方账号

异步任务系统

Celery + Redis：处理邮件提醒等异步任务
定时任务：Celery Beat 调度，支持事件提前提醒
任务队列：Redis 作为消息代理和结果后端

邮件提醒系统

SMTP 配置：支持 QQ 邮箱、Gmail 等
提前提醒：可配置提前时间（5分钟/15分钟/30分钟/1小时/1天）
异步发送：Celery 异步处理，不阻塞主流程
提醒标记：notification_sent 字段防止重复发送

地图集成

多地图服务商支持：百度地图、高德地图、腾讯地图
地点搜索：支持地点名称搜索和坐标定位
导航链接生成：自动生成各平台导航链接
坐标存储：存储经纬度，支持离线查看

AI 助手

通义千问集成：阿里云通义千问 API
自然语言解析：将自然语言转换为结构化日程
智能总结：分析日程安排，提供时间管理建议
对话式交互：支持与 AI 对话查询和创建日程

🎓 项目背景

本项目最初作为南昌大学 Android 开发课程的大作业开发，现已发展成为 Roamio 生态系统的核心组件之一。

课程要求

✅ Kotlin 原生开发
✅ Material Design 设计规范
✅ Room 数据库
✅ 提醒功能
✅ 扩展功能（网络订阅、农历）

实际完成

不仅完成了所有课程要求，还额外实现了：

✅ 完整的后端 API 服务（Django REST Framework）
✅ Web 端管理界面（Vue 3）
✅ AcWing 平台集成
✅ 多种 OAuth 登录（AcWing、QQ）
✅ AI 智能助手（通义千问集成）
✅ 地图定位功能（百度地图 SDK）
✅ 云端部署上线（Docker + Nginx）
✅ 生态化产品设计（Roamio 融合）

🌏 关于 Roamio 生态

Ralendar 是 Roamio 生态系统的重要组成部分：

Roamio 🗺️ - 旅行规划与内容分享平台
Ralendar 📅 - 智能日历与时间管理（本项目）
Rote 📝 - 笔记与知识管理（规划中）
Rapture 📸 - 照片与回忆记录（规划中）

生态协同

在 Roamio 中规划旅行 → 自动同步到 Ralendar 日程
Ralendar 提醒即将到来的行程 → 推送到 Roamio 提前准备
统一的账号体系（QQ、AcWing 一键登录）
无缝的数据互通

🧪 测试

后端测试

cd backend

# 运行所有测试
python manage.py test

# 运行特定应用的测试
python manage.py test api

# 运行特定测试类
python manage.py test api.tests.test_events

# 带覆盖率报告
coverage run --source='.' manage.py test
coverage report

前端测试

# Web 前端
cd web_frontend
npm run test

# AcApp 前端
cd acapp_frontend
npm run test

API 测试

使用 Postman 或 curl 测试 API：

# 获取 Token
curl -X POST https://app7626.acapp.acwing.com.cn/api/auth/login/ \
  -H "Content-Type: application/json" \
  -d '{"username": "test", "password": "test123"}'

# 创建日程
curl -X POST https://app7626.acapp.acwing.com.cn/api/events/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "测试日程",
    "start_time": "2025-11-10T14:00:00Z",
    "location": "测试地点"
  }'

🔧 故障排查

常见问题

1. 后端启动失败

问题：ModuleNotFoundError 或依赖安装失败

解决：

# 确保虚拟环境已激活
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows

# 重新安装依赖
pip install -r requirements.txt --upgrade

2. 数据库迁移错误

问题：django.db.utils.OperationalError

解决：

# 检查数据库连接
python manage.py dbshell

# 重置迁移（开发环境）
python manage.py migrate --fake-initial
python manage.py migrate

3. Celery 任务不执行

问题：邮件提醒未发送

解决：

# 检查 Celery Worker 是否运行
ps aux | grep celery

# 检查 Redis 连接
redis-cli ping

# 重启 Celery
celery -A calendar_backend worker --loglevel=info
celery -A calendar_backend beat --loglevel=info

4. CORS 跨域错误

问题：前端请求被浏览器阻止

解决：

检查 settings.py 中的 CORS_ALLOWED_ORIGINS
确保前端地址在允许列表中
开发环境可使用 CORS_ALLOW_ALL_ORIGINS = True（仅开发）

5. OAuth 登录失败

问题：AcWing/QQ 登录返回错误

解决：

检查 .env 中的 ACWING_APPID、ACWING_SECRET、QQ_APPID、QQ_APPKEY
确认回调 URL 配置正确
查看服务器日志：tail -f /var/log/uwsgi/app.log

6. 邮件发送失败

问题：邮件提醒未收到

解决：

# 检查邮件配置
python manage.py shell
>>> from django.core.mail import send_mail
>>> send_mail('Test', 'Test message', 'from@example.com', ['to@example.com'])

# 检查 Celery 任务日志
celery -A calendar_backend worker --loglevel=debug

日志查看

# Django 日志
tail -f backend/logs/django.log

# uWSGI 日志
tail -f /var/log/uwsgi/app.log

# Nginx 日志
tail -f /var/log/nginx/access.log
tail -f /var/log/nginx/error.log

# Celery 日志
tail -f backend/logs/celery.log

⚡ 性能优化

数据库优化

索引：已为常用查询字段添加索引（见数据模型章节）
查询优化：使用 select_related 和 prefetch_related 减少数据库查询
分页：所有列表接口支持分页，默认 20 条/页

缓存策略

Redis 缓存：热点数据缓存（可扩展）
静态文件：Nginx 缓存静态资源
CDN 加速：AcWing 平台提供 CDN

前端优化

代码分割：Vite 自动代码分割
懒加载：路由和组件懒加载
资源压缩：生产环境自动压缩 JS/CSS

API 优化

分页：所有列表接口必须分页
字段过滤：支持 fields 参数选择返回字段
批量操作：提供批量创建接口（Fusion API）

🔒 安全考虑

认证安全

JWT Token：短期 Access Token（5分钟），长期 Refresh Token（15天）
Token 刷新：自动刷新机制，防止 Token 泄露风险
密码加密：Django 默认使用 PBKDF2 加密

数据安全

SQL 注入防护：使用 Django ORM，自动转义
XSS 防护：前端自动转义，后端验证输入
CSRF 防护：Django CSRF 中间件

API 安全

CORS 配置：仅允许指定域名访问
频率限制：可配置 API 请求频率限制（待实现）
输入验证：DRF Serializer 自动验证

部署安全

HTTPS：生产环境强制 HTTPS
环境变量：敏感信息存储在 .env，不提交到 Git
DEBUG 模式：生产环境关闭 DEBUG

🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

开发规范

代码风格：
- Python: 遵循 PEP 8
- Kotlin: 遵循 Kotlin 官方编码规范
- JavaScript/Vue: 遵循 Vue Style Guide
提交信息：使用语义化的 commit message
- feat: 新功能
- fix: 修复 bug
- docs: 文档更新
- style: 代码格式调整
- refactor: 代码重构
- test: 测试相关
- chore: 构建/工具相关
分支策略：
- main - 主分支（稳定版本）
- develop - 开发分支
- feature/xxx - 功能分支
- bugfix/xxx - Bug 修复分支
- hotfix/xxx - 紧急修复分支

贡献流程

Fork 本仓库
创建特性分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
开启 Pull Request

代码审查

所有 PR 需要至少一个维护者审查
确保代码通过测试
更新相关文档
遵循项目代码风格

📝 开发工作流

本地开发

克隆项目

git clone https://github.com/ppshuX/Ralendar.git
cd Ralendar

后端开发

cd backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env  # 配置环境变量
python manage.py migrate
python manage.py runserver

前端开发
```
cd web_frontend
npm install
npm run dev
```

Celery 开发（邮件提醒需要）

# 终端1：启动 Redis
redis-server

# 终端2：启动 Celery Worker
cd backend
celery -A calendar_backend worker --loglevel=info

# 终端3：启动 Celery Beat
celery -A calendar_backend beat --loglevel=info

部署流程

代码推送

git add .
git commit -m "feat: 新功能"
git push origin main

服务器更新

ssh user@47.121.137.60
cd ~/Ralendar
git pull
cd backend
source venv/bin/activate
pip install -r requirements.txt
python manage.py migrate
python manage.py collectstatic --noinput

重启服务

# 重启 uWSGI
sudo systemctl restart uwsgi

# 重启 Celery
sudo systemctl restart celery
sudo systemctl restart celerybeat

# 检查 Nginx
sudo nginx -t
sudo systemctl reload nginx

数据库迁移

# 创建迁移
python manage.py makemigrations

# 应用迁移
python manage.py migrate

# 查看迁移状态
python manage.py showmigrations

📞 联系方式

GitHub: https://github.com/ppshuX/Ralendar
问题反馈: GitHub Issues
邮箱: 2064747320@qq.com
在线演示: https://app7626.acapp.acwing.com.cn

📈 项目统计

代码规模

总代码行数: ~15,000+ 行
Python 代码: ~5,000 行（Django 后端）
JavaScript/Vue 代码: ~6,000 行（前端）
Kotlin 代码: ~2,000 行（Android）
配置文件: ~1,000 行
文档: ~10,000+ 行

功能模块

API 端点: 30+ 个
数据模型: 6+ 个
前端组件: 20+ 个
视图页面: 10+ 个

技术栈统计

后端框架: Django 4.2 + DRF 3.15
前端框架: Vue 3 (Composition API)
移动端: Kotlin + Android SDK
数据库: SQLite / MySQL
任务队列: Celery + Redis
部署: Docker + Nginx + uWSGI

🎖️ 致谢

感谢以下平台和开源项目的支持：

平台服务

AcWing - 平台和授权服务
腾讯 QQ 互联 - OAuth 登录支持
阿里云 - 云服务器和 AI 服务
百度地图 - 地图定位服务
高德地图 - 地图和天气服务

开源框架

Django - 强大的 Web 框架
Django REST Framework - RESTful API 框架
Vue.js - 渐进式前端框架
Element Plus - 优秀的 UI 组件库
FullCalendar - 专业的日历组件
Room - Android 数据库框架
Retrofit - 类型安全的 HTTP 客户端
Celery - 分布式任务队列
Redis - 内存数据库和消息代理

📄 License

MIT License

用心打造有温度的时间管理工具。 💙

🔗 相关项目: Roamio - 旅行规划平台

Name		Name	Last commit message	Last commit date
Latest commit History 638 Commits
acapp/dist		acapp/dist
acapp_frontend		acapp_frontend
adapp		adapp
assets		assets
backend		backend
docs		docs
web		web
web_frontend		web_frontend
.git_commit_msg.txt		.git_commit_msg.txt
.gitattributes		.gitattributes
.gitignore		.gitignore
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation

📅 Ralendar - Roamio 生态智能日历

📋 目录

✨ 核心功能

📅 日历视图

✏️ 日程管理

🤖 AI 智能助手

🌐 多端同步

🔐 多种登录方式

🏮 特色功能

🏗️ 技术架构

系统架构图

技术栈

后端技术栈

Android 技术栈

Web 前端技术栈

AcApp 前端技术栈

设计模式

🚀 快速开始

前置要求

1. 克隆项目

2. 后端设置

环境变量配置 (.env)

启动 Celery（邮件提醒需要）

3. Web 前端设置

4. AcApp 前端设置

5. Android 应用设置

🌐 在线演示

部署信息

📁 项目结构

📚 API 文档

主要 API 端点

认证相关

日程管理

用户中心

AI 助手

外部服务

融合功能 (Roamio)

OAuth 2.0 服务器端点

API 认证方式

API 响应格式

🗄️ 数据模型

Event（日程事件）

User（用户）

数据库索引

☁️ 云资源使用

云服务器

云数据库

云存储

云平台

第三方服务

数据同步策略

📖 开发文档

快速开始

API 文档

开发指南

集成文档

产品报告

📊 项目进度

已完成功能 ✅

进行中 🚧

技术特性

认证系统

异步任务系统

邮件提醒系统

地图集成

AI 助手

🎓 项目背景

课程要求

实际完成

🌏 关于 Roamio 生态

生态协同

🧪 测试

后端测试

前端测试

API 测试

🔧 故障排查

Packages