From a3cb7dd5fd27649eba533202751437ab29ff49a8 Mon Sep 17 00:00:00 2001 From: efrilm Date: Wed, 30 Sep 2026 18:12:26 +0700 Subject: [PATCH 1/5] fix(customer-auth): register customers into the app's organization Registration put every new customer into a hardcoded organization id, which does not exist in staging, so set-password failed on the fk_customers_organization foreign key with a 500. POST /customer-auth/register/start now takes organization_id, the organization the app is built for. It must be a UUID of an existing organization, checked before the OTP is sent; it is kept in the OTP session and set-password creates the customer there. A registration started before this change has no organization in its session and is asked to start again. Co-Authored-By: Claude Opus 5.5 --- internal/contract/customer_auth_contract.go | 3 +++ internal/processor/customer_auth_processor.go | 24 +++++++++++++++++-- .../repository/customer_auth_repository.go | 12 ++++++++++ internal/validator/customer_auth_validator.go | 7 ++++++ 4 files changed, 44 insertions(+), 2 deletions(-) diff --git a/internal/contract/customer_auth_contract.go b/internal/contract/customer_auth_contract.go index 47547d5..b7501f7 100644 --- a/internal/contract/customer_auth_contract.go +++ b/internal/contract/customer_auth_contract.go @@ -16,6 +16,9 @@ type RegisterStartRequest struct { PhoneNumber string `json:"phone_number" binding:"required"` Name string `json:"name" binding:"required"` BirthDate string `json:"birth_date" binding:"required"` + // The organization (brand) the customer registers with. A customer belongs to one + // organization; the app sends the one it is built for. + OrganizationID string `json:"organization_id" binding:"required"` } type RegisterVerifyOtpRequest struct { diff --git a/internal/processor/customer_auth_processor.go b/internal/processor/customer_auth_processor.go index b2c15b6..57356b0 100644 --- a/internal/processor/customer_auth_processor.go +++ b/internal/processor/customer_auth_processor.go @@ -3,6 +3,7 @@ package processor import ( "context" "fmt" + "strings" "time" "apskel-pos-be/internal/contract" @@ -142,6 +143,20 @@ func (p *customerAuthProcessor) StartRegistration(ctx context.Context, req *cont return nil, fmt.Errorf("phone number already registered") } + // The customer joins the organization the app is built for. Check it exists now, + // before an OTP is sent, rather than failing on a foreign key at the last step. + organizationID, err := uuid.Parse(strings.TrimSpace(req.OrganizationID)) + if err != nil { + return nil, fmt.Errorf("organization_id must be a valid UUID") + } + orgExists, err := p.customerAuthRepo.OrganizationExists(ctx, organizationID) + if err != nil { + return nil, err + } + if !orgExists { + return nil, fmt.Errorf("organization not found") + } + // Generate registration token and create OTP session registrationToken := uuid.New().String() @@ -156,6 +171,7 @@ func (p *customerAuthProcessor) StartRegistration(ctx context.Context, req *cont "registration_token": registrationToken, "name": req.Name, "birth_date": req.BirthDate, + "organization_id": organizationID.String(), "step": "otp_sent", } @@ -294,10 +310,14 @@ func (p *customerAuthProcessor) SetPassword(ctx context.Context, req *contract.R return nil, fmt.Errorf("invalid birth date format: %w", err) } - defaultOrgID := uuid.MustParse("87bec7c1-e274-4f66-bac5-84e632208470") // This should be configurable + orgIDStr, _ := otpSession.Metadata["organization_id"].(string) + organizationID, err := uuid.Parse(orgIDStr) + if err != nil { + return nil, fmt.Errorf("invalid registration data: organization not found, start the registration again") + } customer := &entities.Customer{ - OrganizationID: defaultOrgID, + OrganizationID: organizationID, Name: name, PhoneNumber: &otpSession.PhoneNumber, BirthDate: &birthDate, diff --git a/internal/repository/customer_auth_repository.go b/internal/repository/customer_auth_repository.go index c2132cd..58fd1f6 100644 --- a/internal/repository/customer_auth_repository.go +++ b/internal/repository/customer_auth_repository.go @@ -6,6 +6,7 @@ import ( "apskel-pos-be/internal/entities" + "github.com/google/uuid" "gorm.io/gorm" ) @@ -16,6 +17,8 @@ type CustomerAuthRepository interface { UpdateCustomer(ctx context.Context, customer *entities.Customer) error CheckPhoneNumberExists(ctx context.Context, phoneNumber string) (bool, error) SetCustomerPassword(ctx context.Context, customerID string, passwordHash string) error + // OrganizationExists reports whether an organization with this id exists. + OrganizationExists(ctx context.Context, organizationID uuid.UUID) (bool, error) } type customerAuthRepository struct { @@ -78,3 +81,12 @@ func (r *customerAuthRepository) SetCustomerPassword(ctx context.Context, custom } return nil } + +func (r *customerAuthRepository) OrganizationExists(ctx context.Context, organizationID uuid.UUID) (bool, error) { + var count int64 + err := r.db.WithContext(ctx).Table("organizations").Where("id = ?", organizationID).Count(&count).Error + if err != nil { + return false, fmt.Errorf("failed to check organization: %w", err) + } + return count > 0, nil +} diff --git a/internal/validator/customer_auth_validator.go b/internal/validator/customer_auth_validator.go index 7497eab..51df18f 100644 --- a/internal/validator/customer_auth_validator.go +++ b/internal/validator/customer_auth_validator.go @@ -5,6 +5,8 @@ import ( "regexp" "strings" + "github.com/google/uuid" + "apskel-pos-be/internal/constants" "apskel-pos-be/internal/contract" ) @@ -68,6 +70,11 @@ func (v *CustomerAuthValidatorImpl) ValidateRegisterStartRequest(req *contract.R return errors.New("name cannot exceed 100 characters"), constants.ValidationErrorCode } + // Validate organization + if _, err := uuid.Parse(strings.TrimSpace(req.OrganizationID)); err != nil { + return errors.New("organization_id must be a valid UUID"), constants.ValidationErrorCode + } + // Validate birth date if strings.TrimSpace(req.BirthDate) == "" { return errors.New("birth date is required"), constants.ValidationErrorCode From 8bf2fe55850d91201461fc883c99e239d19f58a0 Mon Sep 17 00:00:00 2001 From: efrilm Date: Wed, 30 Sep 2026 18:16:31 +0700 Subject: [PATCH 2/5] fix(customer-auth): make organization_id optional at registration Requiring organization_id broke the current app, which does not send it. When it is left out and the database has exactly one organization, the customer now joins that one, so the app works unchanged. A sent organization_id must still exist, and with several organizations and none sent registration is refused with a clear message. Co-Authored-By: Claude Opus 5.5 --- internal/contract/customer_auth_contract.go | 5 +- internal/processor/customer_auth_processor.go | 47 +++++++++++++++---- .../repository/customer_auth_repository.go | 11 +++++ internal/validator/customer_auth_validator.go | 6 ++- 4 files changed, 55 insertions(+), 14 deletions(-) diff --git a/internal/contract/customer_auth_contract.go b/internal/contract/customer_auth_contract.go index b7501f7..56d28dc 100644 --- a/internal/contract/customer_auth_contract.go +++ b/internal/contract/customer_auth_contract.go @@ -17,8 +17,9 @@ type RegisterStartRequest struct { Name string `json:"name" binding:"required"` BirthDate string `json:"birth_date" binding:"required"` // The organization (brand) the customer registers with. A customer belongs to one - // organization; the app sends the one it is built for. - OrganizationID string `json:"organization_id" binding:"required"` + // organization. Optional: when it is left out and the database has exactly one + // organization, the customer joins that one. + OrganizationID string `json:"organization_id,omitempty"` } type RegisterVerifyOtpRequest struct { diff --git a/internal/processor/customer_auth_processor.go b/internal/processor/customer_auth_processor.go index 57356b0..02b59f9 100644 --- a/internal/processor/customer_auth_processor.go +++ b/internal/processor/customer_auth_processor.go @@ -143,19 +143,12 @@ func (p *customerAuthProcessor) StartRegistration(ctx context.Context, req *cont return nil, fmt.Errorf("phone number already registered") } - // The customer joins the organization the app is built for. Check it exists now, - // before an OTP is sent, rather than failing on a foreign key at the last step. - organizationID, err := uuid.Parse(strings.TrimSpace(req.OrganizationID)) - if err != nil { - return nil, fmt.Errorf("organization_id must be a valid UUID") - } - orgExists, err := p.customerAuthRepo.OrganizationExists(ctx, organizationID) + // Resolve the organization before an OTP is sent, rather than failing on a foreign + // key at the last step. + organizationID, err := p.registrationOrganization(ctx, req.OrganizationID) if err != nil { return nil, err } - if !orgExists { - return nil, fmt.Errorf("organization not found") - } // Generate registration token and create OTP session registrationToken := uuid.New().String() @@ -458,3 +451,37 @@ func (p *customerAuthProcessor) ResendOtp(ctx context.Context, req *contract.Res } // Helper functions - OTP generation is now handled by OtpProcessor + +// registrationOrganization is the organization a new customer joins: the one the app +// sent, which must exist, or, when the app sent none, the only organization there is. +// With several organizations and none sent there is no way to choose, so it refuses. +func (p *customerAuthProcessor) registrationOrganization(ctx context.Context, requested string) (uuid.UUID, error) { + requested = strings.TrimSpace(requested) + if requested != "" { + id, err := uuid.Parse(requested) + if err != nil { + return uuid.Nil, fmt.Errorf("organization_id must be a valid UUID") + } + exists, err := p.customerAuthRepo.OrganizationExists(ctx, id) + if err != nil { + return uuid.Nil, err + } + if !exists { + return uuid.Nil, fmt.Errorf("organization not found") + } + return id, nil + } + + ids, err := p.customerAuthRepo.OrganizationIDs(ctx, 2) + if err != nil { + return uuid.Nil, err + } + switch len(ids) { + case 1: + return ids[0], nil + case 0: + return uuid.Nil, fmt.Errorf("no organization exists to register customers into") + default: + return uuid.Nil, fmt.Errorf("organization_id is required: there is more than one organization") + } +} diff --git a/internal/repository/customer_auth_repository.go b/internal/repository/customer_auth_repository.go index 58fd1f6..56319d9 100644 --- a/internal/repository/customer_auth_repository.go +++ b/internal/repository/customer_auth_repository.go @@ -19,6 +19,8 @@ type CustomerAuthRepository interface { SetCustomerPassword(ctx context.Context, customerID string, passwordHash string) error // OrganizationExists reports whether an organization with this id exists. OrganizationExists(ctx context.Context, organizationID uuid.UUID) (bool, error) + // OrganizationIDs returns up to limit organization ids. + OrganizationIDs(ctx context.Context, limit int) ([]uuid.UUID, error) } type customerAuthRepository struct { @@ -90,3 +92,12 @@ func (r *customerAuthRepository) OrganizationExists(ctx context.Context, organiz } return count > 0, nil } + +func (r *customerAuthRepository) OrganizationIDs(ctx context.Context, limit int) ([]uuid.UUID, error) { + var ids []uuid.UUID + err := r.db.WithContext(ctx).Table("organizations").Order("created_at").Limit(limit).Pluck("id", &ids).Error + if err != nil { + return nil, fmt.Errorf("failed to list organizations: %w", err) + } + return ids, nil +} diff --git a/internal/validator/customer_auth_validator.go b/internal/validator/customer_auth_validator.go index 51df18f..a62f459 100644 --- a/internal/validator/customer_auth_validator.go +++ b/internal/validator/customer_auth_validator.go @@ -71,8 +71,10 @@ func (v *CustomerAuthValidatorImpl) ValidateRegisterStartRequest(req *contract.R } // Validate organization - if _, err := uuid.Parse(strings.TrimSpace(req.OrganizationID)); err != nil { - return errors.New("organization_id must be a valid UUID"), constants.ValidationErrorCode + if orgID := strings.TrimSpace(req.OrganizationID); orgID != "" { + if _, err := uuid.Parse(orgID); err != nil { + return errors.New("organization_id must be a valid UUID"), constants.ValidationErrorCode + } } // Validate birth date From c1ec6a3dfde9e745e8bff2c53ebe678b849fb447 Mon Sep 17 00:00:00 2001 From: efrilm Date: Wed, 30 Sep 2026 19:21:13 +0700 Subject: [PATCH 3/5] feat(customer): list the customer's outlets Adds GET /customer/outlets for the customer app: the active outlets of the customer's organization, where their EnakPoint and EnakCoin can be used, sorted by name. Each carries its name and address, and from the outlet's loyalty settings whether the cashier accepts EnakPoint and whether orders there earn EnakPoint or EnakCoin. Nothing internal (printer settings, tax rate) is exposed. The outlets list under /outlets needs a staff token, so the app had no way to show where the wallet works. Co-Authored-By: Claude Opus 5.5 --- internal/app/app.go | 5 ++ internal/handler/customer_outlet_handler.go | 26 +++++++ internal/models/customer_outlet.go | 16 ++++ .../processor/customer_outlet_processor.go | 49 ++++++++++++ .../customer_outlet_processor_test.go | 77 +++++++++++++++++++ .../repository/customer_outlet_repository.go | 60 +++++++++++++++ internal/router/router.go | 5 +- internal/router/router_test.go | 1 + internal/service/customer_outlet_service.go | 40 ++++++++++ 9 files changed, 278 insertions(+), 1 deletion(-) create mode 100644 internal/handler/customer_outlet_handler.go create mode 100644 internal/models/customer_outlet.go create mode 100644 internal/processor/customer_outlet_processor.go create mode 100644 internal/processor/customer_outlet_processor_test.go create mode 100644 internal/repository/customer_outlet_repository.go create mode 100644 internal/service/customer_outlet_service.go diff --git a/internal/app/app.go b/internal/app/app.go index 0e04b7e..9ea2e47 100644 --- a/internal/app/app.go +++ b/internal/app/app.go @@ -165,6 +165,7 @@ func (a *App) Initialize(cfg *config.Config) error { services.customerOrderPaymentService, services.customerWalletService, services.customerDeviceService, + services.customerOutletService, a.redisClient, ) @@ -403,6 +404,7 @@ type processors struct { walletTransferProcessor *processor.WalletTransferProcessor walletTraceProcessor *processor.WalletTraceProcessor customerDeviceProcessor *processor.CustomerDeviceProcessor + customerOutletProcessor *processor.CustomerOutletProcessor } func (a *App) initProcessors(cfg *config.Config, repos *repositories) *processors { @@ -484,6 +486,7 @@ func (a *App) initProcessors(cfg *config.Config, repos *repositories) *processor walletTransferProcessor: walletTransferProcessor, walletTraceProcessor: processor.NewWalletTraceProcessor(repository.NewWalletTraceRepository(a.db)), customerDeviceProcessor: customerDeviceProcessor, + customerOutletProcessor: processor.NewCustomerOutletProcessor(repository.NewCustomerOutletRepository(a.db), loyaltySettingsProcessor), walletAdminProcessor: processor.NewWalletAdminProcessor(repository.NewWalletAdminRepository(a.db), repos.walletQueryRepo, processor.NewWalletProcessor(repos.walletRepo), loyaltySettingsProcessor, repos.txManager), } } @@ -534,6 +537,7 @@ type services struct { customerOrderPaymentService *service.CustomerOrderPaymentServiceImpl customerWalletService *service.CustomerWalletServiceImpl customerDeviceService *service.CustomerDeviceServiceImpl + customerOutletService *service.CustomerOutletServiceImpl } func (a *App) initServices(processors *processors, repos *repositories, cfg *config.Config) *services { @@ -622,6 +626,7 @@ func (a *App) initServices(processors *processors, repos *repositories, cfg *con customerOrderPaymentService: service.NewCustomerOrderPaymentService(processors.orderProcessor), customerWalletService: service.NewCustomerWalletService(processors.walletExchangeProcessor, processors.walletTransferProcessor), customerDeviceService: service.NewCustomerDeviceService(processors.customerDeviceProcessor), + customerOutletService: service.NewCustomerOutletService(processors.customerOutletProcessor), } } diff --git a/internal/handler/customer_outlet_handler.go b/internal/handler/customer_outlet_handler.go new file mode 100644 index 0000000..9bd9245 --- /dev/null +++ b/internal/handler/customer_outlet_handler.go @@ -0,0 +1,26 @@ +package handler + +import ( + "github.com/gin-gonic/gin" + + "apskel-pos-be/internal/service" + "apskel-pos-be/internal/util" +) + +// CustomerOutletHandler serves GET /customer/outlets. +type CustomerOutletHandler struct { + outlets service.CustomerOutletService +} + +func NewCustomerOutletHandler(outlets service.CustomerOutletService) *CustomerOutletHandler { + return &CustomerOutletHandler{outlets: outlets} +} + +// List returns the active outlets of the customer's organization. +func (h *CustomerOutletHandler) List(c *gin.Context) { + customerID, ok := customerIDFromGin(c, "CustomerOutletHandler::List") + if !ok { + return + } + util.HandleResponse(c.Writer, c.Request, h.outlets.List(c.Request.Context(), customerID), "CustomerOutletHandler::List") +} diff --git a/internal/models/customer_outlet.go b/internal/models/customer_outlet.go new file mode 100644 index 0000000..191266d --- /dev/null +++ b/internal/models/customer_outlet.go @@ -0,0 +1,16 @@ +package models + +import "github.com/google/uuid" + +// CustomerOutlet is one outlet in GET /customer/outlets: where the customer can shop, +// and what the outlet does with EnakPoint and EnakCoin. +type CustomerOutlet struct { + ID uuid.UUID `json:"id"` + Name string `json:"name"` + Address *string `json:"address"` + // The cashier accepts EnakPoint as payment here. + AcceptsPointPayment bool `json:"accepts_point_payment"` + // Orders here earn EnakPoint / EnakCoin. + EarnsPoints bool `json:"earns_points"` + EarnsCoins bool `json:"earns_coins"` +} diff --git a/internal/processor/customer_outlet_processor.go b/internal/processor/customer_outlet_processor.go new file mode 100644 index 0000000..79c65a1 --- /dev/null +++ b/internal/processor/customer_outlet_processor.go @@ -0,0 +1,49 @@ +package processor + +import ( + "context" + + "github.com/google/uuid" + + "apskel-pos-be/internal/models" + "apskel-pos-be/internal/repository" +) + +// CustomerOutletProcessor lists the outlets the customer app shows: the active +// outlets of the customer's organization, where their wallet can be used (K4). +type CustomerOutletProcessor struct { + repo repository.CustomerOutletRepository + settings outletSettingsReader +} + +func NewCustomerOutletProcessor(repo repository.CustomerOutletRepository, settings outletSettingsReader) *CustomerOutletProcessor { + return &CustomerOutletProcessor{repo: repo, settings: settings} +} + +// List is GET /customer/outlets. +func (p *CustomerOutletProcessor) List(ctx context.Context, customerID uuid.UUID) ([]models.CustomerOutlet, error) { + organizationID, err := p.repo.CustomerOrganizationID(ctx, customerID) + if err != nil { + return nil, err + } + outlets, err := p.repo.ListActiveOutlets(ctx, organizationID) + if err != nil { + return nil, err + } + list := make([]models.CustomerOutlet, 0, len(outlets)) + for _, o := range outlets { + settings, err := p.settings.Outlet(ctx, o.ID) + if err != nil { + return nil, err + } + list = append(list, models.CustomerOutlet{ + ID: o.ID, + Name: o.Name, + Address: o.Address, + AcceptsPointPayment: settings.PointPayment.AcceptPayment, + EarnsPoints: settings.Point.Enabled, + EarnsCoins: settings.Coin.Enabled, + }) + } + return list, nil +} diff --git a/internal/processor/customer_outlet_processor_test.go b/internal/processor/customer_outlet_processor_test.go new file mode 100644 index 0000000..8f05519 --- /dev/null +++ b/internal/processor/customer_outlet_processor_test.go @@ -0,0 +1,77 @@ +package processor + +import ( + "context" + "testing" + + "github.com/google/uuid" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "apskel-pos-be/internal/models" + "apskel-pos-be/internal/repository" +) + +type customerOutletRepoFake struct { + orgs map[uuid.UUID]uuid.UUID + outlets map[uuid.UUID][]repository.CustomerOutlet +} + +func (f customerOutletRepoFake) CustomerOrganizationID(_ context.Context, id uuid.UUID) (uuid.UUID, error) { + org, ok := f.orgs[id] + if !ok { + return uuid.Nil, repository.ErrWalletNotFound + } + return org, nil +} + +func (f customerOutletRepoFake) ListActiveOutlets(_ context.Context, org uuid.UUID) ([]repository.CustomerOutlet, error) { + return f.outlets[org], nil +} + +type outletSettingsFake map[uuid.UUID]models.OutletLoyaltySettings + +func (f outletSettingsFake) Outlet(_ context.Context, id uuid.UUID) (*models.OutletLoyaltySettings, error) { + s := f[id] + return &s, nil +} + +func TestCustomerOutlets_ListsTheCustomersOrganizationWithLoyaltyFlags(t *testing.T) { + customer, org, other := uuid.New(), uuid.New(), uuid.New() + kemang, blokm := uuid.New(), uuid.New() + addr := "Jl. Kemang Raya 10" + repo := customerOutletRepoFake{ + orgs: map[uuid.UUID]uuid.UUID{customer: org}, + outlets: map[uuid.UUID][]repository.CustomerOutlet{ + org: {{ID: blokm, Name: "Blok M"}, {ID: kemang, Name: "Kemang", Address: &addr}}, + other: {{ID: uuid.New(), Name: "Not mine"}}, + }, + } + settings := outletSettingsFake{ + kemang: { + Point: models.LoyaltyEarnSettings{Enabled: true}, + PointPayment: models.LoyaltyPointPaymentSettings{AcceptPayment: true}, + }, + } + + got, err := NewCustomerOutletProcessor(repo, settings).List(context.Background(), customer) + require.NoError(t, err) + assert.Equal(t, []models.CustomerOutlet{ + {ID: blokm, Name: "Blok M"}, + {ID: kemang, Name: "Kemang", Address: &addr, AcceptsPointPayment: true, EarnsPoints: true}, + }, got) +} + +func TestCustomerOutlets_UnknownCustomer(t *testing.T) { + _, err := NewCustomerOutletProcessor(customerOutletRepoFake{}, outletSettingsFake{}).List(context.Background(), uuid.New()) + assert.ErrorIs(t, err, repository.ErrWalletNotFound) +} + +func TestCustomerOutlets_NoOutletsIsAnEmptyList(t *testing.T) { + customer := uuid.New() + repo := customerOutletRepoFake{orgs: map[uuid.UUID]uuid.UUID{customer: uuid.New()}} + got, err := NewCustomerOutletProcessor(repo, outletSettingsFake{}).List(context.Background(), customer) + require.NoError(t, err) + assert.NotNil(t, got) + assert.Empty(t, got) +} diff --git a/internal/repository/customer_outlet_repository.go b/internal/repository/customer_outlet_repository.go new file mode 100644 index 0000000..9013548 --- /dev/null +++ b/internal/repository/customer_outlet_repository.go @@ -0,0 +1,60 @@ +package repository + +import ( + "context" + "errors" + "fmt" + + "github.com/google/uuid" + "gorm.io/gorm" +) + +// CustomerOutlet is what the customer app may see of an outlet. +type CustomerOutlet struct { + ID uuid.UUID + Name string + Address *string +} + +// CustomerOutletRepository reads the outlets a customer can visit: the active outlets +// of their organization. +type CustomerOutletRepository interface { + // CustomerOrganizationID returns ErrWalletNotFound when the customer does not exist. + CustomerOrganizationID(ctx context.Context, customerID uuid.UUID) (uuid.UUID, error) + // ListActiveOutlets returns the organization's active outlets, by name. + ListActiveOutlets(ctx context.Context, organizationID uuid.UUID) ([]CustomerOutlet, error) +} + +type customerOutletRepository struct { + db *gorm.DB +} + +func NewCustomerOutletRepository(db *gorm.DB) CustomerOutletRepository { + return &customerOutletRepository{db: db} +} + +func (r *customerOutletRepository) CustomerOrganizationID(ctx context.Context, customerID uuid.UUID) (uuid.UUID, error) { + var row struct{ OrganizationID uuid.UUID } + err := DBFromContext(ctx, r.db).WithContext(ctx). + Table("customers").Select("organization_id").Where("id = ?", customerID).Take(&row).Error + if err != nil { + if errors.Is(err, gorm.ErrRecordNotFound) { + return uuid.Nil, ErrWalletNotFound + } + return uuid.Nil, fmt.Errorf("failed to get customer organization: %w", err) + } + return row.OrganizationID, nil +} + +func (r *customerOutletRepository) ListActiveOutlets(ctx context.Context, organizationID uuid.UUID) ([]CustomerOutlet, error) { + var outlets []CustomerOutlet + err := DBFromContext(ctx, r.db).WithContext(ctx). + Table("outlets").Select("id, name, address"). + Where("organization_id = ? AND is_active = ?", organizationID, true). + Order("name, id"). + Scan(&outlets).Error + if err != nil { + return nil, fmt.Errorf("failed to list outlets: %w", err) + } + return outlets, nil +} diff --git a/internal/router/router.go b/internal/router/router.go index f72a8c5..cf77c39 100644 --- a/internal/router/router.go +++ b/internal/router/router.go @@ -61,12 +61,13 @@ type Router struct { customerOrderPaymentHandler *handler.CustomerOrderPaymentHandler customerWalletHandler *handler.CustomerWalletHandler customerDeviceHandler *handler.CustomerDeviceHandler + customerOutletHandler *handler.CustomerOutletHandler authMiddleware *middleware.AuthMiddleware customerAuthMiddleware *middleware.CustomerAuthMiddleware redisClient *redis.Client } -func NewRouter(cfg *config.Config, healthHandler *handler.HealthHandler, authService service.AuthService, authMiddleware *middleware.AuthMiddleware, userService *service.UserServiceImpl, userValidator *validator.UserValidatorImpl, organizationService service.OrganizationService, organizationValidator validator.OrganizationValidator, outletService service.OutletService, outletValidator validator.OutletValidator, outletSettingService service.OutletSettingService, categoryService service.CategoryService, categoryValidator validator.CategoryValidator, productService service.ProductService, productValidator validator.ProductValidator, productVariantService service.ProductVariantService, productVariantValidator validator.ProductVariantValidator, inventoryService service.InventoryService, inventoryValidator validator.InventoryValidator, orderService service.OrderService, orderValidator validator.OrderValidator, fileService service.FileService, fileValidator validator.FileValidator, customerService service.CustomerService, customerValidator validator.CustomerValidator, paymentMethodService service.PaymentMethodService, paymentMethodValidator validator.PaymentMethodValidator, analyticsService *service.AnalyticsServiceImpl, reportService service.ReportService, tableService *service.TableServiceImpl, tableValidator *validator.TableValidator, unitService handler.UnitService, ingredientService handler.IngredientService, productRecipeService service.ProductRecipeService, vendorService service.VendorService, vendorValidator validator.VendorValidator, purchaseOrderService service.PurchaseOrderService, purchaseOrderValidator validator.PurchaseOrderValidator, purchaseCategoryService service.PurchaseCategoryService, purchaseCategoryValidator validator.PurchaseCategoryValidator, unitConverterService service.IngredientUnitConverterService, unitConverterValidator validator.IngredientUnitConverterValidator, chartOfAccountTypeService service.ChartOfAccountTypeService, chartOfAccountTypeValidator validator.ChartOfAccountTypeValidator, chartOfAccountService service.ChartOfAccountService, chartOfAccountValidator validator.ChartOfAccountValidator, accountService service.AccountService, accountValidator validator.AccountValidator, orderIngredientTransactionService service.OrderIngredientTransactionService, orderIngredientTransactionValidator validator.OrderIngredientTransactionValidator, gamificationService service.GamificationService, gamificationValidator validator.GamificationValidator, rewardService service.RewardService, rewardValidator validator.RewardValidator, campaignService service.CampaignService, campaignValidator validator.CampaignValidator, customerAuthService service.CustomerAuthService, customerAuthValidator validator.CustomerAuthValidator, customerPointsService service.CustomerPointsService, spinGameService service.SpinGameService, customerAuthMiddleware *middleware.CustomerAuthMiddleware, userDeviceService service.UserDeviceService, userDeviceValidator validator.UserDeviceValidator, notificationService service.NotificationService, notificationValidator validator.NotificationValidator, productOutletPriceService service.ProductOutletPriceService, productOutletPriceValidator validator.ProductOutletPriceValidator, selfOrderHandler *handler.SelfOrderHandler, expenseService *service.ExpenseServiceImpl, expenseValidator *validator.ExpenseValidatorImpl, cashAdvanceService service.CashAdvanceService, cashAdvanceValidator validator.CashAdvanceValidator, walletAdminService service.WalletAdminService, walletValidator validator.WalletValidator, loyaltySettingsService service.LoyaltySettingsService, customerPinService service.CustomerPinService, pointPaymentService service.PointPaymentService, customerOrderPaymentService service.CustomerOrderPaymentService, customerWalletService service.CustomerWalletService, customerDeviceService service.CustomerDeviceService, redisClient *redis.Client) *Router { +func NewRouter(cfg *config.Config, healthHandler *handler.HealthHandler, authService service.AuthService, authMiddleware *middleware.AuthMiddleware, userService *service.UserServiceImpl, userValidator *validator.UserValidatorImpl, organizationService service.OrganizationService, organizationValidator validator.OrganizationValidator, outletService service.OutletService, outletValidator validator.OutletValidator, outletSettingService service.OutletSettingService, categoryService service.CategoryService, categoryValidator validator.CategoryValidator, productService service.ProductService, productValidator validator.ProductValidator, productVariantService service.ProductVariantService, productVariantValidator validator.ProductVariantValidator, inventoryService service.InventoryService, inventoryValidator validator.InventoryValidator, orderService service.OrderService, orderValidator validator.OrderValidator, fileService service.FileService, fileValidator validator.FileValidator, customerService service.CustomerService, customerValidator validator.CustomerValidator, paymentMethodService service.PaymentMethodService, paymentMethodValidator validator.PaymentMethodValidator, analyticsService *service.AnalyticsServiceImpl, reportService service.ReportService, tableService *service.TableServiceImpl, tableValidator *validator.TableValidator, unitService handler.UnitService, ingredientService handler.IngredientService, productRecipeService service.ProductRecipeService, vendorService service.VendorService, vendorValidator validator.VendorValidator, purchaseOrderService service.PurchaseOrderService, purchaseOrderValidator validator.PurchaseOrderValidator, purchaseCategoryService service.PurchaseCategoryService, purchaseCategoryValidator validator.PurchaseCategoryValidator, unitConverterService service.IngredientUnitConverterService, unitConverterValidator validator.IngredientUnitConverterValidator, chartOfAccountTypeService service.ChartOfAccountTypeService, chartOfAccountTypeValidator validator.ChartOfAccountTypeValidator, chartOfAccountService service.ChartOfAccountService, chartOfAccountValidator validator.ChartOfAccountValidator, accountService service.AccountService, accountValidator validator.AccountValidator, orderIngredientTransactionService service.OrderIngredientTransactionService, orderIngredientTransactionValidator validator.OrderIngredientTransactionValidator, gamificationService service.GamificationService, gamificationValidator validator.GamificationValidator, rewardService service.RewardService, rewardValidator validator.RewardValidator, campaignService service.CampaignService, campaignValidator validator.CampaignValidator, customerAuthService service.CustomerAuthService, customerAuthValidator validator.CustomerAuthValidator, customerPointsService service.CustomerPointsService, spinGameService service.SpinGameService, customerAuthMiddleware *middleware.CustomerAuthMiddleware, userDeviceService service.UserDeviceService, userDeviceValidator validator.UserDeviceValidator, notificationService service.NotificationService, notificationValidator validator.NotificationValidator, productOutletPriceService service.ProductOutletPriceService, productOutletPriceValidator validator.ProductOutletPriceValidator, selfOrderHandler *handler.SelfOrderHandler, expenseService *service.ExpenseServiceImpl, expenseValidator *validator.ExpenseValidatorImpl, cashAdvanceService service.CashAdvanceService, cashAdvanceValidator validator.CashAdvanceValidator, walletAdminService service.WalletAdminService, walletValidator validator.WalletValidator, loyaltySettingsService service.LoyaltySettingsService, customerPinService service.CustomerPinService, pointPaymentService service.PointPaymentService, customerOrderPaymentService service.CustomerOrderPaymentService, customerWalletService service.CustomerWalletService, customerDeviceService service.CustomerDeviceService, customerOutletService service.CustomerOutletService, redisClient *redis.Client) *Router { return &Router{ config: cfg, @@ -119,6 +120,7 @@ func NewRouter(cfg *config.Config, healthHandler *handler.HealthHandler, authSer customerOrderPaymentHandler: handler.NewCustomerOrderPaymentHandler(customerOrderPaymentService), customerWalletHandler: handler.NewCustomerWalletHandler(customerWalletService), customerDeviceHandler: handler.NewCustomerDeviceHandler(customerDeviceService), + customerOutletHandler: handler.NewCustomerOutletHandler(customerOutletService), redisClient: redisClient, } } @@ -179,6 +181,7 @@ func (r *Router) addAppRoutes(rg *gin.Engine) { customer.POST("/wallet/transfer", r.customerWalletHandler.Transfer) customer.PUT("/devices", r.customerDeviceHandler.Register) customer.DELETE("/devices/:device_id", r.customerDeviceHandler.Unregister) + customer.GET("/outlets", r.customerOutletHandler.List) customer.POST("/orders/:id/pay-with-points", r.customerOrderPaymentHandler.PayWithPoints) // PIN that approves moving EnakPoint and EnakCoin (docs/prd-point-coin.md F11) customer.GET("/pin/status", r.customerPinHandler.Status) diff --git a/internal/router/router_test.go b/internal/router/router_test.go index 40db753..75cafc7 100644 --- a/internal/router/router_test.go +++ b/internal/router/router_test.go @@ -44,6 +44,7 @@ func TestAllRoutesRegister(t *testing.T) { "POST /api/v1/customer/wallet/transfer", "PUT /api/v1/customer/devices", "DELETE /api/v1/customer/devices/:device_id", + "GET /api/v1/customer/outlets", "GET /api/v1/orders/:id/point-payment/preview", "POST /api/v1/customer/orders/:id/pay-with-points", "GET /api/v1/customer/pin/status", diff --git a/internal/service/customer_outlet_service.go b/internal/service/customer_outlet_service.go new file mode 100644 index 0000000..3322588 --- /dev/null +++ b/internal/service/customer_outlet_service.go @@ -0,0 +1,40 @@ +package service + +import ( + "context" + "errors" + + "github.com/google/uuid" + + "apskel-pos-be/internal/constants" + "apskel-pos-be/internal/contract" + "apskel-pos-be/internal/processor" + "apskel-pos-be/internal/repository" +) + +// CustomerOutletService serves the outlets list of the customer app. +type CustomerOutletService interface { + List(ctx context.Context, customerID uuid.UUID) *contract.Response +} + +type CustomerOutletServiceImpl struct { + outlets *processor.CustomerOutletProcessor +} + +func NewCustomerOutletService(outlets *processor.CustomerOutletProcessor) *CustomerOutletServiceImpl { + return &CustomerOutletServiceImpl{outlets: outlets} +} + +func (s *CustomerOutletServiceImpl) List(ctx context.Context, customerID uuid.UUID) *contract.Response { + outlets, err := s.outlets.List(ctx, customerID) + if err != nil { + code := constants.InternalServerErrorCode + if errors.Is(err, repository.ErrWalletNotFound) { + code = constants.NotFoundErrorCode + } + return contract.BuildErrorResponse([]*contract.ResponseError{ + contract.NewResponseError(code, constants.RequestEntity, err.Error()), + }) + } + return contract.BuildSuccessResponse(outlets) +} From a24d5f0561793191d9081c983389c0cdccaea8c5 Mon Sep 17 00:00:00 2001 From: efrilm Date: Wed, 30 Sep 2026 19:36:35 +0700 Subject: [PATCH 4/5] feat(customer): order history and detail for the customer app Adds GET /customer/orders and GET /customer/orders/:id for the customer app: the orders linked to the logged-in customer across their organization's outlets, newest first, paginated (limit 1-100, default 20). The list shows the order number, outlet, type, status, total, item count, void/refund flags and the EnakPoint and EnakCoin it earned. The detail adds the amounts, the items with product and variant names, weight and unit for weighed lines, modifiers and notes, and the payments with the method and, for EnakPoint, the points used. Costs, cashier and other internal fields are left out. Another customer's order answers 404 like one that does not exist. Co-Authored-By: Claude Opus 5.5 --- internal/app/app.go | 5 + internal/handler/customer_order_handler.go | 49 ++++++ internal/models/customer_order.go | 74 +++++++++ .../processor/customer_order_processor.go | 157 ++++++++++++++++++ .../customer_order_processor_test.go | 145 ++++++++++++++++ .../repository/customer_order_repository.go | 157 ++++++++++++++++++ internal/router/router.go | 6 +- internal/router/router_test.go | 2 + internal/service/customer_order_service.go | 57 +++++++ 9 files changed, 651 insertions(+), 1 deletion(-) create mode 100644 internal/handler/customer_order_handler.go create mode 100644 internal/models/customer_order.go create mode 100644 internal/processor/customer_order_processor.go create mode 100644 internal/processor/customer_order_processor_test.go create mode 100644 internal/repository/customer_order_repository.go create mode 100644 internal/service/customer_order_service.go diff --git a/internal/app/app.go b/internal/app/app.go index 9ea2e47..e477e73 100644 --- a/internal/app/app.go +++ b/internal/app/app.go @@ -166,6 +166,7 @@ func (a *App) Initialize(cfg *config.Config) error { services.customerWalletService, services.customerDeviceService, services.customerOutletService, + services.customerOrderService, a.redisClient, ) @@ -405,6 +406,7 @@ type processors struct { walletTraceProcessor *processor.WalletTraceProcessor customerDeviceProcessor *processor.CustomerDeviceProcessor customerOutletProcessor *processor.CustomerOutletProcessor + customerOrderProcessor *processor.CustomerOrderProcessor } func (a *App) initProcessors(cfg *config.Config, repos *repositories) *processors { @@ -487,6 +489,7 @@ func (a *App) initProcessors(cfg *config.Config, repos *repositories) *processor walletTraceProcessor: processor.NewWalletTraceProcessor(repository.NewWalletTraceRepository(a.db)), customerDeviceProcessor: customerDeviceProcessor, customerOutletProcessor: processor.NewCustomerOutletProcessor(repository.NewCustomerOutletRepository(a.db), loyaltySettingsProcessor), + customerOrderProcessor: processor.NewCustomerOrderProcessor(repository.NewCustomerOrderRepository(a.db), earningProcessor), walletAdminProcessor: processor.NewWalletAdminProcessor(repository.NewWalletAdminRepository(a.db), repos.walletQueryRepo, processor.NewWalletProcessor(repos.walletRepo), loyaltySettingsProcessor, repos.txManager), } } @@ -538,6 +541,7 @@ type services struct { customerWalletService *service.CustomerWalletServiceImpl customerDeviceService *service.CustomerDeviceServiceImpl customerOutletService *service.CustomerOutletServiceImpl + customerOrderService *service.CustomerOrderServiceImpl } func (a *App) initServices(processors *processors, repos *repositories, cfg *config.Config) *services { @@ -627,6 +631,7 @@ func (a *App) initServices(processors *processors, repos *repositories, cfg *con customerWalletService: service.NewCustomerWalletService(processors.walletExchangeProcessor, processors.walletTransferProcessor), customerDeviceService: service.NewCustomerDeviceService(processors.customerDeviceProcessor), customerOutletService: service.NewCustomerOutletService(processors.customerOutletProcessor), + customerOrderService: service.NewCustomerOrderService(processors.customerOrderProcessor), } } diff --git a/internal/handler/customer_order_handler.go b/internal/handler/customer_order_handler.go new file mode 100644 index 0000000..3874676 --- /dev/null +++ b/internal/handler/customer_order_handler.go @@ -0,0 +1,49 @@ +package handler + +import ( + "github.com/gin-gonic/gin" + + "apskel-pos-be/internal/constants" + "apskel-pos-be/internal/contract" + "apskel-pos-be/internal/models" + "apskel-pos-be/internal/service" + "apskel-pos-be/internal/util" +) + +// CustomerOrderHandler serves the customer app's order history. +type CustomerOrderHandler struct { + orders service.CustomerOrderService +} + +func NewCustomerOrderHandler(orders service.CustomerOrderService) *CustomerOrderHandler { + return &CustomerOrderHandler{orders: orders} +} + +// List is GET /customer/orders?page=&limit=. +func (h *CustomerOrderHandler) List(c *gin.Context) { + customerID, ok := customerIDFromGin(c, "CustomerOrderHandler::List") + if !ok { + return + } + var query models.ListCustomerOrdersQuery + if err := c.ShouldBindQuery(&query); err != nil { + util.HandleResponse(c.Writer, c.Request, contract.BuildErrorResponse([]*contract.ResponseError{ + contract.NewResponseError(constants.MalformedFieldErrorCode, constants.RequestEntity, "page and limit must be whole numbers"), + }), "CustomerOrderHandler::List") + return + } + util.HandleResponse(c.Writer, c.Request, h.orders.List(c.Request.Context(), customerID, query), "CustomerOrderHandler::List") +} + +// Detail is GET /customer/orders/:id. +func (h *CustomerOrderHandler) Detail(c *gin.Context) { + customerID, ok := customerIDFromGin(c, "CustomerOrderHandler::Detail") + if !ok { + return + } + orderID, ok := parseUUIDParam(c, "id", "CustomerOrderHandler::Detail") + if !ok { + return + } + util.HandleResponse(c.Writer, c.Request, h.orders.Detail(c.Request.Context(), customerID, orderID), "CustomerOrderHandler::Detail") +} diff --git a/internal/models/customer_order.go b/internal/models/customer_order.go new file mode 100644 index 0000000..c5e5fad --- /dev/null +++ b/internal/models/customer_order.go @@ -0,0 +1,74 @@ +package models + +import ( + "time" + + "github.com/google/uuid" +) + +// CustomerOrderSummary is one order in GET /customer/orders. +type CustomerOrderSummary struct { + ID uuid.UUID `json:"id"` + OrderNumber string `json:"order_number"` + OutletID uuid.UUID `json:"outlet_id"` + OutletName string `json:"outlet_name"` + OrderType string `json:"order_type"` + Status string `json:"status"` + PaymentStatus string `json:"payment_status"` + TotalAmount float64 `json:"total_amount"` + ItemCount int64 `json:"item_count"` + IsVoid bool `json:"is_void"` + IsRefund bool `json:"is_refund"` + // EnakPoint and EnakCoin the order earned; 0 when it earned nothing. + PointsEarned int64 `json:"points_earned"` + CoinsEarned int64 `json:"coins_earned"` + CreatedAt time.Time `json:"created_at"` +} + +// CustomerOrderDetail is GET /customer/orders/:id. +type CustomerOrderDetail struct { + CustomerOrderSummary + TableNumber *string `json:"table_number"` + Subtotal float64 `json:"subtotal"` + DiscountAmount float64 `json:"discount_amount"` + TaxAmount float64 `json:"tax_amount"` + RefundAmount float64 `json:"refund_amount"` + Items []CustomerOrderItem `json:"items"` + Payments []CustomerOrderPayment `json:"payments"` +} + +type CustomerOrderItem struct { + ID uuid.UUID `json:"id"` + ProductID uuid.UUID `json:"product_id"` + ProductName string `json:"product_name"` + VariantName *string `json:"variant_name"` + Quantity int `json:"quantity"` + // Set for products sold by weight, in UnitName. + Weight *float64 `json:"weight,omitempty"` + UnitName *string `json:"unit_name,omitempty"` + UnitPrice float64 `json:"unit_price"` + TotalPrice float64 `json:"total_price"` + RefundQuantity int `json:"refund_quantity"` + Modifiers []map[string]interface{} `json:"modifiers"` + Notes *string `json:"notes,omitempty"` + Status string `json:"status"` +} + +type CustomerOrderPayment struct { + ID uuid.UUID `json:"id"` + MethodName string `json:"method_name"` + MethodType string `json:"method_type"` + Amount float64 `json:"amount"` + Status string `json:"status"` + RefundAmount float64 `json:"refund_amount"` + // Set for a payment with EnakPoint. + PointsUsed *int64 `json:"points_used,omitempty"` + PointValue *float64 `json:"point_value,omitempty"` + CreatedAt time.Time `json:"created_at"` +} + +// ListCustomerOrdersQuery is GET /customer/orders. +type ListCustomerOrdersQuery struct { + Page int `form:"page"` + Limit int `form:"limit"` +} diff --git a/internal/processor/customer_order_processor.go b/internal/processor/customer_order_processor.go new file mode 100644 index 0000000..3a44014 --- /dev/null +++ b/internal/processor/customer_order_processor.go @@ -0,0 +1,157 @@ +package processor + +import ( + "context" + "fmt" + + "github.com/google/uuid" + + "apskel-pos-be/internal/models" + "apskel-pos-be/internal/repository" +) + +const ( + customerOrdersPageLimit = 20 + customerOrdersMaxLimit = 100 +) + +type orderEarnedReader interface { + EarnedByOrders(ctx context.Context, orderIDs []uuid.UUID) (map[uuid.UUID]OrderEarned, error) +} + +// CustomerOrderProcessor serves the customer app's order history: the customer's own +// orders only, without costs or staff details. +type CustomerOrderProcessor struct { + repo repository.CustomerOrderRepository + earned orderEarnedReader +} + +func NewCustomerOrderProcessor(repo repository.CustomerOrderRepository, earned orderEarnedReader) *CustomerOrderProcessor { + return &CustomerOrderProcessor{repo: repo, earned: earned} +} + +// List is GET /customer/orders: the customer's orders across all outlets, newest first. +func (p *CustomerOrderProcessor) List(ctx context.Context, customerID uuid.UUID, query models.ListCustomerOrdersQuery) (*models.PaginatedResponse[models.CustomerOrderSummary], error) { + page, limit := query.Page, query.Limit + if page == 0 { + page = 1 + } + if limit == 0 { + limit = customerOrdersPageLimit + } + if page < 1 || limit < 1 || limit > customerOrdersMaxLimit { + return nil, fmt.Errorf("%w: page must be at least 1 and limit between 1 and %d", ErrInvalidWalletQuery, customerOrdersMaxLimit) + } + + rows, total, err := p.repo.ListOrders(ctx, customerID, (page-1)*limit, limit) + if err != nil { + return nil, err + } + ids := make([]uuid.UUID, 0, len(rows)) + for _, r := range rows { + ids = append(ids, r.ID) + } + earned, err := p.earned.EarnedByOrders(ctx, ids) + if err != nil { + return nil, err + } + data := make([]models.CustomerOrderSummary, 0, len(rows)) + for _, r := range rows { + data = append(data, customerOrderSummary(r, earned[r.ID])) + } + return &models.PaginatedResponse[models.CustomerOrderSummary]{ + Data: data, + Pagination: models.Pagination{ + Page: page, + Limit: limit, + Total: total, + TotalPages: int((total + int64(limit) - 1) / int64(limit)), + }, + }, nil +} + +// Detail is GET /customer/orders/:id. Another customer's order is +// repository.ErrCustomerOrderNotFound, like one that does not exist. +func (p *CustomerOrderProcessor) Detail(ctx context.Context, customerID, orderID uuid.UUID) (*models.CustomerOrderDetail, error) { + row, err := p.repo.GetOrder(ctx, customerID, orderID) + if err != nil { + return nil, err + } + items, err := p.repo.ListItems(ctx, orderID) + if err != nil { + return nil, err + } + payments, err := p.repo.ListPayments(ctx, orderID) + if err != nil { + return nil, err + } + earned, err := p.earned.EarnedByOrders(ctx, []uuid.UUID{orderID}) + if err != nil { + return nil, err + } + + detail := &models.CustomerOrderDetail{ + CustomerOrderSummary: customerOrderSummary(*row, earned[orderID]), + TableNumber: row.TableNumber, + Subtotal: row.Subtotal, + DiscountAmount: row.DiscountAmount, + TaxAmount: row.TaxAmount, + RefundAmount: row.RefundAmount, + Items: make([]models.CustomerOrderItem, 0, len(items)), + Payments: make([]models.CustomerOrderPayment, 0, len(payments)), + } + for _, it := range items { + modifiers := []map[string]interface{}(it.Modifiers) + if modifiers == nil { + modifiers = []map[string]interface{}{} + } + detail.Items = append(detail.Items, models.CustomerOrderItem{ + ID: it.ID, + ProductID: it.ProductID, + ProductName: it.ProductName, + VariantName: it.VariantName, + Quantity: it.Quantity, + Weight: it.Weight, + UnitName: it.UnitName, + UnitPrice: it.UnitPrice, + TotalPrice: it.TotalPrice, + RefundQuantity: it.RefundQuantity, + Modifiers: modifiers, + Notes: it.Notes, + Status: it.Status, + }) + } + for _, pay := range payments { + detail.Payments = append(detail.Payments, models.CustomerOrderPayment{ + ID: pay.ID, + MethodName: pay.MethodName, + MethodType: pay.MethodType, + Amount: pay.Amount, + Status: pay.Status, + RefundAmount: pay.RefundAmount, + PointsUsed: pay.PointsUsed, + PointValue: pay.PointValue, + CreatedAt: pay.CreatedAt, + }) + } + return detail, nil +} + +func customerOrderSummary(r repository.CustomerOrderRow, earned OrderEarned) models.CustomerOrderSummary { + return models.CustomerOrderSummary{ + ID: r.ID, + OrderNumber: r.OrderNumber, + OutletID: r.OutletID, + OutletName: r.OutletName, + OrderType: r.OrderType, + Status: r.Status, + PaymentStatus: r.PaymentStatus, + TotalAmount: r.TotalAmount, + ItemCount: r.ItemCount, + IsVoid: r.IsVoid, + IsRefund: r.IsRefund, + PointsEarned: earned.Points, + CoinsEarned: earned.Coins, + CreatedAt: r.CreatedAt, + } +} diff --git a/internal/processor/customer_order_processor_test.go b/internal/processor/customer_order_processor_test.go new file mode 100644 index 0000000..380e9ad --- /dev/null +++ b/internal/processor/customer_order_processor_test.go @@ -0,0 +1,145 @@ +package processor + +import ( + "context" + "testing" + "time" + + "github.com/google/uuid" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "apskel-pos-be/internal/models" + "apskel-pos-be/internal/repository" +) + +type customerOrderRepoFake struct { + owner map[uuid.UUID]uuid.UUID // order -> customer + orders []repository.CustomerOrderRow + items map[uuid.UUID][]repository.CustomerOrderItemRow + payments map[uuid.UUID][]repository.CustomerOrderPaymentRow + offset int + limit int +} + +func (f *customerOrderRepoFake) ListOrders(_ context.Context, customerID uuid.UUID, offset, limit int) ([]repository.CustomerOrderRow, int64, error) { + f.offset, f.limit = offset, limit + var mine []repository.CustomerOrderRow + for _, o := range f.orders { + if f.owner[o.ID] == customerID { + mine = append(mine, o) + } + } + return mine, int64(len(mine)), nil +} + +func (f *customerOrderRepoFake) GetOrder(_ context.Context, customerID, orderID uuid.UUID) (*repository.CustomerOrderRow, error) { + for _, o := range f.orders { + if o.ID == orderID && f.owner[o.ID] == customerID { + c := o + return &c, nil + } + } + return nil, repository.ErrCustomerOrderNotFound +} + +func (f *customerOrderRepoFake) ListItems(_ context.Context, orderID uuid.UUID) ([]repository.CustomerOrderItemRow, error) { + return f.items[orderID], nil +} + +func (f *customerOrderRepoFake) ListPayments(_ context.Context, orderID uuid.UUID) ([]repository.CustomerOrderPaymentRow, error) { + return f.payments[orderID], nil +} + +type earnedFake map[uuid.UUID]OrderEarned + +func (f earnedFake) EarnedByOrders(_ context.Context, ids []uuid.UUID) (map[uuid.UUID]OrderEarned, error) { + out := map[uuid.UUID]OrderEarned{} + for _, id := range ids { + if e, ok := f[id]; ok { + out[id] = e + } + } + return out, nil +} + +func newCustomerOrderTest() (*customerOrderRepoFake, uuid.UUID, uuid.UUID, uuid.UUID) { + customer, other := uuid.New(), uuid.New() + mine, theirs := uuid.New(), uuid.New() + repo := &customerOrderRepoFake{ + owner: map[uuid.UUID]uuid.UUID{mine: customer, theirs: other}, + orders: []repository.CustomerOrderRow{ + {ID: mine, OrderNumber: "ORD-1", OutletName: "Gokuna 1", Status: "completed", PaymentStatus: "completed", Subtotal: 90000, TotalAmount: 99000, ItemCount: 2, CreatedAt: time.Now()}, + {ID: theirs, OrderNumber: "ORD-2"}, + }, + } + return repo, customer, mine, theirs +} + +func TestCustomerOrders_ListShowsOnlyTheCustomersOrdersWithEarning(t *testing.T) { + repo, customer, mine, _ := newCustomerOrderTest() + p := NewCustomerOrderProcessor(repo, earnedFake{mine: {Points: 900, Coins: 3}}) + + got, err := p.List(context.Background(), customer, models.ListCustomerOrdersQuery{Page: 2, Limit: 10}) + require.NoError(t, err) + require.Len(t, got.Data, 1) + assert.Equal(t, "ORD-1", got.Data[0].OrderNumber) + assert.Equal(t, int64(900), got.Data[0].PointsEarned) + assert.Equal(t, int64(3), got.Data[0].CoinsEarned) + assert.Equal(t, 10, repo.offset, "page 2 of 10 skips the first 10") + assert.Equal(t, 10, repo.limit) + assert.Equal(t, 2, got.Pagination.Page) +} + +func TestCustomerOrders_ListDefaultsAndLimits(t *testing.T) { + repo, customer, _, _ := newCustomerOrderTest() + p := NewCustomerOrderProcessor(repo, earnedFake{}) + + got, err := p.List(context.Background(), customer, models.ListCustomerOrdersQuery{}) + require.NoError(t, err) + assert.Equal(t, 1, got.Pagination.Page) + assert.Equal(t, 20, got.Pagination.Limit) + + for _, q := range []models.ListCustomerOrdersQuery{{Page: -1}, {Limit: 101}, {Limit: -5}} { + _, err := p.List(context.Background(), customer, q) + assert.ErrorIs(t, err, ErrInvalidWalletQuery, "%+v", q) + } +} + +func TestCustomerOrders_DetailHasItemsPaymentsAndEarning(t *testing.T) { + repo, customer, mine, _ := newCustomerOrderTest() + variant, unit := "Large", "ons" + weight := 4.2 + points, value := int64(12500), 1.0 + repo.items = map[uuid.UUID][]repository.CustomerOrderItemRow{ + mine: { + {ProductName: "Kopi Susu", VariantName: &variant, Quantity: 2, UnitPrice: 25000, TotalPrice: 50000, Status: "completed"}, + {ProductName: "Ikan Tude", Quantity: 1, Weight: &weight, UnitName: &unit, UnitPrice: 4500, TotalPrice: 18900, Status: "completed"}, + }, + } + repo.payments = map[uuid.UUID][]repository.CustomerOrderPaymentRow{ + mine: { + {MethodName: "EnakPoint", MethodType: "point", Amount: 12500, Status: "completed", PointsUsed: &points, PointValue: &value}, + {MethodName: "Cash", MethodType: "cash", Amount: 86500, Status: "completed"}, + }, + } + p := NewCustomerOrderProcessor(repo, earnedFake{mine: {Points: 865}}) + + got, err := p.Detail(context.Background(), customer, mine) + require.NoError(t, err) + assert.Equal(t, "Gokuna 1", got.OutletName) + assert.Equal(t, float64(90000), got.Subtotal) + assert.Equal(t, int64(865), got.PointsEarned) + require.Len(t, got.Items, 2) + assert.Equal(t, "Large", *got.Items[0].VariantName) + assert.Equal(t, []map[string]interface{}{}, got.Items[0].Modifiers, "no modifiers is an empty list, not null") + assert.Equal(t, 4.2, *got.Items[1].Weight) + require.Len(t, got.Payments, 2) + assert.Equal(t, int64(12500), *got.Payments[0].PointsUsed) +} + +func TestCustomerOrders_AnotherCustomersOrderIsNotFound(t *testing.T) { + repo, customer, _, theirs := newCustomerOrderTest() + _, err := NewCustomerOrderProcessor(repo, earnedFake{}).Detail(context.Background(), customer, theirs) + assert.ErrorIs(t, err, repository.ErrCustomerOrderNotFound) +} diff --git a/internal/repository/customer_order_repository.go b/internal/repository/customer_order_repository.go new file mode 100644 index 0000000..f6bf8d2 --- /dev/null +++ b/internal/repository/customer_order_repository.go @@ -0,0 +1,157 @@ +package repository + +import ( + "context" + "errors" + "fmt" + "time" + + "github.com/google/uuid" + "gorm.io/gorm" + + "apskel-pos-be/internal/entities" +) + +// ErrCustomerOrderNotFound means the order does not exist or belongs to another +// customer; the two are not told apart. +var ErrCustomerOrderNotFound = errors.New("order not found") + +// CustomerOrderRow is one order as the customer app lists it. +type CustomerOrderRow struct { + ID uuid.UUID + OrderNumber string + OutletID uuid.UUID + OutletName string + OrderType string + TableNumber *string + Status string + PaymentStatus string + Subtotal float64 + DiscountAmount float64 + TaxAmount float64 + TotalAmount float64 + RefundAmount float64 + IsVoid bool + IsRefund bool + ItemCount int64 + CreatedAt time.Time +} + +// CustomerOrderItemRow is one line of an order, without costs. +type CustomerOrderItemRow struct { + ID uuid.UUID + ProductID uuid.UUID + ProductName string + VariantName *string + Quantity int + Weight *float64 + UnitName *string + UnitPrice float64 + TotalPrice float64 + RefundQuantity int + Modifiers entities.Modifiers `gorm:"type:jsonb"` + Notes *string + Status string +} + +// CustomerOrderPaymentRow is one payment of an order. +type CustomerOrderPaymentRow struct { + ID uuid.UUID + MethodName string + MethodType string + Amount float64 + Status string + RefundAmount float64 + PointsUsed *int64 + PointValue *float64 + CreatedAt time.Time +} + +// CustomerOrderRepository reads a customer's own orders for the customer app. Every +// read is scoped to the customer, so one customer can never see another's order. +type CustomerOrderRepository interface { + // ListOrders returns a page of the customer's orders, newest first, and the total. + ListOrders(ctx context.Context, customerID uuid.UUID, offset, limit int) ([]CustomerOrderRow, int64, error) + // GetOrder returns ErrCustomerOrderNotFound unless the order is the customer's. + GetOrder(ctx context.Context, customerID, orderID uuid.UUID) (*CustomerOrderRow, error) + ListItems(ctx context.Context, orderID uuid.UUID) ([]CustomerOrderItemRow, error) + ListPayments(ctx context.Context, orderID uuid.UUID) ([]CustomerOrderPaymentRow, error) +} + +type customerOrderRepository struct { + db *gorm.DB +} + +func NewCustomerOrderRepository(db *gorm.DB) CustomerOrderRepository { + return &customerOrderRepository{db: db} +} + +const customerOrderColumns = `o.id, o.order_number, o.outlet_id, COALESCE(ol.name, '') AS outlet_name, + o.order_type, o.table_number, o.status, o.payment_status, o.subtotal, o.discount_amount, + o.tax_amount, o.total_amount, o.refund_amount, o.is_void, o.is_refund, + (SELECT COUNT(*) FROM order_items oi WHERE oi.order_id = o.id) AS item_count, o.created_at` + +func (r *customerOrderRepository) ListOrders(ctx context.Context, customerID uuid.UUID, offset, limit int) ([]CustomerOrderRow, int64, error) { + db := DBFromContext(ctx, r.db).WithContext(ctx) + var total int64 + if err := db.Table("orders").Where("customer_id = ?", customerID).Count(&total).Error; err != nil { + return nil, 0, fmt.Errorf("failed to count customer orders: %w", err) + } + var rows []CustomerOrderRow + err := db.Raw(`SELECT `+customerOrderColumns+` + FROM orders o LEFT JOIN outlets ol ON ol.id = o.outlet_id + WHERE o.customer_id = ? + ORDER BY o.created_at DESC, o.id + LIMIT ? OFFSET ?`, customerID, limit, offset).Scan(&rows).Error + if err != nil { + return nil, 0, fmt.Errorf("failed to list customer orders: %w", err) + } + return rows, total, nil +} + +func (r *customerOrderRepository) GetOrder(ctx context.Context, customerID, orderID uuid.UUID) (*CustomerOrderRow, error) { + var rows []CustomerOrderRow + err := DBFromContext(ctx, r.db).WithContext(ctx).Raw(`SELECT `+customerOrderColumns+` + FROM orders o LEFT JOIN outlets ol ON ol.id = o.outlet_id + WHERE o.id = ? AND o.customer_id = ?`, orderID, customerID).Scan(&rows).Error + if err != nil { + return nil, fmt.Errorf("failed to get customer order: %w", err) + } + if len(rows) == 0 { + return nil, ErrCustomerOrderNotFound + } + return &rows[0], nil +} + +func (r *customerOrderRepository) ListItems(ctx context.Context, orderID uuid.UUID) ([]CustomerOrderItemRow, error) { + var rows []CustomerOrderItemRow + err := DBFromContext(ctx, r.db).WithContext(ctx).Raw(` + SELECT oi.id, oi.product_id, COALESCE(p.name, '') AS product_name, pv.name AS variant_name, + oi.quantity, oi.weight, COALESCE(u.abbreviation, u.name) AS unit_name, + oi.unit_price, oi.total_price, oi.refund_quantity, oi.modifiers, oi.notes, oi.status + FROM order_items oi + LEFT JOIN products p ON p.id = oi.product_id + LEFT JOIN product_variants pv ON pv.id = oi.product_variant_id + LEFT JOIN units u ON u.id = oi.unit_id + WHERE oi.order_id = ? + ORDER BY oi.created_at, oi.id`, orderID).Scan(&rows).Error + if err != nil { + return nil, fmt.Errorf("failed to list order items: %w", err) + } + return rows, nil +} + +func (r *customerOrderRepository) ListPayments(ctx context.Context, orderID uuid.UUID) ([]CustomerOrderPaymentRow, error) { + var rows []CustomerOrderPaymentRow + err := DBFromContext(ctx, r.db).WithContext(ctx).Raw(` + SELECT pay.id, COALESCE(pm.name, '') AS method_name, COALESCE(pm.type, '') AS method_type, + pay.amount, pay.status, pay.refund_amount, pay.points_used, pay.point_value, pay.created_at + FROM payments pay + LEFT JOIN payment_methods pm ON pm.id = pay.payment_method_id + WHERE pay.order_id = ? + ORDER BY pay.created_at, pay.id`, orderID).Scan(&rows).Error + if err != nil { + return nil, fmt.Errorf("failed to list order payments: %w", err) + } + return rows, nil +} diff --git a/internal/router/router.go b/internal/router/router.go index cf77c39..55bc014 100644 --- a/internal/router/router.go +++ b/internal/router/router.go @@ -62,12 +62,13 @@ type Router struct { customerWalletHandler *handler.CustomerWalletHandler customerDeviceHandler *handler.CustomerDeviceHandler customerOutletHandler *handler.CustomerOutletHandler + customerOrderHandler *handler.CustomerOrderHandler authMiddleware *middleware.AuthMiddleware customerAuthMiddleware *middleware.CustomerAuthMiddleware redisClient *redis.Client } -func NewRouter(cfg *config.Config, healthHandler *handler.HealthHandler, authService service.AuthService, authMiddleware *middleware.AuthMiddleware, userService *service.UserServiceImpl, userValidator *validator.UserValidatorImpl, organizationService service.OrganizationService, organizationValidator validator.OrganizationValidator, outletService service.OutletService, outletValidator validator.OutletValidator, outletSettingService service.OutletSettingService, categoryService service.CategoryService, categoryValidator validator.CategoryValidator, productService service.ProductService, productValidator validator.ProductValidator, productVariantService service.ProductVariantService, productVariantValidator validator.ProductVariantValidator, inventoryService service.InventoryService, inventoryValidator validator.InventoryValidator, orderService service.OrderService, orderValidator validator.OrderValidator, fileService service.FileService, fileValidator validator.FileValidator, customerService service.CustomerService, customerValidator validator.CustomerValidator, paymentMethodService service.PaymentMethodService, paymentMethodValidator validator.PaymentMethodValidator, analyticsService *service.AnalyticsServiceImpl, reportService service.ReportService, tableService *service.TableServiceImpl, tableValidator *validator.TableValidator, unitService handler.UnitService, ingredientService handler.IngredientService, productRecipeService service.ProductRecipeService, vendorService service.VendorService, vendorValidator validator.VendorValidator, purchaseOrderService service.PurchaseOrderService, purchaseOrderValidator validator.PurchaseOrderValidator, purchaseCategoryService service.PurchaseCategoryService, purchaseCategoryValidator validator.PurchaseCategoryValidator, unitConverterService service.IngredientUnitConverterService, unitConverterValidator validator.IngredientUnitConverterValidator, chartOfAccountTypeService service.ChartOfAccountTypeService, chartOfAccountTypeValidator validator.ChartOfAccountTypeValidator, chartOfAccountService service.ChartOfAccountService, chartOfAccountValidator validator.ChartOfAccountValidator, accountService service.AccountService, accountValidator validator.AccountValidator, orderIngredientTransactionService service.OrderIngredientTransactionService, orderIngredientTransactionValidator validator.OrderIngredientTransactionValidator, gamificationService service.GamificationService, gamificationValidator validator.GamificationValidator, rewardService service.RewardService, rewardValidator validator.RewardValidator, campaignService service.CampaignService, campaignValidator validator.CampaignValidator, customerAuthService service.CustomerAuthService, customerAuthValidator validator.CustomerAuthValidator, customerPointsService service.CustomerPointsService, spinGameService service.SpinGameService, customerAuthMiddleware *middleware.CustomerAuthMiddleware, userDeviceService service.UserDeviceService, userDeviceValidator validator.UserDeviceValidator, notificationService service.NotificationService, notificationValidator validator.NotificationValidator, productOutletPriceService service.ProductOutletPriceService, productOutletPriceValidator validator.ProductOutletPriceValidator, selfOrderHandler *handler.SelfOrderHandler, expenseService *service.ExpenseServiceImpl, expenseValidator *validator.ExpenseValidatorImpl, cashAdvanceService service.CashAdvanceService, cashAdvanceValidator validator.CashAdvanceValidator, walletAdminService service.WalletAdminService, walletValidator validator.WalletValidator, loyaltySettingsService service.LoyaltySettingsService, customerPinService service.CustomerPinService, pointPaymentService service.PointPaymentService, customerOrderPaymentService service.CustomerOrderPaymentService, customerWalletService service.CustomerWalletService, customerDeviceService service.CustomerDeviceService, customerOutletService service.CustomerOutletService, redisClient *redis.Client) *Router { +func NewRouter(cfg *config.Config, healthHandler *handler.HealthHandler, authService service.AuthService, authMiddleware *middleware.AuthMiddleware, userService *service.UserServiceImpl, userValidator *validator.UserValidatorImpl, organizationService service.OrganizationService, organizationValidator validator.OrganizationValidator, outletService service.OutletService, outletValidator validator.OutletValidator, outletSettingService service.OutletSettingService, categoryService service.CategoryService, categoryValidator validator.CategoryValidator, productService service.ProductService, productValidator validator.ProductValidator, productVariantService service.ProductVariantService, productVariantValidator validator.ProductVariantValidator, inventoryService service.InventoryService, inventoryValidator validator.InventoryValidator, orderService service.OrderService, orderValidator validator.OrderValidator, fileService service.FileService, fileValidator validator.FileValidator, customerService service.CustomerService, customerValidator validator.CustomerValidator, paymentMethodService service.PaymentMethodService, paymentMethodValidator validator.PaymentMethodValidator, analyticsService *service.AnalyticsServiceImpl, reportService service.ReportService, tableService *service.TableServiceImpl, tableValidator *validator.TableValidator, unitService handler.UnitService, ingredientService handler.IngredientService, productRecipeService service.ProductRecipeService, vendorService service.VendorService, vendorValidator validator.VendorValidator, purchaseOrderService service.PurchaseOrderService, purchaseOrderValidator validator.PurchaseOrderValidator, purchaseCategoryService service.PurchaseCategoryService, purchaseCategoryValidator validator.PurchaseCategoryValidator, unitConverterService service.IngredientUnitConverterService, unitConverterValidator validator.IngredientUnitConverterValidator, chartOfAccountTypeService service.ChartOfAccountTypeService, chartOfAccountTypeValidator validator.ChartOfAccountTypeValidator, chartOfAccountService service.ChartOfAccountService, chartOfAccountValidator validator.ChartOfAccountValidator, accountService service.AccountService, accountValidator validator.AccountValidator, orderIngredientTransactionService service.OrderIngredientTransactionService, orderIngredientTransactionValidator validator.OrderIngredientTransactionValidator, gamificationService service.GamificationService, gamificationValidator validator.GamificationValidator, rewardService service.RewardService, rewardValidator validator.RewardValidator, campaignService service.CampaignService, campaignValidator validator.CampaignValidator, customerAuthService service.CustomerAuthService, customerAuthValidator validator.CustomerAuthValidator, customerPointsService service.CustomerPointsService, spinGameService service.SpinGameService, customerAuthMiddleware *middleware.CustomerAuthMiddleware, userDeviceService service.UserDeviceService, userDeviceValidator validator.UserDeviceValidator, notificationService service.NotificationService, notificationValidator validator.NotificationValidator, productOutletPriceService service.ProductOutletPriceService, productOutletPriceValidator validator.ProductOutletPriceValidator, selfOrderHandler *handler.SelfOrderHandler, expenseService *service.ExpenseServiceImpl, expenseValidator *validator.ExpenseValidatorImpl, cashAdvanceService service.CashAdvanceService, cashAdvanceValidator validator.CashAdvanceValidator, walletAdminService service.WalletAdminService, walletValidator validator.WalletValidator, loyaltySettingsService service.LoyaltySettingsService, customerPinService service.CustomerPinService, pointPaymentService service.PointPaymentService, customerOrderPaymentService service.CustomerOrderPaymentService, customerWalletService service.CustomerWalletService, customerDeviceService service.CustomerDeviceService, customerOutletService service.CustomerOutletService, customerOrderService service.CustomerOrderService, redisClient *redis.Client) *Router { return &Router{ config: cfg, @@ -121,6 +122,7 @@ func NewRouter(cfg *config.Config, healthHandler *handler.HealthHandler, authSer customerWalletHandler: handler.NewCustomerWalletHandler(customerWalletService), customerDeviceHandler: handler.NewCustomerDeviceHandler(customerDeviceService), customerOutletHandler: handler.NewCustomerOutletHandler(customerOutletService), + customerOrderHandler: handler.NewCustomerOrderHandler(customerOrderService), redisClient: redisClient, } } @@ -182,6 +184,8 @@ func (r *Router) addAppRoutes(rg *gin.Engine) { customer.PUT("/devices", r.customerDeviceHandler.Register) customer.DELETE("/devices/:device_id", r.customerDeviceHandler.Unregister) customer.GET("/outlets", r.customerOutletHandler.List) + customer.GET("/orders", r.customerOrderHandler.List) + customer.GET("/orders/:id", r.customerOrderHandler.Detail) customer.POST("/orders/:id/pay-with-points", r.customerOrderPaymentHandler.PayWithPoints) // PIN that approves moving EnakPoint and EnakCoin (docs/prd-point-coin.md F11) customer.GET("/pin/status", r.customerPinHandler.Status) diff --git a/internal/router/router_test.go b/internal/router/router_test.go index 75cafc7..18a39f5 100644 --- a/internal/router/router_test.go +++ b/internal/router/router_test.go @@ -45,6 +45,8 @@ func TestAllRoutesRegister(t *testing.T) { "PUT /api/v1/customer/devices", "DELETE /api/v1/customer/devices/:device_id", "GET /api/v1/customer/outlets", + "GET /api/v1/customer/orders", + "GET /api/v1/customer/orders/:id", "GET /api/v1/orders/:id/point-payment/preview", "POST /api/v1/customer/orders/:id/pay-with-points", "GET /api/v1/customer/pin/status", diff --git a/internal/service/customer_order_service.go b/internal/service/customer_order_service.go new file mode 100644 index 0000000..50019c5 --- /dev/null +++ b/internal/service/customer_order_service.go @@ -0,0 +1,57 @@ +package service + +import ( + "context" + "errors" + + "github.com/google/uuid" + + "apskel-pos-be/internal/constants" + "apskel-pos-be/internal/contract" + "apskel-pos-be/internal/models" + "apskel-pos-be/internal/processor" + "apskel-pos-be/internal/repository" +) + +// CustomerOrderService serves the customer app's order history. +type CustomerOrderService interface { + List(ctx context.Context, customerID uuid.UUID, query models.ListCustomerOrdersQuery) *contract.Response + Detail(ctx context.Context, customerID, orderID uuid.UUID) *contract.Response +} + +type CustomerOrderServiceImpl struct { + orders *processor.CustomerOrderProcessor +} + +func NewCustomerOrderService(orders *processor.CustomerOrderProcessor) *CustomerOrderServiceImpl { + return &CustomerOrderServiceImpl{orders: orders} +} + +func (s *CustomerOrderServiceImpl) List(ctx context.Context, customerID uuid.UUID, query models.ListCustomerOrdersQuery) *contract.Response { + orders, err := s.orders.List(ctx, customerID, query) + if err != nil { + return customerOrderErrorResponse(err) + } + return contract.BuildSuccessResponse(orders) +} + +func (s *CustomerOrderServiceImpl) Detail(ctx context.Context, customerID, orderID uuid.UUID) *contract.Response { + order, err := s.orders.Detail(ctx, customerID, orderID) + if err != nil { + return customerOrderErrorResponse(err) + } + return contract.BuildSuccessResponse(order) +} + +func customerOrderErrorResponse(err error) *contract.Response { + code := constants.InternalServerErrorCode + switch { + case errors.Is(err, repository.ErrCustomerOrderNotFound): + code = constants.NotFoundErrorCode + case errors.Is(err, processor.ErrInvalidWalletQuery): + code = constants.ValidationErrorCode + } + return contract.BuildErrorResponse([]*contract.ResponseError{ + contract.NewResponseError(code, constants.RequestEntity, err.Error()), + }) +} From f16a5da9517181d2acf560267c367e1290aecf00 Mon Sep 17 00:00:00 2001 From: efrilm Date: Wed, 30 Sep 2026 19:39:52 +0700 Subject: [PATCH 5/5] docs(customer): mobile app guide, outlets, order history and registration Adds docs/mobile-customer-enakpoint.md, written as a brief for building the customer app: the UI rules, the API conventions, each screen with its requests and responses, push handling, PIN flows, paying at the cashier, exchange, transfer, games, what was removed, and a checklist. It covers the new GET /customer/outlets, GET /customer/orders and /customer/orders/:id, and the optional organization_id at registration, which the API reference now lists too. Co-Authored-By: Claude Opus 5.5 --- docs/api-enakpoint.md | 5 + docs/mobile-customer-enakpoint.md | 614 ++++++++++++++++++++++++++++++ 2 files changed, 619 insertions(+) create mode 100644 docs/mobile-customer-enakpoint.md diff --git a/docs/api-enakpoint.md b/docs/api-enakpoint.md index 1aeb01b..0f168b1 100644 --- a/docs/api-enakpoint.md +++ b/docs/api-enakpoint.md @@ -41,6 +41,11 @@ Semua endpoint EnakPoint (`POINT`, bisa bayar order) dan EnakCoin (`COIN`, untuk | GET | `/customer/wallet/expiring` | Saldo yang akan kedaluwarsa, per currency dan tanggal | | PUT | `/customer/devices` | Daftarkan token FCM device | | DELETE | `/customer/devices/:device_id` | Hapus device saat logout | +| GET | `/customer/outlets` | Outlet aktif di organisasi customer, dengan `accepts_point_payment`, `earns_points`, `earns_coins` | +| GET | `/customer/orders` | Riwayat order customer (`page`, `limit`), dengan `points_earned` / `coins_earned` | +| GET | `/customer/orders/:id` | Detail order: item, pembayaran, EnakPoint yang dipakai; order customer lain → `404` | + +Registrasi (`POST /customer-auth/register/start`) menerima `organization_id` opsional: bila tidak dikirim dan hanya ada satu organisasi, customer masuk ke organisasi itu. Contoh request dan response lengkap untuk outlet dan order ada di [`mobile-customer-enakpoint.md`](./mobile-customer-enakpoint.md) §4.4–§4.5. ### GET /customer/wallet diff --git a/docs/mobile-customer-enakpoint.md b/docs/mobile-customer-enakpoint.md new file mode 100644 index 0000000..1c7a8d2 --- /dev/null +++ b/docs/mobile-customer-enakpoint.md @@ -0,0 +1,614 @@ +# Prompt: fitur EnakPoint & EnakCoin di Mobile App Customer + +Kamu mengerjakan aplikasi mobile untuk **customer** (bukan kasir, bukan backoffice). +Tugasmu: membangun fitur loyalitas EnakPoint & EnakCoin di aplikasi, memakai API backend +yang sudah jadi dan dijelaskan di dokumen ini. Jangan mengarang endpoint, field, atau +aturan yang tidak tertulis di sini; kalau ada yang kurang jelas, tanyakan dulu. + +--- + +## 1. Konteks bisnis + +| | EnakPoint (`POINT`) | EnakCoin (`COIN`) | +|---|---|---| +| Didapat dari | Belanja (order lunas), koreksi admin, tukar EnakCoin | Belanja, koreksi admin | +| Dipakai untuk | **Membayar order** | **Main game**, ditukar ke EnakPoint | +| Bisa dikirim ke customer lain | Ya | Ya | +| Bisa kedaluwarsa | Ya, bila owner mengaktifkan | Ya, bila owner mengaktifkan | + +Tidak ada lagi "token". Semua yang dulu token sekarang EnakCoin, dan endpoint serta +field bernama token sudah dihapus dari API. + +### Aturan yang wajib dipatuhi di UI + +1. **Semua jumlah bilangan bulat.** Tidak ada desimal pada EnakPoint atau EnakCoin. +2. **Saldo bukan uang.** Nilai rupiah EnakPoint selalu ditulis **"setara potongan + Rp …"**, tidak pernah "saldo Rp …" atau "uang". Tidak ada fitur tarik tunai. +3. **PIN 6 digit wajib** untuk: membuat kode bayar, tukar + EnakCoin, dan transfer. **Main game tidak butuh PIN.** Melihat saldo dan riwayat + tidak butuh PIN. +4. **PIN terpisah dari password login** dan selalu dikirim sebagai **string** (supaya + nol di depan tidak hilang). Jangan pernah menyimpan PIN di perangkat, log, atau + analytics. +5. **Satu akun customer = satu organisasi.** Saldo berlaku di semua outlet organisasi itu. +6. **Waktu memakai WIB.** Tanggal kedaluwarsa berarti saldo masih bisa dipakai sampai + 23:59:59 WIB di tanggal itu. + +--- + +## 2. Koneksi ke API + +- Base URL: `/api/v1` +- Semua endpoint customer: header `Authorization: Bearer ` +- Semua jumlah di request dan response berupa integer. + +### Registrasi customer + +`POST /api/v1/customer-auth/register/start` menerima `organization_id` (opsional): + +```json +{ "phone_number": "0812…", "name": "Budi", "birth_date": "2000-01-31", "organization_id": "648b96a0-1d1d-414e-baee-37e9d6317b4e" } +``` + +- Customer terdaftar di satu organisasi, dan saldonya berlaku di semua outlet organisasi itu. +- Bila `organization_id` tidak dikirim dan backend hanya punya satu organisasi, customer + otomatis masuk ke organisasi itu. Bila ada lebih dari satu, registrasi ditolak + ("organization_id is required"), jadi sebaiknya app selalu mengirimnya dari config per + environment/brand. +- `organization_id` yang dikirim harus ada; bila tidak, registrasi ditolak sebelum OTP dikirim. +- Wallet customer baru belum punya baris sampai saldo pertama kali bergerak; + `GET /customer/wallet` tetap menjawab saldo 0. + +### Format response + +Sukses: + +```json +{ "success": true, "data": { … }, "errors": null } +``` + +Gagal: + +```json +{ "success": false, "data": null, "errors": [{ "code": "304", "entity": "wallet_service", "cause": "wallet move refused: not enough EnakCoin" }] } +``` + +| `errors[0].code` | HTTP | Arti | Yang dilakukan app | +|---|---|---|---| +| `303`, `310` | 400 | Request tidak lengkap / salah format | Bug di app; tampilkan pesan umum | +| `304` | 400 | Ditolak aturan bisnis | Tampilkan pesan yang ramah (lihat tiap fitur); `cause` berbahasa Inggris, jangan tampilkan mentah | +| `404` | 404 | Tidak ditemukan | Tampilkan "tidak ditemukan" | +| `429` | 429 | Minta OTP terlalu cepat | Tampilkan hitung mundur sebelum boleh minta lagi | +| `PIN_NOT_SET` | 403 | Belum punya PIN | Buka alur buat PIN (§6.2) | +| `PIN_INVALID` | 400 | PIN salah | §6.5 | +| `PIN_LOCKED` | 423 | PIN terkunci | §6.5 | +| `TRANSFER_BLOCKED` | 403 | Transfer ditahan setelah reset PIN | §6.5 | +| `900` | 500 | Error server | "Terjadi kesalahan, coba lagi" | + +### Idempotency-Key + +Endpoint **tukar** dan **transfer** wajib header `Idempotency-Key` (string unik, maks. +50 karakter, mis. UUID v4). + +- Buat **satu key baru saat customer menekan tombol konfirmasi**. +- Bila request gagal karena jaringan/timeout, **kirim ulang dengan key yang sama**. + Server mengembalikan hasil pertama dengan `"replayed": true` dan tidak memotong saldo + dua kali. +- Jangan pakai ulang key untuk transaksi yang berbeda; server menolaknya (`304`). + +--- + +## 3. Layar yang perlu dibuat + +| Layar | Endpoint utama | Butuh PIN | +|---|---|---| +| Beranda wallet | `GET /customer/wallet` | – | +| Riwayat mutasi | `GET /customer/wallet/transactions` | – | +| Saldo akan kedaluwarsa | `GET /customer/wallet/expiring` | – | +| Daftar outlet | `GET /customer/outlets` | – | +| Riwayat order + detail | `GET /customer/orders`, `GET /customer/orders/:id` | – | +| Kode bayar (angka + QR) | `POST /customer/wallet/payment-code` | Ya | +| Tukar EnakCoin | `GET …/exchange/preview`, `POST /customer/wallet/exchange` | Ya | +| Transfer | `GET …/transfer/recipient`, `POST /customer/wallet/transfer` | Ya | +| PIN (buat, ganti, lupa) | `/customer/pin/*` | – | +| Game | `POST /customer/spin` | – | +| (latar belakang) registrasi push | `PUT` / `DELETE /customer/devices` | – | + +--- + +## 4. Beranda wallet, riwayat, kedaluwarsa + +### 4.1 Beranda — `GET /customer/wallet` + +```json +{ + "point_balance": 12500, + "coin_balance": 8, + "point_value": 1, + "point_discount_value": 12500, + "nearest_expiring": { + "point": { "amount": 150, "date": "2026-12-31" }, + "coin": null + }, + "recent_transactions": [ /* sama dengan item riwayat §4.2, maksimal 5 */ ] +} +``` + +Tampilkan: +- Saldo EnakPoint (`point_balance`) dengan keterangan "setara potongan Rp + {point_discount_value}" (format ribuan Indonesia: `Rp 12.500`). +- Saldo EnakCoin (`coin_balance`). +- Bila `nearest_expiring.point` / `.coin` tidak `null`: banner "{amount} EnakPoint akan + kedaluwarsa pada {date}" yang membuka layar §4.3. +- 5 mutasi terakhir dari `recent_transactions`, dengan tautan "Lihat semua" ke §4.2. +- Tombol aksi: Bayar di kasir (§7.1), Tukar EnakCoin (§8.1), Transfer (§8.2), Main game (§9). + +Muat ulang beranda setelah setiap transaksi dan saat menerima push (§5). + +Field `total_points`, `points_history`, `last_updated` di response ini **deprecated**; +jangan dipakai. + +### 4.2 Riwayat — `GET /customer/wallet/transactions` + +Query (semua opsional): + +| Query | Contoh | Keterangan | +|---|---|---| +| `page` | `1` | Mulai dari 1 | +| `limit` | `20` | 1–100, default 20 | +| `currency` | `POINT` | `POINT` atau `COIN`; untuk tab EnakPoint / EnakCoin | +| `type` | `EARN,PAYMENT` | Satu atau beberapa tipe dipisah koma, untuk filter | +| `from`, `to` | `2026-09-01` | Tanggal WIB, inklusif | + +```json +{ + "data": [ + { + "id": "…", + "currency": "POINT", + "type": "EARN", + "amount": 875, + "balance_after": 12500, + "description": "Belanja #ORD-0123 di Outlet Kemang", + "source": { "type": "ORDER", "id": "…" }, + "outlet_id": "…", + "group_id": null, + "expires_at": "2026-12-31T23:59:59+07:00", + "lots": [{ "amount": 875, "remaining": 875, "expires_at": "2026-12-31T23:59:59+07:00" }], + "created_at": "2026-09-30T12:01:00Z" + } + ], + "pagination": { "page": 1, "limit": 20, "total_count": 42, "total_pages": 3 } +} +``` + +Aturan tampilan: +- `amount` bertanda: positif tampil hijau dengan `+`, negatif merah dengan `−`. +- `description` sudah siap tampil (nama lawan transfer sudah disamarkan). Tampilkan apa + adanya. +- Mutasi masuk yang punya `expires_at` menampilkan "Berlaku sampai {tanggal}". +- Infinite scroll memakai `pagination.total_pages`. +- Riwayat tidak pernah berubah atau hilang; koreksi muncul sebagai baris baru. + +Label tipe: + +| `type` | Label | Arah | +|---|---|---| +| `EARN` | Dari belanja | + | +| `EARN_REVERSAL` | Dibatalkan (order di-void/refund) | − | +| `PAYMENT` | Bayar pesanan | − | +| `PAYMENT_REFUND` | Pengembalian pembayaran | + | +| `EXCHANGE_OUT` | Ditukar ke EnakPoint | − | +| `EXCHANGE_IN` | Hasil tukar EnakCoin | + | +| `TRANSFER_OUT` | Transfer keluar | − | +| `TRANSFER_IN` | Transfer masuk | + | +| `GAME_SPEND` | Main game | − | +| `EXPIRE` | Kedaluwarsa | − | +| `ADJUSTMENT` | Koreksi | + / − | +| `MIGRATION` | Saldo awal | + | + +### 4.3 Akan kedaluwarsa — `GET /customer/wallet/expiring` + +```json +{ + "point": [ + { "amount": 150, "date": "2026-10-31" }, + { "amount": 200, "date": "2026-12-31" } + ], + "coin": [] +} +``` + +Daftar per tanggal, paling dekat di atas. Daftar kosong: tampilkan "Tidak ada saldo +yang akan kedaluwarsa". Saldo yang kedaluwarsa hangus tanpa kompensasi. + +--- + +### 4.4 Daftar outlet — `GET /customer/outlets` + +Outlet aktif di organisasi customer, tempat saldo EnakPoint & EnakCoin berlaku. Urut +berdasarkan nama. + +```json +[ + { + "id": "…", + "name": "Gokuna Kemang", + "address": "Jl. Kemang Raya 10", + "accepts_point_payment": true, + "earns_points": true, + "earns_coins": false + } +] +``` + +- `address` bisa `null`. +- `accepts_point_payment`: kasir di outlet ini menerima pembayaran EnakPoint. Pakai + untuk label "Bisa bayar pakai EnakPoint". +- `earns_points` / `earns_coins`: belanja di outlet ini memberi EnakPoint / EnakCoin. +- Belum ada telepon, koordinat, atau jam buka; data itu belum disimpan di backend. + + +### 4.5 Riwayat order — `GET /customer/orders` dan `GET /customer/orders/:id` + +Order milik customer yang login di semua outlet organisasinya, terbaru di atas. Order +hanya masuk ke sini bila kasir mengaitkannya ke customer. + +`GET /api/v1/customer/orders?page=1&limit=20` (`limit` 1–100, default 20): + +```json +{ + "data": [ + { + "id": "…", + "order_number": "ORD-0123", + "outlet_id": "…", + "outlet_name": "Gokuna 1", + "order_type": "dine_in", + "status": "completed", + "payment_status": "completed", + "total_amount": 99000, + "item_count": 2, + "is_void": false, + "is_refund": false, + "points_earned": 865, + "coins_earned": 3, + "created_at": "2026-09-30T12:01:00Z" + } + ], + "pagination": { "page": 1, "limit": 20, "total_count": 42, "total_pages": 3 } +} +``` + +`GET /api/v1/customer/orders/{id}` mengembalikan field yang sama, ditambah: + +```json +{ + "table_number": "A3", + "subtotal": 90000, + "discount_amount": 0, + "tax_amount": 9000, + "refund_amount": 0, + "items": [ + { + "id": "…", + "product_id": "…", + "product_name": "Kopi Susu", + "variant_name": "Large", + "quantity": 2, + "unit_price": 25000, + "total_price": 50000, + "refund_quantity": 0, + "modifiers": [], + "status": "completed" + }, + { + "id": "…", + "product_id": "…", + "product_name": "Ikan Tude", + "variant_name": null, + "quantity": 1, + "weight": 4.2, + "unit_name": "ons", + "unit_price": 4500, + "total_price": 18900, + "refund_quantity": 0, + "modifiers": [], + "status": "completed" + } + ], + "payments": [ + { "id": "…", "method_name": "EnakPoint", "method_type": "point", "amount": 12500, "status": "completed", "refund_amount": 0, "points_used": 12500, "point_value": 1, "created_at": "…" }, + { "id": "…", "method_name": "Cash", "method_type": "cash", "amount": 86500, "status": "completed", "refund_amount": 0, "created_at": "…" } + ] +} +``` + +- Order customer lain atau yang tidak ada → `404`. +- `points_earned` / `coins_earned`: yang didapat dari order ini; 0 bila tidak ada. +- Item timbangan membawa `weight` dan `unit_name`; tampilkan "1 × 4,2 ons". +- Pembayaran EnakPoint membawa `points_used`; tampilkan "EnakPoint 12.500 (Rp 12.500)". +- Order yang `is_void` atau `is_refund` tetap tampil, beri label "Dibatalkan" / + "Direfund". + + +## 5. Notifikasi push (FCM) + +### 5.1 Registrasi device + +Setelah login berhasil **dan** setiap kali FCM memberi token baru (`onTokenRefresh`): + +`PUT /api/v1/customer/devices` + +```json +{ "device_id": "", "fcm_token": "", "platform": "android", "app_version": "2.4.0" } +``` + +- `device_id` wajib, stabil untuk satu instalasi (simpan di secure storage). +- `platform`: `android`, `ios`, atau `web`. +- Saat **logout**, panggil `DELETE /api/v1/customer/devices/{device_id}` sebelum + menghapus token login, supaya HP itu tidak lagi menerima notifikasi akun ini. + +Tanpa registrasi ini, customer tidak menerima push apa pun. + +### 5.2 Tipe push + +Semua nilai di `data` berupa string. + +| `data.type` | Kapan | Isi `data` lain | Aksi saat di-tap | +|---|---|---|---| +| `WALLET_TRANSFER_IN` | Menerima transfer | `transaction_id`, `group_id`, `currency`, `amount` | Buka riwayat, sorot transaksi itu | +| `WALLET_EXPIRING` | Beberapa hari sebelum saldo hangus | `currency`, `amount`, `expiry_date` | Buka layar kedaluwarsa (§4.3) | +| `WALLET_EXPIRED` | Saldo baru saja hangus | `currency`, `amount` | Buka riwayat | +| `PIN_LOCKED` | PIN terkunci setelah 5 kali salah | `locked_until` (RFC3339 UTC) | Buka layar lupa PIN (§6.4) | + +Saat app terbuka dan menerima push wallet, muat ulang beranda. + +--- + +## 6. PIN + +### 6.1 Kapan diminta + +Jangan minta PIN saat registrasi. Minta saat customer **pertama kali** melakukan aksi +yang butuh PIN. Cek dengan: + +`GET /api/v1/customer/pin/status` → `{ "has_pin": false, "locked_until": null, "transfer_blocked_until": null }` + +Bila `has_pin: false`, arahkan ke alur buat PIN, lalu kembali ke aksi semula. + +### 6.2 Buat PIN + +1. `POST /api/v1/customer/pin/otp` dengan `{ "purpose": "pin_setup" }`. + Response: `{ "purpose": "pin_setup", "otp_token": "…", "expires_at": "…" }`. + OTP dikirim ke WhatsApp customer. +2. Customer memasukkan kode OTP, lalu PIN dua kali. +3. `POST /api/v1/customer/pin` dengan + `{ "otp_token": "…", "otp_code": "123456", "pin": "482913", "confirm_pin": "482913" }`. + Response: status PIN. + +Validasi di app sebelum kirim (server juga memeriksa, jawab `304`): +- Tepat 6 digit angka, dan konfirmasi sama. +- Bukan satu digit berulang (`111111`). +- Bukan berurutan naik/turun (`123456`, `654321`). +- Bukan tanggal lahir customer (`DDMMYY` atau `YYMMDD`). + +Minta OTP lagi terlalu cepat → `429`: tampilkan hitung mundur. + +### 6.3 Ganti PIN + +`PUT /api/v1/customer/pin` dengan `{ "old_pin": "…", "pin": "…", "confirm_pin": "…" }`. + +### 6.4 Lupa PIN + +1. `POST /customer/pin/otp` dengan `{ "purpose": "pin_reset" }`. +2. `POST /customer/pin/reset` dengan `{ "otp_token", "otp_code", "pin", "confirm_pin" }`. + +Reset juga membuka PIN yang terkunci. Setelah reset, **transfer keluar ditahan 24 jam**; +bayar dan tukar tetap bisa. Beri tahu customer hal ini di layar sukses. + +### 6.5 Menangani error PIN + +Semua endpoint yang menerima `pin` bisa menjawab error PIN. Pada error ini **`data` +tidak `null`**: + +```json +{ "success": false, "data": { "code": "PIN_INVALID", "remaining_attempts": 3 }, "errors": [ … ] } +``` + +| `data.code` | Field tambahan | Tampilan | +|---|---|---| +| `PIN_NOT_SET` | – | Buka alur buat PIN (§6.2) | +| `PIN_INVALID` | `remaining_attempts` | "PIN salah, sisa {n} percobaan." Kosongkan input PIN | +| `PIN_LOCKED` | `locked_until` | "PIN terkunci sampai {jam}." Tombol "Lupa PIN" | +| `TRANSFER_BLOCKED` | `transfer_blocked_until` | "Transfer bisa dilakukan lagi pada {waktu}." | + +5 kali salah berturut-turut mengunci PIN 30 menit; selama terkunci PIN yang benar pun +ditolak. Penghitung ada di server, jadi jangan membuat penghitung sendiri di app. + +--- + +## 7. Membayar dengan EnakPoint + +App customer tidak membuat atau membayar order; order hanya bisa dilihat (§4.5). +EnakPoint hanya dipakai membayar di kasir, lewat kode bayar dari app. Jangan membangun +layar checkout atau memanggil `POST /customer/orders/:id/pay-with-points`. + +### 7.1 Di kasir — kode bayar + +Customer tidak pernah mengetik PIN di mesin kasir. Alurnya: + +1. Customer membuka "Bayar di kasir" dan memasukkan PIN. +2. `POST /api/v1/customer/wallet/payment-code` dengan `{ "pin": "482913" }`: + + ```json + { "code": "482913", "qr_payload": "enakpoint:482913", "expires_at": "2026-09-30T05:02:00Z" } + ``` + +3. Tampilkan `code` besar (angka) **dan** QR dari `qr_payload` (string apa adanya). +4. Tampilkan hitung mundur ke `expires_at` (2 menit). Setelah habis, sembunyikan kode + dan tampilkan tombol "Buat kode baru". +5. Kasir memindai/mengetik kode dan memilih jumlah EnakPoint. App tidak menerima + callback; setelah customer kembali ke beranda, muat ulang saldo. + +Kode sekali pakai. Membuat kode baru membatalkan kode lama. + +### 7.2 Refund + +Bila order yang dibayar EnakPoint dibatalkan atau direfund, EnakPoint kembali sebagai +EnakPoint (tidak pernah tunai) dan muncul di riwayat sebagai `PAYMENT_REFUND`. + +--- + +## 8. Tukar dan transfer + +### 8.1 Tukar EnakCoin → EnakPoint + +1. Customer mengetik jumlah EnakCoin. Panggil preview (debounce saat mengetik): + + `GET /api/v1/customer/wallet/exchange/preview?coins=30` + + ```json + { "coin_amount": 10, "point_amount": 3, "coin_balance": 35, "coins": 30, "points": 9, "valid": true } + ``` + + - Kurs: `coin_amount` EnakCoin = `point_amount` EnakPoint. Tampilkan "10 EnakCoin = + 3 EnakPoint". + - Bila `valid: false`, tampilkan `reason` sebagai alasan dan nonaktifkan tombol. Jumlah + harus kelipatan `coin_amount`. + - Tampilkan "Kamu akan mendapat {points} EnakPoint". + +2. Konfirmasi (tukar tidak bisa dibatalkan) → minta PIN → + + `POST /api/v1/customer/wallet/exchange` + header `Idempotency-Key` + + ```json + { "coins": 30, "pin": "482913" } + ``` + + ```json + { + "group_id": "…", + "coins": 30, + "points": 9, + "coin_amount": 10, + "point_amount": 3, + "lots": [{ "amount": 9, "expires_at": "2026-12-31T23:59:59+07:00" }], + "coin_balance": 5, + "point_balance": 9, + "replayed": false + } + ``` + +3. Layar sukses: saldo baru, dan bila `lots[].expires_at` ada, "EnakPoint ini berlaku + sampai {tanggal}". + +### 8.2 Transfer + +1. Pilih mata uang (EnakPoint / EnakCoin), isi nomor HP penerima dan jumlah. +2. Cek penerima: + + `GET /api/v1/customer/wallet/transfer/recipient?phone=081234561234` + + ```json + { "name": "Bu*** Sa***", "phone_number": "08**-****-1234" } + ``` + + | Hasil | Tampilan | + |---|---| + | Sukses | "Kirim ke Bu*** Sa*** (08**-****-1234)?" | + | `404` | "Nomor ini tidak terdaftar" | + | `304` | "Tidak bisa mengirim ke nomor ini" (diri sendiri, akun nonaktif) | + +3. Konfirmasi (transfer final, tidak bisa dibatalkan) → minta PIN → + + `POST /api/v1/customer/wallet/transfer` + header `Idempotency-Key` + + ```json + { "currency": "POINT", "amount": 120, "recipient_phone": "081234561234", "pin": "482913" } + ``` + + ```json + { + "group_id": "…", + "currency": "POINT", + "amount": 120, + "recipient": { "name": "Bu*** Sa***", "phone_number": "08**-****-1234" }, + "lots": [ + { "amount": 100, "expires_at": "2026-12-31T23:59:59+07:00" }, + { "amount": 20, "expires_at": null } + ], + "balance": 30, + "replayed": false + } + ``` + +4. Layar sukses: saldo tersisa (`balance`). Bila ada `lots[].expires_at`, tampilkan + "Saldo yang dikirim berlaku sampai {tanggal}" (tanggal kedaluwarsa ikut terbawa ke + penerima). + +Penolakan `304` yang mungkin: transfer dimatikan owner, di bawah minimal, di atas +maksimal per transaksi, melewati batas harian (reset tengah malam WIB), saldo tidak +cukup. Tampilkan pesan umum "Transfer tidak bisa diproses" plus alasan yang sesuai +bila bisa dikenali. Bila kena `TRANSFER_BLOCKED`, ikuti §6.5. + +Penerima mendapat push `WALLET_TRANSFER_IN`. + +--- + +## 9. Game (memakai EnakCoin) + +`POST /api/v1/customer/spin` dengan `{ "spin_id": "" }`. Tanpa PIN. + +```json +{ + "game_play": { "id": "…", "game_id": "…", "coins_used": 1, "created_at": "…" }, + "prize_won": { "id": "…", "name": "Voucher 10rb" }, + "coins_remaining": 7 +} +``` + +- Setiap game punya biaya sendiri: `metadata.coin_cost` pada data game dari + `GET /api/v1/customer/games` (atau `GET /customer/ferris-wheel`), default 1 bila kosong. + Tampilkan biaya sebelum main, dan nonaktifkan tombol bila `coin_balance` kurang. +- `304`: EnakCoin kurang, game nonaktif, atau hadiah baru saja habis. Tidak ada + EnakCoin yang terpotong; tampilkan pesan dan biarkan customer mencoba lagi. +- Setelah main, perbarui saldo EnakCoin dari `coins_remaining`. + +--- + +## 10. Yang sudah dihapus / deprecated + +Sudah **dihapus** dari API (jangan dipanggil, akan error / tidak ada): + +| Lama | Pengganti | +|---|---| +| `GET /customer/tokens` | `GET /customer/wallet` → `coin_balance` | +| `total_tokens`, `tokens_history` | `coin_balance`, `GET /customer/wallet/transactions?currency=COIN` | +| `token_used`, `tokens_remaining` di response game | `coins_used`, `coins_remaining` | + +Masih ada tapi **deprecated** (akan dihapus, jangan dipakai di kode baru): + +| Lama | Pengganti | +|---|---| +| `GET /customer/points` | `GET /customer/wallet` → `point_balance` | +| `total_points`, `points_history`, `last_updated` di `/customer/wallet` | `point_balance`, `recent_transactions` | + +--- + +## 11. Checklist selesai + +- [ ] Beranda menampilkan saldo EnakPoint ("setara potongan Rp …"), EnakCoin, dan banner kedaluwarsa terdekat. +- [ ] Riwayat dengan tab per mata uang, filter tipe/tanggal, infinite scroll, label tipe sesuai §4.2. +- [ ] Layar saldo akan kedaluwarsa. +- [ ] Registrasi device FCM setelah login dan saat token berganti; unregister saat logout. +- [ ] Penanganan tap untuk keempat tipe push. +- [ ] PIN diminta hanya saat aksi yang membutuhkan; alur buat, ganti, dan lupa PIN lewat OTP. +- [ ] Keempat error PIN ditangani di semua layar yang meminta PIN. +- [ ] Kode bayar: angka + QR, hitung mundur 2 menit, tombol buat ulang. +- [ ] Tukar dengan preview, kelipatan kurs, konfirmasi, `Idempotency-Key`, retry dengan key sama. +- [ ] Transfer dengan cek penerima tersamar, konfirmasi, `Idempotency-Key`, retry dengan key sama. +- [ ] Game memakai `coins_used` / `coins_remaining` dan menampilkan biaya per game. +- [ ] Riwayat order dengan pagination dan layar detail (item, pembayaran, EnakPoint/EnakCoin yang didapat). +- [ ] Tidak ada pemakaian endpoint atau field di §10. +- [ ] PIN tidak pernah disimpan, di-log, atau dikirim ke analytics.