chore: baseline snapshot — prior-session work + ha-consistency-invariants spec family

Pre-existing uncommitted work: ha-repl-hardening payload data plane (7.x),
heartbeat liveness fix (Req 1.3), connection-reuse ASAN fixes, doc cleanup.
New: ha-consistency-invariants umbrella (requirements/design/research) and
its four implementation sub-specs (specs generated via batch, cross-spec
review applied), steering roadmap + product.md Raft+CP decision.
This commit is contained in:
Rongsong Shen 2026-06-11 13:21:50 +00:00
parent 084244941b
commit 06135954ff
88 changed files with 25611 additions and 5285 deletions

View file

@ -35,37 +35,14 @@ config/ YAML configs and JSON schemas
## Conventions
### Controllers
- Struct: `type {Resource}Controller struct{}`
- Handler signature: `func (c {Resource}Controller) {Action}{Resource}(ctx *gin.Context)`
- Always return via helpers — never write response directly:
```go
ReturnSuccess(ctx, common.SUCCESS_CODE, common.SUCCESS_MSG, data)
ReturnError(ctx, common.ERROR_CODE, err.Error(), nil)
```
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).
### Error Handling
- Early return on every error — no deferred error accumulation
- Log with zap fields before returning: `logger.Error("msg", zap.Error(err))`
- Use `preCheck{Resource}Request()` helpers for input validation before business logic
### RBAC
- Protect routes with `controllers.RequirePermission("action:domain")` middleware
- Permission strings follow `action:scope` pattern (e.g., `job:view:self`, `queue:submit:all`)
### Logging
- Import as: `logger "apiserver/utils"`
- Always include context: `zap.String("key", val)`, `zap.Error(err)`
### Models
- JSON tags use snake_case: `json:"field_name"`
- Required fields: `binding:"required"`
- YAML tags for config structs: `yaml:"field_name,omitempty"`
### Tests
- Use `t.TempDir()` for file fixtures
- Reset global state with a helper (e.g., `resetRBACState()` pattern in rbac_check_test.go)
- Table-driven tests for filter/validation logic
### 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