crud-http

PowerX CRUD HTTP

步骤

1. 打开 本文件内嵌规则。
2. 按规则执行实现/校对。
3. 完成后按核对清单验收。

核对点

• 与 PowerX 当前代码结构、路径与命名一致。
• 仅在传输层/契约层做职责内改动，不跨层越界。

规则（内嵌）

dev_crud_http_guides.md

# 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
}