DoCSoc Clickup 日历映射器

这是一个工具，用于同步 DoCSoc 私有 Google 日历与 ClickUp，以便在 ClickUp 中查看。它设计为在服务器上作为 cron 作业运行。

它使用 ClickUp v2.0 API。 https://clickup.com/api/

[!important] 同步是一向的：在 Google 日历中删除和修改的事件将同步到 ClickUp，但 ClickUp 中的修改将不会同步回 Google 日历。

这是因为作者懒得处理双向同步，因为他必须解决如何解决冲突的问题，这在工具作为 cron 作业或在服务器上无头运行时很难解决！

系统使用通过 Diesel ORM 交互的 PostgreSQL 数据库来存储从日历事件 ID（在 ical 格式中称为 UIDs）到 ClickUp 任务 ID 的映射。这使得系统能够在 Google 日历中更新或删除事件时在 ClickUp 中更新或删除事件。

应用程序已配置为在启动时自动运行迁移，因此您无需自己执行此操作。

快速开始

发布包

1. 在 ClickUp 中创建一个列表以导入日历事件
2. 设置 PostgreSQL 数据库
3. 填写此模板并将其放置在 .env 中，然后从包含该文件的目录运行工具（或者将它们设置为环境变量）

# Template for the .env file to set up the environment variables for the sync tools

# ========================
# Application services
# ========================
# Postgres URL of the database
# E.g. postgres://user:pass@localhost:5432/docsoc-tools
# No need to set this if using the docker compose file
DATABASE_URL=

# ========================
# Google Calendar
# ========================
# Secret URL of the calendar in ical format
# To find it go:
# 1. Go to calendar.google.com
# 2. 3 vertical dots next to calendar > Settings and Sharing > copy secret address in ical format
# For private calendars: DO NOT USE THE PUBLIC ICAL LINK! IT WILL NOT WORK!
ICAL_SYNC_PRIVATE_ICAL=

# First date you want to sync for your committee in YYYY-MM-DD format
# (you probably don't want to pull the whole calendar)
ICAL_SYNC_START_DATE=
# Last date you want to sync for your committee in YYYY-MM-DD format
ICAL_SYNC_END_DATE=

# ========================
# ClickUp
# ========================
# Access token for the ClickUp API
# Use a personal access token - see https://clickup.com/api/developer-portal/authentication/
CLICKUP_ACCESS_TOKEN=
# Target list ID in ClickUp to place events
# To find it go:
# 1. Go to ClickUp
# 2. Right click the list you want to sync and click "Copy link"
# 3. The list ID is the number at the end of the URL
# E.g. for https://app.clickup.com/9015711748/v/li/901505370673 the list ID is 901505370673
CLICKUP_TARGET_LIST_ID=
# Rate limit for the ClickUp API per minute
# Currently as of 2024 this is 100 per minute by default
# Note that the app will take 20 off this automatically as I don't quite trust my code
# and want to be safe
CLICKUP_RATE_LIMIT_PER_MIN=100

Docker Compose

1. 在 ClickUp 中创建一个列表以导入日历事件
2. 复制 .env.template 文件并重命名为 .env，填写它（它解释了每个字段的作用）
3. 在此目录中运行 docker compose up

裸金属/虚拟机

1. 在 ClickUp 中创建一个列表以导入日历事件
2. 设置 PostgreSQL 数据库
3. 复制 .env.template 文件并重命名为 .env，填写它（它解释了每个字段的作用）
4. 定期使用 cargo run --release 运行工具（例如，每小时一次）以保持日历同步

手动构建 Docker 镜像

[重要] 由于代码采用单一代码库结构，构建此项目的Docker镜像必须在代码库的根目录下运行

1. 进入单一代码库的根目录
2. docker build -f ./clickup/calendar/sync/Dockerfile -t docsoc/clickup-calendar-sync .

工作原理

1. 工具下载DoCSoc私有日历的ical文件
2. 解析ical文件并提取事件，以ParsedEvent的迭代器形式呈现
3. 对于每个ParsedEvent，检查事件是否在数据库中
   • 如果是，则更新ClickUp中的事件以确保与Google日历中的所有信息一致
   • 如果不是，则在ClickUp中创建事件并将其映射添加到数据库中
4. 然后创建一个包含从ical下载的所有UID的集合
   • 对于数据库中的每个映射...
     • ...如果UID不在集合中，则在ClickUp中删除事件并从数据库中删除映射

工具的其他特性

• 工具使用govenor存储库来遵守ClickUp API的速率限制，但它以一个不太合适的方式来实现（见代码）