Studi Kasus SDD Golang: Order Service E-commerce dari Spec ke Merge

 1SHOP-456: [Order] Implementasikan fitur cancel order untuk customer
 2
 3Priority: P1 (High)
 4Sprint: 23
 5
 6Business Requirements:
 7- Customer bisa cancel order mereka sendiri
 8- Stok produk dikembalikan setelah cancel
 9- Customer mendapat notifikasi email
10
11Technical Notes:
12- Spec belum ditulis
13- Estimate: 1-2 hari
14
15Assignee: @andi

1$ cat CLAUDE.md | head -30
2# CLAUDE.md — Santekno Shop
3
4## Spec Process
5Every new feature MUST:
61. Have spec at specs/domain/[feature].md
72. Be reviewed (label: spec-review on PR)
83. Get approval BEFORE implementation starts
9...

 1Saya mau implement SHOP-456: cancel order feature untuk Santekno Shop.
 2Sebelum implementasi, saya perlu menulis spec.
 3
 4Context:
 5- Santekno Shop adalah e-commerce B2C Indonesia
 6- Order ada status: PENDING, CONFIRMED, SHIPPED, DELIVERED, CANCELLED
 7- Saat ini tidak ada mekanisme cancel
 8
 9Business requirements dari ticket:
10- Customer bisa cancel order mereka sendiri
11- Stok produk dikembalikan setelah cancel
12- Customer mendapat notifikasi email (via Notification Service via Kafka)
13
14Bantu saya draft spec untuk fitur ini.
15Gunakan template di specs/_templates/feature-spec.md.
16Ajukan pertanyaan klarifikasi yang perlu dijawab sebelum spec bisa ditulis.

 1Sebelum draft spec, ada beberapa hal yang perlu dikonfirmasi:
 2
 31. Cancel window: apakah ada batas waktu untuk cancel? Contoh: hanya bisa 
 4   cancel dalam 15 menit setelah order dibuat?
 5
 62. Status restriction: apakah hanya PENDING yang bisa di-cancel, atau 
 7   CONFIRMED juga bisa di-cancel dalam kondisi tertentu?
 8
 93. Refund: apakah ada proses refund terkait cancel? Atau hanya stock restore?
10
114. Concurrent cancel: jika dua request cancel masuk bersamaan, bagaimana 
12   yang seharusnya terjadi?
13
145. Admin cancel: apakah admin juga bisa cancel order customer? 
15   (beda scope dari customer cancel)

 1Jawaban setelah diskusi dengan @budi dan @maya:
 2
 31. Cancel window: 30 menit dari order created (updated dari awal 15 menit 
 4   berdasarkan user research yang ada)
 5
 62. Status: hanya PENDING yang bisa di-cancel. CONFIRMED sudah dalam 
 7   proses fulfillment.
 8
 93. Refund: tidak ada refund di scope ini (order belum ada payment flow). 
10   Hanya stock restore.
11
124. Concurrent: hanya satu yang berhasil, yang lain error.
13
145. Admin cancel: out of scope untuk ticket ini. Beda ticket.

 1Terima kasih. Dengan konfirmasi tersebut, draft spec untuk cancel order:
 2
 3- Cancel window: 30 menit dari order created
 4- Hanya status PENDING
 5- Tidak ada refund, hanya stock restore
 6- Concurrent: hanya satu berhasil
 7- Notification via Kafka event
 8- Customer cancel saja (bukan admin)
 9
10Format sesuai specs/_templates/feature-spec.md

 1git checkout -b spec/SHOP-456-cancel-order
 2git add specs/order/cancel-order.md
 3git commit -m "docs(spec): add cancel order spec SHOP-456
 4
 5Spec for customer cancel order feature:
 6- Cancel window: 30 minutes from order creation
 7- PENDING status only
 8- Stock restore on cancel
 9- ORDER_CANCELLED Kafka event
10- Concurrent cancel: first wins
11
12Status: DRAFT → pending review"
13
14git push origin spec/SHOP-456-cancel-order

 1Review dari @budi:
 2
 31. AC5 perlu lebih explicit: "stock restore" harus atomic
 4   Tambahkan: "dalam satu database transaction dengan status update"
 5
 62. EC1 (concurrent cancel) perlu dijelaskan implementation expectation:
 7   "Gunakan SELECT FOR UPDATE untuk prevent race condition"
 8
 93. NFR-P2: latency target terlalu longgar (500ms).
10   Saat ini kita sudah di 120ms untuk create order.
11   Suggest: p95 < 300ms untuk cancel (simpler operation)
12
13Review dari @maya:
14
154. AC di spec bilang "30 menit" tapi ticket original bilang "15 menit".
16   Konfirmasi yang dipakai adalah 30 menit (per user research terbaru)?

1@budi: Updated AC5, EC1, dan NFR-P2 — changes di-push.
2@maya: Ya, 30 menit per konfirmasi hari ini. Ticket akan di-update.

1# Spec PR di-merge ke main
2# Spec status: DRAFT → APPROVED

 1Spec cancel-order.md v1.0 sudah di-approve.
 2
 3SEBELUM menulis kode, buat implementation plan untuk:
 4- File yang dibuat/dimodifikasi
 5- SQL queries untuk CancelWithStockRestore
 6- DB migration yang diperlukan
 7- Dependency order
 8- Risks berdasarkan EC1-EC3 di spec
 9
10Referensi pola: internal/usecase/order/create_order.go
11
12Jangan tulis kode. Hanya plan.

1Di plan, kamu menyebut perlu interface baru EventPublisher.
2Apakah interface ini sudah ada di codebase?
3
4Cek di internal/domain/ dan internal/kafka/ apakah ada yang bisa dipakai.

1Berdasarkan plan, buat task breakdown dengan:
2- Estimasi waktu per task
3- Definition of Done untuk setiap task
4- Dependency order
5
6Target: setiap task 30-90 menit.

 1Task 1: Entity update [30 min] → entity.go: StatusCancelled + CanBeCancelled(30 min window)
 2Task 2: EventPublisher interface [20 min] → internal/domain/event/publisher.go
 3Task 3: Repository interface [20 min] → domain/order/repository.go: 2 new methods
 4Task 4: Mock regeneration [10 min] → mockgen untuk updated interface
 5Task 5: DB migration [15 min] → index: idx_orders_user_id_status
 6Task 6: Repository implementation [90 min] → SQL + transaction + SELECT FOR UPDATE
 7Task 7: UseCase implementation [60 min] → cancel_order.go dengan full business logic
 8Task 8: UseCase tests [75 min] → 7 test cases per AC/EC mapping
 9Task 9: HTTP handler [45 min] → CancelOrder handler di order_handler.go
10Task 10: Route registration [10 min] → router.go
11Task 11: Smoke test [20 min] → curl manual test
12
13Total estimate: ~6.5 jam

1Implementasikan Task 1: tambah ke internal/domain/order/entity.go:
21. StatusCancelled Status = "CANCELLED"
32. Method CanBeCancelled() bool
4   - return true jika Status == StatusPending 
5     AND time.Since(CreatedAt) < 30*time.Minute (sesuai spec v1.0)
6
7Spec reference: cancel-order.md v1.0 AC3, AC4

1go test ./internal/domain/order/...
2# OK, 100% pass
3git commit -m "feat(order): add StatusCancelled and CanBeCancelled method
4
5Implements:
6- cancel-order.md v1.0 AC3: PENDING status check
7- cancel-order.md v1.0 AC4: 30-minute cancellation window"

1Implementasikan Tasks 2-4:
21. Interface EventPublisher di internal/domain/event/publisher.go
3   Method: PublishOrderCancelled(ctx, orderID, userID uuid.UUID) error
4
52. Tambah ke OrderRepository interface:
6   - GetByIDAndUserID(ctx, orderID, userID uuid.UUID) (*Order, error)
7   - CancelWithStockRestore(ctx, orderID uuid.UUID) error
8
93. Regenerate mocks dengan mockgen

 1# migration dibuat manual
 2cat > migrations/20250701001_cancel_order_index.sql << 'EOF'
 3-- Cancel Order: add index for GetByIDAndUserID query
 4-- Spec: cancel-order.md v1.0 NFR performance
 5CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_orders_user_id_status 
 6ON orders(user_id, status) WHERE deleted_at IS NULL;
 7EOF
 8
 9# Test di local
10psql $DATABASE_URL -f migrations/20250701001_cancel_order_index.sql
11# \d orders → verify index exists
12
13git commit -m "feat(order): add index for cancel order query
14
15Supports GetByIDAndUserID performance
16Index: idx_orders_user_id_status on (user_id, status)"

 1Implementasikan dua method di internal/repository/postgres/order_repository.go:
 2
 31. GetByIDAndUserID — return nil, nil jika tidak ditemukan atau bukan owner
 4   Sesuai spec AC7, AC8: keduanya return error yang sama (security)
 5
 62. CancelWithStockRestore — transaction dengan SELECT FOR UPDATE
 7   Sesuai spec AC5: atomic, EC1: concurrent protection
 8
 9Referensi pola: GetByID method yang sudah ada untuk scan pattern.
10Referensi SQL: dari plan yang sudah kita buat.

1// Verify EC1 implementation:
2// SELECT id FROM orders WHERE id = $1 FOR UPDATE
3// → lock diperoleh, concurrent request akan wait
4// → setelah 3 detik timeout, lock expire dan request gagal

1// @andi manual addition: 3s timeout for lock acquisition (EC1 protection)
2cancelCtx, cancel := context.WithTimeout(ctx, 3*time.Second)
3defer cancel()
4err = tx.QueryRow(cancelCtx, `SELECT id FROM orders WHERE id = $1 FOR UPDATE`, orderID).Scan(&id)

 1# Integration test dengan test DB
 2go test -tags=integration ./internal/repository/postgres/...
 3# 3 tests pass
 4
 5git commit -m "feat(order): implement cancel order repository methods
 6
 7- GetByIDAndUserID: returns nil,nil for not found OR not owner (security)
 8- CancelWithStockRestore: atomic with SELECT FOR UPDATE (EC1)
 9
10Implements: cancel-order.md v1.0 AC2, AC5, EC1"

 1Implementasikan CancelOrderUseCase di internal/usecase/order/cancel_order.go.
 2
 3Sesuai spec cancel-order.md v1.0:
 4- Input: CancelOrderInput { OrderID, UserID uuid.UUID }
 5- Dependencies: OrderRepository, EventPublisher
 6- Flow: GetByIDAndUserID → CanBeCancelled check → CancelWithStockRestore → Publish
 7
 8Error types:
 9- ErrOrderNotFound (AC7, AC8)
10- OrderNotCancellableError { CurrentStatus } (AC9)
11- CancelWindowExpiredError (AC10)
12
13EC2: Kafka failure = log warning, tidak rollback cancel
14
15Pattern dari: internal/usecase/order/create_order.go

 1Implementasikan unit tests untuk CancelOrderUseCase.
 2
 3Tests yang diperlukan (sesuai mapping spec → test):
 41. TestCancelOrder_PendingOrder_Success → AC1-AC6
 52. TestCancelOrder_OrderNotFound → AC7
 63. TestCancelOrder_OrderNotOwnedByUser → AC8
 74. TestCancelOrder_ConfirmedOrder → AC9
 85. TestCancelOrder_WindowExpired → AC10
 96. TestCancelOrder_ConcurrentCancel_SecondFails → EC1 (via mock)
107. TestCancelOrder_KafkaFails_StillSucceeds → EC2
11
12Gunakan testify/suite + gomock
13Package: package order_test
14Reference: internal/usecase/order/create_order_test.go

 1go test -race -v -cover ./internal/usecase/order/...
 2
 3=== RUN TestCancelOrderUseCaseSuite
 4--- PASS: TestCancelOrder_PendingOrder_Success (0.001s)
 5--- PASS: TestCancelOrder_OrderNotFound (0.000s)
 6--- PASS: TestCancelOrder_OrderNotOwnedByUser (0.000s)
 7--- PASS: TestCancelOrder_ConfirmedOrder (0.001s)
 8--- PASS: TestCancelOrder_WindowExpired (0.001s)
 9--- PASS: TestCancelOrder_ConcurrentCancel_SecondFails (0.001s)
10--- PASS: TestCancelOrder_KafkaFails_StillSucceeds (0.001s)
11PASS
12coverage: 93.7% of statements in ./internal/usecase/order/...

 1Implementasikan CancelOrder method di internal/delivery/http/handler/order_handler.go
 2untuk Echo v4.
 3
 4Error mapping sesuai spec:
 5- ErrOrderNotFound → 404, error_code: "ORDER_NOT_FOUND"
 6- *OrderNotCancellableError → 409, error_code: dari error.ErrorCode()
 7- *CancelWindowExpiredError → 409, error_code: dari error.ErrorCode()
 8- Error lain → 500, log ErrorContext
 9
10Path param: :id (UUID)
11Auth: userID dari c.Get("userID").(uuid.UUID)
12Success: 204 No Content (spec AC6)

 1// Verify spec AC9 error code exact match
 2func (s *OrderHandlerSuite) TestCancelOrder_ConfirmedOrder_Returns409WithCorrectCode() {
 3    mockUC.EXPECT().Execute(gomock.Any(), gomock.Any()).
 4        Return(&cancelorder.OrderNotCancellableError{CurrentStatus: "CONFIRMED"})
 5    
 6    // ... execute ...
 7    
 8    var body map[string]interface{}
 9    json.Unmarshal(rec.Body.Bytes(), &body)
10    
11    // Spec compliance assertion — prevents spec drift
12    s.Equal("ORDER_NOT_CANCELLABLE", body["error_code"],
13        "error_code must match spec cancel-order.md AC9 exactly")
14}

1# Di internal/delivery/http/router/router.go
2# Tambah: DELETE /api/v1/orders/:id → handler.CancelOrder (dengan auth middleware)

 1# Start local server
 2go run cmd/server/main.go &
 3
 4# Test 1: Happy path
 5curl -X DELETE http://localhost:8080/api/v1/orders/$(PENDING_ORDER_ID) \
 6  -H "Authorization: Bearer $(TEST_JWT)"
 7# Expected: 204 No Content ✅
 8
 9# Test 2: Order not found
10curl -X DELETE http://localhost:8080/api/v1/orders/00000000-0000-0000-0000-000000000000 \
11  -H "Authorization: Bearer $(TEST_JWT)"
12# Expected: {"error_code":"ORDER_NOT_FOUND","message":"order not found"} ✅
13
14# Test 3: Already confirmed
15curl -X DELETE http://localhost:8080/api/v1/orders/$(CONFIRMED_ORDER_ID) \
16  -H "Authorization: Bearer $(TEST_JWT)"
17# Expected: {"error_code":"ORDER_NOT_CANCELLABLE","message":"order cannot be cancelled: status is CONFIRMED"} ✅
18
19# Test 4: No auth
20curl -X DELETE http://localhost:8080/api/v1/orders/$(PENDING_ORDER_ID)
21# Expected: {"error_code":"UNAUTHORIZED","message":"authentication required"} ✅

 1Lakukan spec compliance final check.
 2
 3Spec: specs/order/cancel-order.md v1.0
 4
 5Files yang diimplementasikan:
 6- internal/domain/order/entity.go (CanBeCancelled)
 7- internal/usecase/order/cancel_order.go (full usecase)
 8- internal/repository/postgres/order_repository.go (2 new methods)
 9- internal/delivery/http/handler/order_handler.go (CancelOrder)
10- internal/delivery/http/router/router.go (new route)
11
12Untuk setiap AC (AC1-AC10) dan EC (EC1-EC3):
13- Di mana terimplementasikan?
14- Apakah ada test yang cover?
15- Apakah ada gap?

 1## Cancel Order Feature — SHOP-456
 2
 3### Summary
 4Implementasi cancel order endpoint untuk customer.
 5Customer bisa cancel order yang masih dalam status PENDING 
 6dalam 30 menit setelah order dibuat.
 7
 8### Spec Reference
 9- **Spec file:** specs/order/cancel-order.md
10- **Spec version:** v1.0
11- **Spec status:** APPROVED (by @budi + @maya, 2025-07-01)
12- **PR:** #231 (spec PR)
13
14### Spec Compliance
15Semua AC (AC1-AC10) ter-implement. 2/3 EC fully covered.
16
17| AC/EC | Status | Notes |
18|-------|--------|-------|
19| AC1-AC6 (happy path) | ✅ | Full implementation |
20| AC7, AC8 | ✅ | Security: same error for not-found and not-owner |
21| AC9 | ✅ | OrderNotCancellableError → 409 |
22| AC10 | ✅ | CancelWindowExpiredError → 409 |
23| EC1 | ✅ | SELECT FOR UPDATE in transaction |
24| EC2 | ✅ | Best effort Kafka + log warning |
25| EC3 | ⚠️ | Context from HTTP middleware covers this. Tracked: JIRA-789 |
26
27### Test Coverage
28coverage: 93.7% of statements in ./internal/usecase/order/...
29
30### Changes
31- internal/domain/order/entity.go → StatusCancelled, CanBeCancelled()
32- internal/domain/event/publisher.go → EventPublisher interface (new)
33- internal/domain/order/repository.go → 2 new interface methods
34- internal/repository/postgres/order_repository.go → 2 new implementations
35- internal/usecase/order/cancel_order.go → full usecase (new)
36- internal/usecase/order/cancel_order_test.go → 7 test cases (new)
37- internal/delivery/http/handler/order_handler.go → CancelOrder method
38- internal/delivery/http/router/router.go → route registration
39- migrations/20250701001_cancel_order_index.sql → performance index
40
41### Checklist
42- [x] Spec compliance self-review done
43- [x] All high-priority AC/EC have tests (EC3 tracked separately)
44- [x] Error codes match spec exactly
45- [x] HTTP status codes match spec
46- [x] No sensitive data in logs
47- [x] Migration added with CONCURRENTLY for zero-downtime

 1@budi review — General:
 2✅ Spec compliance sangat baik. Semua AC ter-cover.
 3✅ Error codes match spec exactly (cek AC9 dan AC10).
 4✅ Test coverage 93.7% melewati target 85%.
 5
 6@budi review — Technical:
 71. ⚠️ Line 87 di order_handler.go: userID extraction tidak ada nil check
 8   jika middleware tidak set "userID" key.
 9   
10   Current:
11   userID, ok := c.Get("userID").(uuid.UUID)
12   if !ok {
13       return c.JSON(http.StatusInternalServerError, ...)
14   }
15   
16   Ini OK untuk sekarang karena middleware wajib, tapi tambahkan comment
17   tentang assumption ini.
18
192. ✅ SELECT FOR UPDATE implementation di repo — sangat bagus.
20   Sama persis dengan pola yang direkomendasikan di ADR-003.
21
223. 💬 Suggestion (non-blocking): di cancel_order.go baris 68,
23   bisa extract context key "userID" ke constant untuk avoid magic string.

1@budi: 
21. Updated — ditambahkan comment tentang middleware assumption
32. Thanks!
43. Good point, extracted ke OrderHandlerContextKey constant. Update pushed.

1Status: SHOP-456 → Done
2Note: Implementation merged to main branch.
3Spec: specs/order/cancel-order.md updated to ACTIVE status.
4Migration will run automatically via deployment pipeline.
5Known gap: EC3 tracked in JIRA-789

1# specs/order/cancel-order.md
2
3## Status: ACTIVE
4**Implemented in:** PR #232
5**Merged:** 2025-07-01
6**Deploy:** Staging (auto), Production (next release cycle)

1Slack #engineering:
2"🚀 SHOP-456 merged: Cancel Order feature is now in main.
3Spec: cancel-order.md v1.0
4Coverage: 93.7%
5Will deploy to staging via CD pipeline.
6Known gap: EC3 (DB timeout) tracked in JIRA-789"

 1Fase 1 — Menulis Spec:              2 jam (termasuk klarifikasi dengan PM)
 2Fase 2 — Spec Review:               2 jam (review + revisi + approval)
 3Fase 3 — Plan Mode:                 30 menit
 4Fase 4 — Task Breakdown:            20 menit
 5Fase 5-6 — Implementasi:            5 jam
 6Fase 7 — Final Compliance Check:    20 menit
 7Fase 8 — PR:                        30 menit
 8Fase 9 — Code Review:               1.5 jam (review + revisi + approval)
 9Fase 10 — Post-merge:               20 menit
10
11Total: ~12.5 jam (sekitar 1.5 hari kerja)

 1Tanpa SDD:
 2- Implementasi awal: 3 jam
 3- PR #1: "implement cancel order"
 4- Review comments:
 5  "Apa yang terjadi jika cancel setelah 30 menit?" → revisi
 6  "Kenapa timeout 15 menit bukan 30?" → revisi, diskusi dengan PM
 7  "EC1 concurrent cancel tidak di-handle" → revisi
 8  "Test coverage hanya 45%" → tambah test
 9- PR #2 (revisi): 2 jam lagi
10- Review #2: "Error code 'NOT_CANCELLABLE' harusnya 'ORDER_NOT_CANCELLABLE'" → revisi lagi
11- PR #3: 1 jam
12
13Total: ~6 jam + lebih banyak back-and-forth
14Coverage: 45-60% (common untuk code-first approach)
15Keputusan bisnis (30 menit window): mungkin di-discover di review, bukan di awal

 1Step 1: Setup
 2- Buat atau update CLAUDE.md dengan spec rules
 3- Buat template spec di specs/_templates/feature-spec.md
 4- Setup PR template dengan spec reference section
 5
 6Step 2: Pilih fitur kecil sebagai pilot
 7- Pilih fitur yang belum di-implement tapi sudah clear business requirements
 8- Jangan mulai dengan fitur yang paling complex
 9
10Step 3: Follow the workflow
111. Klarifikasi dengan stakeholder
122. Tulis spec dengan Claude Code
133. Spec review (minimal tech lead)
144. Plan Mode → task breakdown
155. Implementasi incremental
166. Test dari spec
177. Spec compliance final check
188. PR dengan spec reference
199. Code review (spec + code)
20
21Step 4: Retrospective setelah pilot
22- Apa yang berjalan baik?
23- Apa yang perlu disesuaikan untuk tim kamu?
24- Update CLAUDE.md dan template

 1AI:
 2- Claude Code (claude-sonnet-4-20250514)
 3
 4Testing:
 5- go test -race -cover
 6- testify/suite v1.9
 7- gomock v1.6
 8
 9Quality:
10- golangci-lint (standard config)
11
12Database:
13- PostgreSQL 15 (local via Docker)
14
15Version Control:
16- Git dengan conventional commits
17- Branch per spec + per implementation
18
19Documentation:
20- Markdown untuk spec
21- PR template di GitHub

 1Setelah PR #232 di-merge, roadmap selanjutnya untuk fitur ini:
 2
 3Sprint 24:
 4- JIRA-789: EC3 explicit DB timeout implementation
 5- JIRA-790: Idempotency key untuk retry-safe cancel
 6
 7Sprint 25:
 8- JIRA-791: Rate limiting untuk cancel (5 per user per jam)
 9- Load test untuk verify NFR-P2 (p95 < 300ms)
10
11Sprint 26:
12- Admin cancel order (separate spec, separate implementation)
13- Analytics dashboard update untuk cancel rate