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:
parent
084244941b
commit
06135954ff
88 changed files with 25611 additions and 5285 deletions
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue