智叟云集周期监控与时间语义：计划版本、时区转换、错过处理和补采操作

​

▣智叟云集周期监控与时间语义：计划版本、时区转换、错过处理和补采操作

◆持续监测与手动运行一次任务有明显区别。用户希望智叟云集每天固定时间观察品牌回答，每周追踪竞品变化，并在节假日、系统维护或平台限流时保持可解释的执行记录。周期监控需要回答的不只是“什么时候触发”，还包括使用哪一版问题、错过时间是否补跑、前一次没有结束怎么办，以及补采能否代表过去。本文围绕日历语义和计划实例展开，补齐GEO优化监测系统长期运行所需的时间模型、前后端契约和落库规则。

◆范围说明：本文按生产环境要求组织工程设计与操作流程。AI功能配图用于说明目标设计；代码中的认证、数据库、出站网络与部署依赖需要按文中边界接入。未连接真实生产数据库的部分不声称已经通过线上验证。

​编辑

▧智叟云集周期监控功能设计：计划日历、时区配置、冲突策略与运行记录。 点击可放大。

▣一、计划不是后台无限循环的按钮

◆计划保存用户希望如何观察世界的规则，例如每天当地时间九点采集一组品牌问题；计划实例表示某一天应发生的那次观察；执行批次表示实例真正创建的采集工作。三者分别使用schedule_id、occurrence_id与run_id。把它们合成一个任务编号，会让历史修改、漏跑解释与费用核对变得困难。

◆智叟云集的周期配置可以包括品牌项目、问题修订集合、平台终端、时区、频率、生效区间、预算上限和错过策略。前端提供可读配置及未来触发预览，服务端计算实际时间并校验权限，数据库记录版本与实例。Worker继续沿用已有采集状态机，本文不重复讨论平台提交重试。

◆这里展示的是可实施的扩展功能设计。系统支持范围应由已接入的平台能力与部署配置决定，不能因为日历上能选某个平台就宣称该平台所有终端都可采集。计划只负责在明确条件下创建新观察，并不会改变AI平台本身的开放能力。

▣二、先区分本地日历时间与固定间隔

◆“每天九点”是本地日历规则，“每隔二十四小时”是经过时长规则。遇到夏令时或时区规则变化，两者并不总是相同。日历计划保存IANA时区名称与本地时间，在每个日期上解析为UTC；固定间隔则从确定的UTC锚点按时长推进，不能混用同一套加法。

◆存储保留计划时区、原始本地时间、解析后的UTC时刻和时区数据版本。运行记录同时显示计划时间与实际开始时间，避免排队延迟被掩盖。用户把浏览器时区切换到其他地区时，只改变展示方式，不应自动重写已保存的监控计划。

◆前端不能只提交浏览器计算出的一个UTC偏移，因为固定偏移无法表达未来日期的时区规则。服务端返回未来若干次触发预览，用户确认的是日期、星期和本地时刻的组合。发布时固定运行环境的时区数据来源，缺少时区库时拒绝启用相关计划。

◆时间查询使用左闭右开区间，某天的结束边界就是下一天的开始，避免午夜样本重复计入两个日期。日历日的UTC长度可能不是二十四小时，所以按当地日期生成统计窗口时，应分别解析当天和次日的边界。数据库保存UTC并不自动保存原时区名称，计划表需要单独持有名称用于未来解析。

▣三、夏令时跳空与重复时刻必须显式处理

◆某些地区进入夏令时时会跳过一段本地时间，配置在这段时间内的任务没有对应真实时刻。退出夏令时时同一段本地时间可能出现两次。系统需要提供明确策略，例如不存在时跳过，重复时选第一次、第二次或分别运行，并把选择写入计划版本。

◆Python代码通过分别指定fold值构造候选UTC时间，再转换回原时区核对本地字段。没有候选表示跳空，两个不同候选表示重复，只有一个表示普通时刻。直接给无时区时间附加tzinfo并不能完成这些有效性判断，因此回转检查是必要步骤。

◆如果业务只在不采用夏令时的时区运行，也应保留完整时区身份。团队扩展到其他区域时才能沿用同一模型。代码中的严格策略遇到跳空或歧义会报错，调用方必须选择业务策略后处理，不能为了让计划顺利保存而静默移动时间。

​编辑

▧周期计划实例化流程 点击可放大。

▣四、数据库用计划实例防止重复触发

◆计划修订表保存不可变规则，实例表保存应执行时刻及状态。以租户、计划修订和计划UTC时刻建立唯一键，多台调度器同时发现到期事件时，只有一个事务能够插入该实例。数据库唯一约束是最终防线，单机内存锁或只在Redis设置短期键不足以形成可靠历史。

◆调度器在短事务内锁定计划控制行，读取当前修订，生成有限数量到期实例并推进扫描位置。创建执行批次与写出任务事件在同一事务中完成，任何一步失败都回滚。事务里不等待外部平台，不发送网络请求，也不长时间遍历多年历史。

◆实例状态可以包括计划中、因策略跳过、等待预算、待执行、已创建批次和已取消。采集完成状态由关联批次表达，不能把调度器成功创建批次当成回答已完成。这样用户能区分“计划没有触发”和“已经触发但平台采集失败”。

▣五、修改计划以生效边界切开历史

◆用户把每日九点改为十点时，系统新建修订并确定生效边界。边界之前已实例化的工作保留原配置，边界之后使用新修订。对于已经预生成但尚未开始的实例，需要明确取消并重建还是继续原计划，不能简单更新数据库规则后让旧实例身份失去解释。

◆同一计划的有效修订区间不得重叠。调度器与修改接口都锁定同一计划控制行，再判断修订和边界，避免修改同时触发两份实例。只在唯一键里放修订号并不能阻止不同修订在同一业务时刻重复运行，因此有效区间和锁定协议必须共同落实。

◆问题库更新也不能默认改变正在生效的计划输入。可以选择固定问题修订集合，或明确在每次触发时解析最新批准集合并保存快照。两种策略都可实施，但历史运行必须记录实际选用版本。页面展示“跟随最新”时，应解释审批和生效条件。

▣六、错过处理决定恢复后的业务行为

◆系统维护期间错过多个时刻，可以跳过全部、只补最近一次，或按有界数量补齐。策略需要同时设置最大回看时间与最多补跑次数，防止一周停机后瞬间创建大量付费采集。每个被跳过的计划实例仍应保留原因，不能让历史日历凭空出现空白。

◆补采只能获得执行当时的平台回答，不能回到过去观察AI输出。因此记录中必须保留原计划时刻与实际采集时刻，报告按明确的观察时间口径展示。把今天补到的回答标成昨天的真实回答，会使趋势分析与优化前后比较失去可信度。

◆如果仅需要恢复昨天已经完成但未汇总的统计，那是重算历史数据，不是重新采集。界面分别提供“补采缺失观察”和“重算已有结果”，两者使用不同任务类型、预算规则和输出标记。操作人员先判断缺的是回答还是分析，才能选择正确动作。

◆选择“只补最近一次”时，系统仍应把其余到期实例记为策略跳过，而不是遗忘它们。恢复页面列出可补范围、预计费用和实际执行时间，用户能判断补采是否仍有业务价值。对已经过期的营销活动问题，可以选择不补，并将缺口保留在趋势图中，避免用连线暗示期间持续观察。

▣七、运行重叠、预算与平台容量一起决策

◆当新实例到期而上一批仍在运行时，可选择跳过、排队或允许并行。跳过适合避免重复观察，排队适合保留每次计划身份，并行需要有容量与预算支持。强制替换上一批必须说明已发出的平台调用无法撤销，不能把取消状态当成费用必然退还。

◆预算检查在实例真正准备创建批次时执行，而不是在计划保存时一次性保证未来所有费用。每个实例记录报价版本、预留结果和失败原因。预算不足时可进入等待或跳过，恢复后是否补跑仍由错过策略决定，不得自动发起超过用户限制的历史采集。

◆大量品牌同一时间触发会形成峰值。可以在用户允许的窗口内使用确定性抖动，按计划身份分散开始时间，并保留名义计划时刻。抖动幅度必须显示给用户，因为采样时间变化可能影响比较。限流分租户和平台执行，避免大项目长期占满共享容量。

​编辑

▧错过计划与恢复流程 点击可放大。

▣八、前端预览、暂停和手动执行的边界

◆编辑页先显示未来触发预览和预计任务量，再允许保存。用户选择工作日时，需要明确是周一到周五还是引用有版本的业务日历；法定节假日与调休不能依靠固定星期判断。日历版本变更应提示影响到的日期，重新生成预览后再发布修订。

◆暂停计划只阻止未来实例继续创建，不默认取消已在运行的批次。恢复时让用户看到暂停期间错过的数量和当前策略。手动立即执行生成独立批次，不推进下一次计划时间，否则临时排查会意外改变长期观察节奏。

◆前端提交expected_version，防止两名管理员互相覆盖计划。服务端返回保存后的规则、版本和生效边界，页面以返回结果更新状态。网络超时后先查询保存结果，不立即重复创建新计划。重要状态通过后端事件或有界轮询刷新，页面关闭不影响调度。

◆节假日日历可以作为独立资源，包含区域、年份、来源、修订和明确的工作日集合。计划引用日历版本后，调休更正不应自动改变已创建批次。管理员先查看影响差异，再确定新版本生效日期。暂未配置业务日历时，只能称为按星期执行，不能把它包装成已经包含完整节假日规则。

▣九、部署与恢复要处理时间和领导权

◆调度器可以多副本部署，但不能只依赖某个进程永远是主节点。数据库锁定与唯一实例约束使重复扫描安全，租约用于限制并发工作，领取后的写回仍验证令牌。时钟同步影响到期判断，服务端使用统一时源监测偏差，数据库时间可用于事务内判定。

◆扫描位置记录已经决定处理的时间边界，跳过也属于已决策结果。每批处理有限数量，提交后再推进下一段。若从备份恢复，扫描位置和实例表必须一起恢复并对账，不能只回退计划游标后无条件重新创建所有历史批次。

◆时区数据升级属于行为变更。升级前对未来触发时间进行差异比较，识别受影响计划，并记录采用新规则的边界。已经生成的实例保留原解析结果；未来规则变化不能让过去的计划时间被重新解释成另一时刻。

◆任务回放应先做只读推演：给定计划修订、扫描边界和固定当前时间，输出将执行、将跳过、将等待的实例列表，再与历史账本比较。推演不创建真实批次，也不预留费用。生产恢复工具与实际执行接口保持分离，使运维能够先核对影响范围，再由授权操作正式提交恢复。

▣十、验收覆盖日历边界和业务后果

◆时间测试至少覆盖普通日期、月末、闰日、跨年、夏令时跳空与重复时刻。固定间隔测试检查UTC时长，日历测试检查当地钟表时间，不用同一断言混淆两个需求。代码把当前时间作为参数传入，使测试不会随着实际日期改变。

◆并发测试让两台调度器同时触发同一实例，验证只有一个批次和一份预算预留；修订切换时检查旧区间结束、新区间开始且没有重叠。暂停恢复测试检查跳过记录，长时间停机测试检查补跑上限和实际观察时间标记。

◆监控关注触发延迟、错过数量、等待预算年龄、计划版本冲突和重复实例冲突。告警应能定位到具体计划与用户选择的策略，而不是只报一个Worker异常。周期监控真正的可靠性，是每一次执行与每一次不执行都有可追溯理由。

◆服务退出时先停止扫描，再提交或回滚当前短事务。重启后从持久化边界继续，数据库唯一约束吸收重复扫描。计划量大时按租户或计划分区扫描，但分区方式变化也应有交接边界，避免两个扫描器都以为对方负责某段范围。

▣十一、系统操作速查

▣01｜配置周期

◆选择品牌问题、平台、时区与本地时间，确定日历规则或固定间隔，核对未来触发预览。

▣02｜设置恢复策略

◆明确错过处理、重叠行为和补跑上限，查看预算与容量要求，再保存带生效边界的版本。

▣03｜检查运行日历

◆分别查看计划时间、实际开始、采集状态和分析状态。跳过或等待应有可读原因和关联实例。

▣04｜修改与补采

◆变更生成新修订，手动运行不移动计划。补采保留实际采集时刻，重算只处理已有证据。

▣十二、代码展示与逐段解释

▣本地时刻解析与错过选择

◆代码文件：03_calendar.py。下方代码对应本节核心逻辑，完整文件与测试说明在资料包的 code 目录。

from datetime import datetime, timezone
from zoneinfo import ZoneInfo

def local_candidates(local: datetime, zone_name: str) -> list[datetime]:
    if local.tzinfo is not None:
        raise ValueError('local wall time must be naive')
    zone = ZoneInfo(zone_name)
    candidates = set()
    for fold in (0, 1):
        aware = local.replace(tzinfo=zone, fold=fold)
        utc = aware.astimezone(timezone.utc)
        back = utc.astimezone(zone)
        if back.replace(tzinfo=None) == local:
            candidates.add(utc)
    return sorted(candidates)

def resolve_local(local: datetime, zone_name: str,
                  ambiguity: str = 'reject') -> list[datetime]:
    if ambiguity not in {'reject', 'first', 'second', 'both'}:
        raise ValueError('invalid ambiguity policy')
    values = local_candidates(local, zone_name)
    if not values:
        raise ValueError('nonexistent local time')
    if len(values) == 1:
        return values
    if ambiguity == 'reject':
        raise ValueError('ambiguous local time')
    if ambiguity == 'both':
        return values
    return [values[0 if ambiguity == 'first' else 1]]

def choose_missed(due: list[datetime], *, now: datetime,
                  max_age_seconds: int, mode: str, limit: int) -> list[datetime]:
    if mode not in {'skip', 'latest', 'bounded'}:
        raise ValueError('invalid missed policy')
    if limit <= 0 or max_age_seconds < 0:
        raise ValueError('invalid bounds')
    if now.utcoffset() is None or any(t.utcoffset() is None for t in due):
        raise ValueError('aware timestamps required')
    now_utc = now.astimezone(timezone.utc)
    absolute = {t.astimezone(timezone.utc) for t in due}
    eligible = sorted(t for t in absolute
                      if 0 <= (now_utc - t).total_seconds() <= max_age_seconds)
    if mode == 'skip':
        return []
    return eligible[-1:] if mode == 'latest' else eligible[-limit:]

◆代码解释 1：local_candidates为两种fold构造候选值，并通过UTC回转检查本地时间是否真实存在。普通日期两个候选会合并为一个，重复时刻保留两个不同UTC值，跳空没有候选。函数只接受无时区的本地钟表输入，避免把已带时区的数据再次错误解释。

◆代码解释 2：resolve_local要求调用方明确处理歧义。first与second按实际UTC先后选择，both返回两次，reject则阻止静默决定。跳空在核心函数中统一拒绝，调度服务依据计划策略记录跳过。Windows运行需要可用的IANA时区数据，部署镜像应锁定其来源与版本。

◆代码解释 3：choose_missed处理已经解析好的绝对时刻，过滤未来与超过回看范围的实例，再按策略选择最近一次或最近有限次数。未选中的实例需要由调度器记录跳过理由，函数只负责决策，不修改扫描位置。实际执行时间由Worker另行记录，不使用计划时间伪造观察时刻。

▣计划控制行与唯一实例

◆代码文件：03_occurrence.sql。下方代码对应本节核心逻辑，完整文件与测试说明在资料包的 code 目录。

-- 同一事务；API和调度器都先锁同一控制行。
SELECT current_revision FROM schedule_control
WHERE tenant_id = $1 AND schedule_id = $2 FOR UPDATE;
-- 应用确认$3仍为当前修订，$4位于其有效区间，且计划启用。
INSERT INTO schedule_occurrence
  (tenant_id, schedule_id, revision, scheduled_at, state)
VALUES ($1, $2, $3, $4, 'pending')
ON CONFLICT (tenant_id, schedule_id, revision, scheduled_at) DO NOTHING
RETURNING occurrence_id;
-- 仅插入成功者在本事务创建run、预留预算、写Outbox。
-- 无返回行时读取既有实例，不重复创建run；失败整体回滚。

◆代码解释 1：控制行锁将计划编辑和实例创建串行化。调度器获得锁后重新核对当前修订、生效区间和启用状态，再插入实例。唯一键防止同一修订与时刻被重复创建，RETURNING结果决定本事务是否继续创建执行批次；冲突时读取已存在实例，而不是再次预留预算。

◆代码解释 2：修订号不同的记录可能绕过这个唯一键，所以修改接口也必须遵守控制行锁与无重叠有效区间的协议。数据库迁移应补齐相应约束，历史预生成实例在切换时按确定规则取消或保留。这些条件不能只写在前端提示中，必须在服务事务中执行。

◆代码解释 3：批次、预算预留与Outbox写入同一事务，任何失败都撤销实例创建的相关结果。循环扫描以有限批次运行，提交后推进已决策边界。SQL是服务内的参数化事务片段，计划表、实例表和预算服务需先完成迁移及真实并发验证，不能直接作为独立脚本运行。

▣计划草稿的前端类型

◆代码文件：frontend.ts。下方代码对应本节核心逻辑，完整文件与测试说明在资料包的 code 目录。

export type ScheduleDraft = {
  expectedVersion: number; zone: string; localTime: string;
  missed: 'skip' | 'latest' | 'bounded'; maxCatchup: number;
};

◆代码解释 1：ScheduleDraft要求携带expectedVersion，服务端用它判断并发编辑。zone保存完整时区名称，localTime表达本地钟表值，missed与maxCatchup共同约束恢复行为。生产表单还应增加问题集合、有效区间和歧义策略，示出的类型专注于本章时间与版本契约。

◆代码解释 2：保存前调用服务端预览接口并显示未来触发点，保存后以服务端返回修订刷新页面。客户端时间只用于展示，不能决定任务是否到期。暂停与立即执行使用独立接口，避免复用保存操作造成计划时间意外推进。

▣十三、FAQ 问答

▣Q1｜每天运行和每隔二十四小时是否相同？

◆答：在固定偏移时区可能表现相同，但遇到夏令时变化会不同。前者按当地日历解析，后者按实际经过时长计算。

▣Q2｜昨天没运行，今天补采能算昨天的数据吗？

◆答：不能把今天观察到的平台回答当作昨天真实输出。应保留原计划时间与实际采集时间，并在报告中说明补采。

▣Q3｜暂停后为什么还有任务完成？

◆答：暂停通常阻止新实例创建，已提交批次仍会继续。取消在途任务是另一个操作，且无法撤回已经发送的外部请求。

▣Q4｜为什么不直接保存一个Cron表达式？

◆答：表达式可以描述部分频率，但不能独自表达问题版本、时区歧义、错过策略、预算和修订生效边界，业务配置仍需要独立模型。

▣十四、实施要点与参考资料

◆智叟云集系统的周期监控把长期观察转化为有身份、有时间语义的计划实例。AI品牌可见度监测系统、GEO监测系统、舆情监控和AI诊断都能复用这套调度基础，但必须保留实际观察时间和执行快照。这样AI数据采集的节奏才可比较，舆情分析的缺口才可解释，系统恢复也不会制造虚假的历史。

◆以下为相关机制的官方参考；本文业务模型、操作流程与组合方案为独立整理的实施设计。

↗Python 时区与fold语义

↗PostgreSQL 时间类型

​