Cancelling the opening unpaid order ran the expiry sweep only implicitly, so a
group whose lifetime had already ended was relabelled cancelled instead of
expired. Both conditions hold in that case; sweep first so the lifetime ending
wins. The behaviour was invisible to shoppers (neither state is joinable) but it
matters to a future refund flow reading expired paid groups.
Add an integration test that reproduces the precedence.
Sync the group-buying capability plus the order, frontend-mall, and
frontend-shop-admin requirements into the main specs, and write the capability
Purpose the archive leaves as a placeholder. This closes the last of the five
planned marketing changes.
Add one active activity for the demo shop on a SKU that is not already in the
seeded flash sale, idempotent by name, so the live mall can open and join a
group.
Add a group-buying page where a shop user lists, creates, edits, and deletes
its own activities, configuring the SKU, localized name and description, group
price, required paid members, active window, and group lifetime, and seeing each
activity's open groups. Expose it as a group-buying navigation entry.
The group-buying page lists active activities, the group price against the
catalog price, and each open group with its paid-member count and expiry. A
shopper opens a group or picks one to join; either way the activity SKU goes
into the cart and the intent is carried to checkout, which submits it and hides
the coupon picker for that order. Payment and order detail show the snapshotted
group price.
The group-buying fixtures leave the page; the fixed-data adapter still serves
the domain as the rollback path.
Shop-owned activities on one SKU, concrete groups with an
open/successful/expired/cancelled lifecycle, and one paid membership row per
paid order. Checkout accepts a single-SKU quantity-1 intent, snapshots the group
price and identity on the pending order, and opens or references a group; a paid
seat is claimed only at payment, which locks the group and fills it exactly at
capacity.
Pending-payment cancellation restores SKU stock only and never rolls back paid
seats; an unpaid opener cancelling closes a still-empty group. Coupons are
refused on a group shop order, and the flash-sale exclusion is now enforced in
both directions because the activity table exists, which activates the guard
add-flash-sales shipped dormant. The activity column names follow the contract
recorded in this change's design.
Surfaces (shop-admin, mall) and seeding follow.
Add the shared promotion-window EXCLUDE-constraint idea to the deferred designs
so the flash/group overlap ordering problem has a recorded structural fix.
Note in AGENTS.md that suite assertions must be scoped to fixtures the test
created, that a list endpoint warrants two consecutive green runs, and that a
piped test command hides the real exit code.
Sync the flash-sales capability plus the order, frontend-mall, and
frontend-shop-admin requirements into the main specs, and write the capability
Purpose the archive leaves as a placeholder.
Restate the flash-price and coupon-exclusion scenarios in the group-buying
order delta, since its MODIFIED checkout block must carry the scenarios the main
order spec now has.
Add one active session for the demo shop with a discounted activity item on one
of its SKUs, idempotent by English label, so the live mall has a discoverable
flash sale to check out.
The inactive-window test asserted that no active session exists at all, which
the shared test database breaks once another test has created one. Assert that
this session is absent from discovery instead.
Add a flash-sale page where a shop user lists, creates, edits, and deletes its
own sessions and their SKU activity items, setting the fixed sale price,
currency, reserved stock, and per-customer limit. Expose it as a flash-sale
navigation entry beside the existing shop operations.
The flash-sale page loads active sessions and their items through the shared
client with live sale price, remaining activity stock, sell-through, and a
countdown, and adds the SKU to the existing cart so checkout resolves the
authoritative price. Payment and order detail tag and render the snapshotted
activity unit price.
The flash-sale fixtures leave the page; the fixed-data adapter still serves the
domain as the rollback path.
Shop-owned timed sessions carry SKU activity items with their own reserved
inventory and per-customer limit. Checkout resolves eligibility on the server,
locks candidate items by primary key after the SKU locks, and splits a cart line
into an activity-priced item plus a standard-priced remainder, so every unit
price snapshot is honest and a customer cannot exceed the limit.
Reserved activity stock and SKU stock decrement together under guards, and a
pending-payment cancellation restores both plus any redeemed coupon. Coupons are
rejected on a shop order that applied activity pricing, and a SKU cannot join
two overlapping enabled sessions.
The overlap check against group buying is present but dormant: that capability
lands later, so the check activates only once its table exists.
Surfaces (shop-admin, mall) and seeding follow.
Sync the points-mall capability plus the frontend-mall and frontend-admin
requirements into the main specs, and write the capability Purpose the archive
leaves as a placeholder.
Add five published points products, idempotent by English name, so the live
mall has a redeemable catalog. Spendable demo points are credited by the API
through the account ledger rather than here.
Platform operators get a points catalog screen (create, edit, publish and
unpublish products with localized names, points price, stock, and ordering) and
a redemption screen that lists orders and moves pending ones to fulfilled or
cancelled. Both are reachable from the console navigation.
The points page loads the published catalog and the customer's live points
through the shared client, redeems with a chosen saved address, refreshes the
balance, and lists the customer's redemption history with its fulfilment state.
The INTEGRAL_PRODUCTS and USER_STATS imports leave the page; the fixed-data
adapter still serves the points domain as the rollback path.
Platform-owned points products and a redemption order lifecycle kept separate
from cash orders. Redeeming locks the published product, reserves stock, creates
the order, debits points through the archived customer-accounts ledger with the
order as reference, and snapshots the line in one transaction; a failure leaves
no order, no stock change, and no ledger entry. Fulfilment moves only from
pending_fulfillment, and customers see only their own redemptions.
Demo seeding credits the demo customer through the same guarded credit path
with reason seed, once, so no balance is ever written absolutely.
Surfaces (admin console, mall points page) and product seeding follow.
Sync the shop-coupons capability plus the order, frontend-mall, and
frontend-shop-admin requirements into the main specs, and write the capability
Purpose the archive leaves as a placeholder.
Renaming the coupon scenario in the flash-sales and group-buying order deltas
to the exact name now in the main order spec keeps those changes archivable,
since a MODIFIED requirement replaces the whole block.
Add a coupons page where a shop user lists, creates, edits, enables/disables,
and deletes only its own templates, with localized titles, minor-unit discount
and threshold, currency, claim stock, and an active window. Expose it as a
coupons navigation entry beside the existing shop operations.
The product page loads a shop's claimable coupons through the shared client and
claims them in place; the buyer coupon list reads owned snapshots with their
claimed/redeemed/expired state. Checkout offers each shop order at most one
owned coupon and submits only the choice; the pay page and order detail render
the server-persisted discount and reduced total, never a client figure.
Coupon fixtures leave the pages; the fixed-data adapter still serves the coupon
domain as the rollback path. The demo seed creates two deterministic templates
and claims them for the demo customer.
Templates belong to a shop; claiming copies their terms into a customer-owned
snapshot so a later edit or disable cannot rewrite a held coupon. Claim stock
is taken with a guarded decrement after locking the template, and a unique
(user, template) index makes a duplicate claim a 409. Deleting a template
leaves claimed snapshots standing via ON DELETE SET NULL.
Checkout accepts at most one owned coupon per generated shop order, locks the
selected coupons by primary key after the SKU locks, and resolves eligibility
and the discount server-side (ownership, shop, status, window, converted
threshold). The realized discount and coupon id land on the order, and a
pending-payment cancellation restores the coupon in the same transaction as
stock.
The shared contract gains the coupon types, claim/list/manage methods, and the
checkout coupon map; the fixed-data adapter implements the same surface.
Surfaces (shop-admin management, mall coupon pages, checkout selection) and
seeding still follow in tasks 3.1-4.2.
Sync the customer-accounts capability and the frontend-mall stats requirement
into the main specs, and write the capability Purpose the archive leaves as a
placeholder so strict validation stays green.
One balance row per (user, kind, currency): available and frozen carry the
platform base currency, points carries none. Monetary and points rows use
separate partial unique indexes because a plain UNIQUE lets NULL repeat.
Balance changes go through transactional primitives that debits guard with a
conditional update, credits add atomically, and freeze/release move both sides
in one transaction after locking rows by primary key. Every change appends an
immutable entry holding its resulting balance. Registration and a migration
backfill create the zero rows; GET /api/me/stats is the only public surface and
no endpoint mutates a balance.
The mall buyer center and points page drop the USER_STATS fixture for the
shared contract; the fixture stays exported so the fixed-data adapter can still
serve the account domain as a rollback path.
Implements openspec change add-customer-accounts.
Rename the group-buying "Order lifecycle" cancel scenario to the exact name
the current order spec uses; a MODIFIED requirement replaces the whole block,
so the old name made archive refuse to drop the existing scenario.
Replace the placeholder Purpose in the archived address-book spec, which the
wave-7 archive left as TBD and strict validation rejected.
openspec validate --all --strict is green again.
Prevent oversell by conditioning stock updates and locking SKUs in primary-key order, and record the same concurrent-counter rule in the API spec and agent guide.
Co-authored-by: Cursor <cursoragent@cursor.com>
Capture exclusive promotion composition, empty-group cancel, and mall surface scope so the five marketing changes can be implemented without stacking or lifecycle ambiguity.
Co-authored-by: Cursor <cursoragent@cursor.com>
Persist the modular-monolith decision (ADR 0001 handler/service/repo,
ADR 0002 keep REST) with the companion tech spec and the api-architecture
OpenSpec capability. Replace the finished mock-migration tracker with
docs/TBD-marketing.md listing the backend-less marketing domains still on
fixtures (coupons, favorites, account stats, seckill, collective, integral,
reviews). README and AGENTS.md point at the new docs.
Live addresses domain for the mall: shared contract (AddressBookEntry +
five client methods), mock adapter state v3, live domain pick, addresses
page CRUD, checkout saved-address picker with manual fallback, demo seed,
and the archived change plus address-book capability spec.
Keep the REST contract; move domain logic out of route files so checkout, fulfillment, and identity can be reused across customer, shop, and admin surfaces.
Co-authored-by: Cursor <cursoragent@cursor.com>
The merge creates the brand capability (two requirements) and extends the
catalog browse requirement with the brand filter, the sales sort and a real
sold count. openspec validate --all --strict stays green at 14 specs.
With every box now checked, docs/TBD-migrate-wave.md is deleted, as its own
instructions require. Its two durable notes move to the README instead of
disappearing with it:
- `nuxt build` does not typecheck, so a green build is not the type gate the
verification section claimed. AGENTS.md told me to treat it as one, which is
why waves 1-5 over-reported "builds pass" as evidence.
- the list of what stays deliberately mock: addresses, coupons, favourites,
account stats, the seckill/collective/integral pages, reviews, and the
fixed-data adapter itself, which the adapter spec requires for rollback.
The README's verification block also gains the real test count (29, not 16).
Wave 6, the last substantive piece of the mock-API migration. Wave 1 removed the
brand facet and the sales/comments sorts for want of a model; sales turn out to
be derivable from order_items and a brand model is a table plus a column.
- a `brands` table with a nullable `products.brand_id` and an ordered admin
replace, mirroring categories and storefront content; a public `GET /api/brands`
and a `brand_id` filter on the catalog, which the search page's facet uses
- `sold_count` per product, computed from `order_items` joined to orders that
reached payment, so an abandoned or cancelled checkout cannot count as a sale.
It is computed per read rather than stored, so it cannot drift from the orders
that produced it
- `sort=sales` alongside `sort=price`; anything else is still a 400
- merchants can set a product's brand through the existing product upsert
- the review UI is gone: the card's review figure and the product detail page's
reviews tab, summary and replies. There is no reviews model, and the mall
attributed invented comments to named shoppers and showed a "good rate". The
now-unreferenced fabrication helpers went with it (`salesOf`, `commentCountOf`,
`commentsFor`, `commentStats`, `salesRankFor`, `productDetail`, `storeDetail`)
Two bugs found by checking rather than trusting: the fixed-data `listProducts`
had silently ignored `brand_id`, `sort` and `order`, so the restored facet
rendered but filtered nothing until the rollback check caught it; and the seed's
brand lookup read back through the shared `r` variable the product loop
reassigns, working once and then throwing.
Verified: 29 backend tests green including a new brand-and-sales case; all three
frontends build; searching filters by brand (24 to 6) and sorts by sales with
counts matching the API; a product page offers detail and after-sale tabs only,
with a real sold count; the fixed-data rollback filters by brand too.
OpenSpec change: openspec/changes/replace-mock-api-wave-6
Planning only: proposal, delta specs, design and tasks. No code yet.
This is the last substantive in-scope box in docs/TBD-migrate-wave.md. Wave 1
removed the brand facet and the sales/comments sorts for want of a model; sales
are derivable from order_items and a brand model is a table plus a column, so
both come back for real.
Decisions recorded in the design:
- brands are reference data in their own table with a nullable products.brand_id
and an ordered replace endpoint, mirroring categories and storefront content
- a "sale" is a unit on an order that reached payment; pending and cancelled
orders do not count, so an abandoned checkout cannot inflate the figure
- sold_count is computed per read rather than stored, so it cannot drift from
the orders that produced it
- the review UI is removed rather than relabelled: the mall attributes invented
comments to named shoppers and shows a "good rate", which a migration that
makes everything else real has no business keeping on screen. Reviews are
recorded as a separate future capability
openspec validate --strict passes and the change is ready to apply.
The merge creates the store-directory capability (two requirements, six
scenarios) and updates the mall's store-and-marketing requirement so the store
directory and store home read live shops and order surfaces name their shop.
openspec validate --all --strict stays green at 13 specs.
Wave 5: the store directory, store home and product-page store card stop reading
MOCK_STORES, and the payment and order surfaces name their shop.
- a `shop_profiles` table beside `shops`, so the identity model both consoles
consume is untouched, with a public `GET /api/shops` and `GET /api/shops/{slug}`
and an admin `PUT /api/admin/shops/{id}/profile`
- a shop with no profile is still listed, with the fields absent rather than
invented; the pages guard every block, and a missing logo renders an
initial-letter placeholder
- `scripts/seed-demo.mjs` upserts a profile per demo shop, since profiles hang
off shops that script creates
- payment and order pages resolve shop ids to names from one cached shop read,
retiring the generic "Shop" label
- three things went rather than being faked, following the wave-1 precedent:
`distanceKm` and its sort (no geo model), the store home's sales/comments
sorts, and its "best sellers" rail (no sales model)
- `lowestSku` moved out of the fixed-data module into `apps/mall/utils/product.ts`
and re-exported, so live pages stop importing the mock module for a pure
helper
Verified: 28 backend tests green including five new shop tests; all three
frontends build; the directory, store home, store card and order cards all render
real data with no distance or sales claims; the fixed-data rollback still renders
the store surfaces with the backend stopped.
Note: `nuxt build` does not typecheck in this repo (no `typescript.typeCheck`,
no `vue-tsc`), which AGENTS.md implies it does. A re-export used here created no
local binding and broke internal callers at runtime while the build stayed green;
`docs/TBD-migrate-wave.md` records the gap.
OpenSpec change: openspec/changes/replace-mock-api-wave-5
Planning only: proposal, delta specs, design and tasks for replacing the
store surfaces. No code yet.
The batch adds a public shop read (profile + products) so the store directory,
store home and product-page store card stop reading MOCK_STORES, and so the
cart, payment and order surfaces can name a shop instead of printing "Shop".
Decisions recorded in the design:
- a `shop_profiles` table beside `shops`, so the existing admin and
shop-admin contracts are untouched
- the four store scores stay stored profile values, because there is no review
model and deriving them would dress fabricated numbers as computed ones
- `distanceKm` is dropped rather than faked: there is no geo model behind it
- profiles are filled by seed-demo.mjs, since they hang off shops that script
creates
- order surfaces resolve names from one cached shop read rather than growing a
denormalised shop name on every order payload
openspec validate --strict passes and the change is ready to apply.
The merge creates the storefront-content capability (two requirements, five
scenarios) and updates the mall's home-page requirement so its banner,
promotion, quick-link and floor advert content comes from the content API.
openspec validate --all --strict stays green at 12 passed / 0 failed.
Wave 4 of replacing the fixed-data mock adapter, and the first capability the
mall never had a backend for: the home page's banners, promo tiles, quick links
and floor advert art move out of local arrays.
- four explicit tables (`banners`, `promos`, `quick_links`, `floor_adverts`)
rather than one JSONB payload table, so Postgres enforces each shape
- a migration seeds them from the assets the page already rendered, so the flip
is visually a no-op. Destinations are real routes now: the mock's promo links
pointed at dangling `?category=c1` ids and its first banner used `sort=sales`,
which the catalog API rejects
- `GET /api/content/home` is public and returns the four active, ordered lists,
always including a key so a page can render a missing block
- `GET /api/admin/content` and `PUT /api/admin/content/{kind}` let a platform
admin read everything and replace one kind transactionally, with positions
reindexed from the submitted order and a rejected list changing nothing
- the mall's fixed-data adapter learns `getHomeContent`, and a `content` domain
joins the per-domain switch so the rollback path still renders the page
Verified: 23 backend tests green including six new content tests; all three
frontends build; the home page renders the same four blocks as before, an admin
reorder and deactivation change the rendered carousel, and the fixed-data
rollback renders every block with the backend stopped.
OpenSpec change: openspec/changes/replace-mock-api-wave-4
Archive the three completed changes behind replace-mock-api-wave-1/2/3. Each
merge applied cleanly to the main specs:
- catalog gains the Public product browse requirement (subtree filtering and
price sort)
- frontend-mall picks up the per-domain adapter, the pinned home page, the
discovery-page changes, the live auth panels and the live transaction flows
- cart's Server-side cart requirement now documents the shop and stock carried
by every line
Also replace the TBD Purpose placeholder in all eleven specs with a one-line
description of what each capability covers. Those placeholders predate this
work and were the only reason `openspec validate --all --strict` reported
0 passed / 11 failed; it now reports 11 passed / 0 failed.
Wave 3 of replacing the fixed-data mock adapter: cart, orders, shipments and
invoices flip together, so one purchase runs end to end against the backend.
- cart: CartItemView carries the line's shop and the SKU's stock, so the cart
keeps grouping per shop and the quantity stepper caps at real stock instead
of a hard-coded 999
- contract: Shipment.items is optional and Invoice.invoice_no nullable, both
matching what the API actually returns. Invoice was declared twice in
types.ts and TypeScript merges duplicate interfaces, so the duplicate had to
go for the change to take effect at all
- an anonymous add-to-cart redirects to /login?redirect=..., and sign-in
honours only same-origin paths
- the fixed-data adapter learns the new cart fields, and its persisted state
key moves to v2 because a cart saved by an older build is no longer valid
- order surfaces drop their storeById lookups and keep the generic store label
until the public store read arrives
Verified end to end: two-shop cart grouping with live shop names, stock caps
read from the API, checkout, payment, shipment, delivery confirmation and an
issued invoice. Rollback re-verified with every domain on fixed data and the
backend stopped.
Also checks off Wave 3 in docs/TBD-migrate-wave.md and re-points that file at
the mock content that remains.
OpenSpec change: openspec/changes/replace-mock-api-wave-3
Wave 2 of replacing the fixed-data mock adapter: the auth domain joins the live
list, so credentials, roles and tokens belong to the real user.
- session: validate a restored token through /auth/me instead of trusting
localStorage, clearing it on 401/403 but keeping it when the API is merely
unreachable; the route guard now uses the validated session
- login: report a 401 as invalid credentials rather than a generic failure, and
drop the 6-character client rule so the API owns the password policy
- register: raise the rule to the API's 8 characters, remove the
verification-code field (its button only counted down and the value was never
sent), and report a duplicate email (409) distinctly
- TopBar and the user profile render their session-dependent branch client-only:
validating the session before hydration made those localStorage-backed
branches report hydration mismatches the previous code did not
Verified against the running backend: wrong password rejected, real JWT issued,
/user reachable, a short password refused with no network call, duplicate email
reported, a tampered token cleared and bounced to sign-in, a stale token kept
when the API is down, and the fixed-data rollback still signs in with the
backend stopped.
Also re-cuts docs/TBD-migrate-wave.md: auth is done, and cart, orders,
shipments and invoices must move together, because the mock adapter keeps their
state in one shared object and a partial flip fails at checkout.
OpenSpec change: openspec/changes/replace-mock-api-wave-2
Wave 1 of replacing the fixed-data mock adapter. The mall now selects its API
adapter per domain, with catalog and currency served live while auth, cart,
orders, shipments and invoices stay on fixed data.
Backend:
- seed the 6 x 2 x 2 category tree as reference data (migration 0005). The API
exposes no category write route, so this cannot come from the seed script
- filter public product listing by the category subtree with a recursive CTE,
matching the mock's existing behaviour instead of exact-match
- add sort=price with order=asc|desc, validated by hand so an unsupported value
returns the project's ApiError 400 shape rather than axum's own rejection
Mall:
- replace the all-or-nothing mockApi boolean with a liveDomains list composed
through a typed per-domain pick map
- source home floors, the category menu, search and product detail from the
catalog API; banners, promos, quick links, store card and comment/coupon
content stay local display-only content
- drop the brand facet and the sales/comments sorts: no backend model backs them
- fix salesOf/commentCountOf, which parsed digits out of the product id and so
rendered "NaN sold" for live UUID ids; they now hash the id
Seed: 24 products across 4 shops, idempotent on re-run.
Note: the mall defaults to a live catalog, so pnpm dev:mall now expects the API
to be running; set NUXT_PUBLIC_LIVE_DOMAINS to an empty array for all-mock work.
OpenSpec change: openspec/changes/replace-mock-api-wave-1
Move the completed change to
openspec/changes/archive/2026-09-17-pin-home-category-menu/ and merge its
delta into openspec/specs/frontend-mall/spec.md.
Modified requirements:
- B2B2C mall-style PC storefront shell: the header stays fully visible
while scrolling (no scroll-based auto-hide), and the category mega-menu
is a hover dropdown on every page except home, where it is pinned in
the hero row. Adds the "header persists while scrolling" and "hover
categories on a non-home page" scenarios.
- Mock PC home page: the hero row is a pinned 240px category sidebar plus
a carousel filling the remainder, both 450px tall, with the mega-menu
overlaying the carousel and banners center-cropped. Adds the "sidebar
stays while scrolling" and "expand a category" scenarios.
Four hero compositions (A: pinned left rail / B: right user rail /
C: short banner / D: stacked banners) for the 1200x450 home hero area,
with A marked as the confirmed direction. Referenced by
openspec/changes/pin-home-category-menu/proposal.md.
Home hero becomes a 450px flex row with a pinned 240x450 category rail
(ShellCategoryMenu `pinned` mode) left of the 960px center-cropped
carousel; hovering a top-level category expands the mega-menu over the
carousel. The header no longer collapses on scroll, and its category
dropdown is now hover-only on non-home pages.
OpenSpec change: openspec/changes/pin-home-category-menu
BREAKING CHANGE: the header logo/search/cart bar no longer auto-hides
past 200px of scroll, and the home page no longer shows the header
category dropdown (it is pinned in the hero row instead).
james
Chengdong ZhangandCursor