# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Overview

This skill contains a single standalone script for scraping Taiwan CPC (中油) official direct-operated gas station information. The script fetches data from `https://vipmbr.cpc.com.tw/mbwebs/service_search.aspx` using form POST requests and parses the HTML response.

## Architecture

The script uses only Python stdlib (no external dependencies):

- `HTMLParser` - Custom `StationTableParser` class extracts data from the `#MyGridView1` table
- `urllib` - Handles HTTP requests with proper User-Agent and form data encoding
- `__VIEWSTATE`/`__EVENTVALIDATION` - ASP.NET hidden fields are extracted and submitted in POST requests

The query flow:
1. GET initial page to extract ASP.NET hidden fields
2. POST with `TypeGroup=rbGroup2` to select "direct-operated stations" (直營站)
3. Extract hidden fields again
4. POST with `btnQuery=查詢` to submit the query
5. Parse HTML response table

## Common Commands

### Get all direct-operated stations (default text output)
```bash
python3 skills/c/cpc_direct_stations.py
```

### Query by city
```bash
python3 skills/c/cpc_direct_stations.py --city 台北市
```

### Filter by keyword (station name or address)
```bash
python3 skills/c/cpc_direct_stations.py --city 新北市 --keyword 中山
```

### Export as JSON
```bash
python3 skills/c/cpc_direct_stations.py --city 台北市 --format json
```

### Export as CSV (with BOM for Excel compatibility)
```bash
python3 skills/c/cpc_direct_stations.py --format csv --out cpc_stations.csv
```

## City Codes

The `CITY_MAP` dict maps Chinese city names to CPC internal codes (e.g., `"台北市": "A "`). Supported cities include all Taiwan counties and cities.

## Output Schema

Each station record contains:
- `縣市` - County/City
- `鄉鎮區` - District
- `類別` - Category (e.g., "直營站")
- `站名` - Station name
- `站代號` - Station code
- `地址` - Address
- `電話` - Phone number
- `營業時間` - Business hours