docs: publish WAVELET architecture white paper and official developer guide

2026-09-29 14:06:36 +08:00 · 2026-08-27 23:51:37 +08:00
parent a25bf7a4f9
commit 94c5aa4cd3
2 changed files with 672 additions and 0 deletions
@@ -0,0 +1,565 @@
+# Wavelet Cordis 插件化架构实战开发指南与标准规范
+
+- **文档类型**: 下游开发者手册 / 架构实战指南 (Cookbook & Architecture Reference)
+- **目标受众**: 官方插件开发者、下游业务二开工程师、架构师
+- **版本**: v1.0.0 (2026-08-27)
+
+---
+
+# 目录
+- [第一部分：下游项目实战开发指南与 22 个高频开发场景解答](#第一部分下游项目实战开发指南与-22-个高频开发场景解答)
+  - [场景 1：插件必须要实现哪些方法与契约？](#场景-1插件必须要实现哪些方法与契约)
+  - [场景 2：插件间如何进行单向服务调用？](#场景-2插件间如何进行单向服务调用)
+  - [场景 3：插件间存在双向/循环调用时如何解决（杜绝 import cycle）？](#场景-3插件间存在双向循环调用时如何解决杜绝-import-cycle)
+  - [场景 4：如何开发并注册一个 HTTP API 接口？如何添加路由中间件？](#场景-4如何开发并注册一个-http-api-接口如何添加路由中间件)
+  - [场景 5：如何获取当前登录用户信息？](#场景-5如何获取当前登录用户信息)
+  - [场景 6：如何开发并注册一个 Asynq 异步 Worker 任务？](#场景-6如何开发并注册一个-asynq-异步-worker-任务)
+  - [场景 7：如何开发并注册一个 Cron 定时任务？](#场景-7如何开发并注册一个-cron-定时任务)
+  - [场景 8：数据库表结构如何声明？ORM 模型规范是什么？](#场景-8数据库表结构如何声明orm-模型规范是什么)
+  - [场景 9：数据库如何做独立迁移？Goose SQL 怎么组织？](#场景-9数据库如何做独立迁移goose-sql-怎么组织)
+  - [场景 10：如果有多个业务插件需要读写同一张表怎么办？](#场景-10如果有多个业务插件需要读写同一张表怎么办)
+  - [场景 11：如果跨插件操作多张表，如何确保事务一致性？](#场景-11如果跨插件操作多张表如何确保事务一致性)
+  - [场景 12：如何发布和订阅领域事件 (EventBus)？](#场景-12如何发布和订阅领域事件-eventbus)
+  - [场景 13：如何向系统注册插件自定义配置（config.yaml 与管理台热加载设置）？](#场景-13如何向系统注册插件自定义配置configyaml-与管理台热加载设置)
+  - [场景 14：如何使用多层缓存（RAM L1 + Redis L2 + PubSub 同步）？](#场景-14如何使用多层缓存ram-l1--redis-l2--pubsub-同步)
+  - [场景 15：如何使用分布式锁 (DistLock) 防止并发超卖与重复消费？](#场景-15如何使用分布式锁-distlock-防止并发超卖与重复消费)
+  - [场景 16：如何向管理后台动态注册监控数据与管理控制台？](#场景-16如何向管理后台动态注册监控数据与管理控制台)
+  - [场景 17：插件如何实现健康检查探针与就绪检查 (Health Check)？](#场景-17插件如何实现健康检查探针与就绪检查-health-check)
+  - [场景 18：插件如何扩展其他插件的能力（如新增一种 OAuth 登录提供商 / 新增消息推送渠道）？](#场景-18插件如何扩展其他插件的能力如新增一种-oauth-登录提供商--新增消息推送渠道)
+  - [场景 19：插件如何编写单元测试与集成测试（Mock 上下文与依赖打桩）？](#场景-19插件如何编写单元测试与集成测试mock-上下文与依赖打桩)
+  - [场景 20：以不同角色（api / worker / schedule / all）启动时，插件代码如何适配？](#场景-20以不同角色api--worker--schedule--all启动时插件代码如何适配)
+  - [场景 21：当某个插件流量暴增需要独立拆分为微服务时，如何零成本平滑改造？](#场景-21当某个插件流量暴增需要独立拆分为微服务时如何零成本平滑改造)
+  - [场景 22：插件如何安全处理文件上传与大文件摄取 (upload.Ingest)？](#场景-22插件如何安全处理文件上传与大文件摄取-uploadingest)
+- [第二部分：整个项目的目录结构划分与包职责定义](#第二部分整个项目的目录结构划分与包职责定义)
+- [第三部分：框架核心提供给插件调用的公用能力矩阵 (Context Capability Matrix)](#第三部分框架核心提供给插件调用的公用能力矩阵-context-capability-matrix)
+
+---
+
+# 第一部分：下游项目实战开发指南与 22 个高频开发场景解答
+
+### 场景 1：插件必须要实现哪些方法与契约？
+每个插件必须实现 `core.Plugin` 接口，仅需提供两个核心方法：`Name()` 与 `Apply(ctx *core.Context)`。
+
+```go
+package myplugin
+
+import "github.com/Rain-kl/Wavelet/core"
+
+type Plugin struct{}
+
+// 1. Name: 返回全局唯一的插件标识符（建议遵循命名空间规范，如 "biz.order"）
+func (p *Plugin) Name() string {
+    return "biz.order"
+}
+
+// 2. Apply: 核心装载入口，所有的路由注册、任务注册、服务提供与依赖消费均在此完成
+func (p *Plugin) Apply(ctx *core.Context) error {
+    // 在此编写装载逻辑
+    return nil
+}
+```
+
+---
+
+### 场景 2：插件间如何进行单向服务调用？
+**规则**：插件之间**禁止直接相互 import 具体实现包**。调用方仅面向 `core/contracts` 中的纯 Interface 编程，运行时通过 Context 解析。
+
+```go
+// 1. 插件 A (提供者 plugins/user) 将服务注入 Context
+func (p *UserPlugin) Apply(ctx *core.Context) error {
+    userSvc := NewUserServiceImpl(ctx.DB())
+    ctx.Provide[contracts.UserService](userSvc)
+    return nil
+}
+
+// 2. 插件 B (消费者 plugins/order) 声明依赖并调用
+func (p *OrderPlugin) Apply(ctx *core.Context) error {
+    return ctx.Using(func(userSvc contracts.UserService) {
+        // userSvc 已由容器自动注入就绪
+        v1 := ctx.Router().Group("/api/v1/orders")
+        v1.POST("", func(c *gin.Context) {
+            userInfo, err := userSvc.GetUserProfile(c.Request.Context(), "user_123")
+            // 处理订单逻辑...
+        })
+    })
+}
+```
+
+---
+
+### 场景 3：插件间存在双向/循环调用时如何解决（杜绝 import cycle）？
+**问题场景**：`auth` 登录成功后需要查 `user` 资料；`user` 重置密码后需要调 `auth` 吊销 session。若两个 package 互相 import，Go 编译器会报 `import cycle not allowed`。
+
+**Cordis 解法**：
+1. 接口均定义在 `core/contracts`，双方只依赖 `core/contracts`。
+2. 运行时采用 **延迟注入 (Lazy Resolution / Inject)** 或 **事件解耦 (EventBus)**：
+
+```go
+// plugins/auth/service.go
+func (s *AuthServiceImpl) OnLoginSuccess(c context.Context, uid string) {
+    // 延迟注入 UserService，不发生 package 级循环导入
+    userSvc, err := core.Inject[contracts.UserService](s.ctx)
+    if err == nil {
+        userSvc.UpdateLastLoginTime(c, uid)
+    }
+}
+```
+*更加推荐的方式是发射领域事件*（见场景 12），由 `user` 插件自愿监听，彻底消除相互调用的硬依赖。
+
+---
+
+### 场景 4：如何开发并注册一个 HTTP API 接口？如何添加路由中间件？
+插件通过 `ctx.Router()` 声明路由。微内核支持标准 Gin 路由组与中间件挂载：
+
+```go
+func (p *OrderPlugin) Apply(ctx *core.Context) error {
+    // 获取全局或 auth 插件提供的中间件
+    authSvc, _ := core.Inject[contracts.AuthService](ctx)
+
+    // 创建带版本前缀和鉴权中间件的路由组
+    group := ctx.Router().Group("/api/v1/orders", authSvc.RequireAuthMiddleware())
+    
+    // 注册 Handler
+    group.GET("", p.handleListOrders)
+    group.POST("", p.handleCreateOrder)
+    group.GET("/:id", p.handleGetOrderDetail)
+
+    return nil
+}
+```
+
+---
+
+### 场景 5：如何获取当前登录用户信息？
+`auth` 插件会在上下文中注入当前用户 Session。业务 Handler 可直接调用统一 Helper：
+
+```go
+func (p *OrderPlugin) handleCreateOrder(c *gin.Context) {
+    // 1. 从当前 Gin 请求上下文中提取认证用户信息
+    currentUser, ok := oauth.GetCurrentUser(c)
+    if !ok {
+        response.AbortUnauthorized(c, errs.ErrUnauthorized)
+        return
+    }
+
+    log.Printf("当前下单用户 ID: %s, 权限角色: %s", currentUser.ID, currentUser.Role)
+    // 2. 正常业务处理...
+}
+```
+
+---
+
+### 场景 6：如何开发并注册一个 Asynq 异步 Worker 任务？
+```go
+func (p *OrderPlugin) Apply(ctx *core.Context) error {
+    // 1. 注册 Asynq 任务类型与消费处理器
+    ctx.Task().Register("order:cancel_timeout", p.handleTimeoutCancelTask)
+    return nil
+}
+
+// 2. 任务执行函数
+func (p *OrderPlugin) handleTimeoutCancelTask(ctx context.Context, t *asynq.Task) error {
+    var payload OrderTimeoutPayload
+    if err := json.Unmarshal(t.Payload(), &payload); err != nil {
+        return err
+    }
+    // 执行超时关单业务逻辑...
+    return nil
+}
+
+// 3. 业务中异步投递任务
+func (p *OrderPlugin) EnqueueTimeoutCheck(ctx context.Context, orderID string) {
+    p.ctx.TaskClient().EnqueueContext(ctx, asynq.NewTask("order:cancel_timeout", payloadBytes), asynq.ProcessIn(15*time.Minute))
+}
+```
+
+---
+
+### 场景 7：如何开发并注册一个 Cron 定时任务？
+```go
+func (p *ReportPlugin) Apply(ctx *core.Context) error {
+    // 每天凌晨 2 点执行日报汇总任务
+    ctx.Schedule().RegisterCron("0 2 * * *", "report:daily_summary", DailyReportPayload{Type: "all"})
+    return nil
+}
+```
+
+---
+
+### 场景 8：数据库表结构如何声明？ORM 模型规范是什么？
+**规范**：
+1. 表名必须带有插件专有前缀（如 `w_order_`、`w_auth_`），避免跨插件表名冲突。
+2. 零值与数据库默认值严格对齐；禁止物理外键，显式建索引。
+3. 必须通过 GORM 结构体清晰声明 `gorm:"..."` 标签与 `json:"..."`。
+
+```go
+package models
+
+import "time"
+
+type Order struct {
+    ID        string     `gorm:"column:id;primaryKey;size:64" json:"id"`
+    UserID    string     `gorm:"column:user_id;index;size:64;not null" json:"user_id"`
+    Amount    int64      `gorm:"column:amount;not null" json:"amount"`
+    Status    string     `gorm:"column:status;size:32;index;not null;default:'pending'" json:"status"`
+    CreatedAt time.Time  `gorm:"column:created_at;autoCreateTime" json:"created_at"`
+    UpdatedAt time.Time  `gorm:"column:updated_at;autoUpdateTime" json:"updated_at"`
+    DeletedAt *time.Time `gorm:"column:deleted_at;index" json:"-"`
+}
+
+func (Order) TableName() string {
+    return "w_orders"
+}
+```
+
+---
+
+### 场景 9：数据库如何做独立迁移？Goose SQL 怎么组织？
+**彻底告别集中大迁移目录**。每个插件在内部目录建立 `migrations/`，并通过 `//go:embed` 打包注入：
+
+```go
+// plugins/order/plugin.go
+package order
+
+import (
+    "embed"
+    "github.com/Rain-kl/Wavelet/core"
+)
+
+//go:embed migrations/*.sql
+var orderMigrations embed.FS
+
+func (p *Plugin) Apply(ctx *core.Context) error {
+    // 注册本插件的专属迁移（系统启动时自动按版本号执行）
+    ctx.Migrations().Register("order", orderMigrations)
+    return nil
+}
+```
+
+#### SQL 迁移脚本规范 (`plugins/order/migrations/20260827000001_create_orders_table.sql`)：
+```sql
+-- +goose Up
+-- +goose StatementBegin
+CREATE TABLE IF NOT EXISTS w_orders (
+    id VARCHAR(64) PRIMARY KEY,
+    user_id VARCHAR(64) NOT NULL,
+    amount BIGINT NOT NULL,
+    status VARCHAR(32) NOT NULL DEFAULT 'pending',
+    created_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    deleted_at TIMESTAMPTZ
+);
+CREATE INDEX IF NOT EXISTS idx_w_orders_user_id ON w_orders(user_id);
+-- +goose StatementEnd
+
+-- +goose Down
+-- +goose StatementBegin
+DROP TABLE IF EXISTS w_orders;
+-- +goose StatementEnd
+```
+
+---
+
+### 场景 10：如果有多个业务插件需要读写同一张表怎么办？
+**黄金准则**：**表有且仅有一个所有者插件 (Single Owner Principle)**。
+* 严禁插件 B 直接通过 SQL 修改插件 A 拥有的核心表（如订单插件直接修改用户表）。
+* **合法模式 1（服务调用）**：插件 A 提供 `UserService.DeductBalance(uid, amount)`，插件 B 调用该接口。
+* **合法模式 2（只读视图 / 共享查询 DTO）**：如果仅仅是高频联合查询（报表），插件 A 暴露只读查询接口，或通过数据库只读从库直接投影。
+
+---
+
+### 场景 11：如果跨插件操作多张表，如何确保事务一致性？
+在插件化和微服务就绪体系下，**跨插件的强分布式事务是反模式**。
+
+1. **同插件内多表操作**：直接使用本地数据库事务：
+   ```go
+   err := ctx.DB().Transaction(func(tx *gorm.DB) error {
+       if err := tx.Create(&order).Error; err != nil { return err }
+       if err := tx.Create(&orderItem).Error; err != nil { return err }
+       return nil
+   })
+   ```
+2. **跨插件操作（如创建订单 + 扣减库存 + 发送通知）**：
+   * 采用 **最终一致性 (Eventual Consistency / Saga 模式)**。
+   * 本地事务成功后，发射 `OrderCreatedEvent` 到 EventBus；
+   * 库存插件监听到事件后扣减库存，若失败则发布补偿事件触发订单取消。
+
+---
+
+### 场景 12：如何发布和订阅领域事件 (EventBus)？
+```go
+// 1. 定义强类型事件结构
+type OrderPaidEvent struct {
+    OrderID   string `json:"order_id"`
+    UserID    string `json:"user_id"`
+    PayAmount int64  `json:"pay_amount"`
+}
+
+// 2. 插件 A 发布事件
+ctx.Events().Emit("order:paid", OrderPaidEvent{OrderID: "ord_1", UserID: "u_1", PayAmount: 9900})
+
+// 3. 插件 B 订阅事件
+ctx.Events().On("order:paid", func(c context.Context, e OrderPaidEvent) error {
+    log.Printf("收到支付成功事件，开始为用户 %s 发放权益", e.UserID)
+    return nil
+})
+```
+
+---
+
+### 场景 13：如何向系统注册插件自定义配置（config.yaml 与管理台热加载设置）？
+```go
+type OrderConfig struct {
+    MaxItemsPerOrder int  `yaml:"max_items" json:"max_items"`
+    AutoCancelMins   int  `yaml:"auto_cancel_mins" json:"auto_cancel_mins"`
+}
+
+func (p *OrderPlugin) Apply(ctx *core.Context) error {
+    var cfg OrderConfig
+    // 1. 自动从 config.yaml 中的 plugins.order 节点绑定配置
+    ctx.Config().Bind("plugins.order", &cfg)
+    
+    // 2. 注册为管理台可动态修改的系统参数
+    ctx.Settings().Register(core.SettingSchema{
+        Key:         "order.auto_cancel_mins",
+        Default:     15,
+        Description: "未支付订单自动取消时间 (分钟)",
+    })
+    return nil
+}
+```
+
+---
+
+### 场景 14：如何使用多层缓存（RAM L1 + Redis L2 + PubSub 同步）？
+框架提供三层穿透缓存能力，防止缓存击穿与雪崩：
+
+```go
+func (s *OrderService) GetOrderWithCache(ctx context.Context, orderID string) (*Order, error) {
+    var order Order
+    err := s.ctx.Cache().GetOrSet(ctx, "order:"+orderID, &order, 10*time.Minute, func() (any, error) {
+        // Cache Miss 回源查 DB
+        var dbOrder Order
+        if err := s.db.WithContext(ctx).First(&dbOrder, "id = ?", orderID).Error; err != nil {
+            return nil, err
+        }
+        return &dbOrder, nil
+    })
+    return &order, err
+}
+
+// 当订单更新时，广播失效所有节点的 L1 内存缓存与 L2 Redis 缓存
+func (s *OrderService) InvalidateCache(ctx context.Context, orderID string) {
+    s.ctx.Cache().Delete(ctx, "order:"+orderID)
+}
+```
+
+---
+
+### 场景 15：如何使用分布式锁 (DistLock) 防止并发超卖与重复消费？
+```go
+func (s *OrderService) ProcessPayment(ctx context.Context, orderID string) error {
+    // 获取分布式锁，租期 5 秒
+    unlock, err := s.ctx.DistLock().Lock(ctx, "lock:order:pay:"+orderID, 5*time.Second)
+    if err != nil {
+        return fmt.Errorf("当前订单正在处理中，请勿重复提交")
+    }
+    defer unlock() // 确保释放
+
+    // 执行扣款操作...
+    return nil
+}
+```
+
+---
+
+### 场景 16：如何向管理后台动态注册监控数据与管理控制台？
+插件可以向管理后台扩展点注入自己的仪表盘指标和诊断探针：
+
+```go
+func (p *OrderPlugin) Apply(ctx *core.Context) error {
+    ctx.Admin().RegisterMetric("order_count_today", func(c context.Context) any {
+        var count int64
+        ctx.DB().Model(&models.Order{}).Where("created_at >= ?", todayStart()).Count(&count)
+        return count
+    })
+    return nil
+}
+```
+
+---
+
+### 场景 17：插件如何实现健康检查探针与就绪检查 (Health Check)？
+```go
+func (p *PaymentPlugin) Apply(ctx *core.Context) error {
+    ctx.Health().RegisterProbe("payment_gateway", func(ctx context.Context) error {
+        // 测试第三方支付网关网络连通性
+        return pingPaymentGateway(ctx)
+    })
+    return nil
+}
+```
+
+---
+
+### 场景 18：插件如何扩展其他插件的能力（如新增一种 OAuth 登录提供商 / 新增消息推送渠道）？
+采用 **注册表扩展点模式 (Registry Pattern)**：
+
+```go
+// 1. 下游编写微信登录插件 plugins/oauth_wechat
+func (p *WeChatOAuthPlugin) Apply(ctx *core.Context) error {
+    return ctx.Using(func(authRegistry contracts.AuthRegistry) {
+        // 向核心 auth 插件注入微信 OAuth 实现
+        authRegistry.RegisterOAuthProvider("wechat", &WeChatProvider{...})
+    })
+}
+```
+
+---
+
+### 场景 19：插件如何编写单元测试与集成测试（Mock 上下文与依赖打桩）？
+微内核提供轻量测试脚手架 `coretest`：
+
+```go
+func TestOrderCreate(t *testing.T) {
+    // 1. 创建内存测试专用 Context
+    ctx := coretest.NewMockContext(t)
+    
+    // 2. Mock 依赖的 UserService
+    mockUserSvc := &MockUserService{ReturnUser: &contracts.UserDTO{ID: "u_1", Balance: 1000}}
+    ctx.Provide[contracts.UserService](mockUserSvc)
+
+    // 3. 装载插件
+    plugin := &OrderPlugin{}
+    require.NoError(t, plugin.Apply(ctx))
+
+    // 4. 发起 HTTP 接口测试
+    w := ctx.PerformRequest("POST", "/api/v1/orders", `{"item_id":"item_1"}`)
+    assert.Equal(t, 200, w.Code)
+}
+```
+
+---
+
+### 场景 20：以不同角色（api / worker / schedule / all）启动时，插件代码如何适配？
+**开发者无需做任何特殊处理**！
+插件只需在一个 `Apply` 方法中把自己的路由、任务、调度全部注册进 `Context`。微内核调度器会根据运行命令自动按需激活对应的运行时驱动，不匹配的能力保持休眠。
+
+---
+
+### 场景 21：当某个插件流量暴增需要独立拆分为微服务时，如何零成本平滑改造？
+```go
+// 1. 之前单体模式：在 main.go 中加载本地实现
+app.Use(&auth.Plugin{}) // 进程内直接运行
+
+// 2. 拆分为微服务后：只需将 main.go 替换为 gRPC 客户端代理插件！
+app.Use(&auth_grpc_client.Plugin{RemoteAddr: "auth-service.prod:9000"})
+
+// 3. 所有依赖 auth 的业务插件（如 order, user）业务代码 0 处修改！
+```
+
+---
+
+### 场景 22：插件如何安全处理文件上传与大文件摄取 (upload.Ingest)？
+**严格规则**：禁止插件自行直接写入对象存储底层 Bucket 或直连底层文件系统。统一走平台摄取服务：
+
+```go
+func (p *OrderPlugin) handleUploadInvoice(c *gin.Context) {
+    fileHeader, _ := c.FormFile("file")
+    
+    // 使用平台统一摄取引擎（自动计算哈希、防重传、生成签名 URL 与入库追踪）
+    ingestResult, err := upload.IngestFormFile(c.Request.Context(), fileHeader, upload.IngestPolicy{
+        AllowedTypes: []string{"image/png", "application/pdf"},
+        MaxSizeBytes: 10 * 1024 * 1024,
+    })
+    if err != nil {
+        response.AbortBadRequest(c, errs.ErrUploadFailed)
+        return
+    }
+
+    c.JSON(200, response.OK(gin.H{"file_url": ingestResult.URL}))
+}
+```
+
+---
+
+# 第二部分：整个项目的目录结构划分与包职责定义
+
+```text
+Wavelet/
+├── cmd/                          # CLI 命令分发与装配入口
+│   ├── root.go                   # Cobra 根命令
+│   ├── server.go                 # 综合启动器（支持 api/worker/schedule/all profile）
+│   └── migrate.go                # 数据库独立迁移命令行工具
+│
+├── core/                         # 【微内核引擎 (Zero Business Logic)】
+│   ├── context.go                # Context 上下文总线与 Fork 树
+│   ├── container.go              # 基于泛型的 IoC 服务注册与解析器
+│   ├── events.go                 # 强类型领域事件总线 (EventBus)
+│   ├── lifecycle.go              # 启动/停止生命周期编排状态机
+│   ├── contracts/                # 【跨插件标准服务契约 (纯 Interface)】
+│   │   ├── auth.go               # AuthService 契约
+│   │   ├── user.go               # UserService 契约
+│   │   ├── cache.go              # CacheService 契约
+│   │   └── database.go           # DBService 契约
+│   └── extpoints/                # 扩展点定义 (Router, Task, Migration, Setting)
+│
+├── plugins/                      # 【官方标准插件库 (完全高内聚闭包)】
+│   ├── drivers/                  # 运行时驱动插件
+│   │   ├── driver_http/          # Gin Web HTTP 驱动
+│   │   ├── driver_asynq_worker/  # Asynq Worker 并发消费驱动
+│   │   └── driver_asynq_cron/    # Asynq Cron 调度器驱动
+│   │
+│   ├── infra/                    # 基础设施服务插件
+│   │   ├── database/             # GORM 多数据源与读写分离插件
+│   │   ├── cache/                # RAM + Redis + PubSub 缓存插件
+│   │   ├── logger/               # Zap + Otel 分布式链路追踪日志插件
+│   │   └── storage/              # S3 / OSS / Local 对象存储插件
+│   │
+│   └── domain/                   # 业务领域能力插件
+│       ├── auth/                 # OAuth / Session / Passkey 认证插件
+│       ├── user/                 # 用户资料 / 权限 / 角色插件
+│       ├── message_gateway/      # Bot 网关 / 渠道推送插件
+│       ├── risk_control/         # 访问控制 / IP 限流 / 安全风控插件
+│       └── admin/                # 系统管理台与监控面板插件
+│
+└── downstream/                   # 【下游二开项目模板与脚手架】
+    ├── custom_plugins/           # 下游自定义业务插件
+    ├── config.yaml               # 声明启用的插件与配置文件
+    └── main.go                   # 下游项目组合启动入口
+```
+
+### 各层职责与禁止规则 (Guardrails)：
+1. **`core/`**：
+   - **职责**：纯抽象，提供 IoC、Context、EventBus 和 Lifecycle。
+   - **严禁**：严禁 import 任何具体业务包，严禁 import `gin`、`gorm`、`asynq`。
+2. **`core/contracts/`**：
+   - **职责**：仅定义公开的 Go Interface 和公共 DTO。
+   - **严禁**：严禁包含任何具体实现逻辑或 SQL 操作。
+3. **`plugins/`**：
+   - **职责**：所有业务逻辑和驱动实现的归宿。每个插件扁平自包含。
+   - **严禁**：插件之间严禁跨包 import 内部私有代码，跨插件调用一律走 `contracts` 接口或 `EventBus`。
+
+---
+
+# 第三部分：框架核心提供给插件调用的公用能力矩阵 (Context Capability Matrix)
+
+每个插件在 `Apply(ctx *core.Context)` 时，都可以无缝调用微内核暴露的以下标准能力：
+
+| 扩展点方法 | 返回类型 | 功能说明 | 适用场景 |
+| :--- | :--- | :--- | :--- |
+| `ctx.Router()` | `RouterExtension` | 声明 HTTP 路由、前缀分组与挂载中间件 | 暴露 API 接口、Web 控制台 |
+| `ctx.Task()` | `TaskExtension` | 注册 Asynq 异步任务消费处理器 | 耗时后台任务、异步消息发送 |
+| `ctx.Schedule()` | `ScheduleExtension`| 注册 Cron 定时调度任务 | 定时报表统计、周期性清理 |
+| `ctx.Migrations()` | `MigrationExtension`| 注册插件专属的 Goose SQL 迁移嵌入系统 | 自建数据表、版本升级 |
+| `ctx.Events()` | `EventBus` | 强类型领域事件的发布与订阅 (Emit / On) | 跨插件完全解耦通知与状态同步 |
+| `ctx.Settings()` | `SettingExtension` | 声明动态可配置项（支持热更新） | 业务参数配置、管理台可调节参数 |
+| `ctx.DB()` | `*gorm.DB` | 获取全局受事务与 Trace 保护的 GORM 数据源 | 数据持久化 CRUD |
+| `ctx.Cache()` | `CacheService` | 三层穿透缓存（RAM L1 + Redis L2 + PubSub 广播）| 高频读数据性能加速 |
+| `ctx.DistLock()` | `DistLockService` | 基于 Redis 的工业级分布式锁 | 防并发超卖、防重复执行 |
+| `ctx.Logger()` | `Logger` | 携带链路 TraceID 的结构化日志记录器 | 业务日志打印与审计 |
+| `ctx.Storage()` | `StorageService` | 统一对象存储读写引擎 | 文件摄取、图片持久化 |
+| `core.Provide[T]`| `void` | 向全局 IoC 容器注册本插件提供的强类型服务 | 暴露自身能力给其他插件消费 |
+| `core.Inject[T]` | `(T, error)` | 从全局 IoC 容器中按类型获取服务实例 | 消费其他插件暴露的服务 |
+| `core.Using[T]` | `error` | 响应式声明依赖，当服务就绪时执行回调 | 声明前置依赖关系 |
+
@@ -0,0 +1,107 @@
+# WAVELET 架构白皮书 (Technical Architecture White Paper)
+
+- **版本**: v1.0.0 (Cordis Architecture Standard)
+- **代号**: Cordis-Wavelet
+- **编写组织**: Wavelet 核心架构委员会
+- **发布日期**: 2026-08-27
+
+---
+
+## 1. 摘要与愿景 (Executive Summary)
+
+Wavelet 是面向下一代云原生与企业级业务中台的 **微内核全插件化框架 (Micro-Kernel & Plugin-Native Platform)**。
+其核心愿景是：**通过极致内聚的微内核与纯净的上下文服务总线，实现“一切皆插件、一切皆服务”的极高业务拓展性与生态繁荣**。
+
+无论是一线工程师开发单个轻量业务功能，还是大型企业面向数万 QPS 高并发流量进行微服务拆分，Wavelet 均能以统一的开发范式支撑未来 5 年的平滑演进。
+
+---
+
+## 2. 核心架构哲学 (Core Architectural Philosophy)
+
+```
+                     ┌────────────────────────┐
+                     │    Context (上下文)    │
+                     │  (统一服务总线/IoC Hub) │
+                     └───────────┬────────────┘
+                                 │
+         ┌───────────────────────┼───────────────────────┐
+         ▼                       ▼                       ▼
+   [提供服务 Provide]       [依赖服务 Using]       [扩展能力 Extend]
+   ctx.Provide(Auth)      ctx.Using([DB, Cache])    ctx.Route / ctx.Task
+```
+
+### 2.1 微内核原则 (Micro-Kernel Principle)
+内核（`core/`）不持有任何具体业务逻辑，不硬编码 Gin、GORM、Asynq 等具体引擎。内核仅提供：
+- 树状上下文（`Context`）与作用域隔离（`Fork`）
+- 泛型依赖注入与服务定位器（`IoC Container`）
+- 强类型领域事件总线（`EventBus`）
+- 生命周期编排器（`Lifecycle Manager`）与标准扩展点契约
+
+### 2.2 扁平自包含插件 (Flat & Self-Contained Plugins)
+告别过度设计的 DDD 样板代码，每个插件作为一个自给自足的高内聚闭包，就近组织路由、Handler、模型与专属数据迁移，实现**随插随用、按需组合、随拔随走**。
+
+### 2.3 编译期依赖组合 (Compile-Time Composition)
+基于 Go 语言的静态强类型优势，下游项目通过 `app.Use(&MyPlugin{})` 在编译期静态组装，产出单一静态二进制文件，兼具极高运行性能与极低运维分发成本。
+
+---
+
+## 3. 架构全景模型 (Architecture Landscape)
+
+```
+-----------------------------------------------------------------------------------+
+|                        下游业务项目 (Downstream Application)                       |
+|           main.go: app.Use(&logger.Plugin{}).Use(&auth.Plugin{})...               |
+-----------------------------------------------------------------------------------+
+                                         │
+                                         ▼
+-----------------------------------------------------------------------------------+
+|                       Wavelet Core (微内核上下文总线)                              |
+|   - Context (服务树与扩展点总线)          - Lifecycle Manager (生命周期编排)     |
+|   - Service Hub (泛型 IoC 容器)           - EventBus (强类型领域事件总线)        |
+-----------------------------------------------------------------------------------+
+         │                                       │
+         ▼ 注册与驱动                            ▼ 挂载能力
+------------------------------------+  +-------------------------------------------+
+|    运行时驱动插件 (Driver Plugins)  |  |       业务领域插件 (Domain Plugins)       |
+|  - driver-http (Gin Web 引擎)      |  |  - plugin-auth (认证/Session/OAuth)       |
+|  - driver-worker (Asynq 消费池)     |  |  - plugin-user (用户资料/角色权限)        |
+|  - driver-cron (Asynq 定时调度器)  |  |  - plugin-msg-gateway (消息通道与推送)    |
+|  - driver-database (GORM 数据源)   |  |  - plugin-risk-control (访问风控与限流)   |
+|  - driver-cache (RAM/Redis 缓存)   |  |  - [下游自定义插件] (业务私有插件)        |
+------------------------------------+  +-------------------------------------------+
+```
+
+---
+
+## 4. 高并发与分布式演进路线 (Scalability & Microservices Strategy)
+
+```mermaid
+graph LR
+    subgraph Monolith ["阶段 1：单体插件化 (进程内零开销)"]
+        UserP["plugin-user"] -->|Go Interface 内存调用| AuthP["plugin-auth"]
+    end
+
+    subgraph Distributed ["阶段 2：高并发微服务拆分 (透明代理替换)"]
+        UserP2["plugin-user"] -->|相同的 Go Interface| AuthClient["plugin-auth-client (gRPC 代理)"]
+        AuthClient -.->|gRPC / HTTP/2| RemoteAuth["独立 Auth 微服务集群"]
+    end
+```
+
+1. **接口不变性原则 (Contract Immutability)**：跨插件交互全部面向 `core/contracts` 纯接口。微服务拆分时仅需引入 gRPC 客户端插件，调用方业务代码 **0 修改**。
+2. **分布式事件网格 (Event Mesh)**：内存 EventBus 支持无缝升级为 Redis Stream / NATS / Kafka 分布式总线。
+3. **数据分片与独立演进**：每个插件自包含 Goose SQL 迁移与独立表前缀，天然支持主从分库与分库分表。
+
+---
+
+## 5. 核心建设与里程碑 (Milestones)
+
+| 阶段 | 里程碑目标 | 交付物 | 状态 |
+| :--- | :--- | :--- | :--- |
+| **Phase 1** | 微内核 Context 与泛型 IoC 容器 | `core/context.go`, `core/container.go` | ✅ 已完成 (96.2% 单测) |
+| **Phase 2** | 领域扩展点与强类型 EventBus | `core/extpoints/`, `core/events.go` | ✅ 已完成 (97.1% 单测) |
+| **Phase 3** | 运行时驱动插件下沉 (HTTP/Worker/Cron) | `plugins/drivers/*` | ✅ 已完成 (生命周期单测) |
+| **Phase 4** | 基础设施服务插件化 (DB/Cache/Log/Storage) | `plugins/infra/*` | 🟡 构建中 |
+| **Phase 5** | 业务领域模块插件化解耦 (Auth/User/Msg/Admin) | `plugins/domain/*` | ⚪ 待构建 |
+| **Phase 6** | CLI 运行时切面调度与 App 编排器 | `core/app.go`, `cmd/*` | ⚪ 待构建 |
+| **Phase 7** | 下游开发者脚手架与全链路 E2E 验证 | `downstream/*` | ⚪ 待构建 |
+