Migrate TickTick OAuth and action tasks

docs/homeassistant-inbound.md

@@ -30,18 +30,27 @@
 
 ## 当前已支持的 Target / Action
 
-当前只接回最小可用路径：
+当前已接回的路径：
 
 - `location_recorder / record`
+- `ticktick / create_action_task`
 
-它会把 `content` 解析为 location recorder 请求，并直接走当前 Python 项目里的 location 写入逻辑。
+其中：
+
+- `location_recorder / record` 会把 `content` 解析为 location recorder 请求，并直接走当前 Python 项目里的 location 写入逻辑
+- `ticktick / create_action_task` 会沿用 legacy 行为，把 `content` 解析为：
+  - `action: string`
+  - `due_hour: int`
+  - 可选 `title` 字段会被忽略
+- TickTick task title 仍使用 `action`
+- due date 仍按 legacy 语义计算：先取 `now + due_hour`，再落到该日期的“次日零点”，最后转成 UTC 后写给 TickTick
+- 具体 project 仍由 `HOME_ASSISTANT_ACTION_TASK_PROJECT_ID` 提供
 
 ## 当前尚未接回
 
 以下 legacy 路径在当前阶段还没有迁入：
 
 - `poo_recorder / get_latest`
-- `ticktick / create_action_task`
 - 其他未定义 target/action
 
 这些请求当前会返回：

docs/ticktick.md

@@ -0,0 +1,42 @@
+# 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`
+
+## 当前配置项
+
+- `TICKTICK_CLIENT_ID`
+- `TICKTICK_CLIENT_SECRET`
+- `TICKTICK_REDIRECT_URI`
+- `TICKTICK_TOKEN`
+- `HOME_ASSISTANT_ACTION_TASK_PROJECT_ID`
+
+## 兼容性说明
+
+- 仍保留 legacy 的 OAuth authorization code flow
+- `state` 仍是进程内临时状态；如果服务在 start 和 callback 之间重启，本轮实现下授权需要重新开始
+- 不再把 token 写回 `.env` 或其他配置文件，统一写入 config 表
+- 当前没有引入 legacy 的第三方 TickTick 库，先用标准库完成兼容行为
+
+## 后续适合单独拆分的工作
+
+- 给 config 页面增加明确的 TickTick 授权入口
+- 增加 project 探测或选择能力，减少手工填写 `HOME_ASSISTANT_ACTION_TASK_PROJECT_ID`
+- 如果后续发现 OAuth/token 生命周期需要更强健，再补 refresh token 或持久化 auth state