refactor(repository): 收敛 model/repository 分层为唯一持久化入口

将 OpenFlare 与平台业务的数据访问从 model 与 apps 直连迁入 repository，
model 仅保留实体与无 IO 规则；补充 code-check 架构守卫与开发规范。

docs/changelog/index.md

@@ -22,6 +22,12 @@ sidebar: false
 
 ## [unreleased]
 
+### 改进
+
+- 统一数据访问分层：业务持久化经 `internal/repository`，`internal/model` 仅保留实体与无 IO 领域规则，避免双轨 CRUD 与职责混淆。
+- 构建检查增加 `internal/model` 禁止直接访问数据库/Redis 的架构守卫，并收敛 model 与 repository 的错误文案定义边界。
+
+
 ## [v3.4.3] - 2026-07-24
 
 ### 新增

docs/design/index.md

@@ -94,9 +94,9 @@ OpenFlare 已收敛为**单 monorepo**（Go 模块 `github.com/Rain-kl/Wavelet`
 | `internal/apps/openflare/` | OpenFlare 控制面业务域（`routers.go` + `logics.go`） |
 | `internal/apps/{admin,user,oauth,upload,cap,...}/` | Wavelet 平台能力（用户、认证、任务、推送等） |
 | `internal/apps/openflare/{agent,relay,flared}/` | **Server 侧**边缘协议处理器（鉴权、心跳、WS） |
-| `internal/model/` | GORM 实体（`openflare_*.go` + 平台模型） |
+| `internal/model/` | GORM 实体 / DTO / 无 IO 领域规则（`openflare_*.go` + 平台模型）；**不含** DB 访问 |
 | `internal/infra/persistence/migrator/goose/` | goose SQL 迁移（PostgreSQL / SQLite / ClickHouse） |
-| `internal/repository/` | 平台域数据访问层 |
+| `internal/repository/` | 数据访问层（平台 + OpenFlare 业务 CRUD、缓存、ClickHouse 分析读写）；**唯一**持久化入口 |
 | `internal/infra/task/` | Asynq 异步任务（Worker + Scheduler） |
 | `internal/infra/config/` | Viper 配置加载 |
 | `internal/shared/` | 统一 API 响应封装（`response/`） |

docs/plan/20260724-model-repository-layering.md

@@ -0,0 +1,44 @@
+# model / repository 分层治理
+
+说明：将 `internal/model` 收敛为无 IO 实体层，`internal/repository` 作为唯一持久化入口。
+
+---
+
+## 1. 目标与背景 (Goal & Context)
+
+* **需求背景**：已提交的 AGENTS 曾允许 model 直接使用 GORM，导致 OpenFlare 业务 CRUD 与平台 repository 双轨并存。工作区目标分层与代码不一致，接手成本高。
+* **开发范围 (Scope)**：
+  * 固化规范：`model` 仅实体 / DTO / 无 IO 规则；`repository` 唯一持久化入口。
+  * 将 `internal/model` 中现有 `db.DB` / Redis / ClickHouse store 适配迁入 `internal/repository`。
+  * 全量更新 call site：`model.Get/List/Create…` → `repository.…`。
+  * 编译通过 + `make format` + 相关单测。
+* **Out of Scope**：不改表结构、不改 API 契约、不做业务行为变更；不强制一次重写所有测试风格。
+
+## 2. 设计与决策
+
+* **分层**：
+  * `apps → repository → model`
+  * `repository → infra/persistence`（及 `repository/analytics`）
+  * **禁止** `model → repository`、**禁止** model 内 `db.DB` / Redis / ClickHouse
+* **迁移策略**：按文件拆分 package-level IO 函数至同名 `repository` 文件；类型与纯函数留在 model；store 适配整文件迁入 repository。
+* **命名**：repository 函数保持原导出名，降低 call site 改动面。
+
+## 3. 具体修改文件清单
+
+### 规范
+
+* #### [MODIFY] `AGENTS.md`
+* #### [MODIFY] `docs/design/index.md`
+* #### [MODIFY] `docs/plan/index.md`（登记本计划）
+
+### 后端
+
+* #### [MODIFY] `internal/model/*.go`（剥离 IO）
+* #### [NEW/MODIFY] `internal/repository/*.go`（承接 CRUD / store）
+* #### [MODIFY] `internal/apps/**`、`internal/infra/task/**` 等 call site
+
+## 4. 验证计划
+
+* `go test ./internal/model/... ./internal/repository/...`
+* 关键包 `go build ./...`
+* `make format` / `make code-check`（在可接受时间内）

docs/plan/index.md

@@ -24,6 +24,8 @@
 
 ## 已完成的计划
 
+* [model / repository 分层治理](./20260724-model-repository-layering.md)：model 无 IO；repository 唯一持久化；已完成 OpenFlare/平台 CRUD 迁入 repository。
+
 * [Pages 项目部署源与 GitHub Releases 自动更新 V2](./20260719-pages-source-sync-v2.md)：已完成 Remote URL / GitHub Release 来源、不可变部署、自动检查更新与安全回滚，并预留独立仓库构建 Provider 边界；生产环境验收边界见计划内验证记录。
 
 ## 使用建议