OpenFlare/docs/superpowers/plans/2026-08-28-cordis-architecture-refactor.md

Cordis 架构重构实施计划 (Cordis Architecture Refactor Implementation Plan)

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: 依据 Cordis 时空可组合性元框架，彻底消除 Wavelet 后端的包级静态单例、init() 隐式副作用建连以及跨插件私有实现依赖，实现微内核纯洁化与契约驱动解耦。

Architecture:

1. 移除 backend/core/context.go 中的特权服务快捷方法（DB() / Cache()）。
2. 将 infra/database 与 infra/cache 的连接初始化移至 Plugin.Apply(ctx)，并在 ctx.OnDispose 中注册 LIFO 逆操作（Close）。
3. 重构全部 8 个 Domain 业务插件（auth、user、admin、cap、message_gateway、risk_control、system、upload），彻底斩断对 infra/database、infra/cache 及其他插件内部包的直接 import，统一面向 contracts.DBService / contracts.CacheService。
4. 清除 admin 等插件的包级全局变量。

Tech Stack: Go 1.24+, GORM, Redis (go-redis/v9), Cordis micro-kernel, Goose migration.

Global Constraints

• 严禁任何业务插件跨包 import Wavelet/plugins/infra/database 或 Wavelet/plugins/infra/cache。
• 严禁跨插件 import 私有实现包（如 admin import risk_control/logstore）。
• 保持 backend/pkg/util/ 绝对纯净，禁止导入 Web/数据库框架。
• 重构后必须确保 go test ./...、make code-check 与 make format 全部 0 错误通过。

---

Task 1: 微内核纯洁化 (backend/core/)

Files:

• Modify: backend/core/context.go:240-260
• Test: backend/core/context_test.go

Interfaces:

• Consumes: core.Context, core.Inject

• Produces: 纯净无特权方法的 core.Context

• Step 1: 编写/更新 Context 纯洁性测试

• Step 2: 移除 Context.DB() 与 Context.Cache() 方法

• Step 3: 运行 go test ./backend/core/... 验证通过

---

Task 2: 基础设施插件生命周期可逆化 (backend/plugins/infra/)

Files:

• Modify: backend/plugins/infra/database/postgres.go
• Modify: backend/plugins/infra/database/plugin.go
• Modify: backend/plugins/infra/cache/redis.go
• Modify: backend/plugins/infra/cache/plugin.go
• Test: backend/plugins/infra/infra_test.go

Interfaces:

• Consumes: core.Plugin, contracts.DBService, contracts.CacheService

• Produces: contracts.DBService 与 contracts.CacheService（带 ctx.OnDispose 逆操作）

• Step 1: 移除 infra/database 中的 func init() 及全局 var db，在 Plugin.Apply 中建连并注册 ctx.OnDispose(sqlDB.Close)

• Step 2: 移除 infra/cache 中的 func init() 及全局 var Redis，在 Plugin.Apply 中建连并注册 ctx.OnDispose(client.Close)

• Step 3: 运行 go test ./backend/plugins/infra/... 验证通过

---

Task 3: 核心 Domain 插件防线重塑（Auth & User 插件）

Files:

• Modify: backend/plugins/domain/auth/*
• Modify: backend/plugins/domain/user/*
• Test: backend/plugins/domain/auth/plugin_test.go
• Test: backend/plugins/domain/user/plugin_test.go

Interfaces:

• Consumes: contracts.DBService, contracts.CacheService

• Produces: contracts.AuthService, contracts.UserService

• Step 1: 移除 auth 插件中对 Wavelet/plugins/infra/database 和 cache 的 import，改用插件持有的 contracts.DBService 与 contracts.CacheService

• Step 2: 移除 user 插件中对 Wavelet/plugins/infra/database 和 cache 的 import，改用 contracts.DBService 与 contracts.CacheService

• Step 3: 运行 go test ./backend/plugins/domain/auth/... ./backend/plugins/domain/user/... 验证通过

---

Task 4: 业务 Domain 插件防线重塑（Cap, MessageGateway, RiskControl, System, Upload）

Files:

• Modify: backend/plugins/domain/cap/*
• Modify: backend/plugins/domain/message_gateway/*
• Modify: backend/plugins/domain/risk_control/*
• Modify: backend/plugins/domain/system/*
• Modify: backend/plugins/domain/upload/*
• Test: backend/plugins/domain/domain_test.go

Interfaces:

• Consumes: contracts.DBService, contracts.CacheService

• Step 1: 改造 cap、message_gateway、risk_control、system、upload 插件，移除所有 infra/database 和 infra/cache 的直接 import

• Step 2: 统一各插件内部 Repository / Service 的 DB / Cache 获取途径

• Step 3: 运行各插件单测验证通过

---

Task 5: Admin 插件解耦与包级全局状态清除

Files:

• Modify: backend/plugins/domain/admin/*
• Test: backend/plugins/domain/admin/plugin_test.go

Interfaces:

• Consumes: contracts.DBService, contracts.CacheService, contracts.UserService, contracts.AuthService, ctx.Tasks()

• Step 1: 移除 admin 插件中对 risk_control/logstore、driver_asynq_worker、infra/storage/diskcache 等私有包的直接 import

• Step 2: 清除 admin/plugin.go 中的 globalUserSvc、globalAuthSvc、globalCoreCtx 等包级变量

• Step 3: 运行 go test ./backend/plugins/domain/admin/... 验证通过

---

Task 6: 组装层对齐与全量质量门禁验证

Files:

• Modify: backend/cmd/app.go

• Modify: backend/cmd/*

• Step 1: 检查并适配 cmd/app.go 及启动指令，确保 Goose 迁移与驱动正确接入新版 DBService

• Step 2: 运行全局跨包 import 检查：grep -r "Wavelet/plugins/infra/database" backend/plugins/domain/ 必须为空

• Step 3: 运行全量单元测试与基准测试：go test ./...

• Step 4: 运行质量门禁：make code-check && make format