# XCE Frontend (API Server + CLI)

## Overview
Go-based REST API server (Gin) and CLI tool (Cobra) that expose cluster management operations. Two independent Go modules sharing no code at the module level.

## Modules
| Module | Path | Entry Point |
|--------|------|-------------|
| `apiserver` | `src/frontend/apiserver/` | `cmd/main.go` |
| `xcecli` | `src/frontend/xcecli/` | `cmd/main.go` |
| `schedulerclient` (Phase 0-1, ✅ done) | `src/frontend/schedulerclient/` | library, no entry point — read + write Go client for the scheduler agent's MCP Server, calls `apiserver`'s REST API. `go vet`/`go build`/`go test` clean (45 tests). Read: `types.go` (URM types), `client.go` (interface), `httpclient.go` (resty impl), `statusmap.go`+`_test.go` (TDD, status mapping). Write (Phase 1): `write.go`+`_test.go` — `JobSpec`, `SubmitJob`/`CancelJob`/`HoldJob`/`ReleaseJob`, `doPost` (HTTP 200 + envelope-code dual check). |
| `mcp-server` (Phase 0-1, ✅ done) | `src/frontend/mcp-server/` | `cmd/main.go` — MCP Server exposing 10 tools (6 read-only + 4 write: `scheduler_submit`/`cancel`/`hold`/`release`); pure Go, `CGO_ENABLED=0`, uses `schedulerclient` as API client, authenticates via `XCE_API_KEY` env var. Uses `github.com/mark3labs/mcp-go@v0.57.0` for MCP stdio transport. `internal/templates.go` — job template registry + `general_serial` (通用串行脚本); `scheduler_submit` has `dry_run` review mode (returns resolved JobSpec before submitting). Read-only tools annotated ReadOnlyHint=true; write tools DestructiveHint=true. `go build`/`go vet`/`go test` clean, binary ~12MB. |

## Build & Test
```bash
make build-server       # → /tmp/apiserver
make build-cli          # → /tmp/xce_static (CGO_ENABLED=0, static binary)
make test               # unit tests only (no live server required)
make test-all           # unit + integration (needs XCE_BIN and SRV_URL env vars)
```

## API Server Architecture
```
cmd/         Entry point — init logger, config, stores, RBAC, auth, then start Gin
router/      Route registration and middleware chain
controllers/ HTTP handlers: one file per resource (jobs, queues, hosts, clusters, users...)
services/    Business logic
store/       Thread-safe in-memory key-value stores (generics-based)
models/      Request/response DTOs and domain structs
middleware/  CORS, rate limiting, IP whitelist, JWT validation
backend/     C library integration stubs
backend/auth Pluggable auth providers (configfile, ldap, oauth2, pam)
utils/       Logger (zap), config parsing, crypto helpers
common/      Global error codes and messages
config/      YAML configs and JSON schemas
```

## Conventions

See `.kiro/steering/api-standards.md` (handler pattern, middleware chain, error codes, response format), `.kiro/steering/error-handling.md` (ReturnError early-return, zap logging), `.kiro/steering/security.md` (RBAC, JWT, auth backends), and `.kiro/steering/testing.md` (TDD, table-driven tests, state isolation).

### Quick reference (from steering)
- Handler: `preCheck*() → service call → ReturnSuccess/ReturnError; return`
- Middleware chain: WhitelistURL → WhitelistIP → RateLimit → JWT → CORS → RBAC
- RBAC: `RequirePermission("action:scope")` — permissions in `config/rbac.yaml`
- Logging: `logger.Error("msg", zap.Error(err))` — never `fmt.Println`
- Tests: co-located `_test.go`, `t.TempDir()`, global state reset via `t.Cleanup`

## Key Files
- `controllers/response.go` — ReturnSuccess / ReturnError helpers
- `controllers/rbac_check.go` — RBAC loading, RequirePermission middleware
- `middleware/validatehandler.go` — JWT token validation middleware
- `backend/auth/provider.go` — AuthProvider interface definition
- `store/store.go` — Generic in-memory store implementation
- `config/rbac.yaml` — Role and permission definitions
- `config/auth.yaml` — Auth provider configuration