update

openspec/specs/agent-open-api/spec.md

@@ -26,6 +26,25 @@
 - **WHEN** 查询或写入
 - **THEN** 请求被统一拒绝且不泄露资源存在性
 
+### Requirement: 代理开放接口查询不触发可靠卡观测
+
+系统 SHALL 对卡流量、卡状态、实名状态和设备流量查询返回当前本地业务事实，且 MUST NOT 因查询成功而提交卡观测序列、展开设备绑定卡观测或安排 Gateway 后台刷新任务。
+
+#### Scenario: 查询单卡本地事实
+
+- **WHEN** 已通过认证和数据范围校验的代理查询单卡流量、状态或实名状态
+- **THEN** 系统返回当前本地业务事实，且不创建卡观测序列或后台观测任务
+
+#### Scenario: 查询设备流量
+
+- **WHEN** 已通过认证和数据范围校验的代理查询设备流量，或以设备标识查询卡流量
+- **THEN** 系统返回当前本地业务事实，且不展开该设备的绑定卡来创建后台观测任务
+
+#### Scenario: 查询后本地事实仍可能由既有机制更新
+
+- **WHEN** 代理完成上述查询后发生既有轮询、回调或可靠业务事件驱动的本地事实更新
+- **THEN** 系统按对应既有机制更新本地事实，查询请求本身不承担触发该更新的责任
+
 ## 可达操作索引
 
 本节只用于入口导航，不是行为 Requirement；业务义务以上述 Requirements 为准。

openspec/specs/external-integration/spec.md

@@ -113,9 +113,41 @@
 - **WHEN** 富友主扫统一下单返回失败或请求结果未知
 - **THEN** 系统返回项目稳定错误且已接入外部交互日志的调用记录脱敏结果
 
+### Requirement: 高频轮询外部交互日志保留边界
+
+系统 SHALL 不为成功且无业务变化的自动轮询逐次创建 `tb_integration_log`。支付、审批、入站回调及其他依赖外部交互记录实现可靠幂等、结果恢复或渠道裁决的调用 MUST 继续持久化其外部交互记录。轮询外部调用失败、响应无效或结果未知时，系统 MUST 持久化可调查的失败或恢复记录。
+
+#### Scenario: Gateway 轮询成功且状态未变化
+- **GIVEN** 一次 Gateway 自动轮询成功，且结果没有引起业务事实变化
+- **WHEN** 系统完成该轮询
+- **THEN** 系统不创建该次轮询的 Integration Log
+
+#### Scenario: Gateway 轮询调用失败
+- **WHEN** 一次 Gateway 自动轮询超时、连接失败或返回无效响应
+- **THEN** 系统创建可调查的失败或恢复记录，并按既有策略处理后续轮询
+
+#### Scenario: 入站支付回调
+- **GIVEN** 支付渠道发送入站回调
+- **WHEN** 系统处理该回调
+- **THEN** 系统继续使用可靠持久化的外部交互记录保证既有幂等和恢复语义
+
+### Requirement: 外部交互日志归档与留存受控执行
+
+系统 SHALL 在审计归档与日留存任务总开关关闭时停止 Integration Log 的日归档和日留存处理，并安全跳过已入队的相关任务。总开关开启后，每次相关任务执行 MUST 至多处理一个已结束的上海自然日，且必须继续满足既有归档校验和 pending 记录保留规则。
+
+#### Scenario: Integration Log 归档任务被停用
+- **GIVEN** 审计归档与日留存任务总开关关闭
+- **WHEN** Integration Log 日归档或日留存任务被调度或消费
+- **THEN** 系统不扫描、归档、删除或更新在线 Integration Log
+
+#### Scenario: Integration Log 积压受控推进
+- **GIVEN** 任务总开关开启且存在多个满足既有归档条件的日期
+- **WHEN** 系统执行一次 Integration Log 归档或留存任务
+- **THEN** 系统仅处理一个自然日，并继续保留未处理日期以供后续执行
+
 ### Requirement: 外部交互日志逐日物理留存
 
-系统 SHALL 以 Asia/Shanghai 已结束的自然日为单位物理留存 `tb_integration_log`。删除一条已终态在线外部交互日志前，系统 MUST 已为其创建日生成可读取、可验证的归档对象和清单；该归档 MUST 包含该日当时全部外部交互日志，并验证日期范围、记录数量和校验摘要可作为恢复凭证。`pending` 记录 MUST 保留在线，不得被物理删除，且不得阻断同日已终态记录或更晚日期的归档、验证与物理清理。每次执行 SHALL 清理所有满足归档校验条件的已终态记录；某一来源的归档或校验失败时，系统 MUST 保留该来源当天及更晚日期的在线外部交互日志。
+系统 SHALL 以 Asia/Shanghai 已结束的自然日为单位物理留存 `tb_integration_log`。删除一条已终态在线外部交互日志前，系统 MUST 已为其创建日生成可读取、可验证的归档对象和清单；该归档 MUST 包含该日当时全部外部交互日志，并验证日期范围、记录数量和校验摘要可作为恢复凭证。`pending` 记录 MUST 保留在线，不得被物理删除，且不得阻断同日已终态记录或更晚日期的归档、验证与物理清理。每次执行 SHALL 至多处理一个满足归档校验条件的已结束自然日；某一来源的归档或校验失败时，系统 MUST 保留该来源当天及更晚日期的在线外部交互日志。
 
 #### Scenario: 最终归档通过后清理在线外部交互日志
 - **GIVEN** 某已结束自然日的外部交互归档对象和清单校验成功，且存在已终态在线外部交互日志
@@ -132,15 +164,15 @@
 - **WHEN** 日留存任务处理该日期
 - **THEN** 系统分批删除该日已终态的在线外部交互日志，保留 `pending` 记录，并保留归档对象
 
-#### Scenario: 历史积压按日期连续补清
+#### Scenario: 历史积压按日期受控推进
 - **GIVEN** 存在多个昨天及更早日期尚未完成物理清理，且这些日期各自存在满足归档校验条件的已终态外部交互日志
 - **WHEN** 日留存任务执行
-- **THEN** 系统按日期从早到晚清理全部符合条件的终态日志
+- **THEN** 系统仅处理最早的一个符合条件日期，并保留其余日期供后续执行
 
 #### Scenario: pending 不阻断后续日期
 - **GIVEN** 较早归档日只剩 `pending` 外部交互日志，且更晚归档日存在满足归档校验条件的已终态外部交互日志
 - **WHEN** 日留存任务执行
-- **THEN** 系统继续处理更晚归档日的已终态外部交互日志，不因较早日期的 pending 停止日期推进
+- **THEN** 系统在后续日留存任务中继续处理更晚归档日的已终态外部交互日志，不因较早日期的 pending 停止日期推进
 
 #### Scenario: pending 后续终结
 - **GIVEN** 某归档日的 pending 外部交互日志在该日首次留存后进入公开终态

openspec/specs/operations-audit/spec.md

@@ -46,9 +46,37 @@
 - **WHEN** 该操作的审计事件构造、校验或持久化失败
 - **THEN** 系统提交或返回该业务操作原本的结果，并以请求关联标识、动作编码和资源标识记录审计失败
 
+### Requirement: 轮询审计事实保留边界
+
+系统 SHALL 仅为产生业务事实变化、轮询失败、结果未知或人工触发的轮询操作持久化统一审计事件及资源快照。成功且无业务变化的自动轮询 MUST 不创建 `tb_audit_event` 或 `tb_audit_event_resource`，审计调查接口仅返回实际已保留的历史事实。
+
+#### Scenario: 自动轮询成功但无业务变化
+- **GIVEN** 一次自动轮询成功且没有改变任何业务状态、有效流量或风险结论
+- **WHEN** 系统结束该轮询处理
+- **THEN** 审计事件和审计资源表不新增该次轮询记录
+
+#### Scenario: 自动轮询改变业务事实
+- **GIVEN** 一次自动轮询产生可应用的业务状态或有效流量变化
+- **WHEN** 系统提交该变化
+- **THEN** 系统保留对应的审计事实与资源快照
+
+### Requirement: 审计归档与日留存受控执行
+
+系统 SHALL 提供独立的审计归档与日留存任务总开关。总开关关闭时，系统 MUST 不调度、不消费且安全跳过已入队的 Audit 日归档、Integration Log 日归档和日志日留存任务，不扫描或修改在线日志表。总开关开启时，每次任务执行 MUST 至多处理一个已结束的上海自然日；维护者可在低峰期重复执行以推进历史积压。
+
+#### Scenario: 归档与留存总开关关闭
+- **GIVEN** 审计归档与日留存任务总开关关闭
+- **WHEN** 定时器触发或 Worker 取得已入队的归档或留存任务
+- **THEN** 系统跳过该任务，不扫描 `tb_audit_event`、`tb_audit_event_resource` 或 `tb_integration_log`，且不创建归档或清理记录
+
+#### Scenario: 总开关开启时处理积压
+- **GIVEN** 审计归档与日留存任务总开关开启，且存在多个未处理的已结束自然日
+- **WHEN** Worker 执行一次归档或留存任务
+- **THEN** 系统至多处理一个自然日，并保留其余日期供后续受控执行
+
 ### Requirement: 审计在线数据逐日物理留存
 
-系统 SHALL 以 Asia/Shanghai 已结束的自然日为单位处理统一审计事件及其资源快照的在线留存。每次留存执行 SHALL 从最早尚未完成清理的归档日开始，连续处理至昨天；Integration Log 的 `pending` 记录不得阻断已通过完整性校验的审计事件及资源快照清理。任一审计归档日未通过完整性校验时，系统 MUST 保留该日及其后续日期的在线审计数据，且不得将它们标记为已清理。系统 MUST 先删除该日的审计资源快照，再删除该日的审计事件，并保留对象存储归档对象及清单作为恢复凭证。
+系统 SHALL 以 Asia/Shanghai 已结束的自然日为单位处理统一审计事件及其资源快照的在线留存。每次留存执行 SHALL 从最早尚未完成清理的归档日开始，至多处理一个已结束的自然日；Integration Log 的 `pending` 记录不得阻断已通过完整性校验的审计事件及资源快照清理。任一审计归档日未通过完整性校验时，系统 MUST 保留该日及其后续日期的在线审计数据，且不得将它们标记为已清理。系统 MUST 先删除该日的审计资源快照，再删除该日的审计事件，并保留对象存储归档对象及清单作为恢复凭证。
 
 #### Scenario: 已验证日期完成物理清理
 - **GIVEN** 某已结束自然日的审计归档成功，归档对象和清单可读取且与在线记录范围、数量和校验摘要一致

openspec/specs/polling-load-control/spec.md

@@ -0,0 +1,49 @@
+# 轮询负载控制当前行为
+
+## Purpose
+
+使高频卡轮询在多 Worker、重启积压和渠道延迟场景下保持受控吞吐，避免正常无变化观测将数据库写入量放大为不可接受的 I/O 负载。
+
+## Requirements
+
+### Requirement: 轮询全局并发与背压
+系统 SHALL 同时对全部轮询任务以及每一种轮询任务应用跨 Worker 实例共享的全局并发上限。达到任一上限的任务 MUST 不调用外部渠道、不创建审计或外部交互记录，并按既有调度语义延后执行。配置的上限 MUST 受安全范围约束，不能以零、负数或不受约束的大值绕过背压。
+
+#### Scenario: 多 Worker 达到同类轮询上限
+- **GIVEN** 多个 Worker 正在执行同一种轮询，且该任务的全局并发已达到配置上限
+- **WHEN** 又一个该类型轮询任务开始处理
+- **THEN** 系统不发起外部调用、不写入 PostgreSQL 观测记录，并将任务延后处理
+
+#### Scenario: 达到全部轮询任务总上限
+- **GIVEN** 不同种类的轮询任务合计已达到全局总并发上限
+- **WHEN** 任意一种新的轮询任务开始处理
+- **THEN** 系统不发起外部调用、不写入 PostgreSQL 观测记录，并将任务延后处理
+
+#### Scenario: 轮询上限配置非法
+- **WHEN** 维护者提交超出允许范围或非正数的轮询并发上限
+- **THEN** 系统拒绝该配置并保留原有有效上限
+
+### Requirement: 正常无变化观测的低写入处理
+系统 SHALL 将“渠道调用成功且未产生业务事实变化”的轮询视为短期运行观测，而非持久化审计事实。该结果 MUST 不创建逐次 Audit Event、Audit Event Resource 或 Integration Log；系统仍 MUST 维护下一次调度所需状态，并可保留短期去重或聚合指标。
+
+#### Scenario: 网络状态轮询无变化
+- **GIVEN** 一张卡的网络状态轮询成功，且规范化后的状态与当前业务事实一致
+- **WHEN** 系统应用该轮询结果
+- **THEN** 系统不新增审计事件、审计资源或外部交互日志，并按配置继续后续轮询
+
+#### Scenario: 流量读数无有效增量
+- **GIVEN** 一张卡的流量轮询成功，且读数未形成有效流量增量或跨周期业务变化
+- **WHEN** 系统应用该轮询结果
+- **THEN** 系统不新增审计事件、审计资源或外部交互日志，并保留后续调度能力
+
+### Requirement: 业务变化与轮询异常仍可追溯
+系统 SHALL 在轮询产生网络、实名、套餐或有效流量等业务事实变化时持久化必要的业务事实与审计记录。外部调用失败、响应无效或结果未知时，系统 MUST 保留可调查的失败或恢复信息，且不得把失败静默降级为正常无变化观测。
+
+#### Scenario: 轮询产生网络状态变化
+- **GIVEN** 渠道返回的网络状态与当前业务事实不同
+- **WHEN** 系统成功应用该状态变化
+- **THEN** 系统持久化业务状态变化及相应审计事实
+
+#### Scenario: 轮询渠道调用失败
+- **WHEN** 轮询调用渠道超时、失败或返回无效响应
+- **THEN** 系统保留可调查的失败或恢复信息，并按既有策略安排后续处理

openspec/specs/qicheng-migration-package-lifecycle-overrides/spec.md

@@ -0,0 +1,36 @@
+# qicheng-migration-package-lifecycle-overrides Specification
+
+## Purpose
+
+为奇成迁移中状态字段无法唯一表达套餐先后关系的少量资产，提供逐卡、可审计且不影响其他资产的套餐生命周期裁决能力。
+
+## Requirements
+
+### Requirement: 迁移配置支持逐卡套餐生命周期覆盖
+系统 SHALL 支持在奇成迁移映射配置中，以完整 ICCID 和 `tbl_card_life` 生命周期记录 ID 指定唯一当前生效套餐，以及待生效或跳过的套餐记录。
+
+#### Scenario: 指定当前与待生效套餐
+- **WHEN** 某 ICCID 的覆盖指定一个当前生效记录和一个待生效记录
+- **THEN** step2 生成结果 SHALL 将前者迁移为生效套餐、后者迁移为待生效套餐，且不再以多个当前生效套餐阻断该资产
+
+#### Scenario: 指定跳过套餐
+- **WHEN** 某 ICCID 的覆盖将一个未来正式套餐记录指定为跳过
+- **THEN** step2 SHALL 不为该记录生成套餐使用数据，并在审核产物中记录其跳过裁决
+
+### Requirement: 覆盖必须完整且可验证
+系统 MUST 拒绝生命周期记录不存在、重复引用、状态互相冲突、未指定唯一当前生效记录，或未明确裁决其他原本可迁移正式套餐的覆盖。
+
+#### Scenario: 覆盖引用不存在的记录
+- **WHEN** 覆盖中的生命周期记录 ID 不属于对应 ICCID 的 `tbl_card_life` 记录
+- **THEN** step2 SHALL 将该 ICCID 记入错误产物且不生成该资产的套餐迁移数据
+
+#### Scenario: 覆盖遗漏另一条可迁移套餐
+- **WHEN** 覆盖指定当前生效记录但遗漏同卡另一条原本会迁移的正式套餐
+- **THEN** step2 SHALL 将该 ICCID 记入错误产物且不猜测其状态
+
+### Requirement: 未覆盖资产维持严格冲突阻断
+系统 SHALL 对未配置生命周期覆盖的资产维持现有套餐状态分类和多个当前生效正式套餐阻断行为。
+
+#### Scenario: 未覆盖资产存在多个当前生效套餐
+- **WHEN** 未配置覆盖的 ICCID 仍有多条当前生效正式套餐
+- **THEN** step2 SHALL 输出 `multiple_active_packages` 错误且不迁移该资产的套餐

openspec/specs/qicheng-migration-package-usage/spec.md

@@ -0,0 +1,25 @@
+# qicheng-migration-package-usage Specification
+
+## Purpose
+
+确保奇成迁移创建的套餐使用记录保存目标套餐在迁移时的完整计时条款快照，并能通过数据库完整性校验。
+
+## Requirements
+
+### Requirement: 迁移套餐使用记录保存计时条款快照
+系统 SHALL 在 step2 为奇成迁移套餐创建使用记录时，写入所选正式套餐的生效基准、周期类型、月数和天数快照。
+
+#### Scenario: 自然月正式套餐迁移
+- **WHEN** step2 为周期类型为 `natural_month` 的目标正式套餐生成使用记录
+- **THEN** 使用记录 SHALL 保存该套餐的生效基准、`natural_month`、正月数和零天数快照
+
+#### Scenario: 按天正式套餐迁移
+- **WHEN** step2 为周期类型为 `by_day` 的目标正式套餐生成使用记录
+- **THEN** 使用记录 SHALL 保存该套餐的生效基准、`by_day`、零月数和正天数快照
+
+### Requirement: 迁移套餐使用 SQL 满足快照完整性约束
+系统 MUST 生成满足套餐使用记录计时快照完整性约束的 SQL，且不得依赖空值或默认值填充迁移记录的快照。
+
+#### Scenario: 执行生成的套餐使用 SQL
+- **WHEN** 在启用套餐使用计时快照校验的数据库中执行 step2 套餐使用 SQL
+- **THEN** 数据库 SHALL 不因计时快照不完整或无效而拒绝迁移记录

openspec/specs/shop-bulk-import/spec.md

@@ -0,0 +1,54 @@
+# shop-bulk-import Specification
+
+## Purpose
+
+定义受控离线迁移工具从已核对的代理商 CSV 生成店铺初始事实 SQL，使维护者可以在执行前审核输入解析、目标库守卫和逐行计划，并以单事务手工执行。
+
+## Requirements
+
+### Requirement: 导入输入必须在生成 SQL 前完成全量预检
+系统 SHALL 在生成 SQL 前校验 CSV 必备列、店铺名称/初始用户名/初始手机号同批唯一性、11 位手机号格式、上下级代理引用、业务员映射、默认角色、迁移操作者和稳定生成的店铺编号。上级代理必须按 CSV 的“奇成代理名称”唯一解析。
+
+#### Scenario: 输入或映射错误被发现
+- **WHEN** 工具发现任一 CSV 行、配置项或同批关系错误
+- **THEN** 工具输出带 CSV 行号和原因的错误清单，不生成可执行导入 SQL
+
+#### Scenario: 上级代理按 CSV 标识解析
+- **WHEN** 子店铺的上级代理名称在同一 CSV 中唯一对应一个代理记录
+- **THEN** 工具将该代理记录排在子店铺之前，并在结果清单中记录上级解析结果
+
+### Requirement: 生成的 SQL 必须在写入前校验目标库状态
+系统 SHALL 在单事务 SQL 的任何店铺、账号、角色、钱包或审计写入前，校验配置指定的默认角色为启用客户角色、业务员映射为启用平台账号、迁移操作者为可用超级管理员，且目标库不存在同店铺编号、用户名或手机号的有效记录。
+
+#### Scenario: 目标库冲突被发现
+- **WHEN** 维护者执行的 SQL 发现角色、账号映射或任一目标记录冲突
+- **THEN** SQL 以包含对应 CSV 行号和原因的错误终止，且不写入本批店铺、账号、角色、钱包或成功审计事实
+
+### Requirement: 批量导入 SQL 必须创建完整的店铺初始事实
+系统 SHALL 为每个通过预检和目标库守卫的 CSV 记录创建启用的店铺、一个启用的店铺主账号、该账号和店铺的默认客户角色关联、主钱包和佣金钱包，并按配置写入平台业务员归属和成功审计。店铺默认角色必须是配置指定的启用客户角色。
+
+#### Scenario: 成功导入店铺
+- **WHEN** 维护者以单事务执行通过审核的导入 SQL
+- **THEN** 每家店铺具有稳定生成的店铺编号、正确的上级层级和业务员归属，并拥有一个主账号、默认角色关联、主钱包、佣金钱包及成功创建审计
+
+#### Scenario: SQL 中保存初始账号密码哈希
+- **WHEN** 工具根据配置的初始密码规则生成店铺主账号 SQL
+- **THEN** SQL 将该账号的 bcrypt 密码哈希写入数据库，结果清单、错误清单、摘要和控制台输出不包含初始密码明文
+
+### Requirement: 导入执行必须由维护者审核后以单事务手工确认
+系统 SHALL 只生成 SQL 和审核产物，不直接连接或写入目标 PostgreSQL。维护者 SHALL 在审核通过后以 PostgreSQL 单事务模式执行生成的 SQL；任一记录创建失败时回滚整批。
+
+#### Scenario: 仅运行生成器
+- **WHEN** 操作者运行 Python 导入生成器
+- **THEN** 工具仅生成审核产物和 SQL，不写入目标 PostgreSQL
+
+#### Scenario: SQL 执行期间发生创建失败
+- **WHEN** 维护者以单事务模式执行 SQL，且任一记录无法创建
+- **THEN** PostgreSQL 回滚整批，且本批次不保留任何店铺、账号、角色关联、钱包或成功创建审计事实
+
+### Requirement: 导入结果必须可审核和重跑定位
+系统 SHALL 为每次 SQL 生成输出不含明文密码的结果清单与摘要，至少包含源 CSV 行号、稳定店铺编号、店铺名称、层级、上级解析结果、业务员映射结果、计划状态和成功/失败统计。生成的 SQL、结果清单、错误清单和摘要 SHALL 使用同一批次标识以便审核和定位。
+
+#### Scenario: 生成完成后审核
+- **WHEN** 工具成功完成 SQL 生成
+- **THEN** 操作者可通过结果清单核对每条源记录及其生成的店铺编号、层级和业务员归属，并通过摘要确认总数和待执行 SQL 文件