memind/docs/schedule-reminder-design.md

# 待办 / 日程 / 提醒能力设计文档

> **状态：** 设计稿  
> **目标版本：** v0.2.x  
> **适用范围：** H5 门户、微信服务号 Agent、MindSpace 行程展示页  
> **生产提醒：** 当前仓库目录可能承载生产服务。开发和验证按 `docs/service-isolation-runbook.md` 先在测试目录完成，不在生产目录直接跑迁移或重启服务。

## 背景

用户希望用自然语言完成两类高频动作：

1. 记录事项：例如“我明天要去开会，帮我记录增加一个提醒”。
2. 查看计划：例如“看看我的行程计划”。

现状里已有几个可利用基础：

- `capabilities.mjs` 已预留 `todo` 能力，但默认关闭，且当前项目没有本地一等的待办/日程表。
- `wechat-mp.mjs` 已能接收微信服务号文本、转给用户专属 Agent、再通过客服消息回复。
- MindSpace 已有生成公开/私有 HTML 页面的能力，适合把一周行程做成简洁精美页面。

缺口在于：日程和提醒还没有结构化存储、没有到点派发 worker、没有 Agent 可调用的本地日程工具，也没有固定的澄清规则。

## 产品目标

### 必须支持

- 用户用自然语言创建待办、日程、提醒。
- 缺少必要时间信息时，助手必须追问，不猜测具体钟点。
- 用户明确“不提醒”时，只记录到待办或日程列表，不创建提醒推送。
- 对会议类表达，如果已有明确开始时间但没有指定提前多久提醒，默认提前 1 小时提醒。
- 用户查看行程时，按指定时间范围展示；未指定范围时展示最近 7 天。
- 行程查询结果优先以简洁消息回复；当内容较多或用户要求“页面/好看一点”时，生成 MindSpace HTML 页面。

### 暂不纳入 MVP

- 复杂重复规则，如“每月第二个周三”。
- 多人共享日程、会议邀请、外部日历同步。
- 地理围栏提醒。
- 跨端原生 push。MVP 先走已绑定微信服务号通知通道，后续再扩展短信、邮件或 App push。

## 概念模型

| 概念 | 说明 | 例子 |
|------|------|------|
| 待办 task | 有或没有截止时间的任务，不一定占用时间段 | “买票”、“周五前交材料” |
| 日程 event | 有开始时间，通常可以有结束时间，占用时间段 | “今天下午三点开会” |
| 提醒 reminder | 某个时间点触发的一次通知，可挂在 task/event 上 | “会议前 1 小时提醒” |

设计原则：

- 待办和日程是“记录”；提醒是“通知计划”。
- 一条待办/日程可以没有提醒。
- 一条待办/日程可以有多条提醒，但 MVP 默认最多一条。
- 所有时间入库使用 epoch 毫秒，额外保存用户时区，展示时按用户时区格式化。

## 自然语言交互规则

### 创建提醒或日程

#### 规则 1：缺少事件发生时间时必须追问

用户说：

```text
我明天要去开会，帮我记录增加一个提醒
```

如果系统当前日期是 2026-06-18，助手能解析“明天”为 2026-06-19，但缺少具体钟点，不能创建到点提醒。回复：

```text
可以。我先记下“明天开会”。你想几点提醒？会议大概几点开始，提前多久提醒你？
```

待用户补充后再创建。

#### 规则 2：用户明确不提醒时只记录

用户说：

```text
不用提醒，先记一下
```

系统创建一条待办或全天日程，不创建 `h5_schedule_reminders` 记录。回复：

```text
已记录到待办列表：明天开会，未设置提醒。
```

#### 规则 3：会议类有明确开始时间时默认提前 1 小时

用户说：

```text
今天下午三点有个会
```

如果系统当前日期是 2026-06-18，解析为：

- 日程：2026-06-18 15:00，标题“开会”或“会议”
- 提醒：2026-06-18 14:00
- 提醒偏移：60 分钟

回复：

```text
已记录：今天 15:00 会议。我会提前 1 小时，也就是 14:00 提醒你。
```

#### 规则 4：非会议类默认不擅自加提前提醒

用户说：

```text
明天上午十点去取护照
```

创建日程，但如果用户没有说“提醒我”，不自动创建提醒。回复可提示：

```text
已记录：明天 10:00 取护照。需要我提前提醒的话，可以告诉我提前多久。
```

#### 规则 5：用户直接指定提醒时间时按提醒时间创建

用户说：

```text
明天上午九点提醒我带材料
```

创建待办“带材料”，并创建 `remind_at = 明天 09:00` 的提醒。此时不需要追问“提前多久”。

#### 规则 6：每天固定时间推送当天待办记录

用户说：

```text
每天早上 7 点给我发一天的待办记录
```

系统必须创建一条每日待办摘要订阅：

- 类型：`todo_day`
- 时间：每天 07:00
- 通道：微信服务号
- 行为：每天到点查询用户当天待办记录，通过服务号主动发送给用户

回复：

```text
已设置：我会每天早上 7点 通过服务号把当天待办记录发给你。
```

如果用户只说“每天给我发待办记录”，缺少时间，必须追问具体时间。

### 查看行程

#### 规则 7：没有时间范围时默认最近 7 天

用户说：

```text
看看我的行程计划
```

查询范围：

- 起点：用户时区当天 00:00
- 终点：起点 + 7 天

回复格式优先按日期分组：

```text
未来 7 天你有 3 个安排：

6 月 18 日 周四
14:00 会议提醒
15:00 会议

6 月 19 日 周五
全天 开会
```

#### 规则 8：指定时间范围时按范围查询

用户说“看下明天的安排”、“下周有什么会”、“6 月 20 到 25 日的计划”，按指定范围查询。

#### 规则 9：需要精美展示时生成页面

触发条件：

- 用户明确说“用页面展示”、“好看一点”、“生成一个行程页”。
- 查询结果超过 8 条，普通文本不易读。
- 用户来自 H5 页面上下文，适合打开 MindSpace 页面。

页面要求：

- 第一屏直接是行程表，不做营销式 landing page。
- 按日期分组，突出今天、明天、逾期、即将到来。
- 对日程、待办、提醒用不同视觉标识。
- 移动端优先，宽屏下使用双栏或周视图。

## 系统架构

```mermaid
flowchart TD
  U["用户文本: 微信/H5"] --> I["意图解析层"]
  I -->|缺必要信息| Q["追问用户"]
  I -->|可执行| T["Schedule Service"]
  T --> DB["MySQL: schedule tables"]
  T --> R["Reminder Worker"]
  R --> W["微信通知通道"]
  T --> V["行程查询 API"]
  V --> A["Agent 文本回复"]
  V --> P["MindSpace 行程页面"]
```

### 组件职责

| 组件 | 职责 |
|------|------|
| 意图解析层 | 从自然语言提取 action、title、date/time、reminder offset、query range；判断是否需要追问 |
| Schedule Service | 统一创建、查询、修改、取消待办/日程/提醒 |
| Reminder Worker | 周期扫描到期提醒，锁定、投递、记录成功/失败 |
| 微信通知通道 | 发送提醒消息。MVP 优先复用已绑定服务号 openid，生产上线前确认模板/订阅通知资质 |
| MindSpace 展示 | 将查询结果渲染为 HTML 页面，保存到用户 `public/` 或私有页面记录 |

## 数据库设计

### `h5_schedule_items`

记录待办和日程主体。

```sql
CREATE TABLE IF NOT EXISTS h5_schedule_items (
  id CHAR(36) PRIMARY KEY,
  user_id CHAR(36) NOT NULL,
  kind ENUM('task', 'event') NOT NULL,
  title VARCHAR(255) NOT NULL,
  description TEXT NULL,
  status ENUM('active', 'completed', 'cancelled', 'deleted') NOT NULL DEFAULT 'active',
  start_at BIGINT NULL,
  end_at BIGINT NULL,
  due_at BIGINT NULL,
  all_day TINYINT(1) NOT NULL DEFAULT 0,
  timezone VARCHAR(64) NOT NULL DEFAULT 'Asia/Shanghai',
  location VARCHAR(255) NULL,
  source_channel ENUM('h5', 'wechat', 'agent', 'api') NOT NULL DEFAULT 'agent',
  source_session_id VARCHAR(128) NULL,
  source_message_id VARCHAR(128) NULL,
  source_text TEXT NULL,
  metadata_json JSON NULL,
  created_at BIGINT NOT NULL,
  updated_at BIGINT NOT NULL,
  deleted_at BIGINT NULL,
  KEY idx_schedule_user_time (user_id, status, start_at, due_at),
  KEY idx_schedule_user_updated (user_id, updated_at),
  CONSTRAINT fk_schedule_item_user FOREIGN KEY (user_id) REFERENCES h5_users(id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
```

字段说明：

- `kind = task`：待办，通常使用 `due_at`，也可没有时间。
- `kind = event`：日程，通常使用 `start_at/end_at`。
- `all_day = 1`：只有日期没有具体钟点，如“明天开会”。
- `source_text`：保留用户原文，便于回溯和修正。

### `h5_schedule_reminders`

记录提醒计划和投递状态。

```sql
CREATE TABLE IF NOT EXISTS h5_schedule_reminders (
  id CHAR(36) PRIMARY KEY,
  user_id CHAR(36) NOT NULL,
  item_id CHAR(36) NOT NULL,
  remind_at BIGINT NOT NULL,
  offset_minutes INT NULL,
  channel ENUM('wechat', 'in_app') NOT NULL DEFAULT 'wechat',
  status ENUM('pending', 'locked', 'sent', 'failed', 'cancelled') NOT NULL DEFAULT 'pending',
  attempts INT NOT NULL DEFAULT 0,
  last_error VARCHAR(500) NULL,
  locked_until BIGINT NULL,
  sent_at BIGINT NULL,
  created_at BIGINT NOT NULL,
  updated_at BIGINT NOT NULL,
  UNIQUE KEY uq_schedule_item_remind_at (item_id, remind_at, channel),
  KEY idx_reminder_due (status, remind_at),
  KEY idx_reminder_user (user_id, status, remind_at),
  CONSTRAINT fk_schedule_reminder_user FOREIGN KEY (user_id) REFERENCES h5_users(id) ON DELETE CASCADE,
  CONSTRAINT fk_schedule_reminder_item FOREIGN KEY (item_id) REFERENCES h5_schedule_items(id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
```

### `h5_schedule_delivery_logs`

记录每次投递尝试，用于排错和审计。

```sql
CREATE TABLE IF NOT EXISTS h5_schedule_delivery_logs (
  id CHAR(36) PRIMARY KEY,
  reminder_id CHAR(36) NOT NULL,
  user_id CHAR(36) NOT NULL,
  channel ENUM('wechat', 'in_app') NOT NULL,
  status ENUM('success', 'failed') NOT NULL,
  provider_message_id VARCHAR(128) NULL,
  error_code VARCHAR(64) NULL,
  error_message VARCHAR(500) NULL,
  created_at BIGINT NOT NULL,
  KEY idx_delivery_reminder (reminder_id, created_at),
  KEY idx_delivery_user (user_id, created_at),
  CONSTRAINT fk_schedule_delivery_reminder FOREIGN KEY (reminder_id) REFERENCES h5_schedule_reminders(id) ON DELETE CASCADE,
  CONSTRAINT fk_schedule_delivery_user FOREIGN KEY (user_id) REFERENCES h5_users(id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
```

## 后端模块设计

### 新增文件建议

| 文件 | 说明 |
|------|------|
| `schedule-service.mjs` | 领域服务：创建、查询、更新、取消、完成 |
| `schedule-intent.mjs` | 轻量规则解析和澄清决策，先覆盖中文常用表达 |
| `schedule-reminder-worker.mjs` | 到点提醒扫描、锁定、投递、重试 |
| `schedule-render.mjs` | 文本摘要和页面数据结构渲染 |
| `schedule-service.test.mjs` | 服务层单测 |
| `schedule-intent.test.mjs` | 意图解析和追问规则单测 |
| `schedule-reminder-worker.test.mjs` | worker 锁和重试单测 |

### `schedule-service.mjs`

建议导出：

```js
export function createScheduleService(pool, deps = {}) {
  return {
    createItem,
    updateItem,
    completeItem,
    cancelItem,
    listItems,
    createReminder,
    cancelReminder,
    listDueReminders,
    lockReminder,
    markReminderSent,
    markReminderFailed,
  };
}
```

关键约束：

- 所有写入校验 `user_id` 所属。
- 删除使用软删除，避免误删历史提醒。
- 创建提醒时必须确认 `remind_at` 是具体时间点，不能是全天日期。
- `remind_at <= now` 的提醒允许创建，但 worker 应尽快投递，并在回复里提示“时间已到，会立即提醒”。

### `schedule-intent.mjs`

MVP 不必追求全量 NLP。先做规则 + LLM 辅助的混合策略：

1. 规则层识别高置信意图：提醒、开会、行程查询、不提醒、完成/取消。
2. 规则层解析常用中文时间：今天、明天、后天、上午/下午/晚上、几点、半点、下周。
3. 不确定时让 Agent 追问，而不是静默创建。
4. 后续可引入 LLM JSON 解析，但输出必须过 schema 校验。

解析结果结构：

```ts
type ScheduleIntent =
  | {
      action: 'create';
      kind: 'task' | 'event';
      title: string;
      startAt?: number;
      endAt?: number;
      dueAt?: number;
      allDay?: boolean;
      reminder?: { remindAt?: number; offsetMinutes?: number; explicitNoReminder?: boolean };
      needsClarification?: Array<'event_time' | 'reminder_time' | 'reminder_offset'>;
    }
  | {
      action: 'query';
      rangeStart?: number;
      rangeEnd?: number;
      preferPage?: boolean;
    }
  | {
      action: 'update' | 'cancel' | 'complete';
      targetText: string;
    };
```

### Agent 接入策略

推荐分两阶段做。

#### 阶段 A：微信服务号入口先做确定性拦截

在 `wechat-mp.mjs` 转发给 Agent 前增加可选的 schedule preflight：

1. 对用户文本调用 `schedule-intent.mjs`。
2. 如果能确定执行，直接调用 `schedule-service.mjs` 并通过微信回复结果。
3. 如果缺必要信息，直接追问。
4. 如果不是日程意图，继续走现有 Agent 回复链路。

优点：

- 不依赖 Agent 是否会正确调用工具。
- 对“提醒”这种强业务流程更稳定。
- 不需要先改 goosed extension。

#### 阶段 B：给 H5 Agent 增加本地 schedule 工具

后续把日程能力暴露为平台工具，而不是让 Agent 调 H5 内部 API。建议工具：

- `schedule_create_item`
- `schedule_list_items`
- `schedule_update_item`
- `schedule_cancel_item`
- `schedule_create_reminder`
- `schedule_render_plan_page`

注意：当前 `api_lockdown` 会阻止 Agent 经代理访问 H5 本地接口，所以不要设计成“Agent 直接请求 `/mindspace/...` 或 `/api/schedule/...`”。更稳的是在服务端扩展平台工具，或在代理层专门白名单化受控的 schedule 工具调用。

## API 设计

H5 前端和管理调试可用 REST API；Agent 工具不直接走这些 API。

### 创建事项

`POST /api/schedule/items`

```json
{
  "kind": "event",
  "title": "会议",
  "start_at": 1781766000000,
  "end_at": null,
  "all_day": false,
  "timezone": "Asia/Shanghai",
  "source_text": "今天下午三点有个会",
  "reminder": {
    "remind_at": 1781762400000,
    "offset_minutes": 60,
    "channel": "wechat"
  }
}
```

### 查询事项

`GET /api/schedule/items?from=1781712000000&to=1782316800000&include_reminders=1`

返回按时间升序的 items，每条带提醒摘要。

### 更新、完成、取消

- `PATCH /api/schedule/items/:id`
- `POST /api/schedule/items/:id/complete`
- `POST /api/schedule/items/:id/cancel`
- `POST /api/schedule/reminders/:id/cancel`

所有接口需要登录态和 user ownership 校验。

## 提醒 worker 设计

### 扫描策略

每 30 秒扫描一次：

```sql
SELECT *
FROM h5_schedule_reminders
WHERE status = 'pending'
  AND remind_at <= ?
ORDER BY remind_at ASC
LIMIT 50
```

锁定时使用事务和状态更新：

```sql
UPDATE h5_schedule_reminders
SET status = 'locked',
    locked_until = ?,
    attempts = attempts + 1,
    updated_at = ?
WHERE id = ?
  AND status = 'pending';
```

投递成功后标记 `sent`；失败则：

- 可重试错误：状态改回 `pending`，`remind_at = now + backoff`。
- 不可重试错误：状态改为 `failed`。
- 超过最大次数：状态改为 `failed`。

### 幂等和并发

- `locked_until` 防止多进程重复投递。
- `delivery_logs` 记录每次尝试。
- `uq_schedule_item_remind_at` 防止同一事项重复创建同一时间提醒。

### 通知通道

MVP：

- 已绑定微信服务号用户：通过微信通知。
- 未绑定或通知失败：保留站内提醒状态，用户下次打开 H5 时展示。

生产上线前必须确认：

- 服务号客服消息是否适用于该次主动提醒。
- 是否需要模板消息或订阅通知模板。
- 对失败码做明确分流，例如未关注、超出发送窗口、模板不可用。

## 行程页面设计

### 页面数据结构

```json
{
  "title": "未来 7 天行程",
  "range_label": "6 月 18 日 - 6 月 24 日",
  "days": [
    {
      "date": "2026-06-18",
      "weekday": "周四",
      "items": [
        {
          "time": "15:00",
          "title": "会议",
          "kind": "event",
          "reminder": "14:00 提醒",
          "status": "active"
        }
      ]
    }
  ]
}
```

### 视觉要求

- 页面第一屏就是行程，不做大段介绍。
- 移动端使用纵向时间线；桌面端可使用 7 日网格。
- 颜色不使用单一紫蓝渐变；建议用清爽白底、墨色文本、低饱和蓝/绿/橙作为状态色。
- 所有文字在 375px 宽度下不溢出。
- 对“已过期、今天、明天、已提醒、无提醒”有明确状态。

## 权限和隐私

- 行程属于用户私密数据，默认不发布到 Plaza。
- 生成 MindSpace 页面时默认保存为私有草稿或用户私有空间；只有用户明确要求分享时才创建公开页。
- API 只返回当前登录用户的数据。
- 日程原文 `source_text` 可能含隐私，后台日志不要直接打印全文。

## 配置项

建议新增环境变量：

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `H5_SCHEDULE_ENABLED` | `0` | 是否启用日程 API 和微信 preflight |
| `H5_REMINDER_WORKER_ENABLED` | `0` | 是否启动提醒 worker |
| `H5_REMINDER_SCAN_INTERVAL_MS` | `30000` | worker 扫描间隔 |
| `H5_REMINDER_DEFAULT_MEETING_OFFSET_MINUTES` | `60` | 会议默认提前提醒分钟数 |
| `H5_REMINDER_MAX_ATTEMPTS` | `5` | 最大投递次数 |
| `H5_DEFAULT_TIMEZONE` | `Asia/Shanghai` | 默认用户时区 |

部署“每天早上 7 点服务号推送待办记录”时，至少需要：

```bash
H5_WECHAT_MP_ENABLED=1
H5_SCHEDULE_ENABLED=1
H5_REMINDER_WORKER_ENABLED=1
H5_DEFAULT_TIMEZONE=Asia/Shanghai
```

## 开发步骤

### P0：设计和测试骨架

- 新增本文档。
- 新增 `schedule-intent.test.mjs`，把关键中文场景先写成测试。
- 新增空服务骨架，确保不影响现有启动。

### P1：本地存储和 API

- 在 `schema.sql` 加三张表。
- 在 `db.mjs` 的 `migrateSchema` 加 `CREATE TABLE IF NOT EXISTS`。
- 实现 `schedule-service.mjs`。
- 实现 REST API，并补 `src/api/client.ts` 类型。

### P2：微信入口 preflight

- 在 `wechat-mp.mjs` 中，当 `H5_SCHEDULE_ENABLED=1` 时启用日程意图解析。
- 对可执行请求直接创建并回复。
- 对缺信息请求直接追问。
- 非日程消息保持现有 Agent 路径。

### P3：提醒 worker

- 实现 `schedule-reminder-worker.mjs`。
- 在 `server.mjs` 启动时按 env 开关启动。
- 先接入微信发送方法，失败后写 delivery log。

### P4：行程展示

- 文本摘要：直接在微信/H5 聊天里展示。
- 页面摘要：生成 MindSpace HTML 草稿或公开页，用户确认后再公开。

## 测试计划

### 单元测试

必须覆盖：

- “我明天要去开会，帮我记录增加一个提醒”解析为缺 `event_time` 和 `reminder_offset`。
- “不用提醒，先记一下”不会创建 reminder。
- “今天下午三点有个会”创建 event，并默认 offset 60。
- “明天上午九点提醒我带材料”创建 task reminder，remind_at 为明天 09:00。
- “看看我的行程计划”默认查询最近 7 天。
- “看下明天的安排”查询明天 00:00 到后天 00:00。

### 服务层测试

- 创建 event + reminder 成功。
- 同一 item 同一 remind_at 重复创建被幂等处理。
- cancel item 后 reminder 自动不可投递。
- listItems 不返回其他用户数据。

### Worker 测试

- 到期 reminder 被锁定并发送。
- 并发 worker 不重复发送。
- 发送失败按 backoff 重试。
- 超过最大次数标记 failed。

### 回归测试

```bash
pnpm test
pnpm run build
```

涉及微信入口时补 `wechat-mp.test.mjs`：

- 日程意图命中时不进入 Agent。
- 非日程文本仍走 Agent。
- 重复微信 `msgId` 仍只处理一次。

## 验收用例

| 输入 | 期望 |
|------|------|
| 我明天要去开会，帮我记录增加一个提醒 | 追问具体会议时间和提前多久提醒 |
| 不提醒，先记一下 | 创建待办/全天日程，无 reminder |
| 今天下午三点有个会 | 创建 15:00 会议，14:00 提醒 |
| 明天上午九点提醒我带材料 | 创建 09:00 提醒 |
| 每天早上 7 点给我发一天的待办记录 | 创建每日 07:00 服务号待办摘要订阅 |
| 看看我的行程计划 | 展示最近 7 天 |
| 看看明天行程 | 只展示明天 |
| 生成一个好看的本周行程页面 | 生成 MindSpace 行程页面 |

## 风险和决策

| 风险 | 处理 |
|------|------|
| 微信主动通知规则限制 | 上线前确认模板/订阅通知资质；客服消息仅作可用时通道 |
| 自然语言时间歧义 | 缺关键时间必须追问 |
| Agent 幻觉创建 | MVP 在微信入口做确定性 preflight，后续再开放工具 |
| 生产库迁移风险 | 测试库先迁移，生产按维护窗口执行 |
| 用户隐私 | 默认私有，不自动公开行程页面 |

## 推荐结论

这项能力可做，建议按 P1 到 P3 先交付一个可靠 MVP：能记录、能追问、能查询、能到点提醒。MindSpace 精美行程页作为 P4 增强，不阻塞核心提醒能力上线。