Reorganize repo: backend/, deploy/, docs/ layout + AGENTS.md

Restructure the monorepo into clear top-level directories:
- backend/: Go module root (cmd, internal, pkg, configs, migrations,
  docs/swagger, scripts, tests, go.mod, Makefile, .air.toml)
- deploy/: Docker (Dockerfile, docker-compose*), quickstart, fluentd
- docs/: project documentation + reports/ (moved from repo root)
- AGENTS.md: new AI coding-agent guide at repo root

Update all references to the new layout:
- Dockerfile: COPY backend/go.mod, COPY backend/ (context = repo root)
- docker-compose files: context ../.., dockerfile deploy/docker/Dockerfile,
  env_file ../../.env, volume mounts ../../backend:/app
- deploy/quickstart/compose.yaml: dockerfile deploy/docker/Dockerfile
- CI: working-directory: backend for go commands, file deploy/docker/Dockerfile,
  coverage path backend/coverage.out, health_check backend/scripts/
- backend/Makefile: docker target uses -f ../deploy/docker/Dockerfile ../
- README: architecture tree, quickstart, config paths updated

Move root stray scripts (rename_models.*, run_m11_tests.sh, verify_build.sh,
gorm_bool_main.go) to backend/scripts/legacy/. All moves via git mv to
preserve history. Build, vet, SQLite tests, and docker compose config verified.

.github/workflows/ci.yml

@@ -55,13 +55,16 @@ jobs:
         uses: golangci/golangci-lint-action@v6
         with:
           version: v1.64
+          working-directory: backend
 
       # Vet
       - name: Run go vet
+        working-directory: backend
         run: go vet ./...
 
       # Unit + Integration Tests
       - name: Run unit & integration tests
+        working-directory: backend
         env:
           GOCHAT_ENV: test
           GOCHAT_TEST_DB: ${{ matrix.db-mode }}
@@ -78,6 +81,7 @@ jobs:
       # E2E Tests (only on postgres matrix)
       - name: Run e2e tests
         if: matrix.db-mode == 'postgres'
+        working-directory: backend
         env:
           GOCHAT_ENV: test
           POSTGRES_HOST: localhost
@@ -91,6 +95,7 @@ jobs:
 
       # Benchmark (quick sanity check, not full bench)
       - name: Run benchmarks
+        working-directory: backend
         env:
           GOCHAT_ENV: test
           GOCHAT_TEST_DB: ${{ matrix.db-mode }}
@@ -106,7 +111,7 @@ jobs:
         if: matrix.db-mode == 'postgres'
         uses: codecov/codecov-action@v4
         with:
-          files: coverage.out
+          files: backend/coverage.out
 
   # ---- Stage 2: Security Scan ----
   security:
@@ -124,9 +129,11 @@ jobs:
         uses: securego/gosec@master
         with:
           args: '-no-fail ./...'
+        working-directory: backend
 
       # Dependency vulnerability scan
       - name: Run govulncheck
+        working-directory: backend
         run: go install golang.org/x/vuln/cmd/govulncheck@latest && govulncheck ./...
 
       # Trivy filesystem scan
@@ -185,7 +192,7 @@ jobs:
         uses: docker/build-push-action@v5
         with:
           context: .
-          file: ./Dockerfile
+          file: ./deploy/docker/Dockerfile
           push: true
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
@@ -260,8 +267,8 @@ jobs:
       # Post-deploy health check
       - name: Health check
         run: |
-          chmod +x scripts/health_check.sh
-          GOCHAT_HOST=gochat-staging GOCHAT_PORT=3000 ./scripts/health_check.sh --full --timeout 30
+          chmod +x backend/scripts/health_check.sh
+          GOCHAT_HOST=gochat-staging GOCHAT_PORT=3000 ./backend/scripts/health_check.sh --full --timeout 30
 
   # ---- Stage 6: Deploy to Production ----
   deploy-production:
@@ -290,5 +297,5 @@ jobs:
       # Post-deploy health check
       - name: Health check
         run: |
-          chmod +x scripts/health_check.sh
-          GOCHAT_HOST=gochat-production GOCHAT_PORT=3000 ./scripts/health_check.sh --full --timeout 30
+          chmod +x backend/scripts/health_check.sh
+          GOCHAT_HOST=gochat-production GOCHAT_PORT=3000 ./backend/scripts/health_check.sh --full --timeout 30

AGENTS.md

@@ -0,0 +1,101 @@
+# AGENTS.md — GoChat
+
+Guidance for AI coding agents (and humans pairing with them) working in this repository.
+
+## Repository Layout
+
+This is a **monorepo** with a clear separation between backend code, deployment
+artifacts, and documentation:
+
+```
+backend/      # Go backend (the Go module lives here)
+  cmd/        # Entry points: gochat (server/seed), migrate, route_parity, ...
+  internal/   # App logic: handler, service, repository, model, config, ws, ...
+  pkg/        # Reusable packages: crypto, logger, pagination, response, ...
+  configs/    # Viper config files (config.yaml + config.{env}.yaml)
+  migrations/ # golang-migrate SQL files (sequential, .up.sql / .down.sql)
+  docs/       # swaggo-generated Swagger Go package (imported by the router)
+  scripts/    # migrate.sh, seed.sh, health_check.sh, route-parity tooling
+  tests/      # e2e tests + test helpers
+deploy/       # Deployment artifacts
+  docker/     # Dockerfile, Dockerfile.dev, docker-compose.{yml,dev,prod,test}.yml
+  quickstart/ # One-shot local/UAT Compose stack (PG+pgvector+Redis+Meilisearch+Mailhog)
+  fluentd/    # Log shipping config
+docs/         # Project documentation (architecture, requirements, plans, reports)
+```
+
+The **Go module root is `backend/`** — run all `go` commands from there.
+Build context for Docker is the **repository root** (`.`), not `backend/`.
+
+## Build & Test Commands
+
+All Go commands run from `backend/`:
+
+```bash
+cd backend
+
+# Build
+go build ./...                      # compile everything
+make build                          # build ./cmd/gochat → bin/gochat
+
+# Run
+go run cmd/gochat/main.go serve     # API server (default subcommand)
+go run cmd/gochat/main.go seed      # seed demo data
+
+# Test
+go test ./...                       # all tests
+GOCHAT_TEST_DB=sqlite go test ./internal/... ./pkg/... ./cmd/...  # no PG needed
+go test -v -race ./...              # with race detector
+go test -v ./tests/e2e/...          # e2e
+
+# Lint
+golangci-lint run ./...
+go vet ./...
+```
+
+Docker (build context = repo root, Dockerfile in `deploy/docker/`):
+
+```bash
+# Quickstart stack from repo root
+cd deploy/quickstart && cp .env.example .env && docker compose up -d --build
+
+# Build image manually from backend/
+make docker
+```
+
+## Go Version & Tooling
+
+- **Go**: 1.24+ (go.mod declares 1.24.0; CI uses 1.25). Toolchain: go1.24.4.
+- **HTTP**: Gin v1.10
+- **ORM**: GORM v2
+- **DB**: PostgreSQL 16 + pgvector (SQLite supported for tests via `GOCHAT_TEST_DB=sqlite`)
+- **Config**: Viper (multi-env overlay: `config.yaml` → `config.{env}.yaml` → `.env`)
+- **Swagger**: swaggo/swag — generated docs live in `backend/docs/` (a Go package imported by `internal/router`); **do not move them out of the module**.
+
+## Code Style & Conventions
+
+- Tabs for Go/Makefile; 2-space for YAML/JSON/TOML (see `.editorconfig`).
+- Match existing patterns in the surrounding code — do not reformat unrelated files.
+- Layered architecture: `handler → service → repository → model`. Respect layer boundaries; don't call repositories directly from handlers.
+- PG-only features (pgvector search, etc.) must guard with `skipIfSQLite` so SQLite test mode stays green.
+- New DB schema changes go through numbered SQL migrations in `backend/migrations/` (`NNNNN_name.{up,down}.sql`).
+
+## Configuration
+
+- Config files: `backend/configs/config.yaml` (base) + `config.dev.yaml` / `config.prod.yaml` (env overlays).
+- Viper search paths: `./configs`, `./`, `/etc/gochat/`.
+- Runtime config dir is resolved from the base config's location, so env overlays load from the same dir automatically.
+- Secrets/`.env` are gitignored — never commit them.
+
+## Deployment Notes
+
+- The production `Dockerfile` (in `deploy/docker/`) uses repo root as build context and `COPY backend/` for sources. When adding files the image needs, place them under `backend/` or update the COPY directives.
+- `docker-compose*.yml` files in `deploy/docker/` use `context: ../..` (repo root) and `dockerfile: deploy/docker/Dockerfile`.
+- CI (`.github/workflows/ci.yml`) runs Go commands with `working-directory: backend` and builds the Docker image with `file: ./deploy/docker/Dockerfile`.
+
+## Things to Avoid
+
+- Do not move `backend/docs/*.go` — they are a compiled Go package imported by the router.
+- Do not add Go files to `backend/scripts/legacy/` expecting them to be excluded — `go build ./...` compiles them; keep that directory for one-off scripts only.
+- Do not commit `.env`, `coverage.out`, `bin/`, or `tmp/`.
+- Do not rewrite git history or force-push without explicit instruction.

README.md

@@ -18,26 +18,36 @@
 GoChat 采用 **分层架构** + **模块化设计**：
 
 ```
-cmd/                    # 入口（migrate, server）
-internal/
-  app/                  # 应用启动、graceful shutdown
-  auth/                 # JWT认证、Refresh Token、TOTP
-  autoassignment/       # 智能分配
-  channel/provider/     # 渠道抽象层（Telegram/WebWidget/Email）
-  config/               # Viper多环境热加载配置
-  handler/api/v1/       # HTTP Handler（Gin，104+路由）
-  llm/                  # CaptainAI LLM Provider（OpenAI/Ollama/volcengine）
-  middleware/           # Auth/CORS/RateLimiting/AccountScope/InputValidation
-  model/                # GORM 数据模型（Base/Account/User/Contact/Inbox等）
-  pubsub/               # Redis Pub/Sub
-  repository/           # 数据访问层（21 repo）
-  service/              # 业务逻辑层
-  ws/                   # WebSocket Hub（/cable）
-pkg/
-  crypto/               # bcrypt Hash/Check
-  validation/           # go-playground/validator/v10 自定义规则
-tests/
-  e2e/                  # 端到端测试（Auth/AccountCRUD/CRM）
+backend/                # Go 后端（单仓库 monorepo 子目录）
+  cmd/                  # 入口（migrate, server）
+  internal/
+    app/                # 应用启动、graceful shutdown
+    auth/               # JWT认证、Refresh Token、TOTP
+    autoassignment/     # 智能分配
+    channel/provider/   # 渠道抽象层（Telegram/WebWidget/Email）
+    config/             # Viper多环境热加载配置
+    handler/api/v1/     # HTTP Handler（Gin，104+路由）
+    llm/                # CaptainAI LLM Provider（OpenAI/Ollama/volcengine）
+    middleware/         # Auth/CORS/RateLimiting/AccountScope/InputValidation
+    model/              # GORM 数据模型（Base/Account/User/Contact/Inbox等）
+    pubsub/             # Redis Pub/Sub
+    repository/         # 数据访问层（21 repo）
+    service/            # 业务逻辑层
+    ws/                 # WebSocket Hub（/cable）
+  pkg/
+    crypto/             # bcrypt Hash/Check
+    validation/         # go-playground/validator/v10 自定义规则
+  configs/              # 多环境配置（config.yaml + config.{env}.yaml）
+  migrations/           # SQL 迁移文件
+  docs/                 # Swagger/OpenAPI 生成代码
+  scripts/              # 迁移、种子、健康检查等脚本
+  tests/
+    e2e/                # 端到端测试（Auth/AccountCRUD/CRM）
+deploy/                 # 部署相关
+  docker/               # Dockerfile + docker-compose（dev/prod/test）
+  quickstart/           # 本地/UAT 一键启动 Compose 栈
+  fluentd/              # 日志收集配置
+docs/                   # 项目文档（架构、需求、计划、报告）
 ```
 
 ## 快速开始
@@ -56,15 +66,16 @@ tests/
 git clone https://github.com/gochat/gochat.git
 cd gochat
 
-# 安装依赖
+# 安装依赖（在 backend/ 下）
+cd backend
 go mod download
 
-# 配置环境
-cp .env.example .env
+# 配置环境（从仓库根目录复制）
+cp ../.env.example ../.env
 # 编辑 .env 配置数据库、Redis、JWT等
 
 # 运行服务
-go run cmd/server/main.go
+go run cmd/gochat/main.go serve
 
 # 运行测试（SQLite模式，无需PG）
 GOCHAT_TEST_DB=sqlite go test ./internal/... ./pkg/... ./cmd/...
@@ -94,9 +105,9 @@ docker compose --profile seed run --rm seed
 
 GoChat 使用 **Viper 多环境叠加**机制：
 
-- `configs/default.yaml` — 默认配置
-- `configs/production.yaml` — 生产覆盖
-- `configs/development.yaml` — 开发覆盖
+- `backend/configs/config.yaml` — 默认配置
+- `backend/configs/config.prod.yaml` — 生产覆盖
+- `backend/configs/config.dev.yaml` — 开发覆盖
 - `.env` — 本地覆盖（最高优先级）
 - 11 个字段支持 **热加载**（无需重启）
 

backend/Makefile

@@ -50,7 +50,7 @@ clean:
 
 ## docker: Build Docker image
 docker:
-	docker build -t $(APP_NAME) .
+	docker build -t $(APP_NAME) -f ../deploy/docker/Dockerfile ../
 
 ## db_create: Create database (ref: Chatwoot make db_create)
 db_create: