home-automation/docs/ticktick.md

TickTick Integration

当前 Python 项目里的 TickTick 迁移先恢复 legacy 的最核心能力，不额外扩成更大的集成层。

当前已支持

• 运行时从 config 表读取 TickTick 配置，缺失时仍可 fallback .env
• GET /ticktick/auth/start
  • 需要已登录 session
  • 生成 OAuth state
  • 直接重定向到 TickTick 授权页
• GET /ticktick/auth/code
  • 校验进程内保存的 state
  • 用 authorization code 换取 access token
  • 将 TICKTICK_TOKEN 持久化到 app_config 表
• TickTick Open API 基础调用：
  • 列 project
  • 列 project 下 task
  • 创建 task
  • 按 title 精确匹配做重复创建保护
• Home Assistant inbound 已重新接回 ticktick / create_action_task

当前配置项

• APP_HOSTNAME
• TICKTICK_CLIENT_ID
• TICKTICK_CLIENT_SECRET
• TICKTICK_TOKEN
• HOME_ASSISTANT_ACTION_TASK_PROJECT_ID

兼容性说明

• 仍保留 legacy 的 OAuth authorization code flow
• OAuth callback URI 现在由 APP_HOSTNAME 和当前环境自动推导：development 使用 http，其他环境使用 https
• state 仍是进程内临时状态；如果服务在 start 和 callback 之间重启，本轮实现下授权需要重新开始
• 不再把 token 写回 .env 或其他配置文件，统一写入 config 表
• 当前没有引入 legacy 的第三方 TickTick 库，先用标准库完成兼容行为

后续适合单独拆分的工作

• 给 config 页面增加明确的 TickTick 授权入口
• 增加 project 探测或选择能力，减少手工填写 HOME_ASSISTANT_ACTION_TASK_PROJECT_ID
• 如果后续发现 OAuth/token 生命周期需要更强健，再补 refresh token 或持久化 auth state