docs(migration): update docs and skills for new migration architecture

Update all relevant documentation and skills to reflect:
- w_schema_versions shared version table with plugin_id discriminator
- Single 00001_initial.sql per plugin (merged from multi-file approach)
- gooseEngine uses goose.NewProvider with goose.WithStore(sharedStore)
- pkg/migrator deleted, all 26 global SQL files moved to per-plugin
- DDL/DML single-file approach (merged seed + schema)

Files updated:
- .agents/skills/database-migration/SKILL.md (full rewrite)
- docs/WAVELET_WHITE_PAPER.md (table matrix + migration check)
- docs/WAVELET_DEVELOPER_GUIDE.md (scenario 9)
- docs/superpowers/specs/2026-08-27-cordis-plugin-architecture-design.md
- docs/superpowers/specs/2026-08-27-cordis-downstream-developer-guide.md
This commit is contained in:
ryan
2026-08-28 12:45:58 +08:00
parent 9bd012a271
commit 33b38f8687
5 changed files with 193 additions and 36 deletions
+92 -14
View File
@@ -19,8 +19,7 @@ plugins/domain/order/
├── plugin.go
├── models.go
└── migrations/
├── 20260827000001_create_orders_table.sql
└── 20260827000002_add_order_discount_column.sql
└── 00001_initial.sql ← 每个插件仅一个初始迁移文件
```
---
@@ -47,7 +46,9 @@ func (p *Plugin) Apply(ctx *core.Context) error {
}
```
### 步骤 2:编写 Goose SQL 脚本 (`migrations/YYYYMMDDNNNN_name.sql`)
### 步骤 2:编写 Goose SQL 脚本 (`migrations/00001_initial.sql`)
每个插件只需维护一个 `00001_initial.sql`,包含其全部建表语句与种子数据。
```sql
-- +goose Up
@@ -58,10 +59,14 @@ CREATE TABLE IF NOT EXISTS w_orders (
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
updated_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP
);
CREATE INDEX IF NOT EXISTS idx_w_orders_user_id ON w_orders(user_id);
-- 种子数据
INSERT INTO w_orders (id, user_id, amount, status)
VALUES ('init_001', 'system', 0, 'completed')
ON CONFLICT (id) DO NOTHING;
-- +goose StatementEnd
-- +goose Down
@@ -72,39 +77,112 @@ DROP TABLE IF EXISTS w_orders;
---
## 3. 核心设计与防线原则 (Guardrails)
## 3. 版本管理与升级机制
### 3.1 版本表结构
所有插件共享一张 `w_schema_versions` 表,以 `plugin_id` 为区分:
```sql
w_schema_versions (
plugin_id VARCHAR(64) NOT NULL, -- 如 "auth", "user", "admin"
version_id BIGINT NOT NULL, -- 迁移文件版本号 (00001 → 1)
applied_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
PRIMARY KEY (plugin_id, version_id)
)
```
### 3.2 升级判定逻辑
启动时,`gooseEngine` 遍历每个已注册的插件:
```
for each plugin:
1. 查询 w_schema_versions WHERE plugin_id = 'auth'
2. 获取该插件的最大 version_id
3. 读取插件 migration/ 目录下的所有 .sql 文件
4. 如果存在 version_id 更大的文件 → 执行升级
5. 如果全部已应用 → 跳过
```
### 3.3 什么情况下升级?
| 场景 | 例子 | 是否升级 |
|------|------|---------|
| 首次部署,插件第一次运行 | auth 插件,表不存在 | ✅ 执行 `00001_initial.sql` |
| 第二次启动,无变化 | 文件未变,版本已记录 | ❌ 跳过 |
| 追加新迁移文件 | 新增 `00002_add_index.sql` | ✅ 执行 `00002_*` |
| 移除一个插件 | 该插件不再注册 | ❌ 其记录在表中被忽略 |
| 新增一个插件 | 新插件有 `00001_initial.sql` | ✅ 执行 |
### 3.4 查看全局迁移状态
```sql
SELECT * FROM w_schema_versions ORDER BY plugin_id, version_id;
```
输出示例:
```
plugin_id | version_id | applied_at
---------------------+------------+---------------------------
admin | 1 | 2026-08-28 10:00:00+00
auth | 1 | 2026-08-28 10:00:00+00
user | 1 | 2026-08-28 10:00:00+00
upload | 1 | 2026-08-28 10:00:00+00
```
---
## 4. 核心设计与防线原则 (Guardrails)
1. **表单一所有者原则 (Single Owner Principle)**:
- 每张数据表归属且仅归属于一个所有者插件(如 `w_orders` 归 `order` 插件)。
- **严禁**插件 B 跨包编写 SQL 直接读写插件 A 拥有的表;必须通过插件 A 暴露的 `contracts` 接口或事件总线进行交互。
2. **表名前缀规范**:
- 所有表名必须带有前缀(如 `w_orders`、`w_auth_users`),杜绝跨插件表名冲突。
3. **DDL 与 DML 分离**:
- 表结构变更(DDL)与初始数据插入(DML/Seed)必须分成两个独立的递增版本 SQL 文件。
3. **单文件初始迁移**:
- 每个插件只维护一个 `00001_initial.sql`,包含该插件所有表的建表语句与初始种子数据。
- 未来如需追加 DDL,新增 `00002_xxx.sql`,Goose 会根据 `w_schema_versions` 判断增量执行。
4. **禁止物理外键**:
- 关系字段统一显式建立单列或联合索引,禁止在数据库中创建物理外键约束。
5. **双方言兼容性(PostgreSQL & SQLite)**:
- 自增主键:PG 用 `BIGSERIAL`,SQLite 用 `INTEGER PRIMARY KEY AUTOINCREMENT`。
- 时间类型:PG 用 `TIMESTAMPTZ`,SQLite 用 `DATETIME`。
- JSON 类型:PG 用 `JSONB`,SQLite 用 `JSON` 或 `TEXT`。
6. **定时调度插入规范**:
- 若迁移中包含初始定时任务插入(`schedules` 表),绝对不能硬编码 `id`,必须依靠数据库自增分配。
6. **幂等性要求**:
- 所有 `CREATE TABLE` 必须使用 `IF NOT EXISTS`。
- 所有 `INSERT` 种子数据必须使用 `ON CONFLICT DO NOTHING`。
- 所有 `ALTER TABLE ADD COLUMN` 必须使用 `IF NOT EXISTS`(如果数据库方言支持)。
---
## 4. ClickHouse 分析库迁移规则 (辅助 OLAP)
## 5. ClickHouse 分析库迁移规则 (辅助 OLAP)
ClickHouse 作为辅助 OLAP 分析存储,采用独立迁移通道:
- 迁移文件位于专属目录(仅单方言 DDL,不创建 SQLite 镜像)。
- 日志/分析用途表必须同时在关系型主库建回落表并接入 `logstore`。
- 迁移文件位于专属目录 `migrations-clickhouse/`(仅单方言 DDL,不创建 SQLite 镜像)。
- 日志/分析用途表必须同时在关系型主库建回落表并接入 `logstore` 门面。
- 分析表高频写入统一接入 `batchwriter` 进行异步批量刷盘。
---
## 5. 质量与验证门禁
## 6. 质量与验证门禁
```bash
make format
make code-check
go test ./plugins/...
```
验证迁移注册完整性:
```bash
# 检查每个有 migrations/ 目录的插件是否同时有 go:embed + Register()
grep -rn 'go:embed.*migrations' plugins/domain/*/plugin.go plugins/drivers/*/plugin.go
grep -rn 'Migrations()\.Register' plugins/domain/*/plugin.go plugins/drivers/*/plugin.go
```
+34 -8
View File
@@ -222,21 +222,24 @@ func (Order) TableName() string {
package order
import (
"embed"
"github.com/Rain-kl/Wavelet/core"
"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
// 注册本插件的专属迁移(系统启动时自动按版本号执行)
ctx.Migrations().Register("order", orderMigrations)
return nil
}
```
#### SQL 迁移脚本规范 (`plugins/order/migrations/20260827000001_create_orders_table.sql`):
#### SQL 迁移脚本规范 (`plugins/order/migrations/00001_initial.sql`):
每个插件只需维护一个 `00001_initial.sql`,包含该插件的全部建表语句与种子数据。
```sql
-- +goose Up
-- +goose StatementBegin
@@ -246,10 +249,14 @@ CREATE TABLE IF NOT EXISTS w_orders (
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
updated_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP
);
CREATE INDEX IF NOT EXISTS idx_w_orders_user_id ON w_orders(user_id);
-- 种子数据(使用 ON CONFLICT DO NOTHING 保证幂等)
INSERT INTO w_orders (id, user_id, amount, status, created_at, updated_at)
VALUES ('init_001', 'system', 0, 'completed', CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)
ON CONFLICT (id) DO NOTHING;
-- +goose StatementEnd
-- +goose Down
@@ -258,6 +265,25 @@ DROP TABLE IF EXISTS w_orders;
-- +goose StatementEnd
```
#### 版本管理机制
所有插件共享一张 `w_schema_versions` 表,以 `plugin_id` 区分:
```
w_schema_versions (plugin_id, version_id, applied_at)
```
启动时,引擎遍历每个插件:
1. 查询 `w_schema_versions WHERE plugin_id = 'order'` 获取当前最大版本号
2. 扫描插件 `migrations/` 目录下的 `.sql` 文件
3. 如果存在未应用的版本号 → 执行迁移
4. 如果全部已应用 → 跳过
```sql
-- 查看全局迁移状态
SELECT * FROM w_schema_versions ORDER BY plugin_id, version_id;
```
---
### 场景 10:如果有多个业务插件需要读写同一张表怎么办?
+9 -4
View File
@@ -91,7 +91,9 @@ Wavelet 是面向未来 5 年生产级云原生与高并发业务中台的 **微
3. **`core/contracts/` 契约隔离防线 (100% Pass)**:
- 所有跨插件交互严格基于纯 Interface 和 DTO 定义(如 `contracts.DBService`, `contracts.AuthService`, `contracts.UserService`, `contracts.StorageService`),消除了 package 级别的强耦合。
4. **`plugins/` 单所有者原则与数据迁移独立性 (100% Pass)**:
- 每个业务插件自包含专有 `migrations/*.sql`,彻底消除单体大迁移目录合并冲突,杜绝 GORM AutoMigrate。
- 每个业务插件自包含专有 `migrations/00001_initial.sql`,通过 `go:embed` 注册。
- 所有插件共享 `w_schema_versions` 表,以 `plugin_id` 列区分版本,彻底消除单体大迁移目录合并冲突,杜绝 GORM AutoMigrate。
- `pkg/migrator/` 全局迁移目录已物理删除,26 个全局 SQL 文件全部分配至对应插件。
5. **并发与生命周期析构安全 (100% Pass)**:
- 全局遵循 LIFO (后进先出) Disposer 逆序优雅注销机制。在开启 `-race` 竞争检测下,所有事件并发广播、多协程注入与读写均 0 数据竞争。
@@ -136,12 +138,15 @@ Wavelet 是面向未来 5 年生产级云原生与高并发业务中台的 **微
| 数据表 | 唯一所有者插件 | 数据结构与仓储位置 | 跨插件交互方式 |
| :--- | :--- | :--- | :--- |
| `w_users`<br>`w_access_tokens` | `plugins/domain/user` | `models.go`<br>`repository.go` | `core/contracts.UserService`<br>`contracts.UserDTO` |
| `w_auth_sources`<br>`w_external_accounts`<br>`w_passkeys`<br>`w_oauth_states` | `plugins/domain/auth` | `models.go`<br>`repository.go` | `core/contracts.AuthService`<br>`contracts.AuthRegistry` |
| `w_users` | `plugins/domain/user` | `models.go`<br>`repository.go` | `core/contracts.UserService`<br>`contracts.UserDTO` |
| `w_auth_sources`<br>`w_external_accounts`<br>`w_access_tokens` | `plugins/domain/auth` | `models.go`<br>`service.go` | `core/contracts.AuthService`<br>`contracts.AuthRegistry` |
| `w_uploads`<br>`w_upload_stats` | `plugins/domain/upload` | `models/models.go`<br>`repository/repository.go` | `core/contracts.StorageService`<br>`upload.Ingest` 流水线 |
| `w_system_configs`<br>`w_templates` | `plugins/domain/admin` | `models.go`<br>`repository.go` | `ctx.Settings()` / `contracts.ConfigService`<br>Redis Pub/Sub 广播 |
| `w_message_channels`<br>`w_message_bindings`<br>`w_message_pairing_codes`<br>`w_push_events`<br>`w_push_channels`<br>`w_push_histories` | `plugins/domain/message_gateway` | `models.go`<br>`repository.go` | `EventBus` 强类型事件广播订阅 |
| `w_task_executions`<br>`w_schedules` | `plugins/drivers/driver_asynq_*` | `types.go`<br>`schedule.go` | `ctx.Task()` 与 `ctx.Schedule()` 扩展点 |
| `w_user_access_logs` | `plugins/domain/risk_control` | `logstore/` | `logstore` 门面<br>ClickHouse PG/SQLite 回落 |
| `w_schedules` | `plugins/drivers/driver_asynq_cron` | `schedule.go` | `ctx.Schedule()` 扩展点 |
| `w_task_executions` | `plugins/drivers/driver_asynq_worker` | `types.go`<br>`executor.go` | `ctx.Task()` 扩展点 |
| `w_schema_versions` | **系统内部** | `cmd/app.go` sharedStore | 自动管理,不归属于任何插件 |
### 5.3 架构防线与单向依赖保障
1. **测试脚手架绝对解耦**:底层通用的 `pkg/testhelper` 严禁反向引用任何上层业务插件。`testhelper` 维护轻量自包含的测试表脚手架,彻底杜绝包导入循环(Import Cycle)。
@@ -222,21 +222,24 @@ func (Order) TableName() string {
package order
import (
"embed"
"github.com/Rain-kl/Wavelet/core"
"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
// 注册本插件的专属迁移(系统启动时自动按版本号执行)
ctx.Migrations().Register("order", orderMigrations)
return nil
}
```
#### SQL 迁移脚本规范 (`plugins/order/migrations/20260827000001_create_orders_table.sql`):
#### SQL 迁移脚本规范 (`plugins/order/migrations/00001_initial.sql`):
每个插件只需维护一个 `00001_initial.sql`,包含该插件的全部建表语句与种子数据。
```sql
-- +goose Up
-- +goose StatementBegin
@@ -246,10 +249,14 @@ CREATE TABLE IF NOT EXISTS w_orders (
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
updated_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP
);
CREATE INDEX IF NOT EXISTS idx_w_orders_user_id ON w_orders(user_id);
-- 种子数据(使用 ON CONFLICT DO NOTHING 保证幂等)
INSERT INTO w_orders (id, user_id, amount, status, created_at, updated_at)
VALUES ('init_001', 'system', 0, 'completed', CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)
ON CONFLICT (id) DO NOTHING;
-- +goose StatementEnd
-- +goose Down
@@ -258,6 +265,25 @@ DROP TABLE IF EXISTS w_orders;
-- +goose StatementEnd
```
#### 版本管理机制
所有插件共享一张 `w_schema_versions` 表,以 `plugin_id` 区分:
```
w_schema_versions (plugin_id, version_id, applied_at)
```
启动时,引擎遍历每个插件:
1. 查询 `w_schema_versions WHERE plugin_id = 'order'` 获取当前最大版本号
2. 扫描插件 `migrations/` 目录下的 `.sql` 文件
3. 如果存在未应用的版本号 → 执行迁移
4. 如果全部已应用 → 跳过
```sql
-- 查看全局迁移状态
SELECT * FROM w_schema_versions ORDER BY plugin_id, version_id;
```
---
### 场景 10:如果有多个业务插件需要读写同一张表怎么办?
@@ -123,13 +123,30 @@ type RouterExtension interface {
### 4.2 数据迁移扩展 (`ctx.Migrations()`)
每个插件通过 Go 内置 `embed.FS` 打包专属的 Goose SQL 文件,彻底消除单体大迁移目录的合并冲突:
```go
type MigrationExtension interface {
// Register 注册插件专属的 SQL 迁移文件系统
Register(pluginID string, fs embed.FS)
Register(pluginID string, fsys fs.FS, dir ...string)
}
```
**版本隔离机制**:所有插件共享一张 `w_schema_versions` 表,以 `plugin_id` 列区分。运行时引擎(`gooseEngine`)实现 `goosedb.Store` 接口,对该表执行 `plugin_id` 限定的 CRUD 操作,确保各插件的版本互不干扰。
```sql
w_schema_versions (
plugin_id VARCHAR(64) NOT NULL,
version_id BIGINT NOT NULL,
applied_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
PRIMARY KEY (plugin_id, version_id)
)
```
**启动流程**:
1. `ApplyPlugins()` 阶段:各插件调用 `ctx.Migrations().Register("order", embedFS)` 收集迁移
2. `RunMigrations()` 阶段:引擎遍历所有 `entries`,为每个插件创建 `goose.NewProvider(dialect, sqlDB, entry.FS, goose.WithStore(store))`
3. `provider.Up()` 查询 `w_schema_versions WHERE plugin_id = 'order'` 决定版本,执行增量迁移
### 4.3 异步任务与定时调度扩展 (`ctx.Task()` & `ctx.Schedule()`)
```go
type TaskExtension interface {
@@ -211,8 +228,13 @@ CLI 命令仅作为**切面激活器 (Target Selector)**,业务插件无需感
1. App Bootstrap: 加载所有已配置插件并构建 Context
↓
2. Apply Phase: 执行所有 plugin.Apply(ctx),收集路由、任务、调度与迁移
└─ 各插件调用 ctx.Migrations().Register("auth", authMigrations) 等
↓
3. Migration Engine: 统一执行所有已激活插件的 Goose SQL 迁移
3. Migration Engine: 遍历所有 entries,逐插件创建 Goose Provider 执行迁移
└─ 每个插件使用独立的 sharedStore(pluginID),共享同一张 w_schema_versions 表
└─ provider.Up() 检查 w_schema_versions WHERE plugin_id = 'auth'
└─ 未执行过 → 执行 00001_initial.sql → INSERT 版本记录
└─ 已执行过 → 跳过
↓
4. Profile Dispatch:
- "api": 激活 DriverTypeHTTP 驱动 (Gin.ListenAndServe)