仓库自包含化：Docker/CI/文档/规范入库，路由分组拆分

.trellis/spec/backend/concurrency.md

@@ -0,0 +1,29 @@
+# 并发规范
+
+> Go 后端并发约定。
+
+- 每个 goroutine 必须有明确退出路径:外部用 `context.Context` 或 stop channel 通知,内部 `select` 响应;禁止 fire-and-forget,不允许 goroutine 泄漏。
+- 调用方能等待 goroutine 退出:`sync.WaitGroup` 或 `done` channel。
+- `init()` 中不启动 goroutine、不做 IO。
+- channel 容量只用 0 或 1,更大缓冲须注释说明理由。
+- 涉及阻塞或远程调用的函数第一个参数是 `ctx context.Context`,不把 ctx 存进 struct。
+
+## 模式:服务级后台 goroutine 的落地形态(2026-07 起为既定写法)
+
+面板内「异步旁路」(通知发送 `Notifier.SendAsync`、日志异步落库 `SystemLogService.Record`、定期清理 `StartCleanup`)统一三件套:
+
+```go
+s.wg.Add(1)
+go func() {
+    defer s.wg.Done()
+    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) // 自带超时,不复用请求 ctx
+    defer cancel()
+    if err := s.doWork(ctx); err != nil {
+        log.Printf("xxx: %v", err) // 旁路失败只记日志,绝不影响主流程
+    }
+}()
+```
+
+- 服务暴露 `Wait()`(内部 `wg.Wait()`);常驻循环(如清理 ticker)额外接收 ctx,`select` 响应退出。
+- cmd/server 装配的 defer 顺序必须是「先停生产者、再等消费者」(LIFO):`defer notifier.Wait()` / `defer systemLogs.Wait()` 写在 `defer tasks.Stop()` / `defer stopCleanup()` **之前**。
+- 陷阱:`cron.Stop()` 返回的 context 要等(`<-s.cron.Stop().Done()`),否则仍在执行的任务尚未 `wg.Add` 时 `Wait()` 会提前返回,goroutine 泄漏且违反 WaitGroup 的 Add/Wait happens-before 约束。

.trellis/spec/backend/database-guidelines.md

@@ -0,0 +1,68 @@
+# Database Guidelines
+
+> Database patterns and conventions for this project.
+
+---
+
+## Overview
+
+<!--
+Document your project's database conventions here.
+
+Questions to answer:
+- What ORM/query library do you use?
+- How are migrations managed?
+- What are the naming conventions for tables/columns?
+- How do you handle transactions?
+-->
+
+(To be filled by the team)
+
+---
+
+## Query Patterns
+
+<!-- How should queries be written? Batch operations? -->
+
+(To be filled by the team)
+
+---
+
+## Migrations
+
+<!-- How to create and run migrations -->
+
+(To be filled by the team)
+
+---
+
+## Naming Conventions
+
+<!-- Table names, column names, index names -->
+
+(To be filled by the team)
+
+---
+
+## Common Mistakes
+
+<!-- Database-related mistakes your team has made -->
+
+### Common Mistake: gorm 读 NULL 列到已有值的结构体字段不会清零
+
+**Symptom**:UPDATE 把可空列(如 `*time.Time`)写成 NULL 后,用**同一个结构体变量**再次 `First()` 读回,该字段仍是旧值;而新变量读取正常。断言/返回值出现「幽灵旧值」。
+
+**Cause**:gorm Scan 遇到 NULL 列时跳过赋值(保持字段现状),不会主动置 nil。复用变量(循环内重读、更新后回读同一 &ch)时旧值残留。
+
+**Fix**:更新后回读一律用新变量(`var fresh model.X; db.First(&fresh, id)`)。
+
+**Prevention**:凡「UPDATE 后回读返回」的服务方法,都声明新变量接收;测试中多次 `First` 同一行也各用独立变量。另:map Updates 写 NULL 用 `gorm.Expr("NULL")` 最稳(无类型 `nil` 在部分路径下不生效)。
+
+### Common Mistake: 需要"条件更新多列含 NULL"时的写法
+
+```go
+// 正确:零写库条件 + 显式 NULL
+db.Model(&model.AiChannel{}).
+    Where("id = ? AND (fail_count > 0 OR disabled_until IS NOT NULL)", id).
+    Updates(map[string]any{"fail_count": 0, "disabled_until": gorm.Expr("NULL")})
+```

.trellis/spec/backend/directory-structure.md

@@ -0,0 +1,32 @@
+# 后端目录结构
+
+> Go 后端工程的目录职责与代码组织约定。
+
+## 目录职责
+
+```text
+oci-portal/
+├── go.mod              模块名 oci-portal,依赖 oracle/oci-go-sdk/v65
+├── go.sum
+├── cmd/
+│   └── server/         启动入口 main.go
+└── internal/
+    ├── api/            HTTP 路由、参数绑定、响应、中间件
+    ├── config/         环境变量读取
+    ├── crypto/         敏感字段 AES-GCM 加解密
+    ├── database/       SQLite 连接和 AutoMigrate
+    ├── model/          GORM 数据模型
+    ├── oci/            OCI SDK 封装,真实云请求只出现在此包
+    └── service/        业务逻辑和本地快照同步
+```
+
+已实现:API Key 导入(ini 原文或显式字段)、测活(Identity GetTenancy)、账户类别判定(Organizations CLOUDCM 订阅)、重新测活时的快照差异同步。
+
+## 代码组织约定
+
+- 布局遵循官方约定:入口在 `cmd/<binary>/main.go`,非导出实现放 `internal/`(出现对外复用库时才建 `pkg/`),不过度分层。
+- 接口定义在使用方包中;先有第二个实现或测试替身需求,再抽接口。
+- 用 guard clause 尽早 return,减少嵌套。
+- `defer` 紧跟资源获取语句,成对管理释放。
+- 结构体初始化写字段名;已知容量的 slice/map 用 `make(T, 0, n)` 预分配。
+- 注释解释"为什么"而非"是什么";导出符号写以名字开头的 godoc 注释。

.trellis/spec/backend/error-handling.md

@@ -0,0 +1,33 @@
+# 错误处理规范
+
+> Go 后端错误处理约定。
+
+- error 向上返回并用 `fmt.Errorf("...: %w", err)` 附加上下文,不吞错。
+- 一个错误只处理一次:要么就地处理(重试、降级),要么包装返回;不要既打日志又返回。
+- 包装消息描述当前操作(如 `load oci config`),不堆叠 `failed to` 前缀。
+- 需要调用方区分的错误用 sentinel(`errors.Is`)或自定义类型(`errors.As`),不比对错误字符串。
+- 正常流程不使用 `panic`;类型断言一律 `v, ok := x.(T)` 双返回值形式。
+
+## 禁止:让错误消息携带敏感信息外流
+
+**问题**:错误消息会流向后端日志与 HTTP 响应(respondError),其中可能嵌着凭据。典型案例:`http.Client.Do` 失败返回 `*url.Error`,其 `Error()` 拼出**完整请求 URL**——对 Telegram 这类把 token 放路径的 API(`/bot<token>/sendMessage`),token 直接进日志和接口响应。
+
+```go
+// 错误:url.Error 原样外传,token 泄漏
+resp, err := c.Do(req)
+if err != nil {
+    return fmt.Errorf("send telegram message: %w", err)
+}
+
+// 正确:剥掉含 URL 的外壳,只保留底层原因(保持 %w 链)
+if err != nil {
+    return fmt.Errorf("send telegram message: %w", sanitizeURLError(err))
+}
+func sanitizeURLError(err error) error {
+    var ue *url.Error
+    if errors.As(err, &ue) { return ue.Err }
+    return err
+}
+```
+
+**预防**:凡外发 HTTP 且 URL/头中含凭据(token、签名、secret 路径段)的客户端,错误必须先脱敏再包装;新增此类客户端时补一条「错误不含凭据」的回归测试(参照 internal/service/notify_test.go 的 TestNotifierSendErrorHidesToken)。

.trellis/spec/backend/index.md

@@ -0,0 +1,57 @@
+# Backend Development Guidelines(oci-portal 后端规范)
+
+> Go 后端(`oci-portal/`)编码规范入口。规范提炼自 Google / Uber Go Style Guide、Effective Go 与 Go 官方模块布局指南,按本项目裁剪;条目与项目约定冲突时,以本 spec 为准。迁自 docs/开发指南.md 与根目录 AGENTS.md(2026-07)。
+
+---
+
+## 技术栈约束
+
+Gin + GORM + SQLite(纯 Go 驱动 `glebarez/sqlite`,免 CGO;默认与推荐)+ AES-GCM 字段加密 + `oracle/oci-go-sdk/v65`;JWT + bcrypt 用于登录。可选 MySQL / PostgreSQL(`DB_DRIVER`/`DB_DSN`,纯 Go 驱动,experimental);模型新增长文本字段时注意 MySQL 映射:确定 <64KB 用 `type:text`,可能超 64KB 用 `size:16777216`(→MEDIUMTEXT),短字段走 DefaultStringSize=512。**不引入 Redis**,单实例部署按需用进程内缓存;SQLite 快照承担"最近一次云端状态"。前端产物经 `internal/webui` go:embed 嵌入,来源为前端仓库 Release 的 `dist.zip`(release.yml 自动下载;本地构建方式见 README)。选型理由与本地运行方式(环境变量等)见 `docs/开发指南.md`。
+
+---
+
+## Guidelines Index
+
+| Guide | 内容 | 状态 |
+|-------|------|------|
+| [Directory Structure](./directory-structure.md) | 目录职责与代码组织约定 | 已填 |
+| [Error Handling](./error-handling.md) | 错误包装、传播与 panic 纪律 | 已填 |
+| [Quality Guidelines](./quality-guidelines.md) | 工具链检查与命名规范 | 已填 |
+| [Concurrency](./concurrency.md) | goroutine 生命周期与 context 传递 | 已填 |
+| [Testing](./testing.md) | table-driven 测试要求 | 已填 |
+| [Database Guidelines](./database-guidelines.md) | ORM 模式、查询、迁移 | 待填 |
+| [Logging Guidelines](./logging-guidelines.md) | 结构化日志、日志级别 | 待填 |
+
+---
+
+## Pre-Development Checklist
+
+写代码前确认:
+
+- [ ] 读过 [Directory Structure](./directory-structure.md),新代码放对了包(云请求只出现在 `internal/oci/`)
+- [ ] 阻塞 / 远程调用函数第一个参数是 `ctx context.Context`(见 [Concurrency](./concurrency.md))
+- [ ] 错误按 [Error Handling](./error-handling.md) 用 `%w` 包装向上返回
+- [ ] 复用已有封装,不重复造轮子(见 `../guides/code-reuse-thinking-guide.md`)
+
+## Quality Check
+
+提交前必过:
+
+```bash
+gofmt -l . && goimports -l .   # 格式(或由编辑器保存时完成)
+go vet ./...
+go test ./...
+go mod tidy                     # 依赖有变更时
+```
+
+有 `golangci-lint` 配置时以其为准。新逻辑必须带 table-driven 测试,`go test ./...` 全绿才算完成。
+
+## API 文档(swagger)
+
+全部 HTTP 接口带 swaggo 注释(@Summary 中文/@Tags 按域/@Param/@Success/@Router;JWT 组接口标 @Security BearerAuth)。**新增或修改接口必须同步注释**,并重新生成 spec:
+
+```bash
+go tool swag init -g cmd/server/main.go -o docs --parseInternal --parseDependency
+```
+
+生成的 `docs/` 一并提交;UI 由 `SWAGGER=1` 开启(/swagger/index.html)。同名 handler 方法(list/create/get/update/remove)分布在多个 struct 上,写注释时确认 @Router 路径与该 receiver 的真实注册一致(routes_*.go)。

.trellis/spec/backend/logging-guidelines.md

@@ -0,0 +1,51 @@
+# Logging Guidelines
+
+> How logging is done in this project.
+
+---
+
+## Overview
+
+<!--
+Document your project's logging conventions here.
+
+Questions to answer:
+- What logging library do you use?
+- What are the log levels and when to use each?
+- What should be logged?
+- What should NOT be logged (PII, secrets)?
+-->
+
+(To be filled by the team)
+
+---
+
+## Log Levels
+
+<!-- When to use each level: debug, info, warn, error -->
+
+(To be filled by the team)
+
+---
+
+## Structured Logging
+
+<!-- Log format, required fields -->
+
+(To be filled by the team)
+
+---
+
+## What to Log
+
+<!-- Important events to log -->
+
+(To be filled by the team)
+
+---
+
+## What NOT to Log
+
+<!-- Sensitive data, PII, secrets -->
+
+(To be filled by the team)

.trellis/spec/backend/quality-guidelines.md

@@ -0,0 +1,18 @@
+# 质量与命名规范
+
+> Go 后端工具链检查与命名约定。
+
+## 工具链(提交前必过)
+
+- 提交前必须通过 `gofmt`/`goimports`、`go vet ./...`、`go test ./...`。
+- 仓库有 `golangci-lint` 配置时以其为准。
+- 依赖变更后运行 `go mod tidy`,`go.mod` 与 `go.sum` 一起提交。
+
+## 命名
+
+- 一律 MixedCaps,不用下划线;缩写词大小写保持一致:`ociConfigID`、`ParseURL`、`HTTPClient`。
+- 包名小写单个词,不用 `util`、`common`、`base` 这类空泛名。
+- 变量名长度与作用域成正比:循环变量可用 `i`、`c`,包级变量用完整单词。
+- Getter 不加 `Get` 前缀:`user.Name()` 而非 `user.GetName()`。
+- 方法接收者 1~2 个字母且同一类型内保持一致,如 `func (s *InstanceService)`。
+- 错误变量:导出 sentinel 用 `ErrXxx`,包内用 `errXxx`;自定义错误类型以 `Error` 结尾。

.trellis/spec/backend/testing.md

@@ -0,0 +1,23 @@
+# 测试规范
+
+> Go 后端测试约定。
+
+- 新逻辑配 table-driven 测试,用例含名字、输入、期望值;`go test ./...` 全绿才算完成。
+- 断言失败时输出 `got/want` 对比,便于定位。
+- 辅助函数标注 `t.Helper()`,清理动作用 `t.Cleanup()`。
+
+## 常见坑:`:memory:` SQLite 每个连接是独立库
+
+**症状**:被测代码里有异步 goroutine 写库(如日志异步落库)时,测试偶发 `no such table: xxx`。
+
+**原因**:glebarez/sqlite 的 `:memory:` 数据库按连接隔离;GORM 连接池为新 goroutine 开新连接时,拿到的是一个没跑过 AutoMigrate 的空库。
+
+**修复**:测试 helper 建库后锁单连接,生产文件库不受影响:
+
+```go
+sqlDB, _ := db.DB()
+sqlDB.SetMaxOpenConns(1) // :memory: 每连接独立库,异步写复用同一连接
+```
+
+**预防**:测试涉及「后台 goroutine 写库」时一律加此设置(参照 internal/api/router_test.go 与 internal/service 各测试 helper);异步写路径同时拆出同步内核函数(如 `record` / `Record`)供测试直调断言。
+