Menu
PowerX CRUD HTTP 开发规范（管理端路由、绑定、错误桥接、多租户）。
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
PowerX API 命名与访问规范（/api/v1、/admin、/internal 边界）。
PowerX 底座 Capability 治理与发布准入规则。用于审计 REST/OpenAPI/gRPC/Gin 生成的能力候选、正式 platform_capabilities 目录、Capability Registry 登记、agent_usable/permission_code/risk_level 元数据、ignore 清单和缺失能力；当用户要求“重新识别能力”“能力是否能发布”“补齐能力登记”“检查 capability-gen/audit/check”“底座接口暴露给插件/agent”时使用。
PowerX STS 与插件鉴权规范（Exchange、KeyRing、拦截器、审计）。
PowerX REST 契约规则（资源命名、分页、错误、版本化）。
PowerX CRUD 依赖注入规则（Deps 单入口、构造注入、跨传输复用）。
PowerX CRUD DTO 规则（输入输出分离、分页、校验）。
| name | crud-http |
| description | PowerX CRUD HTTP 开发规范（管理端路由、绑定、错误桥接、多租户）。 |
本文件内嵌规则。# PowerX 开发规范入口（Dev Guides）
> 本文档是 PowerX 的统一开发规范入口。
>
> - 人类可阅读：开发与评审统一看这里。
> - 工具可扩展：未来可被 `/plan` 与 `/tasks` 解析成可验证规则。
---
## 1. 目的与范围（Scope）
本规范适用于所有 PowerX 核心与插件模块中涉及 **CRUD 能力** 的后端开发，
包括但不限于以下层次：
- 迁移（Migration）
- GORM 模型（Model）
- Repository（仓库层，含 BaseRepository）
- Service（业务服务层）
- DTO（入参/出参）
- Handler（HTTP 层）
- 依赖注入（DI）
- 路由（Routes）
- 契约 / 集成测试（Tests）
---
## 2. 全局策略（Policies）
- **数据库**：统一使用 **GORM 抽象**，默认 **Postgres**。
不允许写死 MySQL 方言或独立 SQL 文件；索引与唯一约束以 GORM tag 或迁移注册为准。
- **HTTP 路由**：统一前缀 `/api/v1/admin/**`（可配置）。
- **多租户**：所有查询与写入都必须携带 `tenant_id`。
- **审计**：所有写操作（Create/Update/Delete/Presign）必须记录审计日志。
- **安全**：预签名链接仅允许受管路径、受限方法（GET/PUT）与 MIME 白名单。
- **依赖注入**：所有仓库与服务实例必须由 `internal/app/shared/deps.go` 统一注册。
---
## 3. 层次结构（Layer Overview）
```plaintext
Model → Repository → Service → Handler → Router
↘ DI(shared) ↙
```
---
## 4. Migration（迁移）
### 约定
- **统一入口**：`cmd/database/migrate.go`
由该入口统筹调用各模块的迁移函数。
- **两种迁移模式**
1. **独立 Server 模块（如 Agent）**：在 `cmd/database/migrate.go` 内实现 `MigrateAgentModels(db *gorm.DB) error`，仅使用 `db.AutoMigrate(...)` 注册模型。
2. **CoreX 内核模块（如 MediaX）**：在 `pkg/corex/db/migration.go` 内实现 `MigrateCoreModels(db *gorm.DB) error`，由其中**直接调用 `AutoMigrate`** 将核心模型（含 MediaX）纳入迁移。
- **不交付任何 `.sql` 文件**，迁移中禁止手写 `db.Exec(...)`。
- **索引/唯一约束**：一律在 **GORM 模型结构体标签**中声明（含唯一索引、GIN 索引、部分索引等）。
- **运行期校验（可选）**：如需校验可用 `db.Migrator().HasIndex()` / `HasConstraint()`，但**不得因此写原生 SQL**。
- **错误处理**：所有迁移函数必须返回 `error`，并在统一入口串联调用。
---
### 示例
#### A. 独立 Server 模块（Agent）
> 在 `cmd/database/migrate.go` 内直接定义并调用：
```go
// cmd/database/migrate.go
package main
import (
"log"
"gorm.io/gorm"
dbmodel "github.com/your/module/internal/server/agent/persistence/model"
)
func MigrateAgentModels(db *gorm.DB) error {
if err := db.AutoMigrate(
&dbmodel.Agent{},
&dbmodel.AgentSetting{},
); err != nil {
return err
}
// 可选：运行期校验（不写 SQL）
if ok := db.Migrator().HasIndex(&dbmodel.Agent{}, "agent_uniq_tenant"); !ok {
log.Println("warn: agent_uniq_tenant not created")
}
return nil
}
func main() {
// init db ...
// 串联调用（示例）
if err := MigrateCoreModels(db); err != nil { log.Fatal(err) }
if err := MigrateAgentModels(db); err != nil { log.Fatal(err) }
}
```
#### B. CoreX 内核模块（含 MediaX）
> 在 `pkg/corex/db/migration.go` 中集中维护 CoreX 的模型清单（例如 MediaX）并 **只用 `AutoMigrate`**：
```go
// pkg/corex/db/migration.go
package corexdb
import (
"gorm.io/gorm"
mediamodel "github.com/your/module/pkg/corex/db/persistence/model/media"
// 其他 CoreX 内核模型...
)
func MigrateCoreModels(db *gorm.DB) error {
return db.AutoMigrate(
&mediamodel.MediaAsset{},
// &mediamodel.MediaSet{}, // 如有
// 其他 CoreX 内核模型...
)
}
```
> 说明：
>
> - **MediaX 等内核能力**作为 CoreX 的一部分，统一纳入 `MigrateCoreModels`；
> - 索引/约束通过模型标签自动创建（如 `unique`、`using:gin`、`where:deleted_at IS NULL` 等）；
> - 不再需要也不建议为 MediaX 再单独写 `MigrateMediaModels`。
### 示例
```go
func MigrateAgentModels(db *gorm.DB) error {
db.AutoMigrate(
&dbmodel.Agent{},
&dbmodel.AgentSetting{},
)
if ok := db.Migrator().HasIndex(&dbmodel.Agent{}, "agent_uniq_tenant"); !ok {
log.Println("warn: agent_uniq_tenant not created")
}
return nil
}
```
### 验收要点
- [ ] 模块定义独立的 `Migrate<Module>Models(db *gorm.DB)` 函数
- [ ] 模型通过 `db.AutoMigrate()` 注册，无需 .sql 文件
- [ ] 索引与唯一约束在 GORM 模型 tag 中声明
- [ ] （可选）运行期校验索引 `db.Migrator().HasIndex()`
- [ ] 迁移函数返回 `error` 并在顶层入口统一调用
---
## 5. Model（GORM 模型）
### 约定
- 模型统一基于 **PowerX Base Model**：
- `PowerModel`：自增整型主键；
- `PowerUUIDModel`：双主键（UUID + 自增 ID），在 `BeforeCreate()` 自动生成 UUID。
- 必须显式声明：
- `CreatedAt` / `UpdatedAt` / `DeletedAt`；
- 表名函数 `TableName()` 与 `GetTableName()`；
- 多租户字段：`TenantID uint64`；
- Schema 默认由 `PowerXSchema` 控制；
- 表名常量集中在 `tables.go`；
- JSON 字段使用 `datatypes.JSON`；
- 唯一/复合索引通过 GORM tag 定义；
- 状态字段统一命名 `Status`，默认值 1；
- 模型文件放在 `pkg/corex/db/persistence/model/<domain>/`。
### 示例
```go
type User struct {
model.PowerUUIDModel
Email string `gorm:"column:email;uniqueIndex:uk_user_email"`
DisplayName string `gorm:"type:varchar(128)"`
Meta datatypes.JSON `gorm:"type:jsonb;default:'{}'"`
DeletedAt gorm.DeletedAt `gorm:"index"`
}
func (u *User) TableName() string {
return model.PowerXSchema + "." + model.TableIAMUser
}
```
### 验收要点
- [ ] 模型嵌入 `PowerModel` 或 `PowerUUIDModel`
- [ ] 含软删字段 `DeletedAt` 并建索引
- [ ] 含租户字段 `TenantID`
- [ ] JSONB 字段正确定义
- [ ] 表名函数返回 `${schema}.${table}`
- [ ] 索引通过 GORM tag 定义
- [ ] 状态字段默认 1
- [ ] 模型对应迁移函数已注册
---
## 6. Repository（仓库层）
### 约定
- 所有仓库组合 `BaseRepository[T]`；
- 所有方法均接收 `context.Context`；
- 写操作返回 `error`；
- 禁止直接操作 DB 或外部 IO；
- 唯一冲突用 `IsUniqueViolation()`；
- 在 `deps.go` 统一注册。
### 示例
```go
type UserRepository struct {
*repository.BaseRepository[dbm.User]
db *gorm.DB
}
func NewUserRepository(db *gorm.DB) *UserRepository {
return &UserRepository{
BaseRepository: repository.NewBaseRepository[dbm.User](db),
db: db,
}
}
```
### 验收要点
- [ ] 组合 `BaseRepository[T]`
- [ ] 构造函数 `New<ModelName>Repository` 存在
- [ ] 方法首参为 `context.Context`
- [ ] 写操作返回 `error`
- [ ] 在 `deps.go` 注册
- [ ] 不含外部 IO 操作
---
## 7. Service（业务服务层）
### 设计原则
Service 层负责 **业务用例编排、鉴权、事务、审计**。
所有数据库操作必须通过 Repository 完成，不得直接调用 GORM 原语或访问外部 IO。
### 约定
- 命名：`<ModelName>Service`；
- 构造函数：`New<ModelName>Service(db *gorm.DB, …)`；
- 首参 `context.Context`；
- 组合 `*BaseService`；
- 统一在 `deps.go` 注册；
- 写操作必须事务化并记录审计；
- 业务错误集中定义于 `internal/service/errors.go`；
- 更新走白名单更新；
- 删除默认软删，硬删需显式授权；
- 错误包装统一。
### 验收要点
- [ ] 组合 `*BaseService`
- [ ] 构造函数存在
- [ ] 方法首参 `context.Context`
- [ ] 不直接访问 DB
- [ ] 写操作包裹事务与审计
- [ ] 删除默认软删，Force 硬删需权限
- [ ] 错误集中定义
- [ ] 已在 `deps.go` 注册
---
## 8. DTO & Validation（数据传输与校验）
### 统一响应与分页
- 成功/失败结构：`ResponseSuccess`、`ResponseError`、`ResponseList`；
- 分页结构：`PaginationRequest`, `PaginationResponse`。
### 参数绑定与校验
- 使用 `ValidateRequestWithContext(c, req)`；
- DTO 字段带 `validate` 标签；
- 校验失败返回统一结构。
### 错误桥接
- 统一错误结构：`AppError{HTTPCode, Message, Details}`；
- 桥接方法：`RespondErrorFrom(c, err)`，成功时直接使用 `ResponseSuccess/ResponseList`，**不得再使用 `MustOK`**。
### SSE / WS
- 事件名统一：`start/intent/plan/token/data/action/final/end/error/heartbeat`；
- SSE 写入：`WriteToSSE(c, flowID, execID, sr, heartbeat)`；
- WS 信封：`WSEnvelope{Type, Data, Timestamp}`。
### 验收要点
- [ ] DTO 独立定义，不复用模型；
- [ ] 参数绑定使用统一函数；
- [ ] 响应结构统一；
- [ ] 错误使用 AppError；
- [ ] 流式接口事件名统一；
---
## 9. Handler & Routes（HTTP）
### 目录结构
```bash
internal/transport/http/
admin/<domain>/
api.go # 路由注册
<feature>_handler.go # 纯 Handler：绑定/校验/DTO映射/调用Service/统一回包
```
### 路由示例
```go
func RegisterMediaRoutes(rg *gin.RouterGroup, deps *shared.Deps) {
h := NewMediaHandler(deps.MediaService)
g := rg.Group("/media/assets")
{
g.POST("", h.Create)
g.GET("", h.List)
g.GET("/:id", h.Get)
g.PATCH("/:id", h.Update)
g.DELETE("/:id", h.Delete)
}
}
```
### 验收要点
- [ ] `api.go` 只注册路由；
- [ ] Handler 只做绑定/校验/调用 Service；
- [ ] 使用统一回包函数；
- [ ] 前缀 `/api/v1/admin`；
- [ ] 动词与路径符合 REST 语义；
- [ ] 契约测试覆盖 CRUD。
---
## 10. Dependency Injection（依赖注入）
### 约定
- 所有依赖集中在 `internal/app/shared/deps.go`；
- 统一构造函数 `NewDeps(db, opts)`；
- 所有服务在 `Deps` 结构体中注册；
- Handler 层通过 `*shared.Deps` 访问；
- 不在模块中重复创建连接；
- Audit 与 Auth 统一实例。
### 验收要点
- [ ] 所有依赖集中初始化；
- [ ] Handler 统一接收 `*shared.Deps`；
- [ ] Service 不自行创建连接；
- [ ] Audit 回调注册成功；
- [ ] 新模块扩展遵循 Deps + Options 模式。
---
## 11. API 契约（REST）
### 路径与版本
- 管理后台：`/api/v1/admin`
- 开放接口：`/api/v1/open`
- Web 前台：`/api/v1/web`
- URL 版本化策略，破坏性变更才升级。
### 错误与分页
- 统一错误结构：`{ code, message, details?, request_id }`；
- 状态码：400/401/403/404/409/429/500；
- 分页响应带 `pagination{total,page,pageSize,pages}`。
### 验收要点
- [ ] API 路径与版本规范；
- [ ] 错误结构统一；
- [ ] 分页字段完整；
- [ ] 幂等与权限策略明确；
- [ ] SSE/WS 事件一致。
---
## 12. 测试（Contracts & Integration）
### 约定
- 契约测试覆盖鉴权/分页/筛选/软删；
- 集成测试覆盖完整业务流；
- 使用 `httptest`；
- 模拟外部依赖可使用 mock。
### 验收要点
- [ ] 契约测试完整；
- [ ] 集成测试覆盖 CRUD；
- [ ] 测试使用 httptest；
- [ ] mock 外部依赖。
---
## 13. 附录：文件结构参考
```
pkg/corex/db/persistence/model/<feature>/
pkg/corex/db/persistence/repository/<feature>/
internal/service/<feature>/
internal/transport/http/admin/<feature>/
internal/app/shared/deps.go
specs/<domain>/<feature>/ # 功能规格与规划 (spec.md / plan.md / tasks.md)
```