update

openspec/changes/add-audit-integration-write-switches/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-09-02

openspec/changes/add-audit-integration-write-switches/proposal.md

@@ -0,0 +1,30 @@
+## Why
+
+生产环境在异常重启恢复后，Worker 对审计与外部交互记录执行的大量读写和留存扫描使 PostgreSQL 出现严重磁盘 I/O 等待。维护者需要能在不修改代码的情况下临时停止新增统一审计记录和外部交互记录，并停止其归档、留存任务，以保护核心业务数据库可用性。
+
+## What Changes
+
+- 新增默认启用的运行时配置开关，分别控制统一审计事件及资源快照、外部交互日志的新增持久化；关闭后不再向 `tb_audit_event`、`tb_audit_event_resource`、`tb_integration_log` 写入新记录。
+- 关闭记录开关时，业务操作、外部调用、回调处理和既有领域状态处理继续执行；审计调查和外部交互日志查询仅返回已有历史记录。
+- **BREAKING** 关闭开关期间不产生审计事实、资源快照或外部交互记录，也不建立新的审计与外部交互关联；依赖 Integration Log 作为内部重试或幂等辅助信息的调用必须在不落库时保持既有业务正确性。
+- 新增默认启用的 Worker 开关，关闭后不注册、不调度且不消费 Audit 日归档、Integration Log 日归档和日志日留存任务；已入队的对应任务必须安全跳过，不扫描或修改三张表。
+- 保持现有归档和留存开关的语义不变；新的任务总开关独立于“是否物理清理”的开关。
+
+## Capabilities
+
+### New Capabilities
+
+- `observability-write-controls`: 审计、外部交互记录和其后台归档/留存任务的运行时启停控制。
+
+### Modified Capabilities
+
+- `operations-audit`: 允许维护者在运行时关闭新增审计事实及审计相关后台任务，并定义关闭期间的查询与任务行为。
+- `external-integration`: 允许维护者在运行时关闭新增外部交互日志及其归档/留存任务，并定义外部调用与回调的降级边界。
+
+## Impact
+
+- 配置：`pkg/config` 默认配置、环境变量映射和生产运行说明。
+- 运行装配：`cmd/api`、`cmd/worker`、`internal/bootstrap`、任务注册与处理。
+- 基础设施：统一审计 Writer、Integration Log Repository 及其调用方的无记录降级路径。
+- 任务：Audit 日归档、Integration 日归档、日志日留存任务及其 Asynq 队列处理。
+- 文档：OpenSpec 契约、生产运维说明与配置说明。

openspec/changes/add-audit-integration-write-switches/specs/observability-write-controls/spec.md

@@ -0,0 +1,21 @@
+## ADDED Requirements
+
+### Requirement: 审计与外部交互记录运行时写入开关
+系统 SHALL 提供默认启用、可由配置文件及环境变量覆盖的独立运行时开关，分别控制统一审计事件/资源快照和外部交互日志的新建持久化。关闭审计开关时，不得向 `tb_audit_event` 或 `tb_audit_event_resource` 写入新记录；关闭外部交互开关时，不得向 `tb_integration_log` 写入新记录。已有历史记录仍可按既有权限查询。
+
+关闭任一开关不得阻断业务状态变更、外部调用、回调处理、钱包/订单等领域事实或已有幂等语义；不得将 Integration Log 是否落库作为业务正确性前提。开关重新启用后只记录后续操作，不回填关闭期间事实。
+
+#### Scenario: 关闭审计写入
+- **WHEN** 审计写入开关关闭且业务操作成功执行
+- **THEN** 业务操作正常完成，系统不创建审计事件或资源快照
+
+#### Scenario: 关闭外部交互日志写入
+- **WHEN** 外部调用或回调在外部交互日志开关关闭期间执行
+- **THEN** 系统维持既有调用、回调和幂等业务结果，且不创建新的外部交互日志
+
+### Requirement: 审计与外部交互后台任务总开关
+系统 SHALL 提供默认启用的 Worker 总开关，分别控制审计日归档、外部交互日志日归档和日志日留存任务。关闭时 Worker 不注册、不调度且不消费对应任务；已经入队的任务被消费时必须安全跳过，不扫描、归档、删除或修改三张目标表。该总开关独立于既有物理清理配置。
+
+#### Scenario: 已入队任务在关闭后执行
+- **WHEN** 相关归档或留存任务已入队且对应 Worker 开关后来关闭
+- **THEN** 任务安全跳过，目标表不发生扫描或写入