Takazudo Modular Docs

Type to search...

to open search from anywhere

Mercari CSV Viewer

Mercari CSV Viewer Overview

Purpose

The Mercari CSV Viewer is a standalone React application designed for managing product data exports from Mercari Shops. It provides a comprehensive interface for viewing, editing, and managing CSV product data with support for long-form product descriptions and draft management functionality.

Location

Key Features

CSV Management

  • View: Load and display the latest CSV from /mercari-data/ directory
  • Edit: Click any cell to edit product information inline
  • Search: Filter products across all fields with real-time search
  • Save: Export edited data with timestamps to /mercari-data/updated/
  • Validation: Built-in validation for problematic characters that break Mercari imports

Draft Management System

  • Create Drafts: Add new product drafts with full form validation
  • Edit Drafts: Update existing drafts with all product fields
  • Delete Drafts: Remove individual drafts or clear all at once
  • Export/Import: Export drafts to CSV format for backup or sharing
  • Persistence: Drafts are saved to /mercari-data/drafts/ directory

Description Drawer

  • Side drawer for viewing and editing long product descriptions
  • Supports multi-line text that doesn’t fit well in CSV cells
  • Preserves formatting and special characters
  • Real-time editing with save functionality

Column Visibility Control

  • Toggle visibility of data columns
  • Settings persist in localStorage
  • Customizable columns include:
    • Product ID
    • Links
    • Stock Count
    • Price
    • Description
    • Condition
    • Category

Dark Theme Interface

  • Consistent with products-viewer styling
  • Optimized for extended editing sessions
  • Clear visual hierarchy for data management

Directory Structure

mercari-data/
├── product_data_YYYY-MM-DD.csv     # Source CSV files from Mercari
├── category/
│   └── category-master.csv         # Category mappings
├── drafts/
│   └── drafts.json                 # Persistent draft storage
└── updated/
    └── YYYYMMDD-timestamp.csv      # Saved edited versions

sub-packages/zmdpreview/docs/products/  # Product markdown files
└── [slug]__[id].md                             # Individual product descriptions

Pages

1. Products Page

  • Main table view showing all products from the CSV
  • Inline editing capabilities for all fields
  • SKU stock management
  • Category lookup with human-readable names
  • Search and filter functionality

2. Drafts Page

  • Draft form for creating new products
  • List view of all existing drafts
  • Edit/Delete functionality for each draft
  • Export drafts to CSV format
  • Clear all drafts option

Workflow

1. Download Product Data

Export the latest product data CSV from Mercari Shops.

2. Save to Directory

Place the CSV file in /mercari-data/ with naming convention:

product_data_YYYY-MM-DD.csv

3. Update Prices (Optional)

Run the price update script to sync with product-master-data:

pnpm update:mercari-prices

4. View and Edit

Start the viewer application:

cd sub-packages/mercari-viewer
pnpm dev

Access at http://zmercari.localhost:23234

5. Create Drafts

  • Navigate to the Drafts page
  • Fill out the comprehensive product form
  • Save drafts for later editing or export

6. Save Changes

Click “Save CSV” to export edited data with automatic timestamp:

/mercari-data/updated/YYYYMMDD-timestamp.csv

Technical Details

Framework

  • Vite + React: Fast development and build
  • Tailwind CSS: Utility-first styling with custom zd-* color classes
  • Testing: Vitest for unit tests, Playwright for E2E tests

Data Handling

  • CSV Parsing: PapaParse for robust CSV handling
  • UTF-8 Support: Proper encoding for Japanese text
  • File I/O: Custom Vite plugin for server-side file operations
  • Draft Manager: DraftManager class for draft CRUD operations

State Management

  • React hooks for local state
  • Controlled inputs for editing
  • Optimistic updates with error handling
  • LocalStorage for column visibility preferences

Validation System

  • CSV Validation: Detects problematic characters that break Mercari imports
  • Form Validation: Comprehensive validation for draft forms
  • Character Validation: Checks for replacement characters (�) and encoding issues
  • Price Validation: Ensures prices are within Mercari’s allowed range (300-9,999,999 yen)

API Endpoints

The Vite development server provides these API endpoints:

  • CSV Operations:

    • POST /api/save-mercari-csv - Save edited CSV with timestamp

  • Draft Operations:

    • GET /api/drafts - Get all drafts
    • GET /api/drafts/:id - Get specific draft
    • POST /api/drafts - Create new draft
    • PUT /api/drafts/:id - Update draft (full replacement)
    • PATCH /api/drafts/:id - Merge partial update
    • DELETE /api/drafts/:id - Delete specific draft
    • DELETE /api/drafts - Clear all drafts
    • POST /api/drafts/export - Export drafts to CSV format
    • POST /api/drafts/import - Import drafts from CSV data

Components Architecture

Core Components

  • App.jsx: Main application component with routing logic
  • ProductListPage: Products table view
  • DraftPage: Draft management interface
  • SearchHeader: Navigation and search controls
  • DescriptionDrawer: Side panel for long descriptions
  • ColumnVisibilityMenu: Column toggle controls

Draft Form Components

  • DraftFormRefactored: Main form component with all sections
  • Form Sections:
    • BasicInfoSection: Product name, category, price
    • DescriptionSection: Product description
    • ImageSection: Image upload placeholders
    • ShippingSection: All shipping configuration
    • SkuSection: SKU variant management

Shipping Components

  • ShippingMethodSelector: Shipping method selection
  • ShippingOriginSelector: Prefecture selection
  • ShippingDurationSelector: Delivery time selection
  • ShippingPayerSelector: Who pays for shipping

Utility Classes

  • MercariDataModel: Data model for CSV operations
  • DraftManager: Server-side draft management
  • csvConverter: CSV to JSON conversion utilities
  • csvValidator: Validation for problematic characters
  • categoryLookup: Category ID to name mapping
  • formValidation: Form field validation rules

Testing

The application includes comprehensive test coverage:

  • Unit Tests: Component and utility function tests
  • Integration Tests: Form submission and data flow
  • E2E Tests: Full user workflows with Playwright
  • Validation Tests: CSV encoding and character validation

Run tests with:

pnpm test           # Run all Vitest tests
pnpm test:run       # Run once and exit
pnpm test:safe      # Run with bail on failures
  • Products Viewer: Main product catalog editor at port 6666
  • Price Update Script: pnpm update:mercari-prices
  • Main Site: Next.js application with product pages