web: the app's own date field and one date format for the dealer's locale

core/api/ROUTES.txt

@@ -167,6 +167,7 @@ GET	/api/v1/dashboard/summary	internal/dashboard	h.HandleSummary
 GET	/api/v1/dashboard/top-customers	internal/dashboard	h.HandleTopCustomers
 GET	/api/v1/dealer-profile	internal/dealerprofile	guarded(g.Read, h.Get)
 PUT	/api/v1/dealer-profile	internal/dealerprofile	guarded(g.Write, h.Put)
+GET	/api/v1/dealer-profile/locale	internal/dealerprofile	guarded(g.Locale, h.GetLocale)
 GET	/api/v1/dealer-profile/logo	internal/dealerprofile	guarded(g.Read, h.GetLogo)
 PUT	/api/v1/dealer-profile/logo	internal/dealerprofile	guarded(g.Write, h.PutLogo)
 POST	/api/v1/delivery/deliveries	internal/delivery	h.HandleAssignOrder

core/api/fragments/dealerprofile.yaml

@@ -41,7 +41,8 @@ paths:
       tags: [dealer-profile]
       summary: Replace the dealer profile
       description: >-
-        Replaces the writable fields (the logo has its own route). Role gated
+        Replaces the writable fields (the logo has its own route; a locale left
+        out keeps the stored one). Role gated
         admin and owner. The revision precondition applies: If-Match or the
         body revision, 428 without either, 409 stale_revision when stale. A
         branch bound machine key is refused. The write is audited with the
@@ -80,6 +81,32 @@ paths:
           $ref: "#/components/responses/WirePreconditionRequired"
         "500":
           $ref: "#/components/responses/WireInternalError"
+  /api/v1/dealer-profile/locale:
+    get:
+      operationId: dealerProfileLocaleGet
+      tags: [dealer-profile]
+      summary: Read the dealer's locale alone
+      description: >-
+        The locale alone, {"locale": "en-CA"}: every signed in desk person may
+        call it (the profile read itself is held to the roles that print), so
+        every page can format its dates for the dealer's locale.
+      security:
+        - BearerJWT: []
+      responses:
+        "200":
+          description: The dealer's locale.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DealerProfileLocale"
+        "400":
+          $ref: "#/components/responses/WireBadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "500":
+          $ref: "#/components/responses/WireInternalError"
   /api/v1/dealer-profile/logo:
     get:
       operationId: dealerProfileLogoGet
@@ -169,9 +196,16 @@ paths:
           $ref: "#/components/responses/WireInternalError"
 components:
   schemas:
+    DealerProfileLocale:
+      type: object
+      required: [locale]
+      properties:
+        locale:
+          type: string
+          description: The dealer's locale (a BCP 47 tag).
     DealerProfile:
       type: object
-      required: [legal_name, trading_name, phone, email, website, remit_to, logo_url, revision, updated_at]
+      required: [legal_name, trading_name, phone, email, website, remit_to, locale, logo_url, revision, updated_at]
       properties:
         legal_name:
           type: string
@@ -186,6 +220,9 @@ components:
         remit_to:
           type: string
           description: The address payments are sent to; invoices and statements print it.
+        locale:
+          type: string
+          description: The dealer's locale (a BCP 47 tag, default en-US); every date the app shows is formatted for it.
         logo_url:
           type: [string, "null"]
           description: /api/v1/dealer-profile/logo when a logo is set, otherwise null.
@@ -217,6 +254,10 @@ components:
         remit_to:
           type: string
           maxLength: 1000
+        locale:
+          type: string
+          maxLength: 35
+          description: A BCP 47 tag (en-US, en-CA), refused in words otherwise. Leave it out to keep the stored one.
         revision:
           type: integer
           format: int64

core/api/fragments/portal.yaml

@@ -70,7 +70,7 @@ paths:
       operationId: portalGetConfig
       tags: [portal]
       summary: The dealer branding config
-      description: Public. The one row of white-label branding the login page renders before any session exists.
+      description: Public. The one row of white-label branding the login page renders before any session exists, with the dealer's locale for the portal's dates.
       security: []
       responses:
         "200":
@@ -1227,7 +1227,7 @@ components:
           format: date-time
     PortalConfig:
       type: object
-      required: [id, dealer_name, logo_url, primary_color, support_email, support_phone, created_at, updated_at]
+      required: [id, dealer_name, logo_url, primary_color, support_email, support_phone, locale, created_at, updated_at]
       description: The white-label branding row.
       properties:
         id:
@@ -1243,6 +1243,9 @@ components:
           type: string
         support_phone:
           type: string
+        locale:
+          type: string
+          description: The dealer profile's locale (a BCP 47 tag); the portal's pages format their dates for it.
         created_at:
           type: string
           format: date-time

core/api/openapi.yaml

@@ -3244,7 +3244,7 @@ paths:
       tags: [dealer-profile]
       summary: Replace the dealer profile
       description: >-
-        Replaces the writable fields (the logo has its own route). Role gated admin and owner. The revision precondition applies: If-Match or the body revision, 428 without either, 409 stale_revision when stale. A branch bound machine key is refused. The write is audited with the before and after in one transaction.
+        Replaces the writable fields (the logo has its own route; a locale left out keeps the stored one). Role gated admin and owner. The revision precondition applies: If-Match or the body revision, 428 without either, 409 stale_revision when stale. A branch bound machine key is refused. The write is audited with the before and after in one transaction.
       security:
         - BearerJWT: []
       parameters:
@@ -3279,6 +3279,30 @@ paths:
           $ref: "#/components/responses/WirePreconditionRequired"
         "500":
           $ref: "#/components/responses/WireInternalError"
+  /api/v1/dealer-profile/locale:
+    get:
+      operationId: dealerProfileLocaleGet
+      tags: [dealer-profile]
+      summary: Read the dealer's locale alone
+      description: >-
+        The locale alone, {"locale": "en-CA"}: every signed in desk person may call it (the profile read itself is held to the roles that print), so every page can format its dates for the dealer's locale.
+      security:
+        - BearerJWT: []
+      responses:
+        "200":
+          description: The dealer's locale.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DealerProfileLocale"
+        "400":
+          $ref: "#/components/responses/WireBadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "500":
+          $ref: "#/components/responses/WireInternalError"
   /api/v1/dealer-profile/logo:
     get:
       operationId: dealerProfileLogoGet
@@ -9621,7 +9645,7 @@ paths:
       operationId: portalGetConfig
       tags: [portal]
       summary: The dealer branding config
-      description: Public. The one row of white-label branding the login page renders before any session exists.
+      description: Public. The one row of white-label branding the login page renders before any session exists, with the dealer's locale for the portal's dates.
       security: []
       responses:
         "200":
@@ -18295,9 +18319,16 @@ components:
           type: integer
           format: int64
           description: Cents.
+    DealerProfileLocale:
+      type: object
+      required: [locale]
+      properties:
+        locale:
+          type: string
+          description: The dealer's locale (a BCP 47 tag).
     DealerProfile:
       type: object
-      required: [legal_name, trading_name, phone, email, website, remit_to, logo_url, revision, updated_at]
+      required: [legal_name, trading_name, phone, email, website, remit_to, locale, logo_url, revision, updated_at]
       properties:
         legal_name:
           type: string
@@ -18312,6 +18343,9 @@ components:
         remit_to:
           type: string
           description: The address payments are sent to; invoices and statements print it.
+        locale:
+          type: string
+          description: The dealer's locale (a BCP 47 tag, default en-US); every date the app shows is formatted for it.
         logo_url:
           type: [string, "null"]
           description: /api/v1/dealer-profile/logo when a logo is set, otherwise null.
@@ -18343,6 +18377,10 @@ components:
         remit_to:
           type: string
           maxLength: 1000
+        locale:
+          type: string
+          maxLength: 35
+          description: A BCP 47 tag (en-US, en-CA), refused in words otherwise. Leave it out to keep the stored one.
         revision:
           type: integer
           format: int64
@@ -23647,7 +23685,7 @@ components:
           format: date-time
     PortalConfig:
       type: object
-      required: [id, dealer_name, logo_url, primary_color, support_email, support_phone, created_at, updated_at]
+      required: [id, dealer_name, logo_url, primary_color, support_email, support_phone, locale, created_at, updated_at]
       description: The white-label branding row.
       properties:
         id:
@@ -23663,6 +23701,9 @@ components:
           type: string
         support_phone:
           type: string
+        locale:
+          type: string
+          description: The dealer profile's locale (a BCP 47 tag); the portal's pages format their dates for it.
         created_at:
           type: string
           format: date-time

core/go.mod

@@ -15,6 +15,7 @@ require (
 	github.com/santhosh-tekuri/jsonschema/v6 v6.0.2
 	github.com/xuri/excelize/v2 v2.11.0
 	golang.org/x/crypto v0.57.0
+	golang.org/x/text v0.42.0
 	gopkg.in/yaml.v3 v3.0.1
 )
 
@@ -51,7 +52,6 @@ require (
 	golang.org/x/net v0.60.0 // indirect
 	golang.org/x/sync v0.23.0 // indirect
 	golang.org/x/sys v0.48.0 // indirect
-	golang.org/x/text v0.42.0 // indirect
 	golang.org/x/time v0.9.0 // indirect
 	google.golang.org/protobuf v1.36.8 // indirect
 	gopkg.in/yaml.v2 v2.4.0 // indirect

core/internal/app/seed/profile.go

@@ -38,7 +38,10 @@ var demoLogoPNG = []byte{
 
 // seedDealerProfile sets the demo's invented dealer profile (migration 115's
 // single row) and logo. It writes only a profile that is still blank, so a
-// profile an operator has filled in is never overwritten by a re-seed.
+// profile an operator has filled in is never overwritten by a re-seed. The
+// locale is en-CA (the demo dealer is in British Columbia); a profile already
+// seeded by the demo that still sits on the migration's en-US default is
+// lifted to en-CA, while any other tag (an operator's own choice) is kept.
 func seedDealerProfile(db *sql.DB) {
 	res, err := db.Exec(`
 		UPDATE dealer_profile
@@ -48,6 +51,7 @@ func seedDealerProfile(db *sql.DB) {
 		       email = 'accounts@gablebuildingsupply.example',
 		       website = 'https://gablebuildingsupply.example',
 		       remit_to = 'Gable Building Supply, Accounts Receivable' || E'\n' || 'PO Box 4100, Kelowna BC V1Y 7R7',
+		       locale = 'en-CA',
 		       logo = $1, logo_content_type = 'image/png',
 		       revision = revision + 1, updated_at = NOW()
 		 WHERE id = 1 AND legal_name = '' AND trading_name = '' AND logo IS NULL`, demoLogo())
@@ -57,5 +61,11 @@ func seedDealerProfile(db *sql.DB) {
 	}
 	if n, _ := res.RowsAffected(); n > 0 {
 		fmt.Println("Seed: Dealer Profile (invented) and logo")
+		return
+	}
+	if _, err := db.Exec(`
+		UPDATE dealer_profile SET locale = 'en-CA', updated_at = NOW()
+		 WHERE id = 1 AND locale = 'en-US' AND trading_name = 'Gable Building Supply'`); err != nil {
+		log.Printf("seed: dealer profile locale: %v", err)
 	}
 }

core/internal/app/seed/seed_test.go

@@ -426,36 +426,40 @@ func TestPosRegisterUpsert_MovesOnlyTheSeedsOwnRow(t *testing.T) {
 }
 
 // The demo seed sets an invented dealer profile and logo, once: a profile the
-// operator has filled in is not overwritten by a re-seed.
+// operator has filled in is not overwritten by a re-seed. The locale is
+// en-CA (the demo dealer is in British Columbia): set on the blank write, and
+// lifted from the migration's en-US default on a profile the demo already
+// seeded; an operator's own tag is kept.
 //
 // DB-gated: it runs the seeder's actual statement against the single row.
 func TestDealerProfileSeed_SetsOnlyABlankProfile(t *testing.T) {
 	db := testutil.RequireDB(t)
 	ctx := context.Background()
 	type snap struct {
 		legal, trading, phone, email, website, remit string
+		locale                                       string
 		logo                                         []byte
 		ctype                                        *string
 		revision                                     int64
 	}
 	var orig snap
-	if err := db.Pool.QueryRow(ctx, `SELECT legal_name, trading_name, phone, email, website, remit_to, logo, logo_content_type, revision FROM dealer_profile WHERE id = 1`).
-		Scan(&orig.legal, &orig.trading, &orig.phone, &orig.email, &orig.website, &orig.remit, &orig.logo, &orig.ctype, &orig.revision); err != nil {
+	if err := db.Pool.QueryRow(ctx, `SELECT legal_name, trading_name, phone, email, website, remit_to, locale, logo, logo_content_type, revision FROM dealer_profile WHERE id = 1`).
+		Scan(&orig.legal, &orig.trading, &orig.phone, &orig.email, &orig.website, &orig.remit, &orig.locale, &orig.logo, &orig.ctype, &orig.revision); err != nil {
 		t.Fatal(err)
 	}
 	t.Cleanup(func() {
-		_, _ = db.Pool.Exec(ctx, `UPDATE dealer_profile SET legal_name=$1, trading_name=$2, phone=$3, email=$4, website=$5, remit_to=$6, logo=$7, logo_content_type=$8, revision=$9 WHERE id = 1`,
-			orig.legal, orig.trading, orig.phone, orig.email, orig.website, orig.remit, orig.logo, orig.ctype, orig.revision)
+		_, _ = db.Pool.Exec(ctx, `UPDATE dealer_profile SET legal_name=$1, trading_name=$2, phone=$3, email=$4, website=$5, remit_to=$6, locale=$7, logo=$8, logo_content_type=$9, revision=$10 WHERE id = 1`,
+			orig.legal, orig.trading, orig.phone, orig.email, orig.website, orig.remit, orig.locale, orig.logo, orig.ctype, orig.revision)
 	})
 	blank := func() {
 		t.Helper()
-		if _, err := db.Pool.Exec(ctx, `UPDATE dealer_profile SET legal_name='', trading_name='', phone='', email='', website='', remit_to='', logo=NULL, logo_content_type=NULL WHERE id = 1`); err != nil {
+		if _, err := db.Pool.Exec(ctx, `UPDATE dealer_profile SET legal_name='', trading_name='', phone='', email='', website='', remit_to='', locale='en-US', logo=NULL, logo_content_type=NULL WHERE id = 1`); err != nil {
 			t.Fatal(err)
 		}
 	}
-	read := func() (legal, remit string, hasLogo bool) {
+	read := func() (legal, remit, locale string, hasLogo bool) {
 		t.Helper()
-		if err := db.Pool.QueryRow(ctx, `SELECT legal_name, remit_to, logo IS NOT NULL FROM dealer_profile WHERE id = 1`).Scan(&legal, &remit, &hasLogo); err != nil {
+		if err := db.Pool.QueryRow(ctx, `SELECT legal_name, remit_to, locale, logo IS NOT NULL FROM dealer_profile WHERE id = 1`).Scan(&legal, &remit, &locale, &hasLogo); err != nil {
 			t.Fatal(err)
 		}
 		return
@@ -472,16 +476,31 @@ func TestDealerProfileSeed_SetsOnlyABlankProfile(t *testing.T) {
 
 	blank()
 	seedDealerProfile(sqlDB)
-	legal, remit, hasLogo := read()
+	legal, remit, locale, hasLogo := read()
 	if legal != "Gable Building Supply Ltd" || !strings.Contains(remit, "Accounts Receivable") || !hasLogo {
 		t.Fatalf("a blank profile was not seeded: %q %q logo=%v", legal, remit, hasLogo)
 	}
-	if _, err := db.Pool.Exec(ctx, `UPDATE dealer_profile SET legal_name = 'Edited By The Operator Ltd' WHERE id = 1`); err != nil {
+	if locale != "en-CA" {
+		t.Errorf("the seeded locale = %q, want en-CA", locale)
+	}
+	if _, err := db.Pool.Exec(ctx, `UPDATE dealer_profile SET legal_name = 'Edited By The Operator Ltd', locale = 'fr-CA' WHERE id = 1`); err != nil {
 		t.Fatal(err)
 	}
 	seedDealerProfile(sqlDB)
-	if legal, _, _ := read(); legal != "Edited By The Operator Ltd" {
+	if legal, _, locale, _ := read(); legal != "Edited By The Operator Ltd" {
 		t.Errorf("a re-seed overwrote the operator's profile: %q", legal)
+	} else if locale != "fr-CA" {
+		t.Errorf("a re-seed overwrote the operator's locale: %q", locale)
+	}
+
+	// A profile the demo already seeded that still sits on the migration's
+	// en-US default is lifted to en-CA.
+	if _, err := db.Pool.Exec(ctx, `UPDATE dealer_profile SET legal_name='Gable Building Supply Ltd', trading_name='Gable Building Supply', locale='en-US' WHERE id = 1`); err != nil {
+		t.Fatal(err)
+	}
+	seedDealerProfile(sqlDB)
+	if _, _, locale, _ := read(); locale != "en-CA" {
+		t.Errorf("the demo default was not lifted to en-CA: %q", locale)
 	}
 }
 

core/internal/app/serve/wire_branch_wall.go

@@ -355,10 +355,13 @@ func (w *branchWall) emailDeliveries(mux *http.ServeMux, h *emaildelivery.Handle
 // dealerProfile mounts the dealer profile: every role that prints reads it
 // and its logo, and only admin and owner write them. The profile is one
 // dealer wide row, so it runs behind the role guard alone and a branch bound
-// key is refused the writes by the route allowlist gate.
+// key is refused the writes by the route allowlist gate. The locale alone is
+// the one read every signed in desk person may call (a cashier, the yard and
+// a driver format their dates for it too).
 func (w *branchWall) dealerProfile(mux *http.ServeMux, h *dealerprofile.Handler) {
 	h.RegisterRoutes(mux, dealerprofile.Guards{
-		Read:  middleware.RequireRole("admin", "owner", "sales", "finance", "purchasing"),
-		Write: middleware.RequireRole("admin", "owner"),
+		Read:   middleware.RequireRole("admin", "owner", "sales", "finance", "purchasing"),
+		Write:  middleware.RequireRole("admin", "owner"),
+		Locale: middleware.RequireRole("admin", "owner", "sales", "finance", "purchasing", "warehouse", "cashier", "driver"),
 	})
 }