Phase 0+1+2 续: 项目骨架 + 配置 + 日志 + 存储层

Phase 0 (项目骨架):
- main.go 改为最小骨架 (config + logging + gin + /healthz + 优雅退出)
- internal/{config,logging,storage,cluster,...}/ 目录占位

Phase 1 (配置 + 日志):
- internal/config: env 解析 + 必填校验 + token 隐藏的 String()
- internal/logging: slog multi-handler 双输出 (终端 text + 主文件 JSON)
  + StartToolCall per-tool 独立文件 (0600), tools 目录 0700

Phase 2 续 (存储层):
- internal/cluster: 16 字段 Cluster struct (AuthPassword json:"-")
- internal/storage: modernc.org/sqlite 接入, WAL 模式, schema 自动迁移
- ClusterRepo CRUD: Create/Get/List/Update/Delete + ErrNotFound
  + AuthPassword 空字符串 = 保留旧密码 (核心约定)
- 7 个单元测试全绿 (:memory: DB)
- created_at/updated_at 改纳秒精度, 消除 List 测试的 sleep 特殊 case

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
tao.chen
2026-07-10 12:12:53 +08:00
co-authored by Claude
parent 1dfef0f598
commit a4e2472716
15 changed files with 2648 additions and 15 deletions
+58
View File
@@ -0,0 +1,58 @@
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project Status
**This repository is freshly initialized.** The only Go source file is `main.go`, which is still the GoLand "Hello, gopher" template. The `go.mod` and `go.sum` already pin the intended runtime dependencies, but no application code has been written yet.
Intended purpose (inferred from module name and pinned dependencies): an **MCP (Model Context Protocol) server for Apache Spark**, written in Go, with HTTP transport, MongoDB-backed persistence, and a local `data/` directory for Spark connection state and pending job state (per `.gitignore`).
When working here, expect to be **building from scratch**, not modifying existing logic.
## Build, Test, Run
Standard Go toolchain (Go 1.25.5 per `go.mod`). All commands run from the repo root.
| Task | Command |
|---|---|
| Build | `go build ./...` |
| Run | `go run .` (currently just prints the template `main`) |
| Test (all) | `go test ./...` |
| Test (single test by name regex) | `go test -run TestName ./...` |
| Test (single test verbose) | `go test -v -run TestName ./path/to/pkg` |
| Test (with coverage) | `go test -cover ./...` |
| Vet (static analysis) | `go vet ./...` |
| Format | `gofmt -w .` |
| Tidy modules | `go mod tidy` |
| Download deps | `go mod download` |
There is no `Makefile`, no `golangci-lint` config, and no test files yet — do not assume they exist.
## Key Pinned Dependencies
`go.mod` declares these as `// indirect` (they will become direct once code is added that imports them):
- **`github.com/mark3labs/mcp-go v0.56.0`** — MCP server framework. This is the core library; all MCP tool/resource/prompt definitions will be built on top of it.
- **`github.com/gin-gonic/gin v1.12.0`** — HTTP router. Likely the transport layer that exposes the MCP server over HTTP (SSE / streamable HTTP).
- **`go.mongodb.org/mongo-driver/v2 v2.5.0`** — MongoDB client. Likely for persisting connection profiles, session state, and job history.
- **`github.com/bytedance/sonic v1.15.0`** — High-performance JSON encoder used internally by Gin.
## Layout Conventions
- Module path: `spark-mcp-go` (see `go.mod:1`). Local package import paths use this prefix.
- Runtime data directory: `data/` at the repo root, **gitignored**. Used for "persisted Spark connections / pending jobs" (per `.gitignore` comment). Anything that needs to survive across process restarts but should not go to MongoDB belongs here.
- IDE config: `.idea/` is gitignored — JetBrains (GoLand / IntelliJ) workspace files. Safe to delete; not part of the project.
## Things To Confirm Before Coding
The codebase is empty enough that a few decisions are not yet pinned down and will affect every subsequent file. Confirm with the user before assuming:
1. **MCP transport** — stdio, HTTP+SSE, or streamable HTTP? The Gin dependency suggests HTTP, but `mark3labs/mcp-go` supports both.
2. **Spark connectivity** — does this server submit jobs to an existing Spark cluster (REST / Livy / Spark Connect), or does it embed a Spark session (likely not — Spark itself is JVM/Scala and won't run in a Go binary)?
3. **Persistence split** — what goes in MongoDB vs. the local `data/` directory? The `.gitignore` implies both will be used.
4. **Configuration** — env vars? config file (YAML/JSON)? CLI flags? Nothing is wired up yet.
## Memory
This is a fresh repo with no `MEMORY.md` or project-level memory file. Decisions made during early development (transport choice, Spark backend interface, persistence schema) are worth recording once they are made — see the `claude-md-management` skill conventions.