create-wakii-stack 0.0.0-stage → 0.1.1

package/stack-template/services/go-svc/internal/api/router.go

@@ -0,0 +1,86 @@
+package api
+
+import (
+	"log/slog"
+	"net/http"
+
+	"github.com/go-chi/chi/v5"
+	"github.com/rs/cors"
+
+	"github.com/wakii-dev/architecture-overview/services/go-svc/internal/swagger"
+)
+
+// Deps chứa mọi dependency router cần — inject từ main (testable).
+type Deps struct {
+	Log         *slog.Logger
+	Readiness   ReadinessChecker
+	CORSOrigins []string
+	JWTSecret   []byte
+	Feed        *FeedHandler
+	Stats       *StatsHandler
+}
+
+// NewRouter dựng chi router:
+//   - naked /healthz + /readyz (ngoài prefix — conventions/02 rule 5)
+//   - /api/activity/* — business routes (gateway pass-through, conventions/08)
+//       - /docs + /openapi.yaml — auth-exempt (tiền lệ auth-mock /api/auth/docs)
+//       - /feed, /stats — JWT bắt buộc (token contract §4)
+//   - KHÔNG còn /events (story FI-76 SF-3 thanh lý REST ingest — event đi qua
+//     Kafka consumer internal/consumer; POST /events → 404 NotFound mặc định)
+func NewRouter(d Deps) http.Handler {
+	r := chi.NewRouter()
+
+	r.Use(RequestIDMiddleware())
+	r.Use(RecoverMiddleware(d.Log))
+	r.Use(RequestLoggerMiddleware(d.Log))
+
+	// CORS dev-profile (conventions/07): origin list từ CORS_DEV_ORIGIN.
+	// P1 code-review: rs/cors với AllowedOrigins rỗng = allow-ALL (không phải
+	// deny-by-default) → CHỈ mount khi có origin; prod/compose (qua gateway)
+	// vốn không cần CORS → không header ACAO nào được emit.
+	if len(d.CORSOrigins) > 0 {
+		c := cors.New(cors.Options{
+			AllowedOrigins: d.CORSOrigins,
+			AllowedMethods: []string{"GET", "POST", "PATCH", "DELETE", "OPTIONS"},
+			AllowedHeaders: []string{"Authorization", "Content-Type", "X-Request-Id"},
+		})
+		r.Use(c.Handler)
+	}
+
+	r.Get("/healthz", Healthz)
+	r.Get("/readyz", Readyz(d.Readiness))
+
+	// 4xx ngoài /api/activity cũng đi qua envelope (conventions/04: MỌI 4xx/5xx)
+	r.NotFound(func(w http.ResponseWriter, req *http.Request) {
+		WriteError(w, req, http.StatusNotFound, CodeNotFound, "route not found", nil)
+	})
+	r.MethodNotAllowed(func(w http.ResponseWriter, req *http.Request) {
+		WriteError(w, req, http.StatusMethodNotAllowed, CodeValidationError, "method not allowed", nil)
+	})
+
+	r.Route("/api/activity", func(ar chi.Router) {
+		// Mirror healthcheck dưới prefix (auth-mock precedent — conventions/02
+		// rule 5): spec activity.yaml khai /healthz+/readyz dưới servers.url
+		// /api/activity; naked path vẫn là nguồn cho compose/CI probes.
+		ar.Get("/healthz", Healthz)
+		ar.Get("/readyz", Readyz(d.Readiness))
+
+		// swagger static — KHÔNG auth (browser demo swagger-ui; gateway vẫn
+		// presence-check qua :8080 nên demo browser dùng direct :8082 — README)
+		ar.Get("/openapi.yaml", ServeOpenAPISpec)
+		ar.Mount("/docs", swagger.Handler("/api/activity/docs"))
+
+		// business routes — JWT bắt buộc
+		ar.Group(func(g chi.Router) {
+			g.Use(JWTMiddleware(d.JWTSecret))
+			g.Get("/feed", d.Feed.List)
+			g.Get("/stats", d.Stats.Get)
+		})
+
+		ar.NotFound(func(w http.ResponseWriter, req *http.Request) {
+			WriteError(w, req, http.StatusNotFound, CodeNotFound, "route not found", nil)
+		})
+	})
+
+	return r
+}

package/stack-template/services/go-svc/internal/api/stats.go

@@ -0,0 +1,63 @@
+package api
+
+// stats.go — GET /api/activity/stats: thống kê schema tasks (readonly theo
+// canonical DDL) + recentEvents 24h (schema activity). tasks không đọc được
+// (permission/missing) → 503 DEPENDENCY_DOWN envelope — chứng minh permission
+// boundary (exit criterion context pack).
+
+import (
+	"errors"
+	"log/slog"
+	"net/http"
+
+	"github.com/wakii-dev/architecture-overview/services/go-svc/internal/apperr"
+)
+
+// statsResponse mirror ActivityStats (activity.yaml).
+type statsResponse struct {
+	TotalTasks    int            `json:"totalTasks"`
+	TasksByStatus map[string]int `json:"tasksByStatus"`
+	RecentEvents  int            `json:"recentEvents"`
+}
+
+// StatsHandler deps cho GET /stats.
+type StatsHandler struct {
+	Store EventStore
+	Tasks TaskReader
+	Log   *slog.Logger
+}
+
+// Get xử lý GET /stats (mount sau JWTMiddleware).
+func (h *StatsHandler) Get(w http.ResponseWriter, r *http.Request) {
+	ts, err := h.Tasks.Stats(r.Context())
+	if err != nil {
+		if errors.Is(err, apperr.ErrTasksUnavailable) {
+			// Permission boundary thể hiện đúng contract: 503 + DEPENDENCY_DOWN.
+			WriteError(w, r, http.StatusServiceUnavailable, CodeDependencyDown,
+				"cannot read schema tasks (readonly permission or not migrated)", nil)
+			return
+		}
+		h.Log.Error("stats query failed", "requestId", RequestID(r.Context()), "err", err.Error())
+		WriteError(w, r, http.StatusInternalServerError, CodeInternal, "stats query failed", nil)
+		return
+	}
+
+	recent, err := h.Store.CountRecent24h(r.Context())
+	if err != nil {
+		h.Log.Error("count recent events failed", "requestId", RequestID(r.Context()), "err", err.Error())
+		WriteError(w, r, http.StatusInternalServerError, CodeInternal, "recent events query failed", nil)
+		return
+	}
+
+	// 4 giá trị khớp CHECK constraint canonical DDL (SF-2 cascade thêm
+	// assignment_failed) — luôn đủ key kể cả khi GROUP BY trả ít hơn.
+	byStatus := map[string]int{"todo": 0, "in_progress": 0, "done": 0, "assignment_failed": 0}
+	for k, v := range ts.ByStatus {
+		byStatus[k] = v
+	}
+	writeJSON(w, http.StatusOK, statsResponse{
+		TotalTasks:    ts.TotalTasks,
+		TasksByStatus: byStatus,
+		RecentEvents:  recent,
+	})
+}

package/stack-template/services/go-svc/internal/api/stats_test.go

@@ -0,0 +1,83 @@
+package api
+
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/wakii-dev/architecture-overview/services/go-svc/internal/model"
+)
+
+// jsonUnmarshal helper cho test.
+func jsonUnmarshal(b []byte, v interface{}) error {
+	return json.NewDecoder(bytes.NewReader(b)).Decode(v)
+}
+
+func TestStats_OK(t *testing.T) {
+	h := &StatsHandler{
+		Store: &fakeStore{eventsLenForRecent: 2},
+		Tasks: &fakeTasks{stats: model.TaskStats{
+			TotalTasks: 7,
+			ByStatus:   map[string]int{"todo": 3, "in_progress": 2, "done": 2},
+		}},
+		Log: slog.Default(),
+	}
+	req := httptest.NewRequest(http.MethodGet, "/api/activity/stats", nil)
+	rec := httptest.NewRecorder()
+	h.Get(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200", rec.Code)
+	}
+	var resp statsResponse
+	if err := jsonUnmarshal(rec.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("bad json: %v", err)
+	}
+	if resp.TotalTasks != 7 {
+		t.Errorf("totalTasks = %d, want 7", resp.TotalTasks)
+	}
+	for _, k := range []string{"todo", "in_progress", "done"} {
+		if _, ok := resp.TasksByStatus[k]; !ok {
+			t.Errorf("tasksByStatus thiếu key %q (contract: 3 giá trị CHECK constraint)", k)
+		}
+	}
+	if resp.RecentEvents != 2 {
+		t.Errorf("recentEvents = %d, want 2", resp.RecentEvents)
+	}
+}
+
+func TestStats_TasksUnavailable503Envelope(t *testing.T) {
+	// exit criterion negative path: không đọc được schema tasks → 503 DEPENDENCY_DOWN
+	h := &StatsHandler{
+		Store: &fakeStore{},
+		Tasks: &fakeTasks{unavail: true},
+		Log:   slog.Default(),
+	}
+	req := httptest.NewRequest(http.MethodGet, "/api/activity/stats", nil)
+	req = req.WithContext(contextWithRequestID(req, "req-stats"))
+	rec := httptest.NewRecorder()
+	h.Get(rec, req)
+
+	if rec.Code != http.StatusServiceUnavailable {
+		t.Fatalf("status = %d, want 503", rec.Code)
+	}
+	assertEnvelope(t, rec.Body.String(), CodeDependencyDown, "req-stats")
+}
+
+func TestStats_UnexpectedErrorIs500(t *testing.T) {
+	h := &StatsHandler{
+		Store: &fakeStore{},
+		Tasks: &fakeTasks{err: errors.New("connection reset")},
+		Log:   slog.Default(),
+	}
+	req := httptest.NewRequest(http.MethodGet, "/api/activity/stats", nil)
+	rec := httptest.NewRecorder()
+	h.Get(rec, req)
+	if rec.Code != http.StatusInternalServerError {
+		t.Fatalf("status = %d, want 500 (lỗi thật không map 503)", rec.Code)
+	}
+}

package/stack-template/services/go-svc/internal/api/types.go

@@ -0,0 +1,32 @@
+package api
+
+// Interfaces handlers tiêu thụ — store/resolve implement ngầm (không import cycle).
+import (
+	"context"
+
+	"github.com/google/uuid"
+
+	"github.com/wakii-dev/architecture-overview/services/go-svc/internal/model"
+)
+
+// EventStore — persist + list events (schema activity, owner conn).
+type EventStore interface {
+	InsertEvent(ctx context.Context, e *model.Event) error
+	ListEvents(ctx context.Context, limit, offset int) ([]model.Event, int, error)
+	CountRecent24h(ctx context.Context) (int, error)
+}
+
+// TaskReader — đọc schema tasks (readonly conn).
+type TaskReader interface {
+	TaskTitle(ctx context.Context, id uuid.UUID) (string, error)
+	Stats(ctx context.Context) (model.TaskStats, error)
+	Probe(ctx context.Context) error
+}
+
+// DisplayResolver — resolve userName qua spring REST (best-effort).
+type DisplayResolver interface {
+	UserName(ctx context.Context, authorization string, userID uuid.UUID) string
+}
+
+// Lỗi schema tasks không đọc được: store trả apperr.ErrTasksUnavailable —
+// handlers map → 503 DEPENDENCY_DOWN (conventions/04).

package/stack-template/services/go-svc/internal/apperr/apperr.go

@@ -0,0 +1,9 @@
+// Package apperr — sentinel errors dùng chung giữa store ↔ api (không import cycle).
+package apperr
+
+import "errors"
+
+// ErrTasksUnavailable — schema tasks chưa migrate (SF-2 song song) hoặc
+// readonly permission bị revoke. Handlers map → 503 DEPENDENCY_DOWN
+// (conventions/04); store trả error này từ các query schema tasks.
+var ErrTasksUnavailable = errors.New("schema tasks unavailable (not migrated yet or readonly permission denied)")

package/stack-template/services/go-svc/internal/config/config.go

@@ -0,0 +1,115 @@
+// Package config load cấu hình go-svc 100% qua env-var (platform/conventions/06).
+// Fail-fast khi thiếu env bắt buộc — không fallback im lặng cho secret.
+package config
+
+import (
+	"fmt"
+	"strings"
+)
+
+// Config là toàn bộ cấu hình runtime của go-svc.
+type Config struct {
+	Port                string
+	DatabaseURL         string // owner connection — role go_svc (schema activity)
+	DatabaseReadonlyURL string // readonly connection — role go_readonly (schema tasks)
+	JWTSecret           string
+	SpringSvcURL        string // resolve userName (conventions: spring sở hữu users)
+	CORSDevOrigins      []string
+	LogLevel            string
+	// Kafka consumer (SF-3, conventions/09) — lazy-connect, KHÔNG vào readyz.
+	KafkaBrokers  []string
+	KafkaGroup    string // consumer group — filter-by-type (task-events.md)
+	KafkaTopic    string
+	KafkaDLQTopic string
+	// Service-token (resolver enrich userName khi consume — không có HTTP caller).
+	AuthMockURL          string
+	SvcActivityPassword  string // secret — KHÔNG default (conventions/06)
+}
+
+// Load đọc env qua hàm getenv (inject được trong test).
+func Load(getenv func(string) string) (*Config, error) {
+	c := &Config{
+		Port:                getenv("PORT"),
+		DatabaseURL:         getenv("DATABASE_URL"),
+		DatabaseReadonlyURL: getenv("DATABASE_READONLY_URL"),
+		JWTSecret:           getenv("JWT_SECRET"),
+		SpringSvcURL:        getenv("SPRING_SVC_URL"),
+		LogLevel:            getenv("LOG_LEVEL"),
+		KafkaBrokers:        parseBrokers(getenv("KAFKA_BROKERS")),
+		KafkaGroup:          getenv("KAFKA_GROUP"),
+		KafkaTopic:          getenv("KAFKA_TOPIC"),
+		KafkaDLQTopic:       getenv("KAFKA_DLQ_TOPIC"),
+		AuthMockURL:         getenv("AUTH_MOCK_URL"),
+		SvcActivityPassword: getenv("SVC_ACTIVITY_PASSWORD"),
+		CORSDevOrigins:      parseOrigins(getenv("CORS_DEV_ORIGIN")),
+	}
+
+	// Defaults theo conventions/05 — secret KHÔNG default (fail-fast).
+	if c.Port == "" {
+		c.Port = "8082"
+	}
+	if c.SpringSvcURL == "" {
+		c.SpringSvcURL = "http://spring-svc:8081"
+	}
+	if c.LogLevel == "" {
+		c.LogLevel = "info"
+	}
+	if c.KafkaGroup == "" {
+		c.KafkaGroup = "go-svc-activity" // task-events.md consumer groups
+	}
+	if c.KafkaTopic == "" {
+		c.KafkaTopic = "task-events"
+	}
+	if c.KafkaDLQTopic == "" {
+		c.KafkaDLQTopic = "task-events.dlq"
+	}
+	if c.AuthMockURL == "" {
+		c.AuthMockURL = "http://auth-mock:8090"
+	}
+
+	var missing []string
+	for _, kv := range []struct {
+		name string
+		val  string
+	}{
+		{"DATABASE_URL", c.DatabaseURL},
+		{"DATABASE_READONLY_URL", c.DatabaseReadonlyURL},
+		{"JWT_SECRET", c.JWTSecret},
+		{"KAFKA_BROKERS", getenv("KAFKA_BROKERS")},
+		{"SVC_ACTIVITY_PASSWORD", c.SvcActivityPassword},
+	} {
+		if kv.val == "" {
+			missing = append(missing, kv.name)
+		}
+	}
+	if len(missing) > 0 {
+		return nil, fmt.Errorf("missing required env vars: %s", strings.Join(missing, ", "))
+	}
+	return c, nil
+}
+
+// parseBrokers tách KAFKA_BROKERS theo dấu phẩy (compose truyền 1 broker).
+func parseBrokers(raw string) []string {
+	var out []string
+	for _, s := range strings.Split(raw, ",") {
+		if s = strings.TrimSpace(s); s != "" {
+			out = append(out, s)
+		}
+	}
+	return out
+}
+
+// parseOrigins tách CORS_DEV_ORIGIN theo dấu phẩy (conventions/07).
+// Rỗng → nil = deny-by-default (prod profile không emit ACAO).
+func parseOrigins(raw string) []string {
+	if strings.TrimSpace(raw) == "" {
+		return nil
+	}
+	var out []string
+	for _, s := range strings.Split(raw, ",") {
+		if s = strings.TrimSpace(s); s != "" {
+			out = append(out, s)
+		}
+	}
+	return out
+}

package/stack-template/services/go-svc/internal/config/config_test.go

@@ -0,0 +1,92 @@
+package config
+
+import (
+	"strings"
+	"testing"
+)
+
+// baseEnv — env tối thiểu cho Load thành công (SF-3 thêm KAFKA_BROKERS +
+// SVC_ACTIVITY_PASSWORD required).
+func baseEnv() map[string]string {
+	return map[string]string{
+		"PORT":                  "9999",
+		"DATABASE_URL":          "postgres://go_svc:pw@db:5432/app",
+		"DATABASE_READONLY_URL": "postgres://go_readonly:pw@db:5432/app",
+		"JWT_SECRET":            "secret-32-chars-minimum-ok",
+		"KAFKA_BROKERS":         "kafka:9092",
+		"SVC_ACTIVITY_PASSWORD": "demo-password",
+		"CORS_DEV_ORIGIN":       "http://localhost:3000, http://localhost:4001",
+	}
+}
+
+func TestLoad_OKWithRequiredEnv(t *testing.T) {
+	env := baseEnv()
+	cfg, err := Load(func(k string) string { return env[k] })
+	if err != nil {
+		t.Fatalf("unexpected err: %v", err)
+	}
+	if cfg.Port != "9999" {
+		t.Errorf("Port = %q, want 9999", cfg.Port)
+	}
+	want := []string{"http://localhost:3000", "http://localhost:4001"}
+	if len(cfg.CORSDevOrigins) != 2 || cfg.CORSDevOrigins[0] != want[0] || cfg.CORSDevOrigins[1] != want[1] {
+		t.Errorf("CORSDevOrigins = %v, want %v", cfg.CORSDevOrigins, want)
+	}
+	// Kafka defaults — group/topic/DLQ theo task-events.md, không cần env
+	if cfg.KafkaGroup != "go-svc-activity" || cfg.KafkaTopic != "task-events" || cfg.KafkaDLQTopic != "task-events.dlq" {
+		t.Errorf("kafka defaults = %q/%q/%q, want go-svc-activity/task-events/task-events.dlq",
+			cfg.KafkaGroup, cfg.KafkaTopic, cfg.KafkaDLQTopic)
+	}
+	if len(cfg.KafkaBrokers) != 1 || cfg.KafkaBrokers[0] != "kafka:9092" {
+		t.Errorf("KafkaBrokers = %v, want [kafka:9092]", cfg.KafkaBrokers)
+	}
+}
+
+func TestLoad_MissingRequiredFailsFast(t *testing.T) {
+	_, err := Load(func(k string) string { return "" })
+	if err == nil {
+		t.Fatal("expected error for missing required env")
+	}
+	for _, want := range []string{"DATABASE_URL", "DATABASE_READONLY_URL", "JWT_SECRET", "KAFKA_BROKERS", "SVC_ACTIVITY_PASSWORD"} {
+		if !strings.Contains(err.Error(), want) {
+			t.Errorf("error %q does not mention %q", err.Error(), want)
+		}
+	}
+}
+
+func TestLoad_MissingKafkaOnlyListsKafkaAndSecret(t *testing.T) {
+	env := map[string]string{
+		"DATABASE_URL":          "postgres://go_svc:pw@db:5432/app",
+		"DATABASE_READONLY_URL": "postgres://go_readonly:pw@db:5432/app",
+		"JWT_SECRET":            "secret-32-chars-minimum-ok",
+	}
+	_, err := Load(func(k string) string { return env[k] })
+	if err == nil {
+		t.Fatal("expected error khi thiếu KAFKA_BROKERS + SVC_ACTIVITY_PASSWORD")
+	}
+	if !strings.Contains(err.Error(), "KAFKA_BROKERS") || !strings.Contains(err.Error(), "SVC_ACTIVITY_PASSWORD") {
+		t.Errorf("error = %q, want nêu cả 2 env thiếu", err.Error())
+	}
+	if strings.Contains(err.Error(), "JWT_SECRET") {
+		t.Errorf("error = %q — JWT_SECRET đã cấp, không được liệt kê", err.Error())
+	}
+}
+
+func TestParseOrigins_EmptyDeniesByDefault(t *testing.T) {
+	if got := parseOrigins(""); got != nil {
+		t.Errorf("parseOrigins(\"\") = %v, want nil (deny-by-default)", got)
+	}
+	if got := parseOrigins(" , ,"); got != nil {
+		t.Errorf("parseOrigins(blank commas) = %v, want nil", got)
+	}
+}
+
+func TestParseBrokers_MultiAndTrim(t *testing.T) {
+	got := parseBrokers(" b1:9092 , b2:9092,")
+	if len(got) != 2 || got[0] != "b1:9092" || got[1] != "b2:9092" {
+		t.Errorf("parseBrokers = %v, want [b1:9092 b2:9092]", got)
+	}
+	if parseBrokers("") != nil {
+		t.Errorf("parseBrokers(\"\") = want nil")
+	}
+}

package/stack-template/services/go-svc/internal/consumer/envelope.go

@@ -0,0 +1,78 @@
+// Package consumer — Kafka consumer cho topic `task-events` (story FI-76 SF-3).
+// Thay REST ingest fire-and-forget (ADR-0006 → ADR-0008): consume envelope,
+// ghi activity IDEMPOTENT bằng envelope id, retry ×3 → compensating
+// `task.assignment_failed` → DLQ event gốc. Hợp đồng: contracts/events/task-events.md
+// + platform/conventions/09-async-messaging.md. Thư viện: segmentio/kafka-go
+// (ADR-0008 ghi franz-go = path production).
+package consumer
+
+import (
+	"encoding/json"
+	"fmt"
+	"time"
+
+	"github.com/google/uuid"
+
+	"github.com/wakii-dev/architecture-overview/services/go-svc/internal/model"
+)
+
+// SchemaVersion hiện tại của envelope (task-events.md — cố định 1).
+const SchemaVersion = 1
+
+// Envelope — JSON envelope bắt buộc của mọi message trên task-events.
+type Envelope struct {
+	SchemaVersion int             `json:"schemaVersion"`
+	ID            uuid.UUID       `json:"id"` // khóa idempotency — producer sinh MỖI event
+	Type          string          `json:"type"`
+	OccurredAt    time.Time       `json:"occurredAt"`
+	Payload       json.RawMessage `json:"payload"`
+}
+
+// taskUserPayload — phần payload consumer cần để ghi activity: taskId + userId
+// có ở cả 4 type consumer nhận (assignment_failed bị filter trước khi parse).
+// Field lạ trong payload được BỎ QUA (conventions/09 rule 3 — non-breaking).
+type taskUserPayload struct {
+	TaskID     uuid.UUID `json:"taskId"`
+	UserID     uuid.UUID `json:"userId"`
+	AssigneeID uuid.UUID `json:"assigneeId"` // chỉ task.assigned — fail hook simulate
+}
+
+// assignmentFailedPayload — payload compensating event go-svc publish khi
+// retry ×3 hết (task-events.md dòng `task.assignment_failed`).
+type assignmentFailedPayload struct {
+	TaskID     uuid.UUID `json:"taskId"`
+	AssigneeID uuid.UUID `json:"assigneeId"`
+	Reason     string    `json:"reason"`
+}
+
+// ParseEnvelope decode + validate envelope: schemaVersion == 1, id UUID hợp lệ,
+// type thuộc enum 5 giá trị, occurredAt khác zero. Message sai shape = poison
+// → caller ĐƯA thẳng DLQ (retry vô ích).
+func ParseEnvelope(raw []byte) (Envelope, error) {
+	var env Envelope
+	if err := json.Unmarshal(raw, &env); err != nil {
+		return Envelope{}, fmt.Errorf("decode envelope: %w", err)
+	}
+	if env.SchemaVersion != SchemaVersion {
+		return Envelope{}, fmt.Errorf("schemaVersion = %d, want %d", env.SchemaVersion, SchemaVersion)
+	}
+	if env.ID == uuid.Nil {
+		return Envelope{}, fmt.Errorf("envelope id rỗng — khóa idempotency bắt buộc")
+	}
+	switch env.Type {
+	case model.ActionTaskCreated, model.ActionTaskUpdated, model.ActionTaskAssigned,
+		model.ActionTaskDeleted, model.ActionTaskAssignmentFailed:
+		// enum hợp lệ (task-events.md)
+	default:
+		return Envelope{}, fmt.Errorf("type %q ngoài enum task-events", env.Type)
+	}
+	if env.OccurredAt.IsZero() {
+		return Envelope{}, fmt.Errorf("occurredAt rỗng")
+	}
+	return env, nil
+}
+
+// Marshal serialise envelope ra JSON (publish compensating).
+func (e Envelope) Marshal() ([]byte, error) {
+	return json.Marshal(e)
+}