From 3792313797006ffb87f3e8246fe0734c9075cacf Mon Sep 17 00:00:00 2001
From: ryan <ryan@arctel.net>
Date: Thu, 27 Aug 2026 23:38:02 +0800
Subject: [PATCH] docs: add cordis plugin architecture implementation plan

---
 .../2026-08-27-cordis-plugin-architecture.md  | 332 ++++++++++++++++++
 1 file changed, 332 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-08-27-cordis-plugin-architecture.md

diff --git a/docs/superpowers/plans/2026-08-27-cordis-plugin-architecture.md b/docs/superpowers/plans/2026-08-27-cordis-plugin-architecture.md
new file mode 100644
index 00000000..a1667639
--- /dev/null
+++ b/docs/superpowers/plans/2026-08-27-cordis-plugin-architecture.md
@@ -0,0 +1,332 @@
+# Wavelet Cordis 微内核与全插件化改造实施计划
+
+> **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:** 将 Wavelet 架构重构为基于 Cordis 理念的微内核与全插件化架构，支持一切能力插件化、自包含数据迁移、多运行切面（API/Worker/Schedule/All）与下游极简二开扩展。
+
+**Architecture:** 
+- **Core (`core/`)**: 纯净微内核，提供 Context 服务总线、泛型 IoC 容器（`Provide/Inject/Using`）、强类型 EventBus、生命周期状态机与 6 大扩展点协议，零外部业务依赖。
+- **Drivers (`plugins/drivers/`)**: Gin HTTP Server、Asynq Worker、Asynq Scheduler 封装为标准运行时驱动插件。
+- **Infra Plugins (`plugins/infra/`)**: 数据库（GORM/DBResolver）、三层缓存（RAM/Redis/PubSub）、日志（Zap/Otel）、对象存储插件化。
+- **Domain Plugins (`plugins/domain/`)**: Auth、User、MessageGateway、RiskControl、Admin 模块拆分为扁平自包含插件，自带独立 Goose 迁移。
+
+**Tech Stack:** Go 1.25+, Gin, GORM, Asynq, Redis, Zap, OpenTelemetry, Goose, Viper, Cobra.
+
+## Global Constraints
+- 保持 `core/` 绝对纯净，禁止 import Gin、GORM、Asynq 或具体业务包。
+- 插件之间严禁相互跨包 import 具体实现，跨插件交互一律通过 `core/contracts` 接口或 `ctx.Events()` 事件总线。
+- 严格遵循 Go 单元测试规范，测试临时目录统一使用 `t.TempDir()`，测试覆盖率严格达标。
+- 完成每个 Task 后必须确保代码能通过 `go build ./...` 与 `go test ./...` 检验并及时提交 Git。
+
+---
+
+### Task 1: 微内核基础契约与泛型 Context 服务总线 (`core/`)
+
+**Files:**
+- Create: `core/types.go`
+- Create: `core/manifest.go`
+- Create: `core/container.go`
+- Create: `core/context.go`
+- Test: `core/context_test.go`
+
+**Interfaces:**
+- Produces: `core.Plugin`, `core.Manifest`, `core.Context`, `core.Provide[T]`, `core.Inject[T]`, `core.Using[T]`
+
+- [ ] **Step 1: 编写 Context 与 IoC 容器的失败测试**
+
+```go
+// core/context_test.go
+package core_test
+
+import (
+	"context"
+	"testing"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"github.com/Rain-kl/Wavelet/core"
+)
+
+type SampleService interface {
+	Greet(name string) string
+}
+
+type sampleServiceImpl struct{}
+
+func (s *sampleServiceImpl) Greet(name string) string {
+	return "Hello, " + name
+}
+
+func TestContextProvideAndInject(t *testing.T) {
+	ctx := core.NewContext(context.Background())
+	core.Provide[SampleService](ctx, &sampleServiceImpl{})
+
+	svc, err := core.Inject[SampleService](ctx)
+	require.NoError(t, err)
+	assert.Equal(t, "Hello, Wavelet", svc.Greet("Wavelet"))
+}
+
+func TestContextUsing(t *testing.T) {
+	ctx := core.NewContext(context.Background())
+	var called bool
+
+	err := core.Using(ctx, func(s SampleService) {
+		called = true
+		assert.Equal(t, "Hello, Cordis", s.Greet("Cordis"))
+	})
+	assert.Error(t, err, "service not ready yet")
+	assert.False(t, called)
+
+	core.Provide[SampleService](ctx, &sampleServiceImpl{})
+	err = core.Using(ctx, func(s SampleService) {
+		called = true
+		assert.Equal(t, "Hello, Cordis", s.Greet("Cordis"))
+	})
+	assert.NoError(t, err)
+	assert.True(t, called)
+}
+```
+
+- [ ] **Step 2: 运行测试验证失败**
+
+Run: `go test -v ./core`
+Expected: FAIL with compilation error (package not found).
+
+- [ ] **Step 3: 实现 Core 核心接口与泛型容器**
+
+编写 `core/types.go`、`core/manifest.go`、`core/container.go`、`core/context.go`，提供基于反射与类型推导的安全泛型服务存取、Scope 隔离与 Disposer 回调链。
+
+- [ ] **Step 4: 运行测试验证通过**
+
+Run: `go test -v ./core`
+Expected: PASS
+
+- [ ] **Step 5: 提交 Task 1 代码**
+
+```bash
+git add core/
+git commit -m "feat(core): implement context service hub and generic ioc container"
+```
+
+---
+
+### Task 2: 领域扩展点规范与强类型 EventBus (`core/extpoints/`, `core/events.go`)
+
+**Files:**
+- Create: `core/events.go`
+- Create: `core/extpoints/router.go`
+- Create: `core/extpoints/migration.go`
+- Create: `core/extpoints/task.go`
+- Create: `core/extpoints/schedule.go`
+- Create: `core/extpoints/setting.go`
+- Test: `core/events_test.go`
+- Test: `core/extpoints/extpoints_test.go`
+
+**Interfaces:**
+- Consumes: `core.Context`
+- Produces: `core.EventBus`, `core.RouterExtension`, `core.MigrationExtension`, `core.TaskExtension`, `core.ScheduleExtension`, `core.SettingExtension`
+
+- [ ] **Step 1: 编写 EventBus 与扩展点测试用例**
+
+```go
+// core/events_test.go
+package core_test
+
+import (
+	"context"
+	"testing"
+	"github.com/stretchr/testify/assert"
+	"github.com/Rain-kl/Wavelet/core"
+)
+
+type UserRegisteredEvent struct {
+	UserID string
+}
+
+func TestEventBusPublishSubscribe(t *testing.T) {
+	bus := core.NewEventBus()
+	var receivedID string
+
+	bus.On("user:registered", func(ctx context.Context, e UserRegisteredEvent) error {
+		receivedID = e.UserID
+		return nil
+	})
+
+	err := bus.Emit(context.Background(), "user:registered", UserRegisteredEvent{UserID: "u_999"})
+	assert.NoError(t, err)
+	assert.Equal(t, "u_999", receivedID)
+}
+```
+
+- [ ] **Step 2: 运行测试验证失败**
+
+Run: `go test -v ./core/...`
+Expected: FAIL
+
+- [ ] **Step 3: 实现 EventBus 与 6 大扩展点适配器**
+
+编写 `core/events.go` 及 `core/extpoints/` 下各个领域的挂载收集器（Router 注册收集、Goose embed.FS 聚合器、Task/Schedule 声明表、Setting 模式注册表）。
+
+- [ ] **Step 4: 运行测试验证通过**
+
+Run: `go test -v ./core/...`
+Expected: PASS
+
+- [ ] **Step 5: 提交 Task 2 代码**
+
+```bash
+git add core/
+git commit -m "feat(core): add typed eventbus and domain extension points"
+```
+
+---
+
+### Task 3: 运行时驱动插件下沉 (`plugins/drivers/`)
+
+**Files:**
+- Create: `plugins/drivers/driver_http/plugin.go`
+- Create: `plugins/drivers/driver_asynq_worker/plugin.go`
+- Create: `plugins/drivers/driver_asynq_cron/plugin.go`
+- Test: `plugins/drivers/drivers_test.go`
+
+**Interfaces:**
+- Consumes: `core.Plugin`, `core.Driver`, `core.Context`
+- Produces: `DriverTypeHTTP`, `DriverTypeWorker`, `DriverTypeScheduler`
+
+- [ ] **Step 1: 编写 Driver 生命周期测试用例**
+
+测试驱动在接收到 `Start(ctx)` 和 `Stop(ctx)` 信号时的平滑启动与退出状态。
+
+- [ ] **Step 2: 编写 Driver 实现**
+
+将 Gin HTTP Server、Asynq Worker Server、Asynq Scheduler 封装为标准 `core.Driver`，并在 `Apply(ctx)` 时挂载到 Context 驱动树。
+
+- [ ] **Step 3: 运行驱动单元测试**
+
+Run: `go test -v ./plugins/drivers/...`
+Expected: PASS
+
+- [ ] **Step 4: 提交 Task 3 代码**
+
+```bash
+git add plugins/drivers/
+git commit -m "feat(plugins): implement runtime drivers for http, asynq worker, and cron"
+```
+
+---
+
+### Task 4: 基础设施服务插件化 (`plugins/infra/`)
+
+**Files:**
+- Create: `plugins/infra/database/plugin.go` (提供 GORM DBService)
+- Create: `plugins/infra/cache/plugin.go` (提供 RAM/Redis 三层缓存)
+- Create: `plugins/infra/logger/plugin.go` (提供 Zap/Otel 结构化日志)
+- Create: `plugins/infra/storage/plugin.go` (提供统一对象存储)
+- Test: `plugins/infra/infra_test.go`
+
+**Interfaces:**
+- Produces: `contracts.DBService`, `contracts.CacheService`, `contracts.LoggerService`, `contracts.StorageService`
+
+- [ ] **Step 1: 编写基础设施插件注入与提取测试**
+- [ ] **Step 2: 实现 4 大基础设施插件并封装现有 pkg 与 infra 底座**
+- [ ] **Step 3: 运行基础设施测试验证**
+
+Run: `go test -v ./plugins/infra/...`
+Expected: PASS
+
+- [ ] **Step 4: 提交 Task 4 代码**
+
+```bash
+git add plugins/infra/
+git commit -m "feat(plugins): package database, cache, logger, and storage as infra plugins"
+```
+
+---
+
+### Task 5: 业务领域插件化重构 (`plugins/domain/`)
+
+**Files:**
+- Create: `plugins/domain/auth/` (认证、Session、Passkey、专属 migrations)
+- Create: `plugins/domain/user/` (用户资料、角色权限、专属 migrations)
+- Create: `plugins/domain/message_gateway/` (Bot网关、推送通道、Worker消费)
+- Create: `plugins/domain/risk_control/` (IP限流、风控中间件)
+- Create: `plugins/domain/admin/` (控制台、系统设置)
+- Test: `plugins/domain/domain_test.go`
+
+**Interfaces:**
+- Consumes: `contracts.DBService`, `contracts.CacheService`, `contracts.LoggerService`
+- Produces: `contracts.AuthService`, `contracts.UserService`
+
+- [ ] **Step 1: 编写 Auth 与 User 插件业务装配与独立迁移测试**
+- [ ] **Step 2: 将各业务模块迁移为扁平自包含插件，嵌入专属 Goose SQL 迁移**
+- [ ] **Step 3: 运行业务插件集成测试**
+
+Run: `go test -v ./plugins/domain/...`
+Expected: PASS
+
+- [ ] **Step 4: 提交 Task 5 代码**
+
+```bash
+git add plugins/domain/
+git commit -m "feat(plugins): migrate auth, user, message_gateway, risk_control, admin to domain plugins"
+```
+
+---
+
+### Task 6: 统一装配入口与运行时切面分发器 (`core/app.go`, `cmd/`)
+
+**Files:**
+- Create: `core/app.go`
+- Modify: `internal/cmd/root.go`
+- Modify: `internal/cmd/api.go`
+- Modify: `internal/cmd/worker.go`
+- Modify: `internal/cmd/scheduler.go`
+- Modify: `internal/cmd/all.go`
+- Test: `core/app_test.go`
+
+**Interfaces:**
+- Consumes: `core.App`, `core.Plugin`, `core.Driver`
+- Produces: 统一 CLI 启动与优雅停机流程
+
+- [ ] **Step 1: 编写 App 生命周期与 Profile 调度测试**
+- [ ] **Step 2: 实现 `core.App` 编排引擎，无缝接入 `wavelet api / worker / schedule / all`**
+- [ ] **Step 3: 运行启动与角色切面集成验证**
+
+Run: `go test -v ./core -run TestAppProfileDispatch`
+Expected: PASS
+
+- [ ] **Step 4: 提交 Task 6 代码**
+
+```bash
+git add core/ internal/cmd/
+git commit -m "feat(core): implement app profile lifecycle dispatcher and wire cli commands"
+```
+
+---
+
+### Task 7: 下游脚手架、自定义示例插件与端到端验证
+
+**Files:**
+- Create: `downstream/custom_plugins/order/plugin.go`
+- Create: `downstream/main.go`
+- Create: `downstream/config.yaml`
+- Test: `downstream/e2e_test.go`
+
+- [ ] **Step 1: 编写下游自定义业务插件并在下游 `main.go` 组装启动**
+- [ ] **Step 2: 执行全量 E2E 测试，验证数据迁移、HTTP 路由访问、Worker 任务消费与平滑停机**
+- [ ] **Step 3: 运行全局质量门禁检查**
+
+Run:
+```bash
+make test
+make code-check
+make format
+```
+Expected: 全部 PASS，0 lint 报错。
+
+- [ ] **Step 4: 提交 Task 7 代码**
+
+```bash
+git add downstream/
+git commit -m "feat(downstream): add starter scaffold, example custom plugin, and e2e tests"
+```
+