Moodle → Microsoft To Do 同步工具

将 Moodle 平台上 Timeline 中的事件（作业、测验截止日期等）自动同步到 Microsoft To Do 的指定列表中，并设置提前 24 小时的提醒。

功能

• 从 Moodle Timeline 获取未来 N 天内的所有事件
• 自动在 Microsoft To Do 中创建对应任务
• 任务包含：课程名 + 事件名、截止日期、提前 24h 的闹钟提醒
• 课程别名：为冗长的课程名设置简短别名（如 "网安"），任务标题自动替换
• 本地 JSON 去重，避免重复创建
• Microsoft Token 缓存，避免重复登录
• Docker 部署：支持容器化部署，定时自动同步

前置准备

1. Moodle 账号

只需你的 Moodle 用户名和密码即可。工具会通过 Moodle Mobile 接口 (/login/token.php) 自动获取 API Token，无需手动申请安全密钥。

2. 注册 Azure 应用（用于 Microsoft 登录）

1. 访问 Azure Portal - 应用注册
2. 点击 新注册
3. 填写：
   • 名称: Moodle2MSTodo（随意）
   • 受支持的账户类型: 选择 个人 Microsoft 帐户
   • 重定向 URI: 留空（设备代码流不需要）
4. 点击 注册，记下 应用程序(客户端) ID
5. 进入 身份验证 页面：
   • 在 高级设置 中，将 允许公共客户端流 设为 是
   • 点击 保存
6. 进入 API 权限 页面：
   • 点击 添加权限 → Microsoft Graph → 委托的权限
   • 搜索并添加 Tasks.ReadWrite
   • 点击 授予管理员同意（如果可用，个人账号可能不需要）

3. 配置项目

首次运行时程序会交互式引导你完成所有配置（Moodle 登录、Azure Client ID、课程别名、To Do 列表选择），无需手动编辑配置文件。

如果你希望手动配置，可以复制模板并编辑：

cp config.example.json config.json

{
    "moodle": {
        "url": "https://ispace.uic.edu.cn"
    },
    "microsoft": {
        "client_id": "你的Azure应用客户端ID"
    },
    "sync": {
        "todo_list_name": "Moodle Assignments",
        "reminder_hours_before": 24,
        "days_ahead": 30,
        "timezone": "Asia/Shanghai"
    }
}

配置项	说明
moodle.url	你的 Moodle 平台地址（已预填 UIC）
microsoft.client_id	Azure 应用的客户端 ID（首次运行时会交互询问）
sync.todo_list_name	To Do 中的目标列表名称（不存在会自动创建）
sync.reminder_hours_before	提前多少小时提醒（默认 24）
sync.days_ahead	获取未来多少天的事件（默认 30）
sync.timezone	时区（默认 Asia/Shanghai）

可选: 如果你有手动获取的 Moodle Web Service Token，可以在 moodle 中添加 "token": "你的Token" 字段跳过登录提示。

本地运行

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

# 运行同步
python main.py

运行时会依次完成以下步骤：

1. Moodle 登录（在终端中输入）：

请输入你的 Moodle 账号信息:
  用户名: your_student_id
  密码: (隐藏输入)

2. 课程别名设置（首次运行或出现新课程时）：

==================================================
设置课程别名
==================================================
以下课程尚未设置别名 (直接回车跳过，保持原名):

  「Computer and Network Security (1002) (Dr. Donald Donglong CHEN) [Semester 2 of 2025-2026]」
   别名: 网安

设置后，任务标题将显示为 [网安] Assignment 1 而非完整课程名。别名保存在 CourseAlias.json 中：

{
    "12345": {
        "original_name": "Computer and Network Security (1002) (Dr. Donald Donglong CHEN) [Semester 2 of 2025-2026]",
        "alias": "网安"
    }
}

• 直接回车跳过的课程不会被重复询问
• 所有课程都已设置别名时，此步骤自动跳过

3. Microsoft 登录（在浏览器中完成，首次需要，后续自动缓存）：

============================================================
Microsoft 登录认证
============================================================
请在浏览器中访问: https://microsoft.com/devicelogin
并输入代码: XXXXXXXX
============================================================

Docker 部署

支持通过 Docker 容器化部署到云服务器，实现定时自动同步。

快速开始

1. 编辑 docker-compose.yml

填写你的 Azure 应用 Client ID，以及可选的 Moodle Token：

environment:
  MS_CLIENT_ID: "你的Azure应用客户端ID"
  MOODLE_TOKEN: "你的Moodle Token（可选，留空则首次交互登录）"

2. 构建镜像

docker compose build

3. 首次交互设置

docker compose run -it moodle-sync python entrypoint.py --once

此命令会以交互模式引导你完成：

• Moodle 账号登录（获取并保存 Token）
• 课程别名设置
• Microsoft 账号认证（Device Code Flow，在浏览器中完成）
• To Do 目标列表选择

所有配置和认证信息会保存到 ./data/ 目录，后续自动同步时直接使用。

4. 启动定时同步

docker compose up -d

容器将在后台运行，默认每小时自动同步一次。

5. 查看日志

docker compose logs -f moodle-sync

环境变量

所有环境变量均为可选。非空值会覆盖 config.json 中的对应配置，空值（""）不会覆盖，因此首次交互设置的结果会被保留。

环境变量	说明	默认值
MOODLE_URL	Moodle 平台地址	https://ispace.uic.edu.cn
MOODLE_TOKEN	Moodle API Token（留空则首次交互获取）	""
MS_CLIENT_ID	Azure 应用客户端 ID（留空则首次交互询问）	""
SYNC_INTERVAL_HOURS	同步间隔（小时）	1
SYNC_DAYS_AHEAD	获取未来多少天的事件	30
SYNC_TIMEZONE	时区	Asia/Shanghai
TODO_LIST_NAME	To Do 目标列表名称	Moodle Assignments
REMINDER_HOURS	提前多少小时提醒	24

数据持久化

容器通过目录映射 ./data:/app/data 持久化以下文件：

文件	用途
config.json	合并后的完整配置
synced_state.json	同步状态记录（去重）
CourseAlias.json	课程别名映射
token_cache.bin	Microsoft Token 缓存

Microsoft Token 过期处理

Microsoft Token 过期后，容器日志会输出 Device Code 认证链接和代码：

请在浏览器中访问: https://microsoft.com/devicelogin
并输入代码: XXXXXXXX

在任意设备的浏览器中完成认证即可，新 Token 会自动缓存到 ./data/token_cache.bin。

文件说明

文件	用途
main.py	入口脚本，串联同步流程
moodle_client.py	Moodle Web Services API 客户端
ms_todo_client.py	Microsoft Graph API 客户端（To Do）
sync_state.py	本地同步状态管理（去重）
entrypoint.py	Docker 入口，环境变量合并 + 定时调度
Dockerfile	容器镜像定义
docker-compose.yml	容器编排配置
.dockerignore	Docker 构建排除规则
config.json	用户配置（不要提交到 Git）
config.example.json	配置模板
CourseAlias.json	课程别名映射（自动生成，不要提交到 Git）
synced_state.json	同步状态记录（自动生成）
token_cache.bin	Microsoft Token 缓存（自动生成）

推送镜像到 Docker Hub

如果你需要将本地构建的镜像推送到 rinsutoringu/moddle2mstodo：

# 1. 登录 Docker Hub
docker login

# 2. 构建并打 tag（同时打 latest 和版本号）
docker build -t rinsutoringu/moddle2mstodo:latest -t rinsutoringu/moddle2mstodo:1.0.0 .

# 3. 推送所有 tag
docker push rinsutoringu/moddle2mstodo --all-tags

只推单个 tag 的话：docker push rinsutoringu/moddle2mstodo:latest