create-wakii-stack 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,351 @@
+package consumer
+
+// runner_test.go — retry/DLQ semantics không broker (seam MessageSource +
+// Publisher): ACCEPTANCE context pack "Retry/DLQ: simulate svc-fail → 3 retry
+// → task.assignment_failed publish + event gốc vào DLQ (test assert)".
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"log/slog"
+	"os"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/segmentio/kafka-go"
+
+	"github.com/wakii-dev/architecture-overview/services/go-svc/internal/model"
+)
+
+type fakeSource struct {
+	mu     sync.Mutex
+	msgs   []kafka.Message
+	i      int
+	fetchErr error // trả khi hết message (mô phỏng broker tạm lỗi)
+	commits []kafka.Message
+}
+
+func (f *fakeSource) FetchMessage(context.Context) (kafka.Message, error) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	if f.i < len(f.msgs) {
+		m := f.msgs[f.i]
+		f.i++
+		return m, nil
+	}
+	return kafka.Message{}, f.fetchErr
+}
+
+func (f *fakeSource) CommitMessages(_ context.Context, msgs ...kafka.Message) error {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	f.commits = append(f.commits, msgs...)
+	return nil
+}
+
+type fakePublisher struct {
+	mu       sync.Mutex
+	messages map[string][][]byte // topic → values
+	failOn   map[string]bool     // topic → Publish trả error
+}
+
+func newFakePublisher() *fakePublisher {
+	return &fakePublisher{messages: map[string][][]byte{}, failOn: map[string]bool{}}
+}
+
+func (f *fakePublisher) Publish(_ context.Context, topic string, _ []byte, value []byte) error {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	if f.failOn[topic] {
+		return errors.New("publish down (fake)")
+	}
+	f.messages[topic] = append(f.messages[topic], value)
+	return nil
+}
+
+func (f *fakePublisher) topicValues(topic string) [][]byte {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	return append([][]byte{}, f.messages[topic]...)
+}
+
+func newTestRunner(store *fakeEventStore, src *fakeSource, pub *fakePublisher) *Runner {
+	return &Runner{
+		Reader:       src,
+		Handler:      newTestHandler(store),
+		Publisher:    pub,
+		Topic:        "task-events",
+		DLQTopic:     "task-events.dlq",
+		Log:          slog.Default(),
+		RetryMaxN:    3,
+		RetryBackoff: time.Millisecond, // test không chờ
+	}
+}
+
+func assignedMsg(assignee string) kafka.Message {
+	return kafka.Message{
+		Key:   []byte("c7c7c7c7-7777-4777-8777-777777777777"),
+		Value: []byte(`{"schemaVersion":1,"id":"3c4d5e6f-7081-4a92-b3c4-d5e6f708192a","type":"task.assigned","occurredAt":"2026-10-13T09:10:00Z","payload":{"taskId":"c7c7c7c7-7777-4777-8777-777777777777","userId":"11111111-1111-4111-8111-111111111111","assigneeId":"` + assignee + `"}}`),
+	}
+}
+
+// TestRunner_SvcFailRetry3ThenCompensatingAndDLQ — ACCEPTANCE retry/DLQ.
+func TestRunner_SvcFailRetry3ThenCompensatingAndDLQ(t *testing.T) {
+	store := &fakeEventStore{}
+	pub := newFakePublisher()
+	src := &fakeSource{msgs: []kafka.Message{assignedMsg(FailUserID.String())}, fetchErr: context.Canceled}
+
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	go newTestRunner(store, src, pub).Run(ctx)
+
+	// Poll đợi runner xử lý xong (fetch canceled → runner return).
+	deadline := time.Now().Add(2 * time.Second)
+	for time.Now().Before(deadline) {
+		if len(pub.topicValues("task-events.dlq")) == 1 {
+			break
+		}
+		time.Sleep(5 * time.Millisecond)
+	}
+
+	if rows := len(store.snapshot()); rows != 0 {
+		t.Errorf("fail hook KHÔNG được ghi activity, got %d rows", rows)
+	}
+
+	comp := pub.topicValues("task-events")
+	if len(comp) != 1 {
+		t.Fatalf("compensating publish = %d, want 1 (retry ×3 hết → task.assignment_failed)", len(comp))
+	}
+	var env Envelope
+	if err := json.Unmarshal(comp[0], &env); err != nil {
+		t.Fatalf("compensating không đúng envelope: %v", err)
+	}
+	if env.Type != model.ActionTaskAssignmentFailed {
+		t.Errorf("compensating type = %q", env.Type)
+	}
+	if env.ID.String() == "3c4d5e6f-7081-4a92-b3c4-d5e6f708192a" {
+		t.Error("compensating id phải MỚI (go sinh), không phải id event gốc")
+	}
+	var p assignmentFailedPayload
+	if err := json.Unmarshal(env.Payload, &p); err != nil {
+		t.Fatalf("payload: %v", err)
+	}
+	if p.TaskID.String() != "c7c7c7c7-7777-4777-8777-777777777777" || p.AssigneeID != FailUserID {
+		t.Errorf("compensating payload = %+v", p)
+	}
+
+	dlq := pub.topicValues("task-events.dlq")
+	if len(dlq) != 1 {
+		t.Fatalf("DLQ = %d, want 1 (event gốc sau retry ×3)", len(dlq))
+	}
+	var dm DLQMessage
+	if err := json.Unmarshal(dlq[0], &dm); err != nil {
+		t.Fatalf("DLQ không parse được: %v", err)
+	}
+	if dm.Error.Retries != 3 {
+		t.Errorf("DLQ retries = %d, want 3", dm.Error.Retries)
+	}
+	var orig Envelope
+	if err := json.Unmarshal([]byte(dm.OriginalEvent), &orig); err != nil {
+		t.Fatalf("DLQ phải chứa event GỐC parse được: %v", err)
+	}
+	if orig.Type != model.ActionTaskAssigned {
+		t.Errorf("DLQ original type = %q, want task.assigned", orig.Type)
+	}
+
+	// Message đã đưa DLQ thì commit offset (KHÔNG block partition).
+	if len(src.committed()) != 1 {
+		t.Errorf("commits = %d, want 1 (message không được kẹt partition)", len(src.committed()))
+	}
+}
+
+// TestRunner_PoisonGoesStraightToDLQ — parse fail KHÔNG retry vô ích.
+func TestRunner_PoisonGoesStraightToDLQ(t *testing.T) {
+	store := &fakeEventStore{}
+	pub := newFakePublisher()
+	src := &fakeSource{msgs: []kafka.Message{
+		{Key: []byte("k"), Value: []byte(`{not-envelope`)},
+	}, fetchErr: context.Canceled}
+
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	go newTestRunner(store, src, pub).Run(ctx)
+
+	deadline := time.Now().Add(2 * time.Second)
+	for time.Now().Before(deadline) {
+		if len(pub.topicValues("task-events.dlq")) == 1 {
+			break
+		}
+		time.Sleep(5 * time.Millisecond)
+	}
+
+	if comp := pub.topicValues("task-events"); len(comp) != 0 {
+		t.Errorf("poison KHÔNG được bắn compensating (không phải task.assigned fail), got %d", len(comp))
+	}
+	if dlq := pub.topicValues("task-events.dlq"); len(dlq) != 1 {
+		t.Fatalf("DLQ = %d, want 1", len(dlq))
+	} else {
+		var dm DLQMessage
+		if err := json.Unmarshal(dlq[0], &dm); err != nil {
+			t.Fatalf("DLQ message không parse được (poison phải vẫn vào DLQ nguyên văn): %v — body: %s", err, dlq[0])
+		}
+		if dm.Error.Retries != 3 {
+			t.Errorf("poison retries ghi nhận = %d, want 3 — body: %s", dm.Error.Retries, dlq[0])
+		}
+		if !strings.Contains(dm.Error.Reason, "poison") {
+			t.Errorf("reason = %q, want chứa 'poison'", dm.Error.Reason)
+		}
+		// Message gốc KHÔNG hợp lệ JSON — vẫn phải nằm nguyên văn trong DLQ
+		if !strings.Contains(dm.OriginalEvent, "not-envelope") {
+			t.Errorf("originalEvent = %q, want nguyên văn poison bytes", dm.OriginalEvent)
+		}
+	}
+}
+
+// TestRunner_HappyPathNoDLQ — golden fixture bob (không svc-fail) → 1 row,
+// KHÔNG compensating, KHÔNG DLQ, commit sau insert.
+func TestRunner_HappyPathNoDLQ(t *testing.T) {
+	store := &fakeEventStore{}
+	pub := newFakePublisher()
+	raw, err := loadFixtureBytes(t, "task.assigned.json")
+	if err != nil {
+		t.Fatalf("fixture: %v", err)
+	}
+	src := &fakeSource{msgs: []kafka.Message{{Key: []byte("k"), Value: raw}}, fetchErr: context.Canceled}
+
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	go newTestRunner(store, src, pub).Run(ctx)
+
+	deadline := time.Now().Add(2 * time.Second)
+	for time.Now().Before(deadline) {
+		if len(store.snapshot()) == 1 {
+			break
+		}
+		time.Sleep(5 * time.Millisecond)
+	}
+
+	if rows := store.snapshot(); len(rows) != 1 {
+		t.Fatalf("rows = %d, want 1", len(rows))
+	}
+	if comp := pub.topicValues("task-events"); len(comp) != 0 {
+		t.Errorf("happy path KHÔNG được publish gì, got %d", len(comp))
+	}
+	if dlq := pub.topicValues("task-events.dlq"); len(dlq) != 0 {
+		t.Errorf("happy path KHÔNG được đưa DLQ, got %d", len(dlq))
+	}
+	if len(src.committed()) != 1 {
+		t.Errorf("commit sau DB tx = %d, want 1 (manual commit rule)", len(src.committed()))
+	}
+}
+
+// TestRunner_FilteredTypeStillCommits — assignment_failed skip → nil → commit
+// (offset không kẹt trên message bị filter).
+func TestRunner_FilteredTypeStillCommits(t *testing.T) {
+	store := &fakeEventStore{}
+	pub := newFakePublisher()
+	raw, err := loadFixtureBytes(t, "task.assignment_failed.json")
+	if err != nil {
+		t.Fatalf("fixture: %v", err)
+	}
+	src := &fakeSource{msgs: []kafka.Message{{Key: []byte("k"), Value: raw}}, fetchErr: context.Canceled}
+
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	go newTestRunner(store, src, pub).Run(ctx)
+
+	deadline := time.Now().Add(2 * time.Second)
+	for time.Now().Before(deadline) {
+		if len(src.committed()) == 1 {
+			break
+		}
+		time.Sleep(5 * time.Millisecond)
+	}
+	if len(src.committed()) != 1 {
+		t.Fatalf("commit = %d, want 1 (filter-by-type vẫn commit)", len(src.committed()))
+	}
+	if rows := store.snapshot(); len(rows) != 0 {
+		t.Errorf("filtered type được ghi %d rows, want 0", len(rows))
+	}
+}
+
+// TestRunner_DLQPublishFailSkipsCommit — P1 code-review SF-3: publish DLQ
+// fail (broker down) → KHÔNG được commit offset — message gốc chỉ còn ở topic
+// chính, commit = mất vĩnh viễn. Skip commit → redelivery sau restart
+// (idempotency DB lo trùng); compensating (publish TRƯỚC DLQ) vẫn ra khỏi
+// runner vì publish topic chính OK.
+func TestRunner_DLQPublishFailSkipsCommit(t *testing.T) {
+	store := &fakeEventStore{}
+	pub := newFakePublisher()
+	pub.failOn["task-events.dlq"] = true
+	src := &fakeSource{msgs: []kafka.Message{assignedMsg(FailUserID.String())}, fetchErr: context.Canceled}
+
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	go newTestRunner(store, src, pub).Run(ctx)
+
+	// Đợi tới khi compensating publish xong (bước ngay trước DLQ-fail).
+	deadline := time.Now().Add(2 * time.Second)
+	for time.Now().Before(deadline) {
+		if len(pub.topicValues("task-events")) == 1 {
+			break
+		}
+		time.Sleep(5 * time.Millisecond)
+	}
+	time.Sleep(50 * time.Millisecond) // grace — commit sai nếu có cũng kịp xảy ra
+
+	if dlq := pub.topicValues("task-events.dlq"); len(dlq) != 0 {
+		t.Errorf("DLQ = %d, want 0 (publish fail — KHÔNG được giả vờ đã đưa DLQ)", len(dlq))
+	}
+	if len(src.committed()) != 0 {
+		t.Errorf("commits = %d, want 0 — commit khi DLQ publish fail = MẤT message vĩnh viễn", len(src.committed()))
+	}
+}
+
+// TestRunner_CompensatingPublishFailSkipsCommit — publish compensating fail
+// → toDLQ trả error TRƯỚC khi DLQ publish → skip commit (at-least-once cho
+// cả compensating: redelivery → Handle fail lại (svc-fail deterministic) →
+// thử compensating lần nữa).
+func TestRunner_CompensatingPublishFailSkipsCommit(t *testing.T) {
+	store := &fakeEventStore{}
+	pub := newFakePublisher()
+	pub.failOn["task-events"] = true
+	src := &fakeSource{msgs: []kafka.Message{assignedMsg(FailUserID.String())}, fetchErr: context.Canceled}
+
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	go newTestRunner(store, src, pub).Run(ctx)
+
+	time.Sleep(100 * time.Millisecond) // retry ×3 (backoff 1ms) + toDLQ fail — đủ xong
+
+	if comp := pub.topicValues("task-events"); len(comp) != 0 {
+		t.Errorf("task-events = %d, want 0 (publish luôn fail — fake không ghi)", len(comp))
+	}
+	if dlq := pub.topicValues("task-events.dlq"); len(dlq) != 0 {
+		t.Errorf("DLQ = %d, want 0 — compensating fail phải chặn TRƯỚC DLQ (thứ tự: compensating rồi DLQ)", len(dlq))
+	}
+	if len(src.committed()) != 0 {
+		t.Errorf("commits = %d, want 0 — compensating mất mà commit = task kẹt assigned mãi", len(src.committed()))
+	}
+}
+
+// --- helpers ---
+
+func (f *fakeEventStore) snapshot() []model.Event {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	return append([]model.Event{}, f.events...)
+}
+
+func (f *fakeSource) committed() []kafka.Message {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	return append([]kafka.Message{}, f.commits...)
+}
+
+func loadFixtureBytes(t *testing.T, name string) ([]byte, error) {
+	return os.ReadFile(fixturesDir(t) + "/" + name)
+}

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

@@ -0,0 +1,49 @@
+// Package logging dựng slog JSON handler đúng shape chung (platform/conventions/03):
+// {"ts":"...","level":"info","service":"go-svc","msg":"...", ...}
+package logging
+
+import (
+	"log/slog"
+	"os"
+	"strings"
+	"time"
+)
+
+const ServiceName = "go-svc"
+
+// New trả về *slog.Logger JSON ra stdout, level theo env LOG_LEVEL.
+func New(level string) *slog.Logger {
+	var lv slog.Level
+	switch strings.ToLower(level) {
+	case "debug":
+		lv = slog.LevelDebug
+	case "warn":
+		lv = slog.LevelWarn
+	case "error":
+		lv = slog.LevelError
+	default:
+		lv = slog.LevelInfo
+	}
+
+	h := slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
+		Level: lv,
+		ReplaceAttr: func(groups []string, a slog.Attr) slog.Attr {
+			switch a.Key {
+			case slog.TimeKey:
+				// ts: ISO 8601 UTC, độ chính xác ms (conventions/03)
+				if t, ok := a.Value.Any().(time.Time); ok {
+					return slog.String("ts", t.UTC().Format("2006-01-02T15:04:05.000Z"))
+				}
+				a.Key = "ts"
+				return a
+			case slog.LevelKey:
+				if l, ok := a.Value.Any().(slog.Level); ok {
+					return slog.String("level", strings.ToLower(l.String()))
+				}
+				return a
+			}
+			return a
+		},
+	})
+	return slog.New(h).With(slog.String("service", ServiceName))
+}

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

@@ -0,0 +1,37 @@
+// Package model — kiểu dữ liệu dùng chung store ↔ api (không import cycle).
+package model
+
+import (
+	"time"
+
+	"github.com/google/uuid"
+)
+
+// Event — dòng activity event (mirror activity.events; display fields
+// resolve best-effort lúc consume — nguồn: Kafka envelope, không còn REST ingest).
+type Event struct {
+	ID        uuid.UUID // envelope id do producer sinh — KHÓA IDEMPOTENCY
+	TaskID    uuid.UUID
+	UserID    uuid.UUID
+	Action    string
+	Timestamp time.Time
+	UserName  string
+	TaskTitle string
+}
+
+// Action constants — khớp enum ActivityFeedItem.action (activity.yaml) =
+// envelope type enum (contracts/events/task-events.md). 5 giá trị CHECK
+// constraint migration 0002.
+const (
+	ActionTaskCreated         = "task.created"
+	ActionTaskUpdated         = "task.updated"
+	ActionTaskDeleted         = "task.deleted"
+	ActionTaskAssigned        = "task.assigned"
+	ActionTaskAssignmentFailed = "task.assignment_failed"
+)
+
+// TaskStats — stats từ schema tasks (readonly, canonical DDL).
+type TaskStats struct {
+	TotalTasks int
+	ByStatus   map[string]int // todo / in_progress / done / assignment_failed — 4 giá trị CHECK (SF-2 cascade)
+}

package/stack-template/services/go-svc/internal/resolve/resolver.go

@@ -0,0 +1,134 @@
+// Package resolve — resolve userName qua spring-svc REST (GET /api/users/{id}).
+// Nguồn sự thật: platform/postgres/init/01-init.sh — go_readonly CHỈ được schema
+// tasks, userName KHÔNG đọc từ DB users mà qua spring (contract activity.yaml).
+// Best-effort + cache TTL; spring down → "" (degraded trung thực, không bịa).
+package resolve
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"sync"
+	"time"
+
+	"github.com/google/uuid"
+)
+
+const (
+	springTimeout = 2 * time.Second // ngang timeout node→spring (epic spec)
+	cacheTTL      = 5 * time.Minute
+)
+
+type cacheEntry struct {
+	name    string
+	expires time.Time
+}
+
+// Resolver resolve display name user với in-memory cache.
+type Resolver struct {
+	springURL string
+	client    *http.Client
+	mu        sync.RWMutex
+	cache     map[uuid.UUID]cacheEntry
+	tokens    *TokenSource // service-token cho consumer path (nil = chỉ REST caller path)
+}
+
+// New tạo resolver trỏ SPRING_SVC_URL.
+func New(springURL string) *Resolver {
+	return &Resolver{
+		springURL: springURL,
+		client:    &http.Client{Timeout: springTimeout},
+		cache:     make(map[uuid.UUID]cacheEntry),
+	}
+}
+
+// WithServiceToken gắn TokenSource (consumer path — go tự mang JWT service
+// user svc-activity, không có HTTP caller để passthrough Authorization).
+func (r *Resolver) WithServiceToken(ts *TokenSource) *Resolver {
+	r.tokens = ts
+	return r
+}
+
+// UserName trả display name (cache → spring REST → ""). authorization là
+// Bearer token của caller — passthrough vì spring tự verify JWT.
+func (r *Resolver) UserName(ctx context.Context, authorization string, userID uuid.UUID) string {
+	r.mu.RLock()
+	if e, ok := r.cache[userID]; ok && time.Now().Before(e.expires) {
+		r.mu.RUnlock()
+		return e.name
+	}
+	r.mu.RUnlock()
+
+	name := r.fetch(ctx, authorization, userID)
+
+	r.mu.Lock()
+	r.cache[userID] = cacheEntry{name: name, expires: time.Now().Add(cacheTTL)}
+	r.mu.Unlock()
+	return name
+}
+
+func (r *Resolver) fetch(ctx context.Context, authorization string, userID uuid.UUID) string {
+	name, status := r.fetchStatus(ctx, authorization, userID)
+	_ = status // REST caller path giữ semantics cũ — fail → ""
+	return name
+}
+
+// ServiceUserName — enrich userName CHO CONSUMER (story FI-76 SF-3): dùng
+// service-token thay caller Authorization; spring trả 401 (token hết hạn/
+// quay lại) → Invalidate + login lại đúng 1 lần rồi thử tiếp (lazy re-login).
+// Best-effort như UserName — fail → "" (degraded trung thực, không bịa).
+func (r *Resolver) ServiceUserName(ctx context.Context, userID uuid.UUID) string {
+	if r.tokens == nil {
+		return ""
+	}
+
+	r.mu.RLock()
+	if e, ok := r.cache[userID]; ok && time.Now().Before(e.expires) {
+		r.mu.RUnlock()
+		return e.name
+	}
+	r.mu.RUnlock()
+
+	name := ""
+	if tok, err := r.tokens.Token(ctx); err == nil {
+		var status int
+		name, status = r.fetchStatus(ctx, "Bearer "+tok, userID)
+		if status == http.StatusUnauthorized {
+			r.tokens.Invalidate()
+			if tok2, err2 := r.tokens.Token(ctx); err2 == nil {
+				name, _ = r.fetchStatus(ctx, "Bearer "+tok2, userID)
+			}
+		}
+	}
+
+	r.mu.Lock()
+	r.cache[userID] = cacheEntry{name: name, expires: time.Now().Add(cacheTTL)}
+	r.mu.Unlock()
+	return name
+}
+
+func (r *Resolver) fetchStatus(ctx context.Context, authorization string, userID uuid.UUID) (string, int) {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet,
+		r.springURL+"/api/users/"+userID.String(), nil)
+	if err != nil {
+		return "", 0
+	}
+	if authorization != "" {
+		req.Header.Set("Authorization", authorization)
+	}
+	res, err := r.client.Do(req)
+	if err != nil {
+		return "", 0
+	}
+	defer res.Body.Close()
+	if res.StatusCode != http.StatusOK {
+		return "", res.StatusCode
+	}
+	var body struct {
+		DisplayName string `json:"displayName"` // users.yaml User schema (required)
+	}
+	if err := json.NewDecoder(res.Body).Decode(&body); err != nil {
+		return "", res.StatusCode
+	}
+	return body.DisplayName, res.StatusCode
+}

package/stack-template/services/go-svc/internal/resolve/resolver_test.go

@@ -0,0 +1,82 @@
+package resolve
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/google/uuid"
+)
+
+func TestUserName_ResolvesFromSpring(t *testing.T) {
+	var gotAuth atomic.Value
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		gotAuth.Store(r.Header.Get("Authorization"))
+		if r.URL.Path != "/api/users/11111111-1111-4111-8111-111111111111" {
+			t.Errorf("path = %q", r.URL.Path)
+		}
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"id":"11111111-1111-4111-8111-111111111111","email":"alice@demo.local","displayName":"Alice Demo","roles":["admin"]}`))
+	}))
+	defer srv.Close()
+
+	r := New(srv.URL)
+	uid := uuid.MustParse("11111111-1111-4111-8111-111111111111")
+	if got := r.UserName(context.Background(), "Bearer tok", uid); got != "Alice Demo" {
+		t.Errorf("UserName = %q, want Alice Demo", got)
+	}
+	if got, _ := gotAuth.Load().(string); got != "Bearer tok" {
+		t.Errorf("Authorization passthrough = %q, want Bearer tok", got)
+	}
+}
+
+func TestUserName_CachesAfterFirstFetch(t *testing.T) {
+	var calls atomic.Int64
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		calls.Add(1)
+		_, _ = w.Write([]byte(`{"displayName":"Bob Demo"}`))
+	}))
+	defer srv.Close()
+
+	r := New(srv.URL)
+	uid := uuid.New()
+	_ = r.UserName(context.Background(), "", uid)
+	_ = r.UserName(context.Background(), "", uid)
+	_ = r.UserName(context.Background(), "", uid)
+	if calls.Load() != 1 {
+		t.Errorf("spring called %d times, want 1 (cache TTL)", calls.Load())
+	}
+}
+
+func TestUserName_SpringDownReturnsEmpty(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusServiceUnavailable)
+	}))
+	defer srv.Close()
+
+	r := New(srv.URL)
+	if got := r.UserName(context.Background(), "", uuid.New()); got != "" {
+		t.Errorf("UserName = %q, want \"\" (degraded, không bịa)", got)
+	}
+}
+
+func TestUserName_TimeoutReturnsEmpty(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		time.Sleep(3 * time.Second) // > springTimeout 2s
+		_, _ = w.Write([]byte(`{"displayName":"Slow"}`))
+	}))
+	defer srv.Close()
+
+	r := New(srv.URL)
+	start := time.Now()
+	got := r.UserName(context.Background(), "", uuid.New())
+	if got != "" {
+		t.Errorf("UserName = %q, want \"\"", got)
+	}
+	if elapsed := time.Since(start); elapsed > 3*time.Second {
+		t.Errorf("resolve took %v — timeout 2s không hiệu lực", elapsed)
+	}
+}