Product Requirements Document¶

Product: TCG Commerce Operations Platform Version: v1.0 PRD Date: April 2026

Product overview¶

The TCG Commerce Operations Platform is a Medusa-powered operations system for a single trading card game merchant selling across Shopee, Lazada, Telegram, Carousell, Instagram, a physical store, and event booths. The product combines a standard commerce core with custom Medusa modules so the merchant can manage orders, inventory, costing, pricing, POS operations, and finance from one place instead of relying on spreadsheets and disconnected scripts.

The product is designed around a clear architectural split: Medusa handles generic commerce capabilities such as orders, inventory, stock locations, fulfillment, returns, and workflow orchestration, while custom Medusa modules in src/ handle connectors, TCG-specific product semantics, DCA costing, finance, and operational tooling.

Scope note: the v1.0 MVP is a single-tenant operations platform for one merchant. All multi-tenancy, subscriptions, cross-merchant administration, and SaaS control-plane features are intentionally deferred — see the companion project plan's "Deferred: SaaS & Multi-Tenancy (Post-MVP)" section. No requirement in this PRD should introduce tenant-awareness into the MVP.

Problem statement¶

The merchant operates across multiple channels but does not have a single reliable operating system for inventory, order processing, event sales, and profitability tracking. Inventory is currently tracked in spreadsheets, platform orders are handled separately, social-channel orders require manual follow-up, and financial visibility is fragmented across ad hoc tools and human memory.

This creates five recurring problems:

• Overselling or stock drift because channel stock is not synchronized reliably.
• Slow order handling because operators must switch between multiple systems.
• Poor pricing control because landed costs and DCA calculations are not tied directly to sellable inventory.
• Weak event/POS visibility because tradeshow sales and warehouse sales live in different processes.
• Incomplete profitability and cashflow visibility because finance data is not linked to inventory batches and channel fees.

Product vision¶

The long-term vision is to become the default operations layer for this TCG business's cross-channel operations, starting with Shopee and Lazada while also handling offline and social-commerce channels. The initial version is optimized for one merchant's real operating needs. Any future commercialization path is explicitly out of scope for this PRD.

Goals¶

Business goals¶

• Replace spreadsheet-heavy operations with a reliable product workflow for day-to-day commerce operations.
• Reduce manual reconciliation effort across marketplaces and offline channels.
• Improve stock accuracy and prevent avoidable oversell incidents.
• Improve gross margin visibility through batch-based costing and finance reporting.

Product goals¶

• Centralize orders from Shopee, Lazada, Telegram, Carousell, Instagram, POS, and manual channels.
• Provide a unified inventory and stock-location operating model.
• Implement import batch management and DCA-based cost tracking.
• Support POS and event workflows with proper stock transfers and reconciliation.
• Provide finance dashboards for profitability, receivables, cashflow, and stakeholder tracking.

Non-goals for v1.0¶

• Full TikTok Shop integration.
• Native iOS or Android application.
• Full enterprise multi-warehouse optimization beyond the merchant's current use cases.
• Loyalty/CRM automation as a primary v1 launch capability.
• Automated procurement and restocking decisions.
• Multi-tenancy, subscriptions/billing, tenant provisioning, or any SaaS control-plane functionality.

Target users¶

Primary users¶

• Merchant owner — needs end-to-end visibility across sales, stock, costs, and payouts.
• Operations staff — process orders, move stock, manage imports, and handle exceptions daily.
• Finance stakeholder — needs cashflow, profitability, and repayment visibility.

Secondary users¶

• Event sales staff using POS during card shows and booths.
• Partner buyers / streamers using the Telegram Mini App to see privileged pricing tiers and place orders.

User personas¶

Merchant owner — "Wei"¶

Primary device: desktop, occasional phone. Logs in most days. Owns the business and has final say on pricing, margins, and supplier decisions. Needs a single source of truth for inventory, pricing, and profitability across all channels. Success looks like trusting the dashboard enough to close the backing spreadsheet for good. Frustrated by anything that makes him cross-check two tools to answer one question.

Operations manager — "Farah"¶

Primary device: desktop, all day. The daily-driver user. Processes dozens to hundreds of orders a day across Shopee, Lazada, and social channels. Moves stock between warehouse and event locations. Owns the exception queue. Cares about speed, low error rates, and not having to cross-check multiple tools for one order. Needs bulk actions, keyboard-friendly flows, and clear channel attribution.

Finance stakeholder — "Sam"¶

Primary device: desktop. Logs in weekly and at month/event end. Needs accurate view of cash in and cash out, inventory valuation, batch contributor balances, and channel profitability. Cares about traceability: every number in a report must be drillable back to an underlying order, transfer, or batch. Works in parallel with external accounting tooling, so export capability matters.

Event seller — "Jia"¶

Primary device: tablet or phone, typically during a noisy, crowded event. Runs the POS at card shows and booths. Needs a fast POS flow with reliable stock behavior during events and after-event reconciliation. Cares about speed on touch devices, tolerance for flaky network conditions, and simple payment capture workflows.

Partner buyer — "Ken"¶

Primary device: phone, inside Telegram. Uses the Mini App to see partner/streamer pricing, browse available stock, and place orders. Not a staff user — a customer. Needs the experience to be fast, lightweight, and to clearly show what's in stock at his tier.

Core product principles¶

• Use Medusa for standard commerce. Orders, inventory, locations, fulfillment, returns, and workflow primitives should not be rebuilt unnecessarily.
• Own the product moat. Connectors, TCG semantics, DCA, finance, and event/POS flows are the real differentiators.
• Preserve auditability. Every material stock, sync, finance, and pricing action should be traceable.
• Design for operator speed. Common tasks must require minimal clicks and minimal context switching.
• Prefer reliability over feature breadth. The product must work consistently for Shopee, Lazada, warehouse, and event operations before expanding aggressively.

Scope¶

In scope for v1.0¶

Channel integrations¶

• Shopee order, stock, and pricing connector.
• Lazada order, stock, and pricing connector.
• Telegram Bot for admin notifications and quick actions.
• Telegram Mini App for product browsing, partner-tier pricing, and ordering flows.
• Manual order entry for Instagram, Carousell, and in-person sales.

Core workflows¶

• Unified order management.
• Multi-location stock management.
• Import batches and DCA costing.
• Pricing engine with per-channel and partner tiers.
• PayNow QR payment generation and confirmation.
• Event stock transfer and event reconciliation.
• POS for event and physical-store operations.
• Finance and profitability dashboards.
• Data migration from existing spreadsheets.

Platform and support¶

• Audit logging and raw event storage.
• Exception queue and retry tooling.
• Reporting and exports.
• Single-tenant merchant role-based access control.

Out of scope for v1.0¶

• TikTok Shop connector.
• Native mobile apps.
• Loyalty and CRM automation.
• Automated purchasing or demand forecasting as a production-grade launch feature.
• Multi-tenancy, subscriptions, cross-merchant admin tooling, and SaaS control-plane features.

Functional requirements¶

Commerce core requirements¶

FR-1 Unified order ingestion¶

The system must ingest orders from Shopee and Lazada through connector workflows and normalize them into the platform's canonical order flow while storing the commerce order state in Medusa. The system must also support manually created orders for Telegram, Carousell, Instagram, POS, and other offline channels.

Acceptance criteria - Shopee and Lazada orders appear in the unified order list with channel attribution. - Manual/offline orders can be created without marketplace payloads. - Order status transitions are visible to operators. - Failed ingestions are surfaced in an exception view. - Duplicate marketplace events are idempotent and do not create duplicate orders.

FR-2 Inventory and stock locations¶

The system must maintain accurate inventory quantities using Medusa inventory primitives and stock-location support, with application-defined workflows for warehouse, event, and store operations. Inventory availability must support both standard order handling and location-aware operational flows.

Acceptance criteria - Operators can view stock by SKU and by location. - Inventory changes are reflected after sales, fulfillment, returns, and transfers. - Event and warehouse locations are distinguishable in UI and workflow behavior. - Negative inventory is prevented or explicitly flagged, never silently allowed.

FR-3 Product and SKU management¶

The system must support a central TCG product catalog built on Medusa product and variant primitives, extended with custom TCG-specific attributes. Product records must support listing behavior and channel mapping needed for marketplace operations.

Acceptance criteria - Products and variants can be created and edited. - TCG metadata (title/game, language, set number, variation, condition, foil, grading) can be stored and queried. - Channel listing visibility and mapping can be tracked per sellable unit. - Serialized (one-of-one) items are distinguishable from fungible stock in both UI and workflow.

FR-4 Pricing engine¶

The system must support per-channel and per-segment pricing, including Shopee, Lazada, Standard, Partner, Streamer, and optional bulk pricing tiers. The system must allow operators to update pricing while maintaining pricing history for audit purposes.

Acceptance criteria - Prices can be set independently by commercial channel or customer tier. - Suggested prices can be computed using cost and target margins. - Price change history is available for review, with who/when/old/new fields. - Bulk price updates can be previewed before commit.

FR-5 Import batches and DCA costing¶

The system must support import batches with per-SKU quantities, landed costs, GST, and contributor data, and it must compute DCA-based costs used for profitability and pricing decisions. This module is custom and does not depend on Medusa for costing logic.

Acceptance criteria - Operators can create import batches and move them through lifecycle states. - The system computes batch cost-per-unit according to defined formulas. - Cost data is linked to profitability logic and price suggestions. - Contributor balances and repayments can be tracked by batch. - DCA output for a reference batch matches the existing spreadsheet calculation.

FR-6 Fulfillment, returns, and post-order handling¶

The system must support fulfillment and return handling using Medusa's post-order commerce capabilities while preserving platform-specific channel context. Operators must be able to see shipment and return status without leaving the unified order workflow.

Acceptance criteria - Order views show fulfillment state (pending, packed, shipped, delivered). - Returns can be represented and reconciled against order state. - Post-order changes (refunds, partial fulfillment, cancellations) appear in the order timeline with timestamps and actor.

FR-7 PayNow QR payments¶

The system must generate PayNow QR codes for manual and Mini-App orders and allow operators to mark orders as paid once confirmation is received.

Acceptance criteria - PayNow QR codes can be generated for any manual or Mini-App order with a correct amount and reference. - An operator can mark an order paid with optional reference/screenshot attachment. - Paid status is reflected consistently in the unified order view and finance records.

Operations requirements¶

FR-8 Exception queue and replay¶

The system must store raw incoming marketplace payloads and support replay or retry for failed sync operations. Operators must be able to distinguish between transient sync failures and domain/business-rule failures.

Acceptance criteria - Every inbound connector event is stored before transformation. - Failed events appear in an exception queue with failure reason and classification (transient vs. domain). - Operators can retry eligible failures without creating duplicates. - Replay outcomes are logged against the original event.

FR-9 Reconciliation workflows¶

The system must support reconciliation between marketplace state, Medusa state, and application audit state so that stock or order drift can be detected and investigated.

Acceptance criteria - Operators can run or view reconciliation results on demand and on schedule. - Drift issues are visible with enough detail for manual action (SKU, location, delta, source). - Reconciliation outcomes are logged for auditability.

FR-10 POS and event workflows¶

The system must support POS for event and in-store sales, including payment method capture, stock deductions, and end-of-event reconciliation. The system must support stock transfer workflows tied to event locations and allow event closure with review of differences and returns.

Acceptance criteria - Users can create POS sales quickly on mobile or tablet (target: under 15 seconds per item for a trained user). - POS remains usable on intermittent/slow connectivity at events. - Event locations can receive dedicated or shared stock and later return unsold stock. - Event close workflow surfaces variance and remaining stock review, and blocks closure until variance is acknowledged.

FR-11 Finance and reporting¶

The system must support reporting for order profitability, channel profitability, cashflow, receivables, inventory valuation, stakeholder balances, and contributor repayments. Finance data must be traceable back to operational records where applicable.

Acceptance criteria - Users can view profitability by order and by channel. - Users can record and review cashflow entries. - Inventory valuation can be derived from quantity and batch cost state. - Stakeholder and contributor views are available. - Every reported number is drillable to its underlying order, transfer, or batch. - Core finance views can be exported to CSV for external accounting.

Platform requirements¶

FR-12 Single-tenant merchant RBAC¶

The system must support role-based access control scoped to a single merchant organization. Permissions must restrict access to sensitive financial and admin capabilities.

Acceptance criteria - Staff users can log in with username/password and recover access via email. - Roles (at minimum: Admin, Ops, Finance, Event Staff) gate access to sensitive views and actions. - Sensitive actions (price changes, refunds, finance edits, user management) are audit-logged with actor and timestamp. - The system does not model tenants, subscriptions, or cross-merchant identity.

FR-13 Auditability¶

The system must keep sufficient audit history for stock-affecting actions, connector events, pricing updates, finance entries, and admin interventions. The audit design must support debugging, compliance, and operational trust.

Acceptance criteria - Every stock movement is attributable to a source (order, transfer, manual adjustment, reconciliation). - Pricing and finance changes record before/after values and actor. - Raw connector events are retained for at least 90 days.

FR-14 Telegram Bot and Mini App¶

The system must expose a Telegram Bot for merchant-side notifications and a Mini App for partner buyers to browse product and place orders against their pricing tier.

Acceptance criteria - The bot posts new-order, exception, and end-of-day alerts to a configured admin channel. - Authorized admin users can execute a small set of quick commands (e.g. check stock by SKU, check order status). - The Mini App shows a product catalog filtered by the viewer's partner tier. - Mini App orders land in the unified order list with correct channel attribution and pricing. - Mini App access is gated so non-partner viewers do not see partner-tier prices.

FR-15 Data migration from spreadsheets¶

The system must support a one-time import from the merchant's existing spreadsheets (Master Inventory, Imports, Additional Import Fees, Orders, Cashflow) as part of initial onboarding.

Acceptance criteria - A documented import procedure exists for each source sheet. - Import runs are idempotent and can be re-run after fixes without creating duplicates. - Post-import totals (stock on hand, cash balance, open batches) match the source spreadsheet within an agreed tolerance. - A reconciliation report is produced for each migration run.

Non-functional requirements¶

Reliability¶

• Order ingestion should complete within 5 minutes of marketplace event receipt under normal operating conditions.
• Critical connector flows must be idempotent and retry-safe.
• Inventory changes must be traceable and recoverable through audit and reconciliation workflows.
• Core workflows should target 99.5% monthly uptime.

Performance¶

• Core admin APIs should target less than 300ms p95 for common actions where practical.
• Unified order and inventory views should remain usable at the merchant's realistic scale (tens of thousands of SKUs, hundreds of daily orders).

Security¶

• Secrets must not be stored in source code.
• Role-restricted actions must be auditable.
• All operator-facing services must be exposed over HTTPS.

Privacy and compliance¶

• Personal data should be stored only as needed for business operations and support.
• The product should support PDPA-aware handling of customer information and deletion-related workflows where legally appropriate.
• Financial records are retained for 7 years where required for compliance.

Maintainability¶

• Medusa customizations should use official extension points where possible to reduce upgrade risk.
• Application-specific logic should be separated cleanly from generic commerce logic.

Key workflows¶

Workflow 1: Marketplace order import¶

1. Connector receives or polls a marketplace order event.
2. Raw payload is stored in the application audit/event store.
3. Payload is normalized into canonical fields.
4. Medusa order and inventory flows are invoked as needed.
5. Unified order UI is updated for operator visibility.
6. Failures are sent to exception handling with retry metadata.

Workflow 2: Import batch arrival and DCA¶

1. Operator creates an import batch with supplier and landed-cost information.
2. Per-SKU quantities are added.
3. Batch status moves to arrival-ready or arrived state.
4. DCA logic recalculates cost-per-unit based on current business rules.
5. Updated cost data is available to pricing and profitability views.

Workflow 3: Event stock allocation and POS sale¶

1. Operator creates an event and associated stock location workflow.
2. Stock is moved to the event context according to shared or dedicated mode.
3. POS records event sales on device-friendly UI.
4. End-of-event workflow reviews remaining stock and variance.
5. Unsold stock returns to warehouse state where relevant.

Workflow 4: Failed sync replay¶

1. Connector or workflow step fails.
2. Failure is logged with payload reference and reason.
3. Operator reviews the failure and applies fix or retry.
4. Replay executes the workflow safely without duplicating side effects.

Workflow 5: Partner buyer order via Mini App¶

1. Partner buyer opens the Telegram Mini App and authenticates via Telegram identity.
2. App displays product catalog filtered to the buyer's pricing tier and in-stock items.
3. Buyer places an order; system generates a PayNow QR for the total.
4. Order lands in the unified order list as a Mini App channel order in pending-payment state.
5. Operator confirms payment; order moves into normal fulfillment.

Success metrics¶

Metrics below should be baselined during Phase 1 onboarding so that "reduction" targets have a starting number.

Operational metrics¶

Product metrics¶

Business metrics¶

Dependencies¶

• Medusa v2 as commerce core.
• Shopee Open Platform access and app credentials.
• Lazada Open Platform access and app credentials.
• Telegram Bot and Mini App setup.
• PayNow merchant setup for QR generation.
• Hosting and deployment environment with production and staging separation.

Risks and constraints¶

Release strategy¶

MVP definition¶

MVP is achieved when the merchant can reliably use the platform for Shopee and Lazada order ingestion, warehouse inventory visibility, import batch costing, core pricing workflows, manual/social orders, Telegram Mini App partner orders, event POS, and basic finance reporting without depending on spreadsheets for the primary operating loop.

Launch phases¶

• Phase 1: Foundation & onboarding. Internal replacement of spreadsheet workflows for products, orders, and imports, including one-time data migration.
• Phase 2: Marketplace slice. Reliable Shopee and Lazada sync and unified order operations.
• Phase 3: Event & finance. Event/POS flows and finance reporting stabilized end-to-end.
• Phase 4: Hardening & cutover. UAT, parallel run against spreadsheets, full cutover.

Open questions¶

• What is the exact v1 policy for serialized singles versus fungible sealed products within inventory and pricing UX?
• Which reconciliation flows must be fully automated versus operator-assisted in v1?
• How much finance detail should be first-class in-app versus exported for external accounting workflows?
• What tolerance is acceptable for post-migration balance differences during onboarding?
• Who owns partner-tier assignment, and how is it changed over time (admin-only, bot command, self-service)?

Appendix: Medusa versus custom ownership¶

A detailed module-by-module coverage table lives in the companion project plan under "Module Specifications → Coverage summary" and should be treated as the source of truth. The condensed view below is intended only for PRD-level orientation.