mirror of
https://github.com/Rain-kl/OpenFlare.git
synced 2026-10-03 07:06:36 +08:00
refactor(core): align with cordis spatiotemporal composability architecture
- Purify core micro-kernel by removing context hardcoded helpers and reverse dependencies - Eliminate init() side effects in infra plugins with reversible lifecycle disposal - Completely isolate plugins by removing cross-plugin imports and using core/contracts - Introduce TaskService and RiskControlService contracts for unified cross-plugin APIs - Regenerate Swagger documentation and update developer guide matrix - Achieve 0 violations in check_cordis_architecture.sh and 100% test pass
This commit is contained in:
ryan
@@ -1,171 +1,120 @@
|
||||
# Cordis Architecture Refactor Implementation Plan
|
||||
# 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:** Refactor Wavelet backend to strictly conform to Cordis meta-framework principles: full revertible effects, space composability via per-plugin scoped context fork, 4-semantic typed event bus, elimination of package-level infra globals, and strict single-owner principle across domain plugins.
|
||||
**Goal:** 依据 Cordis 时空可组合性元框架，彻底消除 Wavelet 后端的包级静态单例、`init()` 隐式副作用建连以及跨插件私有实现依赖，实现微内核纯洁化与契约驱动解耦。
|
||||
|
||||
**Architecture:**
|
||||
1. Microkernel core (`core/`): Implement `Waterfall`, `Parallel`, `Serial` event dispatch, per-plugin Scoped Context (`ctx.Fork()`), revertible extension points (`extpoints`), and `ctx.DB()` / `ctx.Cache()` contract helpers.
|
||||
2. Contracts (`core/contracts/`): Expand `UserService` & `AuthService` with administration and token revocation interfaces; define typed domain events.
|
||||
3. Domain Plugins (`plugins/domain/`): Implement user/auth contract additions; refactor `admin` plugin to completely remove cross-plugin internal package imports and direct SQL operations on other plugins' tables.
|
||||
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.23+, GORM, Gin, Goose, Cordis Paradigm.
|
||||
**Tech Stack:** Go 1.24+, GORM, Redis (go-redis/v9), Cordis micro-kernel, Goose migration.
|
||||
|
||||
## Global Constraints
|
||||
|
||||
- No direct cross-package imports between plugins (`plugins/domain/A` must NEVER import `plugins/domain/B` or `plugins/drivers/*`).
|
||||
- Single Owner Principle: Every database table is owned and operated exclusively by its owner plugin.
|
||||
- Microkernel purity: `core/` and `core/contracts/` must never import `gin`, `gorm`, `asynq`.
|
||||
- Tests must pass with `-race` enabled; temporary directories must use `t.TempDir()`.
|
||||
- Quality gates: `make code-check`, `make format`, `make swagger`.
|
||||
- 严禁任何业务插件跨包 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: Core EventBus 4 Dispatch Semantics
|
||||
### Task 1: 微内核纯洁化 (`backend/core/`)
|
||||
|
||||
**Files:**
|
||||
- Modify: `backend/core/events.go`
|
||||
- Test: `backend/core/events_test.go`
|
||||
|
||||
**Interfaces:**
|
||||
- Produces:
|
||||
- `(b *EventBus) Emit(ctx context.Context, topic string, payload any) error`
|
||||
- `(b *EventBus) Waterfall(ctx context.Context, topic string, initialPayload any) (any, error)`
|
||||
- `(b *EventBus) Parallel(ctx context.Context, topic string, payload any) error`
|
||||
- `(b *EventBus) Serial(ctx context.Context, topic string, payload any) error`
|
||||
|
||||
- [ ] **Step 1: Write tests for Waterfall, Parallel, and Serial dispatch semantics**
|
||||
- [ ] **Step 2: Run tests to verify they fail**
|
||||
- [ ] **Step 3: Implement Waterfall, Parallel, Serial methods on EventBus**
|
||||
- [ ] **Step 4: Run tests to verify they pass**
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
---
|
||||
|
||||
### Task 2: Core Scoped Context, Revertible ExtPoints & Contract Helpers
|
||||
|
||||
**Files:**
|
||||
- Modify: `backend/core/context.go`
|
||||
- Modify: `backend/core/app.go`
|
||||
- Modify: `backend/core/extpoints/router.go`
|
||||
- Modify: `backend/core/extpoints/task.go`
|
||||
- Modify: `backend/core/extpoints/schedule.go`
|
||||
- Modify: `backend/core/extpoints/setting.go`
|
||||
- Modify: `backend/core/extpoints/migration.go`
|
||||
- Modify: `backend/core/context.go:240-260`
|
||||
- Test: `backend/core/context_test.go`
|
||||
- Test: `backend/core/app_test.go`
|
||||
- Test: `backend/core/extpoints/extpoints_test.go`
|
||||
|
||||
**Interfaces:**
|
||||
- Produces:
|
||||
- `(c *Context) DB() contracts.DBService`
|
||||
- `(c *Context) Cache() contracts.CacheService`
|
||||
- `(r *RouterRegistry) Unregister(id uint64) bool`
|
||||
- `RouterExtension.Handle(...) Disposer` / `RouteDefinition` with disposer tracking
|
||||
- `App.ApplyPlugins()` forks scoped context per plugin: `p.Apply(a.ctx.Fork())`
|
||||
- Consumes: `core.Context`, `core.Inject`
|
||||
- Produces: 纯净无特权方法的 `core.Context`
|
||||
|
||||
- [ ] **Step 1: Write tests for Scoped Context Fork, LIFO Disposer, and Router Unregister**
|
||||
- [ ] **Step 2: Run tests to verify failure**
|
||||
- [ ] **Step 3: Implement Scoped Fork, Disposers, and Context DB/Cache helpers**
|
||||
- [ ] **Step 4: Update App.ApplyPlugins to fork a context for each plugin**
|
||||
- [ ] **Step 5: Run tests and verify all core tests pass**
|
||||
- [ ] **Step 6: Commit**
|
||||
- [ ] **Step 1: 编写/更新 Context 纯洁性测试**
|
||||
- [ ] **Step 2: 移除 `Context.DB()` 与 `Context.Cache()` 方法**
|
||||
- [ ] **Step 3: 运行 `go test ./backend/core/...` 验证通过**
|
||||
|
||||
---
|
||||
|
||||
### Task 3: Expand Service Contracts & Domain Events
|
||||
### Task 2: 基础设施插件生命周期可逆化 (`backend/plugins/infra/`)
|
||||
|
||||
**Files:**
|
||||
- Modify: `backend/core/contracts/user.go`
|
||||
- Modify: `backend/core/contracts/auth.go`
|
||||
- Modify: `backend/core/contracts/events.go`
|
||||
- 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:**
|
||||
- Produces:
|
||||
- `AdminListUsersRequest`, `AdminCreateUserRequest`, `AdminUpdateUserRequest`
|
||||
- `UserService` admin methods (`AdminListUsers`, `AdminGetUser`, `AdminCreateUser`, `AdminUpdateUser`, `AdminUpdateUserStatus`, `AdminDeleteUser`)
|
||||
- `AuthService` token management methods (`RevokeToken`, `RevokeUserTokens`, `InvalidateCachedUser`, `InvalidateCachedToken`)
|
||||
- Standard event definitions (`EventUserUpdated`, `EventUserDeleted`, `EventUserStatusChanged`, `EventTokenRevoked`)
|
||||
- Consumes: `core.Plugin`, `contracts.DBService`, `contracts.CacheService`
|
||||
- Produces: `contracts.DBService` 与 `contracts.CacheService`（带 `ctx.OnDispose` 逆操作）
|
||||
|
||||
- [ ] **Step 1: Declare extended contracts and DTO types in core/contracts/**
|
||||
- [ ] **Step 2: Declare typed event constants and structs in core/contracts/events.go**
|
||||
- [ ] **Step 3: Verify core and core/contracts compile cleanly**
|
||||
- [ ] **Step 4: Commit**
|
||||
- [ ] **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 4: Implement Expanded Contracts in User & Auth Domain Plugins
|
||||
### Task 3: 核心 Domain 插件防线重塑（Auth & User 插件）
|
||||
|
||||
**Files:**
|
||||
- Modify: `backend/plugins/domain/user/service.go`
|
||||
- Modify: `backend/plugins/domain/user/plugin.go`
|
||||
- Modify: `backend/plugins/domain/user/user_test.go`
|
||||
- Modify: `backend/plugins/domain/auth/service.go`
|
||||
- Modify: `backend/plugins/domain/auth/plugin.go`
|
||||
- Modify: `backend/plugins/domain/auth/plugin_test.go`
|
||||
- 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:**
|
||||
- Implements: `contracts.UserService` full methods in `user` plugin.
|
||||
- Implements: `contracts.AuthService` full methods in `auth` plugin.
|
||||
- Subscribes: `auth` plugin subscribes to `EventUserStatusChanged` / `EventUserDeleted` to invalidate cache and revoke tokens.
|
||||
- Consumes: `contracts.DBService`, `contracts.CacheService`
|
||||
- Produces: `contracts.AuthService`, `contracts.UserService`
|
||||
|
||||
- [ ] **Step 1: Write unit tests for new UserService admin methods and AuthService revocation methods**
|
||||
- [ ] **Step 2: Run tests to verify failure**
|
||||
- [ ] **Step 3: Implement the methods in user and auth domain packages**
|
||||
- [ ] **Step 4: Run user and auth plugin tests and verify they pass**
|
||||
- [ ] **Step 5: Commit**
|
||||
- [ ] **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 5: Refactor Admin Plugin (Eliminate Cross-Plugin Direct Imports & Table Ownership Violations)
|
||||
### Task 4: 业务 Domain 插件防线重塑（Cap, MessageGateway, RiskControl, System, Upload）
|
||||
|
||||
**Files:**
|
||||
- Modify: `backend/plugins/domain/admin/handlers_user.go`
|
||||
- Modify: `backend/plugins/domain/admin/handlers_auth_source.go`
|
||||
- Modify: `backend/plugins/domain/admin/handlers_config.go`
|
||||
- Modify: `backend/plugins/domain/admin/handlers_logs.go`
|
||||
- Modify: `backend/plugins/domain/admin/handlers_status.go`
|
||||
- Modify: `backend/plugins/domain/admin/handlers_tasks.go`
|
||||
- Modify: `backend/plugins/domain/admin/repository.go`
|
||||
- Modify: `backend/plugins/domain/admin/system_config_cache.go`
|
||||
- Modify: `backend/plugins/domain/admin/plugin.go`
|
||||
- Modify: `backend/plugins/domain/admin/plugin_test.go`
|
||||
- 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.UserService`, `contracts.AuthService`, `contracts.DBService`, `contracts.CacheService`, `ctx.DB()`, `ctx.Cache()`
|
||||
- Zero imports of `plugins/domain/auth`, `plugins/domain/risk_control`, `plugins/domain/cap`, `plugins/drivers/*`, `plugins/infra/database`
|
||||
- Consumes: `contracts.DBService`, `contracts.CacheService`
|
||||
|
||||
- [ ] **Step 1: Write integration tests for Admin handlers using mocked/injected contracts**
|
||||
- [ ] **Step 2: Refactor admin handlers to delegate user/auth operations to contracts**
|
||||
- [ ] **Step 3: Remove all cross-plugin direct package imports and illegal SQL DML**
|
||||
- [ ] **Step 4: Run admin plugin tests to verify passing**
|
||||
- [ ] **Step 5: Commit**
|
||||
- [ ] **Step 1: 改造 `cap`、`message_gateway`、`risk_control`、`system`、`upload` 插件，移除所有 `infra/database` 和 `infra/cache` 的直接 import**
|
||||
- [ ] **Step 2: 统一各插件内部 Repository / Service 的 DB / Cache 获取途径**
|
||||
- [ ] **Step 3: 运行各插件单测验证通过**
|
||||
|
||||
---
|
||||
|
||||
### Task 6: Clean up Domain & Infra Plugins Database / Cache Injections
|
||||
### Task 5: Admin 插件解耦与包级全局状态清除
|
||||
|
||||
**Files:**
|
||||
- Modify: `backend/plugins/domain/cap/...`
|
||||
- Modify: `backend/plugins/domain/message_gateway/...`
|
||||
- Modify: `backend/plugins/domain/risk_control/...`
|
||||
- Modify: `backend/plugins/domain/upload/...`
|
||||
- Modify: `backend/plugins/domain/system/...`
|
||||
- Modify: `backend/plugins/domain/admin/*`
|
||||
- Test: `backend/plugins/domain/admin/plugin_test.go`
|
||||
|
||||
- [ ] **Step 1: Audit and replace direct `database.DB(ctx)` calls with `ctx.DB()` / injected `contracts.DBService`**
|
||||
- [ ] **Step 2: Audit and replace direct `cache.Client()` calls with `ctx.Cache()` / injected `contracts.CacheService`**
|
||||
- [ ] **Step 3: Run domain plugins test suite**
|
||||
- [ ] **Step 4: Commit**
|
||||
**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 7: Full Verification & Quality Gates
|
||||
### Task 6: 组装层对齐与全量质量门禁验证
|
||||
|
||||
**Files:**
|
||||
- All backend files
|
||||
- Modify: `backend/cmd/app.go`
|
||||
- Modify: `backend/cmd/*`
|
||||
|
||||
- [ ] **Step 1: Run full test suite with race detector: `go test -v -race ./backend/...`**
|
||||
- [ ] **Step 2: Run `make code-check`**
|
||||
- [ ] **Step 3: Run `make format`**
|
||||
- [ ] **Step 4: Run `make swagger`**
|
||||
- [ ] **Step 5: Final commit**
|
||||
- [ ] **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`**
|
||||
|
||||
Reference in New Issue
Block a user