138 lines
4.3 KiB
Markdown
138 lines
4.3 KiB
Markdown
# CLAUDE.md
|
|
|
|
## Overview
|
|
|
|
E-commerce SEO audit tool for product page optimization, product schema validation, category taxonomy analysis, and marketplace presence checking. Supports Naver Smart Store optimization and Korean marketplace platforms (Coupang, Gmarket, 11번가).
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
pip install -r scripts/requirements.txt
|
|
|
|
# E-commerce SEO audit
|
|
python scripts/ecommerce_auditor.py --url https://example.com --json
|
|
|
|
# Product schema validation
|
|
python scripts/product_schema_checker.py --url https://example.com/product --json
|
|
```
|
|
|
|
## Scripts
|
|
|
|
| Script | Purpose | Key Output |
|
|
|--------|---------|------------|
|
|
| `ecommerce_auditor.py` | Full e-commerce SEO audit | Product page issues, category structure, marketplace presence |
|
|
| `product_schema_checker.py` | Validate product structured data | Schema completeness, errors, rich result eligibility |
|
|
| `base_client.py` | Shared utilities | RateLimiter, ConfigManager, BaseAsyncClient |
|
|
|
|
## E-Commerce Auditor
|
|
|
|
```bash
|
|
# Full audit
|
|
python scripts/ecommerce_auditor.py --url https://example.com --json
|
|
|
|
# Product page audit only
|
|
python scripts/ecommerce_auditor.py --url https://example.com --scope products --json
|
|
|
|
# Category taxonomy analysis
|
|
python scripts/ecommerce_auditor.py --url https://example.com --scope categories --json
|
|
|
|
# Check Korean marketplace presence
|
|
python scripts/ecommerce_auditor.py --url https://example.com --korean-marketplaces --json
|
|
```
|
|
|
|
**Capabilities**:
|
|
- Product page SEO audit (titles, meta descriptions, image alt text, H1 structure)
|
|
- Category taxonomy analysis (depth, breadcrumb implementation, faceted navigation)
|
|
- Duplicate content detection (parameter URLs, product variants, pagination)
|
|
- Pagination/infinite scroll SEO validation (rel=prev/next, canonical tags)
|
|
- Internal linking structure for product discovery
|
|
- Naver Smart Store optimization checks
|
|
- Korean marketplace presence (Coupang, Gmarket, 11번가 product listing detection)
|
|
|
|
## Product Schema Checker
|
|
|
|
```bash
|
|
# Validate single product page
|
|
python scripts/product_schema_checker.py --url https://example.com/product/123 --json
|
|
|
|
# Batch validate from sitemap
|
|
python scripts/product_schema_checker.py --sitemap https://example.com/product-sitemap.xml --sample 50 --json
|
|
```
|
|
|
|
**Capabilities**:
|
|
- Product schema validation (Product, Offer, AggregateRating, Review, BreadcrumbList)
|
|
- Required property completeness check (name, image, description, offers, price, availability)
|
|
- Optional property recommendations (brand, sku, gtin, mpn, review, aggregateRating)
|
|
- Rich result eligibility assessment
|
|
- Price and availability markup validation
|
|
- Merchant listing schema support
|
|
- Korean market: Naver Shopping structured data requirements
|
|
|
|
## Data Sources
|
|
|
|
| Source | Purpose |
|
|
|--------|---------|
|
|
| `our-seo-agent` CLI | Primary data source (future); use `--input` for pre-fetched JSON |
|
|
| WebSearch / WebFetch | Supplementary live data |
|
|
| Notion MCP | Save audit report to database |
|
|
|
|
## Output Format
|
|
|
|
```json
|
|
{
|
|
"url": "https://example.com",
|
|
"product_pages_audited": 50,
|
|
"issues": {
|
|
"critical": [...],
|
|
"high": [...],
|
|
"medium": [...],
|
|
"low": [...]
|
|
},
|
|
"category_structure": {
|
|
"max_depth": 4,
|
|
"breadcrumbs_present": true,
|
|
"faceted_nav_issues": [...]
|
|
},
|
|
"schema_validation": {
|
|
"pages_with_schema": 42,
|
|
"pages_without_schema": 8,
|
|
"common_errors": [...]
|
|
},
|
|
"korean_marketplaces": {
|
|
"naver_smart_store": {"found": true, "url": "..."},
|
|
"coupang": {"found": false},
|
|
"gmarket": {"found": false}
|
|
},
|
|
"score": 65,
|
|
"timestamp": "2025-01-01T00:00:00"
|
|
}
|
|
```
|
|
|
|
## Notion Output (Required)
|
|
|
|
**IMPORTANT**: All audit reports MUST be saved to the OurDigital SEO Audit Log database.
|
|
|
|
### Database Configuration
|
|
|
|
| Field | Value |
|
|
|-------|-------|
|
|
| Database ID | `2c8581e5-8a1e-8035-880b-e38cefc2f3ef` |
|
|
| URL | https://www.notion.so/dintelligence/2c8581e58a1e8035880be38cefc2f3ef |
|
|
|
|
### Required Properties
|
|
|
|
| Property | Type | Description |
|
|
|----------|------|-------------|
|
|
| Issue | Title | Report title (Korean + date) |
|
|
| Site | URL | Audited website URL |
|
|
| Category | Select | E-Commerce SEO |
|
|
| Priority | Select | Based on issue severity |
|
|
| Found Date | Date | Audit date (YYYY-MM-DD) |
|
|
| Audit ID | Rich Text | Format: ECOM-YYYYMMDD-NNN |
|
|
|
|
### Language Guidelines
|
|
|
|
- Report content in Korean (한국어)
|
|
- Keep technical English terms as-is (e.g., Schema Markup, Product, Offer)
|
|
- URLs and code remain unchanged
|