From 62a95ca171a46637e6018e0afe0767f2014d4e29 Mon Sep 17 00:00:00 2001 From: Lxy Date: Sat, 4 Jul 2026 15:27:26 +0800 Subject: [PATCH] =?UTF-8?q?chore:=20=E5=BD=92=E6=A1=A3=20storage-cache-ref?= =?UTF-8?q?actor=20change?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../2026-07-04-storage-cache-refactor.md | 1 + ...026-07-04-storage-cache-refactor-design.md | 2 + .../.comet.yaml | 2 +- .../.comet/handoff/brainstorm-summary.md | 0 .../.comet/handoff/design-context.json | 0 .../.comet/handoff/design-context.md | 0 .../.comet/subagent-progress.md | 0 .../.openspec.yaml | 0 .../design.md | 0 .../proposal.md | 0 .../specs/dual-write-consistency/spec.md | 0 .../specs/mysql-persistence/spec.md | 0 .../specs/redis-cache-layer/spec.md | 0 .../specs/storage-fallback/spec.md | 0 .../tasks.md | 0 openspec/specs/dual-write-consistency/spec.md | 30 ++++++++++++++ openspec/specs/mysql-persistence/spec.md | 41 +++++++++++++++++++ openspec/specs/redis-cache-layer/spec.md | 41 +++++++++++++++++++ openspec/specs/storage-fallback/spec.md | 38 +++++++++++++++++ 19 files changed, 154 insertions(+), 1 deletion(-) rename openspec/changes/{storage-cache-refactor => archive/2026-07-04-storage-cache-refactor}/.comet.yaml (98%) rename openspec/changes/{storage-cache-refactor => archive/2026-07-04-storage-cache-refactor}/.comet/handoff/brainstorm-summary.md (100%) rename openspec/changes/{storage-cache-refactor => archive/2026-07-04-storage-cache-refactor}/.comet/handoff/design-context.json (100%) rename openspec/changes/{storage-cache-refactor => archive/2026-07-04-storage-cache-refactor}/.comet/handoff/design-context.md (100%) rename openspec/changes/{storage-cache-refactor => archive/2026-07-04-storage-cache-refactor}/.comet/subagent-progress.md (100%) rename openspec/changes/{storage-cache-refactor => archive/2026-07-04-storage-cache-refactor}/.openspec.yaml (100%) rename openspec/changes/{storage-cache-refactor => archive/2026-07-04-storage-cache-refactor}/design.md (100%) rename openspec/changes/{storage-cache-refactor => archive/2026-07-04-storage-cache-refactor}/proposal.md (100%) rename openspec/changes/{storage-cache-refactor => archive/2026-07-04-storage-cache-refactor}/specs/dual-write-consistency/spec.md (100%) rename openspec/changes/{storage-cache-refactor => archive/2026-07-04-storage-cache-refactor}/specs/mysql-persistence/spec.md (100%) rename openspec/changes/{storage-cache-refactor => archive/2026-07-04-storage-cache-refactor}/specs/redis-cache-layer/spec.md (100%) rename openspec/changes/{storage-cache-refactor => archive/2026-07-04-storage-cache-refactor}/specs/storage-fallback/spec.md (100%) rename openspec/changes/{storage-cache-refactor => archive/2026-07-04-storage-cache-refactor}/tasks.md (100%) create mode 100644 openspec/specs/dual-write-consistency/spec.md create mode 100644 openspec/specs/mysql-persistence/spec.md create mode 100644 openspec/specs/redis-cache-layer/spec.md create mode 100644 openspec/specs/storage-fallback/spec.md diff --git a/docs/superpowers/plans/2026-07-04-storage-cache-refactor.md b/docs/superpowers/plans/2026-07-04-storage-cache-refactor.md index 106d1f8..f0c245b 100644 --- a/docs/superpowers/plans/2026-07-04-storage-cache-refactor.md +++ b/docs/superpowers/plans/2026-07-04-storage-cache-refactor.md @@ -2,6 +2,7 @@ change: storage-cache-refactor design-doc: docs/superpowers/specs/2026-07-04-storage-cache-refactor-design.md base-ref: 8b5e43f4915cef786208a8132460f87b8b191765 +archived-with: 2026-07-04-storage-cache-refactor --- # Storage Cache Refactor - 实施计划 diff --git a/docs/superpowers/specs/2026-07-04-storage-cache-refactor-design.md b/docs/superpowers/specs/2026-07-04-storage-cache-refactor-design.md index b143c21..2fa0c76 100644 --- a/docs/superpowers/specs/2026-07-04-storage-cache-refactor-design.md +++ b/docs/superpowers/specs/2026-07-04-storage-cache-refactor-design.md @@ -2,6 +2,8 @@ comet_change: storage-cache-refactor role: technical-design canonical_spec: openspec +archived-with: 2026-07-04-storage-cache-refactor +status: final --- # Storage Cache Refactor - Technical Design diff --git a/openspec/changes/storage-cache-refactor/.comet.yaml b/openspec/changes/archive/2026-07-04-storage-cache-refactor/.comet.yaml similarity index 98% rename from openspec/changes/storage-cache-refactor/.comet.yaml rename to openspec/changes/archive/2026-07-04-storage-cache-refactor/.comet.yaml index bf46290..a3fd7b9 100644 --- a/openspec/changes/storage-cache-refactor/.comet.yaml +++ b/openspec/changes/archive/2026-07-04-storage-cache-refactor/.comet.yaml @@ -17,7 +17,7 @@ verification_report: docs/superpowers/reports/2026-07-04-storage-cache-refactor- branch_status: handled created_at: 2026-07-04 verified_at: 2026-07-04T15:00:00 -archived: false +archived: true handoff_context: openspec/changes/storage-cache-refactor/.comet/handoff/design-context.json handoff_hash: 1064fdf5186e511848878541bdad663ac6b521ee5721807d01eaf3481bb0cd5a build_command: python -m pytest tests/ -v diff --git a/openspec/changes/storage-cache-refactor/.comet/handoff/brainstorm-summary.md b/openspec/changes/archive/2026-07-04-storage-cache-refactor/.comet/handoff/brainstorm-summary.md similarity index 100% rename from openspec/changes/storage-cache-refactor/.comet/handoff/brainstorm-summary.md rename to openspec/changes/archive/2026-07-04-storage-cache-refactor/.comet/handoff/brainstorm-summary.md diff --git a/openspec/changes/storage-cache-refactor/.comet/handoff/design-context.json b/openspec/changes/archive/2026-07-04-storage-cache-refactor/.comet/handoff/design-context.json similarity index 100% rename from openspec/changes/storage-cache-refactor/.comet/handoff/design-context.json rename to openspec/changes/archive/2026-07-04-storage-cache-refactor/.comet/handoff/design-context.json diff --git a/openspec/changes/storage-cache-refactor/.comet/handoff/design-context.md b/openspec/changes/archive/2026-07-04-storage-cache-refactor/.comet/handoff/design-context.md similarity index 100% rename from openspec/changes/storage-cache-refactor/.comet/handoff/design-context.md rename to openspec/changes/archive/2026-07-04-storage-cache-refactor/.comet/handoff/design-context.md diff --git a/openspec/changes/storage-cache-refactor/.comet/subagent-progress.md b/openspec/changes/archive/2026-07-04-storage-cache-refactor/.comet/subagent-progress.md similarity index 100% rename from openspec/changes/storage-cache-refactor/.comet/subagent-progress.md rename to openspec/changes/archive/2026-07-04-storage-cache-refactor/.comet/subagent-progress.md diff --git a/openspec/changes/storage-cache-refactor/.openspec.yaml b/openspec/changes/archive/2026-07-04-storage-cache-refactor/.openspec.yaml similarity index 100% rename from openspec/changes/storage-cache-refactor/.openspec.yaml rename to openspec/changes/archive/2026-07-04-storage-cache-refactor/.openspec.yaml diff --git a/openspec/changes/storage-cache-refactor/design.md b/openspec/changes/archive/2026-07-04-storage-cache-refactor/design.md similarity index 100% rename from openspec/changes/storage-cache-refactor/design.md rename to openspec/changes/archive/2026-07-04-storage-cache-refactor/design.md diff --git a/openspec/changes/storage-cache-refactor/proposal.md b/openspec/changes/archive/2026-07-04-storage-cache-refactor/proposal.md similarity index 100% rename from openspec/changes/storage-cache-refactor/proposal.md rename to openspec/changes/archive/2026-07-04-storage-cache-refactor/proposal.md diff --git a/openspec/changes/storage-cache-refactor/specs/dual-write-consistency/spec.md b/openspec/changes/archive/2026-07-04-storage-cache-refactor/specs/dual-write-consistency/spec.md similarity index 100% rename from openspec/changes/storage-cache-refactor/specs/dual-write-consistency/spec.md rename to openspec/changes/archive/2026-07-04-storage-cache-refactor/specs/dual-write-consistency/spec.md diff --git a/openspec/changes/storage-cache-refactor/specs/mysql-persistence/spec.md b/openspec/changes/archive/2026-07-04-storage-cache-refactor/specs/mysql-persistence/spec.md similarity index 100% rename from openspec/changes/storage-cache-refactor/specs/mysql-persistence/spec.md rename to openspec/changes/archive/2026-07-04-storage-cache-refactor/specs/mysql-persistence/spec.md diff --git a/openspec/changes/storage-cache-refactor/specs/redis-cache-layer/spec.md b/openspec/changes/archive/2026-07-04-storage-cache-refactor/specs/redis-cache-layer/spec.md similarity index 100% rename from openspec/changes/storage-cache-refactor/specs/redis-cache-layer/spec.md rename to openspec/changes/archive/2026-07-04-storage-cache-refactor/specs/redis-cache-layer/spec.md diff --git a/openspec/changes/storage-cache-refactor/specs/storage-fallback/spec.md b/openspec/changes/archive/2026-07-04-storage-cache-refactor/specs/storage-fallback/spec.md similarity index 100% rename from openspec/changes/storage-cache-refactor/specs/storage-fallback/spec.md rename to openspec/changes/archive/2026-07-04-storage-cache-refactor/specs/storage-fallback/spec.md diff --git a/openspec/changes/storage-cache-refactor/tasks.md b/openspec/changes/archive/2026-07-04-storage-cache-refactor/tasks.md similarity index 100% rename from openspec/changes/storage-cache-refactor/tasks.md rename to openspec/changes/archive/2026-07-04-storage-cache-refactor/tasks.md diff --git a/openspec/specs/dual-write-consistency/spec.md b/openspec/specs/dual-write-consistency/spec.md new file mode 100644 index 0000000..da38826 --- /dev/null +++ b/openspec/specs/dual-write-consistency/spec.md @@ -0,0 +1,30 @@ +## ADDED Requirements + +### Requirement: 刷新接口双写 +系统应当在刷新接口中实现 Redis 和 MySQL 的同步双写，保证数据一致性。 + +#### Scenario: 刷新接口双写成功 +- **WHEN** 用户调用刷新接口更新行情数据 +- **THEN** 系统先删除 Redis 缓存，再写入 MySQL，最后更新 Redis 缓存 + +#### Scenario: MySQL 写入失败 +- **WHEN** 刷新接口写入 MySQL 失败 +- **THEN** 系统返回错误响应，不更新 Redis 缓存，保证数据一致性 + +#### Scenario: Redis 写入失败 +- **WHEN** 刷新接口写入 MySQL 成功但 Redis 写入失败 +- **THEN** 系统返回成功响应（MySQL 数据已持久化），输出 Redis 写入失败警告日志 + +### Requirement: 双写顺序保证 +系统应当保证双写的顺序：先写 MySQL，再更新 Redis。 + +#### Scenario: 双写顺序 +- **WHEN** 刷新接口执行双写 +- **THEN** 系统先写入 MySQL 并确认成功，再更新 Redis 缓存 + +### Requirement: 缓存回填一致性 +系统应当在缓存未命中回填时保证回填数据与 MySQL 数据一致。 + +#### Scenario: 缓存未命中回填 +- **WHEN** Redis 缓存未命中且从 MySQL 读取数据 +- **THEN** 系统将 MySQL 数据回填到 Redis，TTL 设置为 30 天 diff --git a/openspec/specs/mysql-persistence/spec.md b/openspec/specs/mysql-persistence/spec.md new file mode 100644 index 0000000..e7e3f08 --- /dev/null +++ b/openspec/specs/mysql-persistence/spec.md @@ -0,0 +1,41 @@ +## ADDED Requirements + +### Requirement: MySQL 连接管理 +系统应当提供 MySQL 连接管理能力，包括连接初始化、连接池管理和表结构初始化。 + +#### Scenario: MySQL 连接初始化成功 +- **WHEN** 应用启动且 MySQL 配置有效 +- **THEN** 系统成功建立 MySQL 连接并创建必要的表结构 + +#### Scenario: MySQL 连接初始化失败 +- **WHEN** 应用启动但 MySQL 服务不可用 +- **THEN** 系统输出错误日志并标记 MySQL 为不可用状态，但不阻止应用启动 + +### Requirement: 行情数据持久化存储 +系统应当使用 MySQL 作为行情数据的主要持久化存储，替代 SQLite。 + +#### Scenario: 行情数据写入 MySQL +- **WHEN** 刷新接口接收到行情数据更新请求 +- **THEN** 系统将数据写入 MySQL 的 `market_data` 表 + +#### Scenario: 行情数据从 MySQL 读取 +- **WHEN** Redis 缓存未命中且 MySQL 可用 +- **THEN** 系统从 MySQL 读取行情数据并返回 + +### Requirement: MySQL 表结构迁移 +系统应当提供从 SQLite 到 MySQL 的数据迁移能力，保证历史数据不丢失。 + +#### Scenario: 首次启动数据迁移 +- **WHEN** 应用首次启动且 MySQL 可用但表为空 +- **THEN** 系统从 SQLite 读取历史数据并迁移到 MySQL + +#### Scenario: 迁移完成 +- **WHEN** 数据迁移完成 +- **THEN** 系统输出迁移成功日志，后续读写直接操作 MySQL + +### Requirement: MySQL 事务支持 +系统应当使用 MySQL 事务保证数据写入的原子性和一致性。 + +#### Scenario: 批量写入事务 +- **WHEN** 刷新接口需要写入多个品种的行情数据 +- **THEN** 系统使用事务保证所有数据要么全部写入成功，要么全部回滚 diff --git a/openspec/specs/redis-cache-layer/spec.md b/openspec/specs/redis-cache-layer/spec.md new file mode 100644 index 0000000..4410e71 --- /dev/null +++ b/openspec/specs/redis-cache-layer/spec.md @@ -0,0 +1,41 @@ +## ADDED Requirements + +### Requirement: Redis 缓存连接管理 +系统应当提供 Redis 连接管理能力，包括连接初始化、健康检查和连接池管理。 + +#### Scenario: Redis 连接初始化成功 +- **WHEN** 应用启动且 Redis 配置有效 +- **THEN** 系统成功建立 Redis 连接并输出初始化成功日志 + +#### Scenario: Redis 连接初始化失败 +- **WHEN** 应用启动但 Redis 服务不可用 +- **THEN** 系统输出警告日志并标记 Redis 为不可用状态，但不阻止应用启动 + +### Requirement: 行情数据缓存读取 +系统应当优先从 Redis 读取行情数据，缓存未命中时回源 MySQL。 + +#### Scenario: Redis 缓存命中 +- **WHEN** 用户请求行情数据且 Redis 中存在该数据 +- **THEN** 系统直接从 Redis 返回数据，不访问 MySQL + +#### Scenario: Redis 缓存未命中 +- **WHEN** 用户请求行情数据但 Redis 中不存在该数据 +- **THEN** 系统从 MySQL 读取数据，回填到 Redis（TTL 30 天），并返回数据 + +### Requirement: Redis 缓存 TTL 管理 +系统应当为缓存数据设置 30 天过期时间，过期后自动清理。 + +#### Scenario: 缓存数据过期 +- **WHEN** 缓存数据超过 30 天未访问 +- **THEN** Redis 自动清理该数据，下次访问时从 MySQL 重新加载 + +#### Scenario: 缓存数据续期 +- **WHEN** 用户访问已缓存的行情数据 +- **THEN** 系统返回缓存数据，TTL 保持为 30 天（不续期） + +### Requirement: Redis 缓存失效 +系统应当在数据更新时主动失效相关缓存，保证数据一致性。 + +#### Scenario: 刷新接口触发缓存失效 +- **WHEN** 用户调用刷新接口更新行情数据 +- **THEN** 系统先删除 Redis 中对应的缓存数据，再执行双写流程 diff --git a/openspec/specs/storage-fallback/spec.md b/openspec/specs/storage-fallback/spec.md new file mode 100644 index 0000000..60f05ca --- /dev/null +++ b/openspec/specs/storage-fallback/spec.md @@ -0,0 +1,38 @@ +## ADDED Requirements + +### Requirement: 三级降级策略 +系统应当实现 Redis → MySQL → SQLite 的三级降级读取策略，保证系统可用性。 + +#### Scenario: 正常模式（Redis + MySQL 可用） +- **WHEN** Redis 和 MySQL 均可用 +- **THEN** 系统优先从 Redis 读取，未命中时回源 MySQL + +#### Scenario: Redis 不可用降级 +- **WHEN** Redis 服务不可用但 MySQL 可用 +- **THEN** 系统直接从 MySQL 读取数据，跳过 Redis 缓存层 + +#### Scenario: Redis 和 MySQL 均不可用降级 +- **WHEN** Redis 和 MySQL 均不可用 +- **THEN** 系统降级到 SQLite，从 SQLite 读取数据并保证基础服务可用 + +### Requirement: 降级状态检测 +系统应当能够检测存储后端的可用性状态，并在降级时输出明确的日志。 + +#### Scenario: 启动时降级检测 +- **WHEN** 应用启动时检测到 Redis 或 MySQL 不可用 +- **THEN** 系统输出降级警告日志，说明当前使用的存储模式 + +#### Scenario: 运行时降级触发 +- **WHEN** 运行中 Redis 或 MySQL 连接异常 +- **THEN** 系统自动切换到降级模式，输出降级日志，并继续提供服务 + +### Requirement: 降级恢复 +系统应当能够在存储后端恢复后自动恢复到正常模式。 + +#### Scenario: Redis 恢复 +- **WHEN** Redis 从不可用状态恢复 +- **THEN** 系统自动恢复到 Redis + MySQL 模式，后续读取优先使用 Redis + +#### Scenario: MySQL 恢复 +- **WHEN** MySQL 从不可用状态恢复 +- **THEN** 系统自动恢复到 Redis + MySQL 模式，SQLite 降级结束