docs: 监控层表结构说明（带字段备注）

13 张表逐字段写清楚类型、可空、含义，外加四条必须先知道的约定：
毫秒时间戳、NULL 不是 0、平台 id 是 xhs/dy 而抖音落盘目录叫 douyin、作品从不删除。

和 db-schema.sql（原始 DDL）配套：那份给机器看，这份给人看。

docs/db-schema.md

@@ -0,0 +1,347 @@
+# 监控层数据库表结构
+
+`api/monitor/**` 这一层用到的全部表。库名 `mediacrawler_prod`（MySQL 5.7，utf8mb4）。
+
+配套的原始 DDL 在 [`db-schema.sql`](./db-schema.sql) —— 那份是 `SHOW CREATE TABLE` 直接导的，
+含引擎、字符集和索引定义；本文是**带字段说明**的可读版。
+
+> **这两份都不是迁移脚本。** 建表和补列是 `api/monitor/db.py::init_db()` 在每次启动时按 ORM
+> 元数据自动做的：`create_all` 建缺失的表，`_ensure_columns` 对已存在的表逐列 `ALTER TABLE
+> ADD COLUMN`（新增 NOT NULL 列会带上默认值给老行兜底）。所以加一个字段只需要改
+> `models.py`，不用手写 SQL。
+
+---
+
+## 读之前要知道的四条约定
+
+1. **时间戳一律是毫秒**（`bigint`），由 `tools/time_util.get_current_timestamp()` 产生。
+   平台给秒的（抖音是秒）在 `adapters.PlatformAdapter.time_scale` 里换算 —— 差 1000 倍，
+   不换算的话 2026 年的作品会显示成 1970 年。
+2. **NULL 和 0 是两回事。** 指标、粉丝数这些「读不出来」的值一律存 **NULL，不存 0**：
+   0 在趋势图上是一条砸到底的线，和「不知道」完全不同。界面上 NULL 显示成「—」。
+3. **平台 id 是 `xhs` / `dy`**（`api/monitor/adapters.py`）。注意 `dy` 是监控层的 id，
+   爬虫落盘目录叫 `douyin` —— 两者不一致，靠 `adapters.artifact_dir()` 换算。
+4. **作品删除是从来不做的。** 掉出采集窗口的作品仍然留在库里（趋势图、报表、导出要用），
+   只是界面不再显示。
+
+---
+
+## 表之间的关系
+
+```
+monitor_task ─┬─< monitor_target        一个任务配若干个目标（博主 / 作品）
+              ├─< monitor_run           每次运行一条
+              ├─< monitor_note ──< monitor_note_metric
+              └─< monitor_creator_stat
+
+monitor_note ──┬── monitor_note_alias   （按 platform + note_id 关联，不是外键）
+               └── monitor_note_tag ──< monitor_tag
+
+monitor_creator_alias                   （按 platform + creator_hash 关联）
+monitor_event                           事件流，多数挂在 task / run 上
+monitor_setting                         键值设置，独立
+```
+
+有真正外键（`ON DELETE CASCADE`）的只有 `task_id`：`monitor_target` / `monitor_run` /
+`monitor_note` / `monitor_creator_stat` 都指向 `monitor_task`，删任务会一并带走。
+
+其余关联**刻意不用外键**：它们跨的是「平台 + 业务 id」而不是主键，而且备注/标签是人为
+维护的，不该跟着采集数据被级联掉。
+
+---
+
+## monitor_task — 监控任务
+
+| 字段 | 类型 | 空 | 说明 |
+|---|---|:--:|---|
+| `id` | int | 否 | 主键 |
+| `name` | varchar(200) | 否 | 任务名，人起的 |
+| `platform` | varchar(32) | 否 | `xhs` / `dy` |
+| `mode` | varchar(16) | 否 | `creator` 博主模式 / `note` 作品模式 |
+| `enabled` | tinyint(1) | 否 | 是否参与定时调度 |
+| `interval_minutes` | int | 否 | 间隔模式的周期（分钟） |
+| `max_notes_count` | int | 否 | 每个博主每轮采多少条。**作品栏也按它开窗**（只画最新 N 条），但库里不删 |
+| `enable_comments` | tinyint(1) | 否 | 是否采评论 |
+| `max_comments_count` | int | 否 | 每条作品最多采多少条评论 |
+| `run_timeout_seconds` | int | 否 | 一轮的墙钟上限，超了判 `timeout` |
+| `notify_enabled` | tinyint(1) | 否 | 推送「有新作品」。默认**关**——可能每轮都有，会刷屏 |
+| `notify_failures` | tinyint(1) | 否 | 推送「出异常了」（登录失效 / 运行失败 / 没抓到数据）。默认**开** |
+| `schedule_mode` | varchar(16) | 否 | `interval` / `daily` / `weekly` |
+| `schedule_hours` | varchar(96) | 否 | `daily`/`weekly` 用：几点跑，逗号分隔，如 `9,18` |
+| `schedule_days` | varchar(32) | 否 | `weekly` 用：周几，**0 = 周一**（对齐 Python 的 `date.weekday()`） |
+| `schedule_minute` | int | 否 | 整点后的第几分钟，三个模式共用 |
+| `next_run_at` | bigint | 是 | 下次该跑的时刻。调度器就按这个字段挑任务 |
+| `last_run_at` | bigint | 是 | 上次运行的**开始**时刻（不是结束） |
+| `last_status` | varchar(32) | 否 | 上次运行状态，取值见 `monitor_run.status` |
+| `last_error` | text | 是 | 上次失败的原因，给人看的一句话 |
+| `last_notified_at` | bigint | 是 | 上次推送的时刻，用来限流 |
+| `created_at` / `updated_at` | bigint | 否 | |
+
+`schedule_hours` / `schedule_days` 存的是**逗号分隔的字符串**而不是关联表 —— 内容是几个
+小整数，单独建表只会让每次读取多一跳。
+
+---
+
+## monitor_target — 任务的目标
+
+一个任务可以配多个博主（或作品）。
+
+| 字段 | 类型 | 空 | 说明 |
+|---|---|:--:|---|
+| `id` | int | 否 | 主键 |
+| `task_id` | int | 否 | → `monitor_task.id`，**级联删除** |
+| `kind` | varchar(16) | 否 | 等于任务的 `mode`：`creator` / `note` |
+| `external_id` | varchar(128) | 否 | 规范化后的 id。博主是 sec_uid（抖音）/ user_id（小红书），作品是 note_id |
+| `xsec_token` | varchar(512) | 否 | **只有小红书有**：分享链接里那个会过期的令牌。抖音恒为空串 |
+| `xsec_source` | varchar(64) | 否 | 同上，配套的 source 参数 |
+| `raw_value` | text | 否 | 用户当初粘进来的原文（URL 或裸 id），出问题时用来回溯 |
+| `label` | varchar(200) | 否 | 展示用的名字 |
+| `enabled` | tinyint(1) | 否 | 关掉的目标这一轮不采 |
+| `created_at` | bigint | 否 | |
+
+**唯一键** `(task_id, kind, external_id)` —— 同一个目标粘两次不会变成两行。
+
+---
+
+## monitor_run — 每一次运行
+
+| 字段 | 类型 | 空 | 说明 |
+|---|---|:--:|---|
+| `id` | int | 否 | 主键 |
+| `task_id` | int | 否 | → `monitor_task.id`，级联删除 |
+| `trigger` | varchar(16) | 否 | `scheduled` 定时 / `manual` 手动 |
+| `status` | varchar(16) | 否 | `pending` 排队中、`running` 运行中、`success`、`partial` 部分成功、`failed`、`timeout`、`interrupted` 被中断 |
+| `phase` | varchar(16) | 否 | 建这条 run 时任务的 `mode`。任务中途改了模式，也还能知道当时跑的是什么 |
+| `save_data_path` | text | 否 | 这一轮产物的落盘目录 |
+| `queued_at` | bigint | 否 | 入队时刻 |
+| `not_before` | bigint | 否 | 在这之前不许开跑（错峰 / 防抖） |
+| `started_at` | bigint | 是 | 真正开跑的时刻 |
+| `finished_at` | bigint | 是 | 结束时刻 |
+| `exit_code` | bigint | 是 | 退出码。抖音走进程内 HTTP，值是 0 / 1；小红书走子进程。Windows 的进程崩溃会是大整数（NTSTATUS），`ingest.describe_exit_code()` 会翻译 |
+| `notes_fetched` | int | 否 | 这一轮**读到**多少条作品 |
+| `comments_fetched` | int | 否 | 读到多少条评论 |
+| `new_notes` | int | 否 | 其中多少条是**新的** |
+| `new_comments` | int | 否 | 同上 |
+| `is_baseline` | tinyint(1) | 否 | 是否该任务的**第一轮成功运行**。基线轮刻意不发增量事件 —— 没有「上一轮」可比，全报成新增只是噪音 |
+| `max_comments_count` | int | 否 | 跑的时候用的值快照。任务后来改了，历史记录仍然能解释得通 |
+| `error_message` | text | 是 | 失败原因 |
+
+---
+
+## monitor_note — 作品（笔记 / 视频）
+
+| 字段 | 类型 | 空 | 说明 |
+|---|---|:--:|---|
+| `id` | int | 否 | 主键 |
+| `task_id` | int | 否 | → `monitor_task.id`，级联删除 |
+| `note_id` | varchar(128) | 否 | 平台上的作品 id（抖音叫 `aweme_id`） |
+| `title` | text | 否 | 标题 / 文案 |
+| `note_url` | text | 否 | 作品页地址 |
+| `cover` | text | 否 | 封面。**优先是本地缓存地址** `/api/monitor/covers/{note_id}`——远程图床地址带签名、会过期（实测隔天 403），本地那份不会 |
+| `creator_hash` | varchar(64) | 否 | 创作者 id 的**单向哈希**。爬虫刻意不落原始 user_id，所以这是唯一稳定的创作者标识，作品栏按它分组 |
+| `creator_name` | varchar(200) | 否 | 创作者昵称（本仓库关掉了脱敏，是原文） |
+| `source_kind` | varchar(16) | 否 | 平台自己的作品类型：小红书取 `type`，抖音取 `aweme_type` |
+| `published_at` | bigint | 是 | **作者发布**的时间。和 `first_seen_at` 完全不是一回事——把早就发过的作品加进监控时，两者能差好几个月 |
+| `first_seen_run_id` | int | 是 | 第一次看到它是在哪一轮 |
+| `first_seen_at` | bigint | 否 | **我们第一次看到它**的时刻 |
+| `last_seen_run_id` | int | 是 | 最后一次采到它的轮次 |
+| `last_seen_at` | bigint | 否 | 最后一次采到它的时刻 |
+
+**唯一键** `(task_id, note_id)` —— 同一件作品被两个任务同时监控就是两行，各算各的增量。
+
+> 掉出采集窗口的作品**不会被删**。界面按 `max_notes_count` 开窗只画最新 N 条，而库里保留
+> 全部：趋势图、报表、导出读的都是这份全量。
+
+---
+
+## monitor_note_metric — 作品指标快照（趋势的来源）
+
+一轮一条，作品的四项互动指标。
+
+| 字段 | 类型 | 空 | 说明 |
+|---|---|:--:|---|
+| `id` | int | 否 | 主键 |
+| `task_id` | int | 否 | 属于哪个任务 |
+| `note_id` | varchar(128) | 否 | 哪条作品 |
+| `run_id` | int | 否 | 哪一轮采的 |
+| `captured_at` | bigint | 否 | 采集时刻 |
+| `liked_count` | int | **是** | 点赞。**解析不出来就是 NULL，不是 0** |
+| `comment_count` | int | **是** | 评论 |
+| `collected_count` | int | **是** | 收藏 |
+| `share_count` | int | **是** | 分享 |
+| `raw_liked_count` | varchar(64) | 否 | 平台返回的**原文**（可能是 `1.2万`） |
+| `raw_comment_count` | varchar(64) | 否 | 同上 |
+| `raw_collected_count` | varchar(64) | 否 | 同上 |
+| `raw_share_count` | varchar(64) | 否 | 同上 |
+
+**唯一键** `(task_id, note_id, run_id)`。
+
+留 `raw_*` 四列是为了**事后可审计**：解析规则出问题时，原文还在，能重新算一遍。
+
+---
+
+## monitor_comment — 评论
+
+| 字段 | 类型 | 空 | 说明 |
+|---|---|:--:|---|
+| `id` | int | 否 | 主键 |
+| `task_id` | int | 否 | 属于哪个任务 |
+| `note_id` | varchar(128) | 否 | 评论挂在哪条作品下 |
+| `comment_id` | varchar(128) | 否 | 平台上的评论 id |
+| `content` | text | 否 | 评论正文 |
+| `nickname` | varchar(200) | 否 | 评论人昵称 |
+| `creator_hash` | varchar(64) | 否 | 评论人 id 的哈希 |
+| `create_time` | bigint | 是 | 评论发布时间 |
+| `like_count` | int | 是 | 这条评论的点赞 |
+| `sub_comment_count` | int | 否 | 子评论数。平台没给就是不填，**不猜** |
+| `parent_comment_id` | varchar(128) | 否 | 父评论 id。**顶层评论两边写法不同**：小红书是空串，抖音是 `"0"`——`adapters.parent_comment_id()` 会把 `"0"` 归一成空串 |
+| `first_seen_run_id` | int | 是 | 第一次见到是在哪一轮 |
+| `first_seen_at` | bigint | 否 | 第一次见到的时刻 |
+
+**唯一键** `(task_id, note_id, comment_id)`。
+
+> 评论接口**没有时间排序**，只能看到平台默认顺序下的前 N 条。所以第一次见到的评论分成
+> 「上一轮之后发的」和「第一次见到的」两类事件，而不是一口咬定都是新发的。
+
+---
+
+## monitor_creator_stat — 博主账号级快照
+
+一门一个人：粉丝数 / 总获赞 / 作品数。这是**作品列表给不了**的东西 —— 作品说的是「这条涨了
+多少赞」，这里说的是「这个人整个账号在涨还是在掉」。
+
+| 字段 | 类型 | 空 | 说明 |
+|---|---|:--:|---|
+| `id` | int | 否 | 主键 |
+| `task_id` | int | 否 | → `monitor_task.id`，级联删除 |
+| `run_id` | int | 否 | 哪一轮采的 |
+| `creator_hash` | varchar(64) | 否 | 博主哈希（和 `monitor_note.creator_hash` 同一个口径） |
+| `nickname` | varchar(128) | 否 | 昵称 |
+| `creator_id` | varchar(128) | 否 | **平台上的主页 id**（抖音是 sec_uid）。用来拼「跳到他主页」的链接——哈希是单向的，拼不出地址 |
+| `fans` | bigint | **是** | 粉丝数 |
+| `total_favorited` | bigint | **是** | 总获赞 |
+| `works_count` | bigint | **是** | 主页作品总数（和我们监控到的条数不是一回事） |
+| `following` | bigint | **是** | 关注数 |
+| `captured_at` | bigint | 否 | 采集时刻 |
+
+**唯一键** `(task_id, creator_hash, run_id)`。
+
+> **目前只有抖音会写这张表。** 小红书走的是爬虫子进程，而它的 `save_creator()` 在教学版里
+> 是空函数，从来没落过创作者资料。所以小红书的博主没有粉丝数，也没有主页链接。
+
+---
+
+## monitor_creator_alias — 博主备注
+
+| 字段 | 类型 | 空 | 说明 |
+|---|---|:--:|---|
+| `id` | int | 否 | 主键 |
+| `platform` | varchar(16) | 否 | `xhs` / `dy` |
+| `creator_hash` | varchar(64) | 否 | 哪个博主 |
+| `alias` | varchar(128) | 否 | 人自己起的名字（「竞品A」）。空串表示没起过 |
+| `updated_at` | bigint | 否 | |
+
+**唯一键** `(platform, creator_hash)` —— 同一个博主出现在多个任务里，备注只填一次。
+
+作品栏按 `creator_hash` 分组，可那是个哈希、昵称又常常认不出是谁；备注是唯一能把账号对上
+人的东西。
+
+---
+
+## monitor_note_alias — 作品备注
+
+| 字段 | 类型 | 空 | 说明 |
+|---|---|:--:|---|
+| `id` | int | 否 | 主键 |
+| `platform` | varchar(16) | 否 | `xhs` / `dy` |
+| `note_id` | varchar(128) | 否 | 哪条作品 |
+| `alias` | varchar(128) | 否 | 一句话的备注 |
+| `updated_at` | bigint | 否 | |
+
+**唯一键** `(platform, note_id)`。
+
+和博主备注是一对，但回答的不是同一个问题：博主备注回答「这个账号是谁」，作品备注回答
+「这条我要盯着」。一个博主底下常常只有一两件值得盯的，所以不能合并。
+
+---
+
+## monitor_tag — 标签词表
+
+在「设置 → 作品标签」里维护。**全局一套，不按平台分**——「重点」是给人自己用的心智，不该在
+小红书和抖音各定义一遍。
+
+| 字段 | 类型 | 空 | 说明 |
+|---|---|:--:|---|
+| `id` | int | 否 | 主键 |
+| `name` | varchar(32) | 否 | 标签名 |
+| `color` | varchar(16) | 否 | **调色板里的名字**：`cyan`/`pink`/`green`/`orange`/`muted`。不是色值——Tailwind 的类名是构建时静态提取的，拼出来的动态类名它看不见，线上会静默变无色 |
+| `sort_order` | int | 否 | 展示顺序。新建时取 `max+1` 而不是 `count`：删过标签之后 count 会撞上已有的值 |
+| `created_at` | bigint | 否 | |
+
+**唯一键** `(name)` —— 两个「重点」在筛选列表里是灾难，选哪个都像对的。
+
+---
+
+## monitor_note_tag — 作品 ↔ 标签
+
+| 字段 | 类型 | 空 | 说明 |
+|---|---|:--:|---|
+| `id` | int | 否 | 主键 |
+| `platform` | varchar(16) | 否 | `xhs` / `dy` |
+| `note_id` | varchar(128) | 否 | 哪条作品 |
+| `tag_id` | int | 否 | → 逻辑上指向 `monitor_tag.id`，**但没有外键**（见下） |
+| `created_at` | bigint | 否 | |
+
+**唯一键** `(platform, note_id, tag_id)` —— **多对多**：一条作品可以既是「重点」又是「竞品」。
+
+> 删标签时**显式删关联**，不依赖外键级联：测试跑的是 SQLite，而它默认不启用外键约束。
+> 靠级联的话会出现「测试全绿、线上才对」或者反过来的情况。
+
+标签和备注并存、不是一回事：备注是一句话的**自由文字**，标签是**封闭词表里的分类**。分类
+必须封闭，否则「重点/重要/优先」各写各的，筛选就没法用了。
+
+---
+
+## monitor_event — 变化事件
+
+界面上的「变化」列表和企业微信推送读的都是它。
+
+| 字段 | 类型 | 空 | 说明 |
+|---|---|:--:|---|
+| `id` | int | 否 | 主键 |
+| `task_id` | int | 否 | 属于哪个任务 |
+| `run_id` | int | 是 | 由哪一轮产生 |
+| `type` | varchar(32) | 否 | 见下表 |
+| `severity` | varchar(16) | 否 | `info` / `warning` / `error` |
+| `target_kind` | varchar(16) | 否 | 目前只有两种值：作品级的事件写 `note`，任务级的事件（运行失败 / 疑似登录失效 / 没抓到数据）留**空串** |
+| `target_id` | varchar(128) | 否 | 对象 id —— 作品级的是作品 id（note_id / aweme_id），任务级的是空串 |
+| `title` | text | 否 | 一句话。推送和列表里显示的就是它 |
+| `payload_json` | text | 否 | 结构化细节（增量数值、退出码、失败原因…） |
+| `created_at` | bigint | 否 | |
+| `is_read` | tinyint(1) | 否 | 未读数就是按它统计的 |
+
+`type` 的取值：
+
+| 值 | 含义 |
+|---|---|
+| `new_note` | 发现新作品 |
+| `new_comment_posted` | 上一轮之后**发布**的评论 |
+| `new_comment_seen` | 第一次见到的评论（未必是刚发的，见评论那节的说明） |
+| `metric_delta` | 指标有明显变化 |
+| `run_failed` | 运行失败 |
+| `suspected_auth_failure` | 疑似登录失效（一条都没抓到，且没有别的解释） |
+| `no_data_found` | 没抓到数据，但原因不是登录（比如产物写在别的目录） |
+
+---
+
+## monitor_setting — 键值设置
+
+| 字段 | 类型 | 空 | 说明 |
+|---|---|:--:|---|
+| `key` | varchar(64) | 否 | 主键。两种形状：`platform.<平台>.<名字>` / `system.<名字>` |
+| `value` | text | 否 | **一律存字符串**，读的时候按注册表里的类型转 |
+| `updated_at` | bigint | 否 | |
+
+哪些 key 合法、各是什么类型/默认值，由 `api/monitor/app_settings.py` 的注册表决定 —— 设置页
+的表单就是照它自动生成的。密钥类的设置（webhook 地址、cookie）存进来但**从不原样返回**给
+前端，只回「有没有设置」和长度。