scraper-expert

name	scraper-expert
description	BaseScraper contract, field rules, and Peatix-specific conventions for the Scraper Expert agent
applyTo	.github/agents/scraper-expert.agent.md

Scraper Expert Skills

Read this at the start of every session before writing any scraper.

Language Rule

• Use English for rule bodies in this file. Keep Japanese and Chinese only for code literals, incident titles, and short source-specific phrases that must match the site content.

Taiwan Relevance & Selection Reason Guidelines

• The "Wansei" (湾生) Signal: For any Japanese artist or historical figure, check if they were born in Taiwan during the colonial period. This "Wansei" status is a primary signal for High Taiwan Relevance. Explicitly mention this in the description and selection_reason.
• Taiwan roots category signal: When a featured author, artist, creator, or performer is explicitly described as born in or from Taiwan (台湾出身, 台湾生まれ, Taiwan-born, born in Taiwan, or a Taiwan city + 出身), include history for the roots dimension. Do not add history for Taiwan university attendance, study-abroad history, or work activity in Taiwan alone.
• Small venue exhibition organizer fallback: For small gallery/shop/cafe/bookstore/craft-venue/museum exhibition pages hosted by the venue itself, the public-facing venue or shop name may be used as organizer when no 主催 label is present and the name appears in source text. Do not infer organizer from generic rental halls, universities, convention centers, aggregator platforms, or news/source names.
• Concrete Selection Reasons: NEVER use generic descriptions like "promotes Taiwan-Japan exchange" as the sole reason. You must specify the concrete connection:
  • "The artist X was born in Kaohsiung, Taiwan (Wansei)."
  • "Exhibition features 15th-century artifacts from Taiwan's Yami people."
  • "Film directed by Z, who won the Golden Horse Award in Taiwan."
  • "Lecture discussing Japan's infrastructure legacy in Taiwan."
• Selection reason filter order: Apply the three-pass go_taiwan filter in this order and do not reorder the stages. Stage 1 = title Taiwan-only rejection, Stage 2 = Taiwan-venue rejection with the Japanese-visitor exception, Stage 3 = Japan-keyword acceptance. If Stage 2 rejects, Stage 3 must not override it.
• Category Enrichment: Events with direct Taiwan-Japan historical or biographical links (like Wansei artists) MUST include the taiwan_japan category in addition to art, history, etc.

BaseScraper Contract

• Every scraper must extend BaseScraper and implement scrape() → list[Event].
• source_id must be stable across runs — derive from URL slug or platform ID, never from title or list position.
• Always set start_date explicitly. Never fall back silently to the page's publish/update date.
• Prepend a date prefix to raw_description only after the scraper has finished extracting the structured fields it needs from the body.
  • Standard / non-cinema calendar-date scrapers: prepend 開催日時: YYYY年MM月DD日\n\n when a single event date is found in the page body.
  • When end_date is known and differs from start_date, prepend the full range 開催日時: YYYY年MM月DD日〜YYYY年MM月DD日.
  • Cinema Type 3 scrapers with no known end_date must not prepend a fallback date prefix that would trigger the annotator SINGLE-DAY RULE.
• .tw ドメインの SSL 証明書エラー (Missing Subject Key Identifier): 台湾政府サイト（startupterrace.tw 等）は TLS 証明書に Subject Key Identifier 拡張が欠落しており、requests のデフォルト verify=True が SSLCertVerificationError を raise する。該当サイトには verify=False + warnings.simplefilter("ignore") を使う helper _get() を定義すること。

  def _get(url: str) -> requests.Response:
      """GET with SSL verification disabled (cert missing SKI extension)."""
      with warnings.catch_warnings():
          warnings.simplefilter("ignore")
          return requests.get(url, headers=_HEADERS, timeout=15, verify=False)
  

  (Incident: startup_terrace 99d9fde, 2026-05-17.)
• start_date/end_date must use tzinfo=timezone.utc for calendar dates: For all-day calendar dates, never pass JST-aware datetimes (tzinfo=_JST / timezone(timedelta(hours=9))) to Supabase. Use datetime(y, m, d, tzinfo=timezone.utc) so the date stays on the intended calendar day. For event times that are explicitly written in JST and need hour-level precision, convert the JST timestamp to UTC before storing it, then strip the tzinfo only if the caller expects a naive UTC datetime. Audit after every fix: grep -rn "tzinfo=_JST\|tzinfo=JST" scraper/sources/. (Incidents: Stranger b7dc34f, shin_bungeiza bcb6142.)
• Blog / RSS feed post fallback-date guard (2026-06-07): For long-text sources or blogs (e.g. note_creators, general news RSS), NEVER let the event start_date fall back blindly to the article's publishing date (pubDate). Doing so pollutes the active calendar with duplicate, non-event blog posts or misaligned dates. If an actual event date (e.g. M月D日) cannot be parsed from the title or description, set start_date = None and clear any fallback. This forces the annotator to either identify the real event date via GPT, or reject the post due to missing event evidence (M1 intake gate).
• Strict timezone adjustment before stripping tzinfo (2026-06-07): For RFC 2822 timestamps or other explicitly zoned-date values, perform timezone adjustments (e.g. converting UTC or foreign offsets to JST) before stripping the tzinfo. Dropping tzinfo on a raw UTC datetime (like converting 23:00 UTC directly to a naive datetime on the same day, which actually wraps to the next day's morning 08:00 JST in JST) causes a silent 1-day calendar drift.
• Strip null bytes from all scraped text: Before writing any string to raw_description, name_ja, or speaker fields, call .replace("\x00", ""). Null bytes (\u0000) can appear in web-scraped text and cause Postgres error 22P05: unsupported Unicode escape sequence. (Incident: taiwan_prism.py c7e9b73 — ×\u0000栖来ひかり in speakers field broke all 13 events.)
• parent_event_id must be a real UUID, never a source_id string: parent_event_id is a uuid column. Passing a source_id string (e.g. f"scraper_{year}") causes Postgres 22P02. Use database.get_event_id_by_source(SOURCE_NAME, parent_source_id) to resolve the UUID. On the first run, when the parent UUID does not yet exist, emit the child with parent_event_id=None and log a WARNING. Do not skip the sub-event. The second run will upsert the correct UUID via the normal scrape cycle. (Incident: taiwan_prism c7e9b73)
• List-page / search-card location_name ≠ actual venue (multi-page scrapers): When a platform shows events on a search/list page AND has a separate detail page, the list card may display the admin/managing branch (e.g. 新宿教室) rather than the actual venue (e.g. 立川サテライト教室). Always fetch the detail page to extract the real location_name. Pattern to look for on detail page: table row 備考 → 「会場名」 bracket pattern; fall back to card branch only if the detail page yields nothing. (Incident: asahiculture da3ac31, 2026-05-15.)
• Multi-classroom scrapers: detect online courses BEFORE resolving physical address. Platforms like 朝日カルチャーセンター serve both in-person (classroom) and online courses. If "オンライン" in raw_title or "オンライン" in location_name, set location_name = "オンライン", location_address = None and skip CLASSROOM_ADDRESS_MAP lookup entirely. Failure to check causes the course's managing classroom address to be written to DB even though the event is online-only. (Incident: asahiculture d617e8c4, 2026-05-15.)

  _is_online = "オンライン" in raw_title or "オンライン" in (detail["location_name"] or "")
  if _is_online:
      location_name, location_address = "オンライン", None
  else:
      location_name = detail["location_name"] or card_branch
      location_address = detail["location_address"] or CLASSROOM_ADDRESS_MAP.get(location_name)
  

• Use re.findall() for start/end date ranges, never re.search(): Strings like "2026/04/07火～2026/06/16火" contain two full dates. re.search() stops at the first match, silently dropping end_date. Use re.findall(pattern, text) then take matches[0] as start_date and matches[-1] as end_date. Single-day events have len(matches) == 1 → end_date = None. (Incident: asahiculture_8759178, 2026-05-15.)
• Keyword-filtered description scan silently hides structured fields: If _fetch_detail* only collects paragraphs containing Taiwan keywords (台湾/Taiwan), any structured field in a non-keyword section — lecturer <h3>, schedule table, venue 備考 row — will never be captured. Always scan the full detail page with separate passes for each structured field type (table rows, headings) independent of keyword filtering. (Incident: asahiculture performer 村山 秀太郎 extracted as "記", 2026-05-15.)
• location_address ≠ location_name rule (ALL scrapers): location_address must NEVER equal location_name. When a scraper has a single combined "location" field, parse it: venue name → location_name, street address (using _ADDR_RE: 〒 or prefecture+city+street pattern) → location_address. If no real street address can be extracted, set location_address = None. This is enforced by auto_qa_address_is_venue_name detector. Also note: _ai_or_existing() in annotator preserves non-null DB values, so a scraper writing the wrong value cannot be corrected by the annotator.
• Japan/Taiwan address extraction rule (2026-06-07):
  • Japan: Address regex must NOT use start-of-string anchors (^). Many addresses start with 〒123-4567 which blocks static anchors. Use local searching for the 47 prefectures.
  • Taiwan: Support 22 cities. Normalize 臺 to 台 before extraction. Ensure the 22 cities (e.g., 台北市, 台東縣) are mapped to their standard names (stripping 市/縣 suffixes for chips).
• Hybrid Venue (Physical + Online) Rule (2026-06-07):
  • For events that have both a physical venue AND an online stream (common in performing_arts), set location_name to a joined string (e.g., “D-Bop”Jazz Club Sapporo / オンライン).
  • MUST retain the physical address in location_address and its prefecture in location_prefectures so the event appears in regional filters and maps.
  • Marking Rule: "Remember to mark both" (記得兩個都標) means capturing both the venue context in name and the physical coordinates in address/prefecture.
  • Apply field_corrections to these fields to prevent AI from reverting the event to "Online only".
• Pure publication is exact-only: Only normalized event_form == ["publication"] is pure. Source, category, title prefix, and placeholder text are drift evidence, not classification inputs.
• Pure publication intentional-null contract: Keep location_address, location_address_zh, location_address_en, business_hours, business_hours_zh, business_hours_en, and location_prefectures NULL with matching empty sentinels.
• Pure publication price presentation: Preserve real DB prices (is_paid, price_info, price_amount) and hide them only in pure-publication UI and JSON-LD. Price fields, location_name, and location_url are outside the seven-field NULL/clear policy.
• Publication title prefixes are locale-aware: name_ja/name_zh keep [新刊出版], name_en uses [New Release], and periodical articles should use name_ja=[雑誌記事], name_zh=[期刊專文], name_en=[Periodical Article]. Do not reuse [期刊專文] in Japanese titles.
• Publication metadata semantics: performer = author, organizer_url = publisher homepage, official_url = book detail/official page, and Hanmoto date fallback order is 発売日 > 登録日.
• Fixed-venue scrapers (cinema, gallery, theater) MUST set organizer= and organizer_type=["commercial_brand"]: location_name is stored in DB and shown in the venue column, but it does NOT appear in the admin event card. The 🏢 venue line in the event card is powered by the organizer field. A fixed-venue scraper that sets only location_name without organizer produces events that look venue-less in the admin list. Correct pattern (see kyoto_cinema.py, kino_shinsaibashi.py, sakurazaka.py):

  location_name="シネマ・クレール 丸の内１・２",
  location_address="岡山市北区丸の内１丁目５−１",
  organizer="シネマ・クレール",
  organizer_type=["commercial_brand"],
  

  (Incident: cinemaclair.py and human_trust_cinema.py missing organizer=, 2026-05-15.)
• Never restrict geographic scope: The project covers all of Japan（全日本）. Regional keyword filters (e.g. _TOKYO_KANTO_KEYWORDS) must never be added to any scraper.
• Date-parser helper functions must have exhaustive return paths: Any _extract_dates() / _parse_*_date() helper must have an explicit return on every branch — never rely on Python's implicit None. A function that falls through returns None, and callers that do start, end = helper() will raise TypeError: cannot unpack non-iterable NoneType object — this is silently swallowed by outer try-except, causing the entire page's events to be dropped with no ERROR log. Add return None, None as the final fallback. (Incident: peatix _extract_peatix_dates, commit 2a9540c, 7 days of silent 0 events.)
• After fixing a filter bug: Run python main.py --source <name> (non-dry-run) after the fix is committed and peer-reviewed. This rule applies specifically to filter bugs that caused events to be silently dropped. A dry-run confirms the fix works but does NOT write to DB — the data gap remains until the next CI cycle.
• --source X is NOT cost-bounded — it always runs the full annotator/merger over the whole DB after scraping. scraper/main.py unconditionally calls annotate_pending_events() + enrich_movie_titles() + enrich_person_names() regardless of --source. These scan the entire events table for annotation_status='pending', so looping --source X over N sources locally triggers the annotator N times and burns ~N× the OpenAI quota of the daily cron. Use cases:
  • Local staging / quota check / SCRAPERS audit across many sources → python main.py --dry-run --source X (no DB writes, no annotator/merger, no OpenAI calls).
  • Verify a single scraper's DB upsert path after a fix → python main.py --source X (one call, accept the annotator pass as cost).
  • Production daily cron → python main.py (no --source) — scrapes all 114 sources then runs annotator/merger ONCE. Do not "optimize" this by sharding into per-source calls; it would increase cost, not reduce it.
• SCRAPERS registration: Every new scraper class must be registered in SCRAPERS in main.py in the same commit it is created. Audit command:

  cd scraper && python3 -c "
  import re, glob
  registered = set(re.findall(r'(\w+Scraper)\(\)', open('main.py').read()))
  for f in glob.glob('sources/*.py'):
      c = open(f).read()
      m = re.search(r'class (\w+Scraper)\b', c)
      if m and m.group(1) not in registered and m.group(1) != 'BaseScraper':
          print('UNREGISTERED:', m.group(1), f)
  "
  

• Run SCRAPERS audit after ANY main.py change: Not only when adding new scrapers. Any refactor or chore commit touching main.py risks silently dropping registrations. Run the audit and confirm "ALL CLEAR" before git push.
• ⚠ Rewriting main.py drops all registrations: When adding a new scraper, NEVER regenerate the full imports+SCRAPERS block from scratch — always append to the existing list. In commit 045d1fa, adding WasedaICL by rewriting main.py silently dropped 24 scrapers that ran without error for weeks (6a83c64 restored them). SCRAPERS count before any commit: python3 -c "import re; print(len(re.findall(r'\\w+Scraper\\(\\)', open('scraper/main.py').read())))" — if count drops vs prior commit, something was lost.
• Source removal procedure (3-step atomically): When removing a scraper entirely:
  1. Remove import from main.py
  2. Remove ScrapeClass() from SCRAPERS in main.py
  3. Hard delete existing DB records: sb.table('events').delete().eq('source_name', '<source_name>').execute() All 3 steps must happen in the same session. Missing step 3 leaves stale data visible in production.
• Promotion checklist (新規スクレイパー完成時 — auto_generate 問わず全件適用): 新しい scraper ファイルを作成した時点で、以下 5 ステップを 同一 session で完了すること。ファイル作成 ≠ 完成。
  1. scraper/sources/<name>.py 作成・dry-run 確認済み。
  2. scraper/main.py — import + SCRAPERS 登録済み（下記 SCRAPERS audit で確認）。
  3. research_sources row — status = 'implemented'。
  4. research_sources.scraper_source_name = '<scraper key>' — 手動で必ず入力。auto_generate も Researcher も書かない。省略すると /admin/sources のイベント数が 0 になり、「今すぐ実行」ボタンも非表示になる（backend が scraper_runs を source_name で JOIN するため）。
  5. 下記 Combined Post-Build Audit を実行し ALL CLEAR を確認。
  • ⚠ 必須在同一個 session で全 5 ステップを完了すること。 途中で session を切ると研究状態が中断し、research_sources 未登録のまま scraper が CI に入る。
  • update_source.py は researched/not-viable のみ対応。 implemented ステータスは update_source.py で設定できない — Supabase SDK で直接 upsert する必要がある:

    sb.table("research_sources").upsert({
        "url": "<listing_url>",
        "name": "<display name>",
        "status": "implemented",
        "scraper_source_name": "<source_key>",
        "scraping_feasibility": "medium",  # or easy/hard
        "agent_category": "event_listing",
    }, on_conflict="url").execute()
    

Venue Registry 使用慣例

1. Scraper 端不要硬編固定場館地址。固定場館應新增到 venues，並設定 is_authoritative = true，scraper 只保留 location_name 原文。
2. Annotator 會透過 venue_registry.lookup_venue() 自動補齊 location_address、location_prefectures、venue_id 與 i18n 欄位。
3. 新場館流程：先由 scraper 穩定抓到 location_name，確認重複出現（至少 2 筆）後，將場館加入 scraper/_oneoff_seed_authoritative_venues.py 的 SEED_DATA，並附上 pre-flight diff 無衝突證據。
4. 多場館系列（影展等）請設定 is_multi_venue = true，讓 annotator 自動使用 prefectures 並將 location_address 保持為 None。
5. Seed pre-flight 衝突 SKIP の注意点:
   • _has_conflict() は NFKC 正規化 + 番地レベルのトランケートで住所を比較する（exact match 禁止）。\u3000・全形数字・大樓名有無・都道府縣前綴の有無はすべて compatible として扱われる。
   • 衝突チェックは active イベントのみ（is_active=True）を対象にする。inactive gnews イベントの住所は不完全なことが多く、seed を誤ブロックする原因になる。
   • SKIP が出た場合は event_id sample を確認し、住所が本当に異なるか（別場所）または単なるフォーマット差異かを判別すること。

Default Fallback & Pricing Policies (系統預設回退與收費政策)

1. 時間空白回退 (Empty Business Hours Fallback): 當事件無 business_hours (場次/營業時間) 時，前端在 UI 上不應只顯示 "—"。

   • 若 official_url 或 source_url 存在，前端會顯示 「請參照原始來源」 并加上指向該 URL 的超連結。這由 web/app/[locale]/events/[id]/page.tsx 中實作。

2. 電影院類的預設有料 (Cinema Default Pricing Fallback): 在 annotator.py AI enrichment 過程中，針對電影院類別（event_form 含有 screening 或 screening_with_talk，或 category 是 movie，或 source_name 符合電影院來源（如 cinema, cinemart, cineswitch, eurospace, human_trust, bungeiza, cinemarine, morc））：

   • 若 is_paid 為空，且非台灣文化中心（source_name="taiwan_cultural_center" 或 organizer 含有台灣文化中心）主辦，預設為 is_paid = True（有料）。
   • 若 is_paid 為 True 且 price_info 為空白，預設為 price_info = "有料"，避免前台因沒有票價顯示留空或破圖。

3. Venue/address display must be normalized once: When an address contains a postal prefix such as 〒123-4567, create one cleaned display string and reuse it across every user-facing surface that renders the same event. The narrative summary, FAQ answer, calendar export, and address card must all use the same cleaned value. Keep the raw address only for map/search queries when needed.

⚡ Combined Post-Build Audit — 新規 scraper 完成後に必ず実行

新しい scraper ファイルを作成・編集するたびに、task_complete 前に必ずこのコマンドを実行し、両方 ALL CLEAR を確認すること。

python3 -W ignore scraper/audit_post_build.py

出力例（正常）:

✅ SCRAPERS: all registered
✅ research_sources: all implemented rows have scraper_source_name
🎉 ALL CLEAR — safe to commit

エラー例（未対応時）:

❌ UNREGISTERED in main.py: TsutayaPortalScraper (sources/tsutaya_portal.py)
❌ scraper_source_name NULL: "蔦屋書店ポータル（台湾キーワード横断検索）" (status=implemented)

• meta.json に source_name / class_name がない場合は generated.py 先頭を直接確認する: auto_scraper/runs/{id}/meta.json に source_name が含まれていない場合がある。その場合は auto_scraper/runs/{id}/generated.py の先頭数行を読んで class XxxScraper(BaseScraper): を探す。クラス名から source_name は snake_case 変換で導ける（BookAndBeerScraper → bookandbeer）。
• auto-scraper feature branch は生成後 24 時間以内にマージする: SCRAPERS リストは全員が同じ行/ブロックを編集するため、放置するほど conflict が深刻化。長期放置 → 複数の scraper 追加コミットが main に積まれ → マージ時に手動解決が必要になる（commit 7cedc68 の Artist Cafe 衝突事例）。
• Identify source_name from a problem event: Never guess from the event title — always query the DB:

  sb.table('events').select('source_name,source_id,source_url').eq('id', '<uuid>').execute()
  

• start_date / end_date must be datetime.datetime, NOT datetime.date: dedup_events in base.py calls .date() on start_date. Passing a bare date object raises AttributeError: 'datetime.date' object has no attribute 'date'. Always use datetime(y, m, d) when constructing dates in scrapers.
• category must be list[str], NOT a bare string: The DB column is text[]. Passing category="movie" raises malformed array literal at write time. Always use category=["movie"]. This fails silently at compile time and only surfaces on DB upsert.
• Sub-events — always look up parent UUID via get_event_id_by_source(): When setting parent_event_id on a sub-event, call database.get_event_id_by_source(source_name, source_id) -> str | None to retrieve the parent's UUID. Never assume the UUID in the scraper or depend on insertion order. Example:

  from scraper.database import get_event_id_by_source
  parent_uuid = get_event_id_by_source("taiwanshi", parent_source_id)
  Event(..., parent_event_id=parent_uuid)
  

• requests.Session() must always mount HTTPAdapter with Retry: Any scraper that creates a requests.Session() must attach a retry adapter in __init__. Without it, a single transient network blip from GitHub Actions runners raises Max retries exceeded and triggers Sentry — even when the target site is healthy. Required pattern:

  from requests.adapters import HTTPAdapter
  from urllib3.util.retry import Retry
  
  _retry = Retry(
      total=3,
      backoff_factor=2,
      status_forcelist=[429, 500, 502, 503, 504],
      raise_on_status=False,
  )
  self._session.mount("https://", HTTPAdapter(max_retries=_retry))
  self._session.mount("http://", HTTPAdapter(max_retries=_retry))
  

  Backoff: 2s → 4s → 8s. Mount both https:// and http://.
• WordPress 活動頁標籤變體防漏抓（主催/講師）: 對 WordPress/類 CMS 活動頁，人物與主辦欄位不得只依賴單一標籤。至少實作 講演者 → 講師 → 登壇者 的 fallback，並同時抽取 主催（必要時 共催）。此外，需將 主催: 與 講師: 顯式寫入 raw_description，確保 annotator 可在結構化文本中穩定回填 organizer / performer，避免觸發 auto_qa_missing_organizer / auto_qa_missing_performers。

WordPress RSS — <strong> Strip 後空格問題

Rule: WordPress RSS の <description> を BeautifulSoup で parse すると、<strong> 等の inline タグ除去後に数字の間に空白が挿入される（例："2026 年 1 月 31 日"）。日付 regex では \d と漢字の間を \s* で繋ぐこと。

# ✅ 正確：\s* で tag-strip artifact を吸収
_DATE_RE = re.compile(r"(\d{4})\s*年\s*(\d{1,2})\s*月\s*(\d{1,2})\s*日")

# ❌ 誤り：スペース固定 or スペースなし — WordPress 環境では失敗する
_DATE_RE = re.compile(r"(\d{4})年(\d{1,2})月(\d{1,2})日")

WordPress RSS CDATA — <a href> URL は .get_text() で消える

Rule: WordPress RSS の <content:encoded> CDATA には Peatix・チケット販売サイト・公式サイトへのリンクが <a href="..."> アンカーとして埋め込まれる。BeautifulSoup(content_html, "html.parser").get_text() でテキスト変換すると href 属性が消えるため、正規表現によるプレインテキスト検索では URL を検出できない。

必ず生 HTML 文字列を別途 BS4 でパースし find_all("a", href=True) を走査する関数を用意すること:

def _extract_peatix_url_from_html(html_text: str) -> Optional[str]:
    """Extract Peatix event URL from HTML anchor href attributes.

    Priority: peatix.com/event/NNN (specific event page) over
    *.peatix.com subdomain (organizer channel page).
    Channel links often appear as banners BEFORE the event link.
    """
    soup = BeautifulSoup(html_text or "", "html.parser")
    channel_url: Optional[str] = None
    for a in soup.find_all("a", href=True):
        href: str = a["href"]
        if "peatix.com" not in href:
            continue
        href = href.rstrip("./,、）)")
        # Prefer /event/NNN path — return immediately
        if re.search(r"peatix\.com/event/\d+", href):
            return href
        if channel_url is None:
            channel_url = href
    return channel_url

呼び出し側でテキスト検索と HTML 検索を OR で組み合わせる:

_peatix = _extract_peatix_url(content_text) or _extract_peatix_url_from_html(content_html)

⚠️ URL 種別の優先度: Peatix には 2 種類の URL が存在する:

• peatix.com/event/NNN/view — 個別イベントページ（チケット購入・詳細情報あり）← 優先
• org.peatix.com — 主催者チャンネルページ（イベント一覧のみ）← fallback

HTML 内に両方が現れる場合、チャンネルページが先に出現することが多い。常に全アンカーを走査して /event/NNN を優先すること。

適用範囲: WordPress RSS を使う全 scraper（ftip、その他 WordPress ベースのソース）。

(Incidents: ftip ee870f7 CDATA extraction, 34368e3 channel-vs-event priority, 2026-05-17.)

Peatix — ロケールプレフィックス URL の正規化（URL 収集段階で実施）

Rule: Peatix は headless ブラウザのロケール設定に応じて https://peatix.com/us/event/{id} や /ja/event/{id} 形式の URL を返すことがある。これらは実際のイベントページ（https://peatix.com/event/{id}）へのリダイレクトが失われると 302 → トップ になり broken link となる。URL は 収集段階（_search_events・_scrape_group_events）で正規化すること。

import re

_PEATIX_LOCALE_RE = re.compile(
    r"(https://peatix\.com)/[a-z]{2,5}(?:-[A-Z]{2})?(/event/)"
)

def _normalize_peatix_url(url: str) -> str:
    """Strip locale prefix from Peatix URLs.

    https://peatix.com/us/event/123  →  https://peatix.com/event/123
    https://peatix.com/ja/event/123  →  https://peatix.com/event/123
    https://peatix.com/event/123     →  unchanged
    """
    return _PEATIX_LOCALE_RE.sub(r"\1\2", url)

収集ループでの適用:

# _scrape_group_events / _search_events 両方に適用
full = _normalize_peatix_url(full.split("?")[0])

既存 DB に locale 付き URL が混入している場合の修正手順:

1. sb.table('events').select(...).like('source_url','%/us/event/%') で件数確認
2. 正規化後 source_id = hashlib.md5(new_url).hexdigest()[:16] を計算
3. その source_id で既存レコードが存在するか確認
   • DUP あり → /us/ 版を merged_into_event_id 設定して soft-delete
   • DUP なし → source_url・source_id を直接 update

(Incidents: peatix e9c6f80b 2026-05-17, 55d766ae 2026-05-19, commit 8b901ec.)

aggregator scraper の location_name フォールバックに組織名を使わない

Rule: 会場抽出に失敗した場合、組織名定数（例: LOCATION_NAME = "台湾原住民族との交流会"）を location_name のフォールバックに使わないこと。組織名が会場として DB に入り、UI で「会場：台湾原住民族との交流会」と誤表示される。

# ✅ 正確：会場不明なら None
location_name = venue_name if venue_name else None

# ❌ 誤り：組織名定数をフォールバックに使う
location_name = venue_name if venue_name else LOCATION_NAME  # "〇〇協会" が venue になる

会場が不明な場合は location_name = None とし、annotator または手動修正に委ねること。

(Incident: ftip 278e6d8, 2026-05-17.)

適用範囲：WordPress 6.x 以降の全 RSS ベース scraper。get_text() / get_text(strip=True) を問わず発生する。

Reference incident: 2026-05-12 — nittai_toumonkai.py（WordPress 6.9.4）の <description> で 2026 年 1 月 31 日 形式を確認。

venue regex 負向前瞻 — (?!<後綴詞>) 誤匹配防止

Rule: 会場、場所、開催場所 等の venue キーワード regex に負向前瞻を追加して複合語の誤マッチを防ぐ。

# ✅ 正確：会場受付 を venue として拾わない
_VENUE_RE = re.compile(r"会場(?!受付)[：:]\s*(.+)")

# ❌ 誤り：会場受付 も venue として抽出してしまう
_VENUE_RE = re.compile(r"会場[：:]\s*(.+)")

要注意の複合語一覧：会場受付、会場費、会場変更、会場案内 各 regex 追加時に上記複合語を検討し、必要に応じて (?!受付|費|変更|案内) を付与すること。

Reference incident: 2026-05-12 — nittai_toumonkai.py で 会場受付 が venue name として誤抽出。

Venue / 日時ラベル抽出 — セパレーター量詞と get_text 使い分け

セパレーター文字クラスは +（1 回以上）にする

venue・日時ラベル（会場、場所、開催場所、日時 等）の後ろに続くセパレーター文字クラスは必ず + にする。* を使うと本文中の同名の一般名詞（例：称揚する場所」...）にマッチしてゴミテキストを venue として取得してしまう。

# ✅ 正確：セパレーターが最低 1 文字必要
_VENUE_RE = re.compile(r"(?:会場|場所|開催場所)[　\s：:]+([^\n]{3,60})")

# ❌ 誤り：セパレーターなし（0 回）でもマッチ → 本文中の一般名詞に誤マッチ
_VENUE_RE = re.compile(r"(?:会場|場所|開催場所)[　\s：:]*([^\n]{3,60})")

get_text("\n") と get_text(" ") の使い分け

用途	推奨	理由
venue・日時（構造依存、[^\n] を使う regex）	get_text("\n", strip=True)	HTML ブロック境界が \n に変換され [^\n] がブロック内で停止する
日付・概要・キーワード判定（改行不要）	get_text(" ", strip=True)	1 行テキストで regex が扱いやすい

両バリアントを変数として保持するのが安全：

full_text    = soup.get_text(" ",  strip=True).replace("\x00", "")  # 日付・概要用
full_text_nl = soup.get_text("\n", strip=True).replace("\x00", "")  # venue・日時用

mv = _VENUE_RE.search(full_text_nl)   # ✅ [^\n] がブロック境界で停止
md = _DATE_RE.search(full_text)        # ✅ 改行なし 1 行テキストで日付 regex

get_text(" ") のみで venue regex を走らせると、会場行と次のセクション（プログラム・講師情報 etc.）が 1 行に結合されるため、[^\n]{3,60} が 60 文字まで次のセクションを取り込む。

Reference incident: 2026-05-15 — snet_taiwan.py で 場所 が本文に誤マッチ（量詞 * 修正）後も get_text(" ") によりプログラム情報が混入（get_text("\n") 導入で解決）。

全形数字 — unicodedata.normalize("NFKC") 事前変換

Rule: 日本語ウェブページの数字は全角（２０２６年）で記述されている場合がある。parse 前に unicodedata.normalize("NFKC", text) で半角に統一すること。

import unicodedata

def _fw_to_ascii(self, text: str) -> str:
    """全形数字・記号を半形に変換する。"""
    return unicodedata.normalize("NFKC", text)

# parse pipeline
text = self._fw_to_ascii(raw_text)
m = _DATE_RE.search(text)  # \d が全角を拾い損ねない

適用範囲：全角数字が出現しうる全 scraper（特に団体サイト・勉強会系）。BeautifulSoup.get_text() は全角のまま返すため変換は必須。

Reference incident: 2026-05-12 — nittai_toumonkai.py 本文に ２０２６年 が出現。

時間レンジ区切り文字 — 5 種類すべてを character class に含める

Rule: 日本語テキストの時間レンジ（開始〜終了）を正規表現でパースする際は、以下 5 種類の区切り文字すべてを character class に含めること。

文字	Unicode	典型ソース
〜	U+301C WAVE DASH	一般的
~	U+007E ASCII TILDE	一般的
～	U+FF5E FULLWIDTH TILDE	一般的
-	U+002D HYPHEN-MINUS	ASCII
－	U+FF0D FULLWIDTH HYPHEN-MINUS	学術・waseda 系

_TIME = r'\d{1,2}:\d{2}'
# ✅ 全 5 種の区切り文字を網羅
m = re.search(rf'({_TIME})\s*[〜~～\-－]\s*({_TIME})', text)

annotator.py の _extract_hours_from_raw() はこのパターンを実装済み（commit b3b32b3）。新たに時間パーサを書く際は同じ character class を踏襲すること。

修正時のテスト手順：

cases = [
    '15:05－17:00',  # U+FF0D
    '15:05～17:00',  # U+FF5E
    '15:05〜17:00',  # U+301C
    '15:05-17:00',   # ASCII
    '15:05~17:00',   # U+007E
]
for t in cases:
    assert re.search(rf'({_TIME})\s*[〜~～\-－]\s*({_TIME})', t), f'MISS: {t!r}'

Reference incident: 2026-05-30 — waseda_taiwan event 75a46729 で business_hours が 15:05 のみ（17:00 欠落）。commit b3b32b3。

Jimdo / 一部 CMS — URL パス encoding 不統一 → unquote(href)

Rule: Jimdo, 一部の WordPress, FC2 等のCMSは、<a href> の日本語パスをあるページでは URL-encode し、別のページでは生の日本語文字で出力する。比較・重複排除を行う前に unquote() で正規化すること。

from urllib.parse import unquote, urljoin

href = a.get("href", "")
normalized = unquote(href)  # %E3%83%96%E3%83%AD%E3%82%B0 → ブログ
full_url = urljoin(base_url, normalized)

注意：urljoin は encode 済み URL も未 encode URL も正しく処理するが、比較は必ず decode 後に行うこと（/ブログ/ と /%E3%83%96%E3%83%AD%E3%82%B0/ は同一 URL だが文字列比較では不一致）。

Reference incident: 2026-05-12 — tsudoi_osaka.py（Jimdo CMS）の href に encoding 不統一が確認された。

POST 検索フォームサイト — requests.post + 302 追跡

大学・機関サイトの検索機能は GET パラメータでなく POST body を使うことが多い。

必須確認：ブラウザ devtools の Network タブまたは curl -v でフォームの method 属性を確認する。

# ✅ POST 検索 — Cookie なし、302 自動追跡
resp = requests.post(
    "https://www.wuext.waseda.jp/course/search-list/",
    data={"keyword": "台湾", "page": 1},
    allow_redirects=True,
    headers={"User-Agent": "Mozilla/5.0"},
    timeout=30,
)

# ❌ GET パラメータは無視される（POST フォームサイト）
resp = requests.get("https://www.wuext.waseda.jp/course/search-list/?keyword=台湾")

規則:

• POST フォームサイトは Cookie なしで動作することが多い（まず試す）。セッション Cookie が必要な場合のみ requests.Session() を使う。
• allow_redirects=True で 302 を自動追跡する。
• form[method="post"] サイトへの GET リクエストは検索結果でなくデフォルトページを返す。結果が 0 件の場合は必ず POST を試すこと。

Reference incident: 2026-05-13 — wuext_waseda.py で ?keyword=台湾 GET が無視され 0 件。POST に変更で正常動作。

大学・機関サイト — コンテンツコンテナと台湾フィルタ

本文コンテナの特定

大学・機関サイトの detail ページは固有の id または class を持つコンテンツコンテナを使う。

# ✅ 早稲田エクステンション: id="course"
content = soup.find(id="course") or soup.find("main") or soup

# ❌ find('body') はナビゲーション・サイドバー・フッターを含む — キーワード判定が不正確
content = soup.find("body")

手順:

1. curl -s <url> | grep -E 'id=|class=' | head -30 でコンテナ候補を列挙する。
2. ブラウザ devtools で実際のコンテンツ div を確認する。
3. id を優先し、なければ class セレクターを使う。find('main') は最終手段。

要注意のサイト別コンテナ例:

• 早稲田エクステンション（wuext_waseda）: id="course"
• 朝日カルチャーセンター（asahiculture）: div.course-detail / 備考 th/td row

台湾フィルタは詳細ページ本文まで検索する

大学講座・機関イベントはタイトルに「台湾」を含まず、本文のみで台湾を言及する場合が多い（例: 「緊迫する世界状勢と現代地政学」「台湾有事」を内容で扱う）。

_TAIWAN_KEYWORDS = ("台湾", "台北", "台中", "高雄", "台南", "日台", "台日", "中華民国")

def _is_taiwan_content(self, title: str, detail_soup) -> bool:
    """タイトルまたは詳細ページ本文に台湾キーワードが含まれるか判定する。"""
    if any(kw in title for kw in _TAIWAN_KEYWORDS):
        return True
    content = detail_soup.find(id="course") or detail_soup
    body_text = content.get_text(" ", strip=True)
    return any(kw in body_text for kw in _TAIWAN_KEYWORDS)

規則:

• 詳細ページ取得が価格・日付抽出と兼用できる場合は必ず本文フィルタを有効にする。
• タイトルのみフィルタは教育・学術系サイトでは収録漏れが多い。
• _TAIWAN_KEYWORDS は最低限 台湾 日台 台日 を含めること。

Reference incident: 2026-05-13 — wuext_waseda.py でタイトルのみフィルタにより「緊迫する世界状勢と現代地政学」等が脱落。

Date Extraction — General Rules

Rules that apply to ALL scrapers when constructing raw_description and start_date/end_date.

開催日時: prefix — complete format when end_date is known

When a scraper already knows end_date AND end_date ≠ start_date, the 開催日時: prefix in raw_description must include the full date range:

開催日時: YYYY年MM月DD日〜YYYY年MM月DD日

Writing only the start date (開催日時: YYYY年MM月DD日) tells GPT there is a single day → SINGLE-DAY RULE fires → end_date is set to start_date, discarding the correct value already held by the scraper.

Note: annotator.py's annotation.get("end_date") or event.get("end_date") fallback is blind to non-null wrong values — it only activates when GPT returns null. If GPT returns a non-null but incorrect end_date (e.g. same as start_date via SINGLE-DAY RULE), the scraper's correct value is silently discarded.

Year anchor for date-less news scrapers

When a news-type scraper (google_news_rss, prtimes, nhk_rss, etc.) cannot extract a complete date from the article (i.e. the article only mentions a month/day or no date at all), embed the RSS pub_date as a year anchor in raw_description:

（記事配信日: YYYY年MM月DD日）

Insert this before the article body text. Without a year anchor, GPT may infer the wrong year (e.g. guessing 2024 when the correct year is 2026).

N日間 duration keywords

annotator.py SYSTEM_PROMPT Rule 10 covers N日間 → end_date = start_date + (N-1) days, but scrapers should also attempt self-resolution rather than defaulting to end_date = start_date:

import re
from datetime import timedelta

m = re.search(r'(\d+)日間', raw_description)
if m:
    n = int(m.group(1))
    end_date = start_date + timedelta(days=n - 1)

Similarly, N週間 → N × 7 days. Apply BEFORE falling back to end_date = start_date.

On-Demand / Viewing Period — detail page date extraction

When a listing table cell has only a term name (e.g. 2025年度 冬期 全4回) with no explicit date range, the actual start/end dates are often embedded in the detail page body as (YYYY/MM/DD) or YYYY年MM月DD日.

Priority order for on-demand / date-less courses:

1. Tier 1: Parse explicit date range from listing column (e.g. 07月04日～07月25日)
2. Tier 2: Extract (YYYY/MM/DD) or YYYY年MM月DD日 from detail page body — take earliest as start_date, latest as end_date
3. Tier 3: Term fallback (春期→4/1, 夏期→7/1, 秋期→10/1, 冬期→1/1 of next calendar year)

_DETAIL_DATE_PARENS_RE = re.compile(r"\((\d{4})/(\d{1,2})/(\d{1,2})\)")

def _extract_detail_dates(detail_soup):
    text = (detail_soup.find(id="course") or detail_soup).get_text(" ", strip=True)
    found = []
    for m in _DETAIL_DATE_PARENS_RE.finditer(text):
        found.append(datetime(int(m.group(1)), int(m.group(2)), int(m.group(3)), tzinfo=timezone.utc))
    found.sort()
    return (found[0], found[-1] if len(found) > 1 else None) if found else (None, None)

Always try detail page dates before term fallback — term fallback yields YYYY-01-01 / YYYY-04-01 which shows as "日期未定" on the web UI and misleads users.

Reference incident: 2026-05-14 — wuext_waseda event 30bdfc30「台湾と日本―興味の台湾案内」 had start_date=2026-01-01 (term fallback). Actual viewing period (2025/11/26)～(2026/04/30) was in the detail body. Fixed in commit bacd4cd.

annotator or event.get("end_date") fallback — blind spot

The pattern annotation.get("end_date") or event.get("end_date") only rescues the scraper's value when GPT returns null. When GPT returns a non-null wrong value (most commonly SINGLE-DAY RULE: end_date = start_date), the or branch is never reached — the wrong value is written to DB. Fix: always embed the correct date range in raw_description (see § 開催日時: prefix above) so GPT never needs to fall back to SINGLE-DAY RULE in the first place.

Contentful CDA — 年度系列展日期 slug Fallback

問題：Contentful 年度系列展使用 scheduleStartsOn=YYYY-01-01 作為財年佔位符。
偵測：start_date.month == 1 and start_date.day == 1
修復：從 URL slug 末尾提取真實日期：

slug_m = re.search(r"/(\d{4}-\d{2}-\d{2})$", slug)
if slug_m and start_date and start_date.month == 1 and start_date.day == 1:
    start_date = self._parse_date(slug_m.group(1))

驗證：乾跑後確認無事件 start_date 為 Jan 1。

Reference incident: 2026-05-05 — event 6a91a4ce (アジア美術の歩き方 東アジア編) scheduleStartsOn=2026-01-01 為佔位符，真實日期 2026-04-18 在 slug 末尾 (commit a1e58a9)。

URL Handling — Relative Path Guard

Rule: Every a["href"] value that may be a relative path must be converted via urljoin before storing in source_url or detail_url.

from urllib.parse import urljoin

# ✅ 正確：無論 href 是相對或絕對路徑，都透過 urljoin 轉換
source_url = urljoin(page.url, a["href"])

# ❌ 錯誤：直接存相對路徑，會產生 ../news/n*.html 等無效 URL
source_url = a["href"]

Incident: hakusuisha.py 的 ../news/n*.html 直接存入 DB（commit 1b344f7），導致 10 筆事件 source_url 404。

Auto-generated scraper 的 detail_url 補全規則（spec_to_code template 生成的 _extract_cards 模式）：

# ✅ 最正確：urljoin(page.url, href) — 處理 /path、../path、relative/path 等所有形式
from urllib.parse import urljoin
if detail_url and not detail_url.startswith(("http://", "https://")):
    detail_url = urljoin(page.url, detail_url)

# ❌ 不完全：BASE_URL + path は ../news/n*.html 形式を解決できない
# if detail_url and not detail_url.startswith("http"):
#     detail_url = f"{BASE_URL}/{detail_url}"

BASE_URL 文字列結合は / 前導パスには機能するが ../news/n*.html 形式では {BASE_URL}/../news/... という無効 URL になる。urljoin(page.url, href) が唯一の正解。Incidents: cine_gallery.py 事件 cdf5e555（2026-05-14）; hakusuisha.py ../news/n*.html → 2026-05-30 c099bcb で修正。

BeautifulSoup 多行文字提取 — separator="\n"

Rule: 任何需要保留行結構的文字提取（排程、場次、地址、時間表等），必須使用 separator="\n"。

# ✅ 正確：保留行結構
text = element.get_text(separator="\n", strip=True)

# ❌ 錯誤：連續 inline 元素的文字直接拼接，時間/場次資訊擠在一起
text = element.get_text(strip=True)

Incident: gguide_tv.py 排程文字缺 separator="\n"，時間資訊擠在一起（commit a895e07）。

Cinema scraper — end_date と business_hours 完全規則

適用対象: 全ての cinema scraper（category=["movie"] を持つ全 scraper）

分類ごとの実装パターン

日本の電影院 scraper は3タイプに分類される。タイプごとに end_date と business_hours の取得戦略が異なる。

---

Type 1: 票務平台分離型（例: starcat_cinema）

特徴: 主サイト（eiga.starcat.co.jp）は映画情報・あらすじのみ。場次時間と排片日程は別の票務平台（starcat-ticket.com など）に存在する。

end_date 規則: 日本の映画館は毎週木曜日に翌週（金曜〜木曜）の上映スケジュールを発表する。したがって:

• end_date = 票務スケジュール内のその映画の最後の日（当週木曜）
• _build_ticket_schedule() は dict[str, tuple[str, Optional[datetime]]] を返す: (business_hours_str, last_date_utc)
• 上映スケジュールに未登場の映画（未公開または上映終了）: end_date = None
• 每次 CI 実行で end_date は自動延伸（滚动视窗）

business_hours 規則: _build_ticket_schedule(ticket_url) から取得。形式: M/DD(曜): HH:MM〜HH:MM（複数日は \n 区切り）

raw_description 前綴必須規則（SINGLE-DAY RULE 防止）:

# end_date が start_date と異なる場合、必ず完整な期間範囲を前綴に入れる
if start_date and schedule_end and schedule_end != start_date:
    date_prefix = f"上映期間: {start_date.year}年{start_date.month}月{start_date.day}日〜{schedule_end.year}年{schedule_end.month}月{schedule_end.day}日"
# ❌ NG: "2026年5月15日(金)より公開" のみ → annotator SINGLE-DAY RULE → end_date = start_date

参考実装: starcat_cinema.py — TICKET_SCHEDULE_URLS + _build_ticket_schedule() + _lookup_schedule_entry() + _lookup_end_date() + _lookup_business_hours()

---

Type 2: 排片表嵌入型（例: shin_bungeiza, cinemart_shinjuku, ks_cinema, rightscube）

特徴: 映画詳細ページ内に上映スケジュール（日付 + 時刻）が直接含まれる。

end_date 規則: max(dates in schedule) — スケジュール内の最終日

end_date = max(parsed_dates, default=None)

business_hours 規則: HTML スケジュール要素から直接抽出。常見容器:

• div.schedule-program (shin_bungeiza)
• div.schedule-table / table.schedule (各映画館)
• dl.showtime / ul.times (単館映画館)
• p.nihon-date + div.program 組合せ (shin_bungeiza パターン)

日付ヘッダー（<h2> / <p class="nihon-date">）と上映時刻（<div class="schedule-program">）が別要素の場合は両者を組み合わせる:

business_hours = "\n".join(
    f"{date_label}: {' '.join(times)}"
    for date_label, times in schedule_map.items()
)

---

Type 3: 上映中リスト型（例: cineswitch_ginza, human_trust_cinema, uedaeigeki）

特徴: 現在上映中 / 近日公開映画のカード一覧ページ。詳細な場次時間は別ページまたは別プラットフォームに存在する。

end_date 規則: カードに "M/D まで" / "〜M/D" / "終映日：M/D" / "※M/D で上映終了" ラベルがある場合はそこから解析。ない場合は None（推測禁止）。

business_hours 規則: リストページに場次時間がない場合は None。ただし詳細ページに時刻がある場合は詳細ページを取得して抽出する（コスト対効果を考慮すること）。

---

共通禁止事項

1. end_date = start_date の扱い: cinema scrapers では原則として end_date = start_date を新たに作らない。end_date を持つ場合は少なくとも start_date + 1日 にする。例外は movie-extend 用の明示的 fallback だけで、その場合に限り end_date = start_date を許容する。（Incident: kyoto_cinema, 2026-05-20）
2. 空文字列 business_hours = "" 禁止: 場次が取得できない場合は None を設定。空文字列は DB に不要なデータを残す。
3. 推測による end_date 禁止: 「通常2〜3週間上映」などの仮定で end_date を算出してはいけない。ソースから取得できない場合は None。
4. 視覚上に場次時間があるのに business_hours = None は scraper bug: サイトを目視確認して時刻要素のセレクタを追加すること。
5. event_form=["screening"] 必須: 全 cinema scraper は event_form=["screening"] を設定すること。DB check constraint（migration 047）の valid 値: 'exhibition','screening','lecture','performance','market','workshop','conference','networking','screening_with_talk','tour','competition','tasting','broadcast','study_abroad','other'。"film_screening" は DB に存在しない（constraint エラー）。（Incident: kyoto_cinema・sakurazaka・kino_shinsaibashi・human_trust_cinema で "film_screening" を誤設定 → constraint 違反、commit で revert）

JST ISO datetime パース規則

一部 CMS（TTCG など）は data-date="2026-05-15T00:00:00+09:00" のような JST-aware ISO 文字列を出力する。.replace("+09:00", "") パターンは禁止 — JST offset を除去しても naive datetime が生成されるだけで UTC 変換にならない。

# ✅ 正確：JST-aware parse → UTC midnight
dt_jst = datetime.fromisoformat(data_date)  # 2026-05-15 00:00:00+09:00
start_date = datetime(dt_jst.year, dt_jst.month, dt_jst.day, tzinfo=timezone.utc)

# ❌ 誤り：offset を strip した naive datetime になる
start_date = datetime.fromisoformat(data_date.replace("+09:00", ""))

Incident: human_trust_cinema commit 7849021。

Annotator SINGLE-DAY RULE 防護

raw_description に単一の日付しか含まれない場合、annotator は end_date = start_date と設定する（SINGLE-DAY RULE）。Cinema scraper では以下を守ること:

• raw_description の前綴に必ず上映期間全体を記載する: 上映期間: YYYY年M月D日〜YYYY年M月D日
• Type 1 scraper で end_date が取得できた場合は前綴を期間表示に置き換える（単日 より公開 記述のまま放置しない）
• Type 3 で end_date が取得不可の場合は date prefix を入れない: サイトに end_date 情報がない場合は、raw_description に日付前綴を追加しない。start_date はフィールドに正しく格納済みなので raw_description に繰り返す必要はない。（Incident: human_trust_cinema commit 7849021）

稽核表 ghost エントリ防止

稽核表に新行を追加する前に、ファイルの実在を確認すること:

ls scraper/sources/<name>.py

不存在のファイルを稽核表に記載すると後続の修復作業で混乱を招く。（Incident: ciemarine 行 — ファイル不存在のまま記載されていたため削除）

現況稽核表（2026-05-15 時点）

Scraper	Type	end_date	business_hours	状態
cinemart_shinjuku	2	✅ max(dates)	✅ cineticket.jp	完全準拠
shin_bungeiza	2	✅ h2 dates max	✅ schedule-program	完全準拠
starcat_cinema	1	✅ 木曜末日	✅ starcat-ticket.com	完全準拠
rightscube	2	✅ THEATER区段	✅ business_hours_text	完全準拠
ks_cinema	2	✅ 表格期間	✅ schedule_text (commit 23e417f)	完全準拠
kino_shinsaibashi	3	✅ 終映日	❌ None（JS 驅動，Type 3 可）	完全準拠（screening + prefix, commit 544bbc4）
kyoto_cinema	3	✅ 終映日M/D; fallback=start_date（movie-extend 用）	✅ homepage time slots	完全準拠（screening + prefix, commit e91f5cd; movie-extend fallback, 2026-05-20）
cineswitch_ginza	3	✅ M/D まで	❌ None（Type 3 可）	完全準拠（UTC fix, commit e91f5cd）
theater_enya	3	✅ 期間文字	❌ None（Type 3 可）	完全準拠（UTC fix, commit e91f5cd）
cinewind	2	✅ YYYY/M/D	❌ None（Type 2, 追加調査要）	UTC 修正済み（commit e91f5cd）
ciema	2/3	✅ 週表頭	❌ None（Type 3 可）	完全準拠（UTC fix, commit e91f5cd）
cinemadict	2	✅ 完整期間（UTC fix）	✅ date_text HH:MM（commit 544bbc4）	完全準拠
ycam_cinema	2	✅ 節目期間	❌ None（Type 2, 追加調査要）	UTC 修正済み（commit e91f5cd）
sakurazaka	3	✅ 上映中/予定	❌ None（Type 3 可）	完全準拠（screening, commit e91f5cd）
uedaeigeki	2	✅ 上映日程	❌ None（Type 2, 追加調査要）	UTC + prefix 修正済み（commit e91f5cd）
human_trust_cinema	3	❌ None（サイト非公開, JS-driven）	❌ None（同上）	UTC+event_form 完了（commit 7849021→revert）, end_date はサイト制限
theater_kino	2	✅ 静的HTML	❌ None（Type 2, 追加調査要）	UTC + prefix 修正済み（commit e91f5cd）

新規 cinema scraper 作成時は、上記稽核表に行を追加すること。

Incidents:

• shin_bungeiza（commit 1ffb98e）— _parse_nihon_date_only() が <h2> 日付のみ取得し <div class="schedule-program"> の場次時間を無視。
• starcat_cinema（2026-05-15）— 主サイトに場次なし → starcat-ticket.com から別途取得。end_date=None が annotator SINGLE-DAY RULE で start_date に上書きされた。

---

auto_qa 地名關鍵字設計規則

• TAIWAN_VENUE_KEYWORDS 必須使用完整行政單位名（台北市、新北市），禁用裸縮寫（台北、新北）以避免日本地名假陽性
• 新增關鍵字前：grep -rn "<keyword>" scraper/sources/ 確認不在任何已知日本地名中
• 假陽性無法靠 dismiss 解決：dedup 邏輯在 updated_at > confirmed_at 時重新觸發；根治需修正關鍵字

Reference incident: 2026-05-05 — '新北' 匹配大阪市 新北島，event 371cf624 (GRAFFYHALL) 連續三次 auto_qa_taiwan_venue (commit 6b7174a)。

_extract_after_label() を使う構造化テキスト scraper の _STOP_LABELS 管理

_extract_after_label(text, label_re) は _STOP_LABELS に登録された語で抽出を打ち切るが、同一行に出現しうる全ラベルが未登録だと venue_raw に発表者・対象者情報が混入する。

Rule: _STOP_LABELS は「同一行に現れうる全ラベル」を網羅すること

# 典型的な早稲田台湾研究所ソース行：
場所：〇〇教室 講演者：郭智輝氏（...） モデレーター：久保克行 対象：学生・一般

講演者/モデレーター/対象 が _STOP_LABELS に未登録だと、venue_raw が 〇〇教室 講演者：郭智輝氏... 対象：... になり、会場: {venue_raw} として raw_description に混入 → annotator が全テキストを location_name に格納する。

学術イベント系 raw_description 構成ルール

講演者/モデレーター が存在する場合、raw_desc_parts に独立したエントリとして追加する：

speaker_raw = _extract_after_label(content, r"講演者")   # stops at モデレーター:
moderator_raw = _extract_after_label(content, r"モデレーター")  # stops at 対象:

raw_desc_parts = []
if date_raw:     raw_desc_parts.append(f"開催日時: {date_raw}")
if venue:        raw_desc_parts.append(f"会場: {venue_raw[:200] or venue}")
if speaker_raw:  raw_desc_parts.append(f"講演者: {speaker_raw}")
if moderator_raw: raw_desc_parts.append(f"モデレーター: {moderator_raw}")

会場: 行に発表者情報を混ぜると annotator は performers を正しく抽出できない。

Reference incident: 2026-05-30 — waseda_taiwan event 75a46729、_STOP_LABELS 未登録で venue に発表者混入 (commits 0604a6f, b3be645)。

Performer Job Title Guard

Rule: performer 欄位只能填人名，不可填職稱/職業描述。

下列詞彙單獨出現時必須視為職稱並設 performer = null：

• 日語職稱：シェフ、料理人、講師、先生、司会、ゲスト、ホスト、演者、指揮者、伴奏者
• 中文職稱：主廚、老師、講師、主持人

判斷規則：

1. performer 字串若只含職稱詞且無可辨識人名（CJK 人名 ≥ 2 字、或拉丁姓名）→ 設 null
2. _extract_performer_from_raw() 的 role list regex 命中後，必須確認後方緊跟的是人名而非獨立職稱

Regex guard 範例（加在 _extract_performer_from_raw 最後）：

_JOB_TITLE_ONLY_RE = re.compile(
    r"^(シェフ|料理人|講師|先生|司会|ゲスト|ホスト|演者|指揮者|伴奏者|主廚|老師|主持人)$"
)
if _JOB_TITLE_ONLY_RE.fullmatch(candidate.strip()):
    return None

Reference incident: 2026-05-08 — 湾.味(ワンウェイ) 台湾料理体験会 performer='シェフ' 應為 null。

ZERO_EVENT_OK_SOURCES — 偶發性 scraper 零事件豁免

Rule: 合法情況下絕大多數時間返回 0 events 的 scraper，必須加入 health_check.py 的 ZERO_EVENT_OK_SOURCES 集合，避免 CI 每日觸發假「missing」警告。

加入標準（三項全符合）：

1. Scraper 邏輯已驗證正確（dry-run 通過、已 commit）
2. 台灣相關內容為偶發性（年 0–3 次，如藝廊特展、部分影院）
3. 0 events 是預期行為，不代表爬蟲失敗

反模式：不應因「通常有 0 events」就忽略加入此集合——遺漏會導致每次 CI 都需人工確認雜訊。

實作位置：scraper/health_check.py → ZERO_EVENT_OK_SOURCES: set[str]

Reference incident: 2026-05-08 — whitestone_gallery 加入 ZERO_EVENT_OK_SOURCES（台灣藝術家展覽為偶發性）。

Encoding guard before classifying zero-event output

For requests + BeautifulSoup static HTML scrapers, if the HTTP header omits charset but the page declares <meta charset="UTF-8">, do not parse resp.text. Pass resp.content to BeautifulSoup, or set resp.encoding explicitly before reading text.

Validate Japanese markers such as 月, 日, and 開催日時, then confirm the scraped text has no mojibake or U+FFFD before deciding that 0 events are expected.

Keyword-filtered long-tail sources

ZERO_EVENT_OK is not limited to cinemas and galleries. Keyword-filtered feeds, listings, and aggregators can legitimately return 0 events after the scraper logic is verified.

Current examples: nhk_rss, walkerplus, bookandbeer, internet_museum.

Do not hide a fresh bug with ZERO_EVENT_OK

If a source just had an active selector or encoding fix, keep it out of ZERO_EVENT_OK until dry-run proves the parsing path works and quiet periods are expected. johakyu stayed monitored after switching the schedule parser to resp.content.

Reference incident: 2026-07-10 — johakyu used requests resp.text on a UTF-8 page without charset header, mojibaked schedule text and silently returned 0 events; fix used resp.content. Same update added nhk_rss, walkerplus, bookandbeer, internet_museum to ZERO_EVENT_OK_SOURCES after classifying them as verified keyword-filtered long-tail sources.

organizer_zh/en FC 跨事件污染偵測

Rule: organizer_zh/organizer_en 若含有在 raw_title + raw_description 中完全找不到的內容，即為 FC 跨事件污染（cross-event field_corrections pollution）。

污染機制：annotator 的 few-shot context 中，若前一事件的 FC 資料帶入了 organizer_zh/en，GPT 可能將該值套用到當前事件——即使兩者完全無關。annotation_status = annotated 不會重新觸發驗證，因此污染可長期潛伏。

偵測查詢（定期執行）：

SELECT id, organizer_zh, organizer_en, source_name
FROM events
WHERE organizer_zh IS NOT NULL
  AND raw_description NOT ILIKE '%' || split_part(organizer_zh, ' ', 1) || '%'
  AND raw_title NOT ILIKE '%' || split_part(organizer_zh, ' ', 1) || '%'
LIMIT 50;

修正流程：確認污染後，field_corrections で organizer_zh・organizer_en を FC lock（annotator の再上書き防止）。

• source に正式な中国語名がある場合 → 正しい値を設定して FC lock。
• source に信頼できる中国語名が存在しない場合 → null に設定して FC lock（幻覚値より null が安全。UI は organizer（ja）へ fallback する）。

追加検出サイン：organizer_zh 値に （AI翻訳） / （AI翻譯） サフィックスが含まれる場合は即 null クリア + FC lock。⚠️ auto_qa.py _detect_performer_ai_marker は performer_zh/en + category=movie 限定であり organizer_zh は自動検出されない。定期的に以下 SQL で補完すること：

-- organizer_zh の AI マーカー残留スキャン
SELECT id, organizer_zh, source_name
FROM events
WHERE is_active = true
  AND (organizer_zh LIKE '%AI翻譯%' OR organizer_zh LIKE '%AI翻訳%')
LIMIT 50;

Reference incidents:

• 2026-05-08 — fe03288b/b8621ee9（湾.味 台湾料理体験会）organizer_zh/en 含上田村振興会・普門寺資料，與 raw_description 完全無關。
• 2026-05-30 — fb12bfa7（台湾茶ゲームイベント / kokuchpro）同一の 上田村振興会・普門寺（AI翻訳） が再発。raw_description は「語学スクール」のみ。organizer_zh/en = null + FC lock で対応。location_name・location_address も kokuchpro 構造フィールド（会場:/住所:）から正値に修正。

Frontend Client Component — UTC 日期表示一貫性ルール

Rule: DB に保存された timestamp は UTC。Next.js の client component で new Date(dateStr) を使う場合、ブラウザの TZ が UTC でなければ getDate() / getMonth() はローカル時間で評価される。JST（UTC+9）では UTC 15:00 が翌日 00:00 に見えて日付が 1 日ずれる。

修正パターン:

// ✅ 正確：UTC 日付として取り出す
const d = new Date(dateStr)
const day = d.getUTCDate()       // getDate() ではなく getUTCDate()
const month = d.getUTCMonth() + 1
const year = d.getUTCFullYear()

// ✅ toLocaleDateString も timeZone: "UTC" 必須
d.toLocaleDateString("ja-JP", { timeZone: "UTC", month: "short", day: "numeric" })

// ❌ 誤り：ブラウザ TZ に依存
const day = d.getDate()
d.toLocaleDateString("ja-JP", { month: "short", day: "numeric" })

対象: client component 内で Date オブジェクトを生成・操作する全コード。SSR（Node.js は UTC 環境）との整合性のために必須。

根本原因: 爬蟲が JST 時間を +00:00 として保存（tzinfo=timezone.utc）しているため、DB の 2026-06-13T00:00:00+00:00 は実際には JST 2026-06-13 09:00（問題なし）だが、scraper によっては深夜値（15:00 UTC = 翌日 00:00 JST）が混入する可能性がある。Client side では常に UTC で読む実装が最も安全。

Reference incident: 2026-05-12 — EventListClient.tsx / MovieWorksList.tsx の getDate() が JST ブラウザで 1 日ずれ → getUTCDate() + { timeZone: "UTC" } に修正。

Rule: 聚合站 scraper（ftip、prtimes、gnews、walkerplus 等）的 source_url 必須永遠保留聚合站自身的 URL。從文章中提取的第一方主辦方 URL 存入 official_url，不可覆寫 source_url。

正確分工：

• source_url = 聚合站頁面 URL（https://www.ftip-japan.org/NNN、https://prtimes.jp/...）— 資料溯源憑證
• official_url = 提取的第一方官方 URL（活動官網、Facebook event 頁、主辦方網站）；無法提取時為 None

常見提取模式（ftip content 中的 公式サイト 格式）：

_OFFICIAL_URL_RE = re.compile(
    r"公式サイト\s+(https?://\S+|[\w.-]+\.\w{2,}(?:/\S*)?)",
    re.IGNORECASE,
)

def _extract_official_url(self, content: str) -> str | None:
    m = _OFFICIAL_URL_RE.search(content)
    if not m:
        return None
    url = m.group(1)
    if not url.startswith("http"):
        url = "https://" + url
    return url.rstrip("。、）")

✅ 正確模式：

source_url = rss_link          # 聚合站 URL，永遠保留
official_url = self._extract_official_url(content)  # None 是合法值

❌ 反模式（已廢棄）：

# 用官方 URL 覆蓋 source_url — 破壞資料溯源 audit trail
source_url = self._extract_official_url(content) or rss_link

Reference incidents:

• 2026-05-10 commit ab771e2 — ftip.py 首次修正誤以「官方 URL 較有資訊量」讓 source_url 指向 www.taiwanprism.com，破壞 FTIP audit trail
• 2026-05-10 commit 7c34788 — 更正為正確模式：source_url=ftip-japan.org/699、official_url=taiwanprism.com，DB 事件 023dcbec 同步修正

M/D~D 多日範圍 — end_date 提取與跨月防護

Rule: 日期字串含 ~（如 8/30~31）表示多日活動，必須同時提取 start_date 和 end_date。

實作範例：

_END_DAY_RE = re.compile(
    r"(\d{1,2})/(\d{1,2})~(\d{1,2})(?![/])"  # M/D~D — (?![/]) 防止跨月假匹配
)

def _parse_date_range(self, text: str, year: int) -> tuple[date | None, date | None]:
    m = _END_DAY_RE.search(text)
    if m:
        month, start_day, end_day = int(m.group(1)), int(m.group(2)), int(m.group(3))
        return date(year, month, start_day), date(year, month, end_day)
    return None, None

跨月防護：(?![/]) 確保 ~ 後面不接 /。若接 /（跨月，如 3/10~5/31），跳過 end_date 提取，避免把月份誤解為日數。

正確/錯誤案例：

• 8/30~31 → start=8/30, end=8/31 ✅
• 3/10~5/31 → (?![/]) 命中，不提取 end_date ✅（正確放棄）
• 無 ~ → 僅提取 start_date，end_date=None ✅

Reference incident: 2026-05-10 — ftip.py 事件 023dcbec（台湾光譜 8/30~31）start_date 回退到 RSS pubDate，end_date 未設定（commit ab771e2）。

location_address 硬編碼城市名 — 反模式

Rule: 以城市名（"東京都"、"大阪"、"京都"）作為全國性組織的 location_address fallback 是反模式，必須禁止。

為何危險：

1. GPT annotator 信任 scraper 提供的非 null location_address（_ai_or_existing() 只在值為 null 時才詢問 GPT）
2. 錯誤城市名寫入 DB 後，即使活動實際在其他縣市，location_prefectures 也會被錯誤推斷
3. 讓使用者在地圖/篩選功能中看到錯誤地點

正確做法：

# ✅ 正確：無法確定地址時設 None
location_address = self._extract_venue_address(content) or None

# ❌ 錯誤：以組織所在城市作為全國活動的 fallback
location_address = "東京都"  # 全國性組織的活動可能在任何地方

例外（允許硬編碼）：scraper 專屬於單一地點的場館（固定影院、固定展覽館）時，可硬編碼該場館地址。

Reference incident: 2026-05-10 — ftip.py location_address = "東京都" 導致台湾光譜（京都活動 〒603-8163 京都府...）被錯誤標為東京（commit ab771e2）。

note_creators レポート記事・結果発表 — report カテゴリ自動注入パターン

Rule: note_creators 來源的レポート記事には必ず三つの問題が発生する。検出時は以下の三点を一括修正し、FC 鎖定すること。

三重問題（全件に発生）：

1. start_date = 記事公開日（≠ 活動日）：記事が公開された日が自動的に start_date に入り、実際の開催日（1〜数ヶ月前）と異なる。本文中の「〇月〇日開催」「〇月〇日に参加」等から正しい日付を特定すること。
2. location = 主催者の日本拠点：主催者が日本に拠点を持つ場合、annotator がその住所を location として設定する。実際の活動場所（特に台灣で開催の場合）を確認し、location_address / location_prefectures を null に修正。
3. 接頭辭 + report category 欠如：annotator.py の _REPORT_TRIGGER_RE が自動注入する（commit 1e00933 + d0eb93e 以降）。検知キーワード：レポート・レポ・報告・記録・アーカイブ・recap・行ってきた・観てきた・見てきた・鑑賞レポ・結果発表。注入時 ja 名称がすでに 【...】 で始まる場合は 【レポート】 を重ねない（_inject_report_prefix の二重括弧ガード）。既存 annotated events には Supabase SQL で report を追加後 python annotator.py --backfill-report-prefix を実行。

FC 鎖定対象（計 9 項）：start_date、location_name、location_address、location_prefectures、name_ja、name_zh、name_en、categories

自動化範囲（annotator.py commit 1e00933 以降）：report category 注入 + 三語接頭辭注入は自動処理。start_date / location の修正は human review 必須。

Reference incident: 2026-05-10 — event a7a05be6（台湾薬膳文化体験レポート）start_date=2026-05-08（記事日）→ 修正後 2026-04-21（活動日）；location_name=台湾華語文学習センター大阪弁天町（主催者拠点）→ 修正後 台北医学大学（活動場所、台灣）。

RSS/Podcast scraper-specific

• Normalize & in RSS link text before regex: RSS <link> text nodes may contain HTML-entity-encoded & even after XML parsing (double-encoded by the origin server). item.find("link").text can return "...?uid=4&pid=103701". Any regex on the raw text will miss &pid=. Always normalize: link = link_raw.replace("&", "&") before extraction. Apply to both source_url construction and any _extract_pid()-style function. (Incident: rti_jp 0 events, 2026-05-14.)
• XML Element truth value — always use is not None: if element: on an xml.etree.ElementTree Element is always True (DeprecationWarning since Python 3.8). Write element is not None and element.text instead.
• STALE_DAYS guard for podcast/RSS scrapers: For scrapers that loop over a curated list of program IDs, check the latest episode's pubDate before iterating all items. If it exceeds STALE_DAYS (e.g. 90), the program is discontinued — skip to avoid a full-page fetch that returns 0 events:

  STALE_DAYS = 90
  latest_pub = _parse_pubdate(items[0].find("pubDate").text)
  if latest_pub and (now - latest_pub).days > STALE_DAYS:
      logger.info("rti_jp: id=%s latest episode %dd old — discontinued", pid, age)
      continue
  

• LOOKBACK_DAYS must match broadcast frequency: Weekly programs → 14d is sufficient. Monthly programs → 60d minimum. If a program's cadence is unknown, default to 60d.

Peatix-specific

• Blocked organizer patterns live in BLOCKED_ORGANIZER_PATTERNS in peatix.py — always check before adding new title-based blocks.
• 台東区 false positive: 台東 in TAIWAN_KEYWORDS can match the Tokyo ward 台東区. Use _TAIWAN_KW_NO_TAITO guard list.
• Detail text blocks are primary for venue/time: Parse LOCATION / 場所 and DATE AND TIME / 日時 blocks before CSS fallback. Detect Online event / オンライン before any physical address fallback, reject generic address candidates (Japan, 東京都, ward-only fragments), and write business_hours from the text block or body labels such as 時間：14:00-15:30.
• Price selector label-only fallback: If .ticket-price or [class*='price'] returns only a generic label (料金, 参加費, チケット, etc.), treat it as empty and read body lines that start with a known price label plus a price/free signal. Do not extract unlabeled amounts from descriptive body copy.
• Locale-prefixed URLs must be normalized before page.goto(): Peatix redirects to /us/event/{id} or /jp/event/{id} depending on browser locale. Strip the prefix in both the collection stage (_search_events/_scrape_group_events) AND _scrape_detail() so source_url is always https://peatix.com/event/{id}. (Incidents: peatix e9c6f80b 2026-05-17, 55d766ae 2026-05-19.)
• inner_text() length guard for short-string fields: Playwright inner_text() on a group anchor or any interactive DOM element can return the entire page content (e.g. starting with "Translate this page...") instead of just the element text. Always add a length guard for fields expected to be short:
  if _txt and len(_txt) <= 100
  Without this guard, a multi-thousand-character blob silently passes through to organizer_name, performer, location_name etc. Apply to both primary extraction path and any fallback path. The threshold should be ≈2–3× the expected maximum (organizer/location names: ≤ 100). (Incident: peatix organizer f839508, 2026-05-19.)
• "Extract but not store" anti-pattern: When a field is extracted for one purpose (e.g. blocklist checking), ensure it is also passed to Event(). Forgetting to include it in the constructor causes the field to always be null in DB — silent failure, no error. Before submitting a PR, cross-check all extracted variables against Event() constructor arguments. Pattern: organizer=organizer_name or None. (Incident: peatix organizer_name always null — commit 24198d0, 2026-05-19.)
• Three-layer organizer architecture:
  • Layer 1: keyword search (peatix.com/search?q=...)
  • Layer 2: hardcoded organizer list in _ORGANIZERS — never remove; serves as backup if DB changes
  • Layer 3: DB-driven dynamic load via _load_db_organizers() — queries research_sources WHERE agent_category='peatix_organizer' AND status='implemented'
• Layer 3 expansion rule: When extending Layer 3 to a new platform, use a platform-specific agent_category (e.g. peatix_organizer). Do NOT reuse note_creator or generic names.
• Group page scraping: _scrape_group_events() fetches peatix.com/group/{group_id}/events; group_id extracted from source_profile.group_id or URL path.
• Validation: python discovery_accounts.py --dry-run --slot 3 to verify Peatix slot without DB writes.
• ⚠ React SPA 遅延レンダリング問題: Peatix は React SPA。networkidle 発火後も .event-description 内容が数十ms 遅延してレンダリングされる場合があり、description_ja が None → raw_description が日付 prefix のみになる。
  • 検出: raw_description の長さが 50 字未満かつ内容が 開催日時: のみ → 「汚薄 raw_description」と判定。
  • 対処フロー: Playwright で再取得 → raw_description パッチ → annotation_status = 'pending' → annotator.py --source-ids <source_id> で手動実行。
  • (Incident: peatix ee17c509 2026-05-30)
• performer vs organizer 区別: Peatix ページの「By ‹名前›」= organizer（主催者）。イベントを実施するアーティスト/動作者 = performer。GPT が両者を入れ替える可能性があるので、日本語淡化語（「夫婦」「ユニット」など一般名詞）が performer に入っていたら手修正 + FC lock。(Incident: peatix ee17c509 performer='夫婦' → 'Floti Studio' 2026-05-30)
• performers 一般名詞ガード: performers に「夫婦」「カップル」「グループ」等の一般名詞が入っていたらアーティストの固有名（ユニット名・人名）に修正 + FC lock が必須。annotator は raw_description のカタカナ/漢字をそのまま取り込むため、一般名詞を固有名詞と誤認することがある。(Incident: peatix ee17c509 performers=['夫婦'] → ['Floti Studio'] 2026-05-30)
• 英語ブランド名 → performer_zh/en は翻訳不要: Floti Studio 等の英語固定名称は performer_zh も performer_en も同じ値を設定。GPT は英語名を繁体中文に翻訳しようとして null を返すことがある。手動補完 + FC lock が必要。(Incident: peatix ee17c509 2026-05-30)
• 英語ブランド名 → organizer_zh/en も同様: organizer 値が英語固定商標の場合、organizer_zh/en も翻訳不要—同じ値を FC lock。翻訳しようとした GPT が （AI翻譯） マーカー付きで格納する場合もある。判定基準: organizer 値の文字が全て ASCII / アルファベット → organizer_zh/en = organizer。(Incident: iwafu a4442567 QUEEN SHOP 2026-05-31)
• 専用イベントページ非存在時の URL 設定: Peatix が source_url の場合、SNS リンクの設定先は次のルールに従う:
  • 演者の Instagram/SNS → performer_url（単一演者）または performer_urls[]（複数演者、インデックスは performers[] と対応）
  • 主催者の SNS/公式サイト → organizer_url
  • official_url = 専用イベントページ URL のみ。SNS を official_url に設定するのは非推奨（performer_url / organizer_url を優先）。専用ページが存在しない場合は official_url = null。
  • ⚠ 旧ルール廃止: performer_url 新設（migration 078、2026-05-30）以前は演者 Instagram を official_url に設定していたが、現在は performer_url に設定し official_url は null のままにする。
  • (Incident: peatix ee17c509 旧: official_url='https://www.instagram.com/flotistudio/' → 新: performer_url='https://www.instagram.com/flotistudio/' + official_url=null 2026-05-30)

iwafu-specific

• Global-tour false positive: If description contains 台湾など世界各地 / 全国各地.*台湾 etc., the event is a nationwide/global tour where Taiwan is just one stop. Reject it — it is NOT a Taiwan-themed event. The _GLOBAL_TOUR_PATTERNS regex in iwafu.py implements this guard.
• Title-level block: Known IP series (e.g. リアル脱出ゲーム×名探偵コナン) must be blocked by _BLOCKED_TITLE_PATTERNS in _scrape_detail before the page load — this catches all tour stops as new source_ids appear. Add new entries here when a series is confirmed non-Taiwan-themed.
• Permanent IP series block: For series where ALL events are non-Taiwan-themed (e.g. 名探偵コナン), add the IP name to _BLOCKED_SERIES. Checked on BOTH card title (pre-load, fast-reject) AND h1 title (post-load). Card titles from search results can be truncated, so the pre-load check alone is not sufficient.
• Taiwan relevance criterion: Taiwan must be the theme or primary focus, not just one venue on a multi-city tour.
• organizer_url enrichment: iwafu ソースページは主催者の公式サイト URL を常に含むわけではない。ブランド商標の場合は raw_description 内の extract_first_party_url() で抽出を試みるか、公式サイトを手動で FC 設定すること。organizer_url を設定すると UI に「主催者名 ↗」リンクが自動表示される。(Incident: a4442567 QUEEN SHOP 2026-05-31)
• 小売 / モールイベントの business_hours: デパート・ショッピングモールの定常営業時間はイベント固有ではなく venue-level データ。venues テーブルに business_hours カラムが存在しないため、現状は手動 FC 修正で対応。将来的には venues.business_hours カラム（migration 必要）+ enrich_location.py から自動取得する設計。UI 側は event.business_hours 存在時の表示に既対応済み。
  • ⚠️ 必ず公式 venue サイトを確認してから FC 設定。推測・常識での設定は誤りの原因（Incident: a4442567 ルミネエスト 11:00〜22:30 と推測設定 → 実際は平日 11:00〜21:00 / 土日祝 10:30〜21:00 だった）。
  • 参考: ルミネエスト新宿（2026-05）ショッピング: 平日 11:00〜21:00 / 土日祝 10:30〜21:00、レストラン: 11:00〜22:00。
• After adding a scraper filter, always audit the DB: run ilike("raw_title", "%keyword%") to find existing records that should also be deactivated. The filter only prevents future inserts.
• Hard delete vs deactivation: If an IP series is confirmed permanently non-Taiwan-themed, hard delete (table.delete().eq("id", eid)) rather than just deactivating. Deactivated events remain accessible via direct URL unless the event page also checks is_active.
• location_name / location_address: Extract from 場所[：:]\s*(.+?)(?:\n|交通手段|Q&A|https?://|$) in main_text.
  • location_name = the venue name captured from 場所：.
  • location_address = search the surrounding text with _ADDR_RE (matches 〒 or prefecture+city+street pattern). If a real address is found AND it differs from the venue name, use it; otherwise set None. NEVER set location_address = location_name — identical values are flagged by auto_qa_address_is_venue_name and violate the Sub-Venue Parent Address Rule (sub-spaces like SC 広場 need the parent building's address, not the sub-space name).
  • Fall back to card.prefecture for location_address only when the 場所： label is absent. Never store bare prefecture names (e.g. "東京") as the address.

Venue / live house scrapers — management post blocklist

For scrapers on live houses / venue sites (e.g. moonromantic), the site publishes both public event listings and internal venue-management posts (rental announcements, wedding inquiries, system maintenance). These are NEVER Taiwan-related.

• Always add _BLOCKED_POST_PATTERNS at the module level for known management post types.
• Apply the block BEFORE the Taiwan keyword check — it avoids loading the detail page unnecessarily.
• Apply twice: once on page_text first-line (fast-reject) and once on the confirmed title (second-pass, catches nav-renders-first edge cases).
• Known patterns to always block for live venue sites:
  • RENTAL / PRIVATE RENTAL / RENT (venue hire)
  • 場所貸し / 会場貸し (Japanese venue rental)
  • WEDDING (if venue offers wedding venue hire)
• Example:

  _BLOCKED_POST_PATTERNS = re.compile(
      r"\bRENTAL\b|PRIVATE\s+RENTAL|\bRENT\b|場所貸し|会場貸し",
      re.IGNORECASE,
  )
  

eiga_com-specific

• Per-theater granularity: One event per theater per movie. source_id = eiga_com_{movie_id}_{theater_id}. Each daily run upserts and updates end_date to the last date in the current week's schedule.
• URL flow: /movie/{id}/theater/ → area links /movie-area/{id}/{pref}/{area}/ → div.movie-schedule[data-theater] + .more-schedule a.icon.arrow → /movie-theater/{id}/{pref}/{area}/{theater_id}/ (address).
• a.icon.arrow is the all-schedule link: The .more-schedule div has 3 links — copy (/mail/), print (/print/), all-schedule (bare /{theater_id}/). Always use a.icon.arrow; the first a[href*='/movie-theater/'] is the /mail/ link.
• Address extraction: Use table.theater-table th:contains("住所") + td on the theater page. Call a_tag.decompose() on all <a> children before get_text() to strip "映画館公式ページ". Never use page-wide address regex — JS code can contain 東京都 fragments.
• Fallback event: If no area links found, emit one movie-level event with source_id = eiga_com_{movie_id} and location_name=None.

Thin Pointer Article Detection — General Rule (all scrapers)

任何 scraper 遇到「薄內容指引文」時，應主動抓取外部 ref URL 補充 raw_description。

偵測條件（兩者同時成立）：

1. len(body_text) < N（各 scraper 自行設定閾值，koryu 使用 600 chars）
2. body_text 包含非本站的外部 HTTP URL

處理流程：

1. 提取外部 URL（正則排除本站 domain）
2. 呼叫 fetch_ref_text(ref_url) — 已在 base.py 實作，直接 import 使用
3. 追加到 raw_description：[参照ページ ({ref_url})]:\n{ref_text}
4. date_prefix 改用 記事投稿日: 而非 開催日時: — 避免 GPT 把文章發布日當活動日

薄內容指引文的典型特徵：

• 組織公告：「弊社は XX イベントを後援します。詳細は URL をご確認ください。」
• 新聞式 RSS 摘要：只有標題＋一句描述＋原文連結
• 公募通知：只說明有公募，所有細節在外部網站

通用函數：from .base import fetch_ref_text

• fetch_ref_text(url, max_chars=3000) — requests + BeautifulSoup，selector 優先序：main > article > body
• 回傳 None 表示失敗或內容 < 200 chars

Annotator-side thin content detection（annotator.py）：

• Playwright 文章 fetch 觸發條件：not start_date OR len(raw_description) < 400 chars
• 常數：_GNEWS_THIN_DESC_CHARS = 400
• 實作：inner 函數 _gnews_needs_article_fetch(e) — gnews_needs_fetch 計數與 per-event trigger 統一使用此函數
• 適用來源：目前僅 google_news_rss（使用 Playwright 跟進 Google News redirect）
• 注意：手動修正 start_date 後重新 annotate 時，若 raw_desc 仍短，fetch 仍會觸發 → 確保 GPT 看到完整文章
• 原則：「start_date 有值」不代表「描述足夠豐富」，薄內容偵測邏輯應在 scraper 和 annotator 兩層都套用

Thin Content Detection — Applicability Matrix

Source	Scraper-side fix	Annotator-side fallback	Reason
google_news_rss	pub_date anchor + Playwright (in annotator)	✅ _GNEWS_THIN_DESC_CHARS=400, Playwright	RSS snippet only; Google redirect URL
koryu	fetch_ref_text() for pointer articles	— (scraper handles)	Pointer articles < 600 chars + external URL
nhk_rss	pub_date anchor + fetch_ref_text(article_url)	✅ _NHK_THIN_CHARS=400, requests-based	RSS snippet always < 200 chars
doorkeeper	N/A	N/A	API returns full description
connpass	N/A	N/A	API returns full description
iwafu	N/A	N/A	Visits detail page
arukikata	N/A	N/A	Fetches full article (BS4)
peatix	N/A	N/A	Visits detail page (Playwright)
taiwan_cultural_center	N/A	N/A	Visits detail page (Playwright)
hakusuisha	skip_tags HTMLParser + 8000 char limit in _fetch_detail_text_fallback()	✅ thin-content rescue when source_name == "hakusuisha" and 日時 absent in raw_description	JS/nav content consuming 2000-char budget; ■日時: typically appears after char 2000; raised from 4000→8000 (commit a0292a2)
taioan_dokyokai	N/A	N/A	Visits detail page (Playwright)
taiwan_kyokai	N/A	N/A	Visits detail page (Playwright)
taiwan_festival_tokyo	N/A	N/A	Structured widget, not article-based
ide_jetro	N/A	N/A	date_prefix fix sufficient

Rule: Only apply thin-content detection when the scraper stores a snippet (RSS/headline) and the full content lives at a separate URL. API-based and detail-page-visiting scrapers are inherently complete.

Auto-generated Scraper Date Accuracy

auto_generate が生成した FIELD_SELECTORS["date"] が指すセレクタは、記事公開日（publication date） を指している場合がある。プロモーション審査時に必ず確認すること。

確認ステップ

1. listing page の HTML を実際に開き、FIELD_SELECTORS["date"] のセレクタが何を取得するか確認する（span.note、.date、time[datetime] 等）。
2. 取得した値が「記事公開日」か「活動日」かを目視確認（YYYY.MM.DD 形式は公開日の可能性が高い）。
3. 活動日が detail page の 日時： / 開催日時： ラベルに存在する場合は、listing page の selector を使わずに detail page から抽出すること。

活動日が detail page にある場合の実装パターン

# _extract_event_dates(detail_text, card_year) パターン（hakusuisha.py を参照）
# 対応パターン1: 2026年3月20日・21日（同月 ・ 複数日）
# 対応パターン2: 2025年11月23日...／24日（同月 ／ 複数日）
# 対応パターン3: 2026年1月10日 / 2026年1月11日（完全日付2つ）

raw_description プレフィックスルール

• 日時 ラベルあり → 開催日時: YYYY年MM月DD日 プレフィックス（GPT annotator への明確なシグナル）
• 日時 ラベルなし（公告・お知らせ文）→ （記事投稿日: YYYY年MM月DD日） 年号アンカー

対象

auto_generate で生成されたすべての scraper のプロモーション前に FIELD_SELECTORS["date"] を人工審査すること。Playwright ベースのスクレーパー（detail page を訪問する）でも、listing page の date selector が残っている場合は要確認。

Reference incident: 2026-05-04 hakusuisha FIELD_SELECTORS["date"] = "span.note" → 記事公開日を取得（活動日ではない）（commit b3708e1）。

Auto-generated Scraper — Body Text Limit

Rule: auto-generated scraper の body.inner_text() および HTTP fallback のスライス上限は 最低 8000 字元 を使うこと。4000 字元では nav / header ノイズに予算を消費され、イベント本文の ■日時: / 会場: / 主催: が切り捨てられる。

# ❌ 4000 は nav のある site では不足
full_description = body.inner_text()[:4000]

# ✅ 8000 以上を推奨
full_description = body.inner_text()[:8000]

Incident: hakusuisha.py — nav menu が 2000+ 字消費し、■日時： を截斷点の外に押し出した（commit a0292a2）。

Self-injected Prefix Interference

Rule: scraper が raw_description 先頭に 開催日時: YYYY年MM月DD日 等のプレフィックスを追加する前に、日時/会場/主催の regex 抽出を完了させること。

問題：_JITSU_RE = re.compile(r"日時[:：]") は 開催日時: にもマッチする。scraper が自己注入したプレフィックスを先に検索すると、group(1) がプレフィックスの日付テキスト（時間なし）になり、後続の _TIME_RE が正文の時間 (HH:MM〜HH:MM) を永遠に見つけられなくなる。

# ❌ Bad: プレフィックスを先に加えてから検索
raw_description = f"開催日時: {date_str}\n\n{full_description}"
m = _JITSU_RE.search(raw_description)  # → マッチするのはプレフィックスの "開催日時:"

# ✅ Good: 検索を先に行い、プレフィックスは最後に加える
m = _JITSU_RE.search(full_description)  # または _TIME_RE で直接時間を検索
# ... 抽出完了後 ...
raw_description = f"開催日時: {date_str}\n\n{full_description}"

代替解法：日時[：:] の代わりに [■◆●▼]\s*日時[：:] で検索（行頭の記号を要求）するか、_TIME_RE（\d{1,2}:\d{2} を含む時刻パターン）で full_description を直接検索して前綴を回避する。

Incident: hakusuisha.py — _JITSU_RE.search() が 開催日時: 2026年4月26日 プレフィックスにマッチし、_TIME_RE が正文の 14:00〜16:00 を見つけられなかった（commit a0292a2）。

Auto-Generate Scraper — Date Field Accuracy Check

FIELD_SELECTORS["date"] が正確なイベント開催日を返すか検証する手順：

1. ブラウザで listing ページを開き、カード上の日付テキスト要素を inspect
2. その日付が「記事投稿日」「更新日」「公開日」のラベルに付いていれば ⚠️ 要注意
3. detail ページの本文に 日時： / 開催日： / 期間： ラベルがあればそちらを使う
4. 修正パターン：
   • _JITSU_RE = re.compile(r"[■◆●▼]?\s*日時[：:]\s*(.{5,150})", re.MULTILINE)
   • _FULL_YMD_RE = re.compile(r"(\d{4})年(\d{1,2})月(\d{1,2})日")
   • _END_DAY_RE = re.compile(r"[・/／]\s*(\d{1,2})日")
   • 参照実装：scraper/sources/hakusuisha.py の _extract_event_dates()
5. end_date も同時に設定すること（「・DD日」パターンで終了日が取れる場合が多い）

---

学術場地括弧地址模式

日本學術研討會的 location_name 有時包含完整郵遞區號地址於括號中：

南山大学 Q棟103教室 (〒466-8673 名古屋市昭和区山里町18)

scraper 的 _extract_venue() 應優先識別 [（(](〒\d{3}-\d{4}...) 模式，提取為 location_address 並從 location_name 中去除括號部分。 已實作：scraper/sources/taiwanshi.py 作為參考實作。

note.com RSS 截斷處理

note.com RSS <description> 約在 140 字截斷，末尾可能為「続きをみる」（endswith，非 equals）。 當 _is_truncated(plain_desc) 為 True 時，_parse_item() 呼叫 _fetch_article_content() 取得全文（JSON-LD articleBody / description / BeautifulSoup p fallback）。 已實作：scraper/sources/note_creators.py → _fetch_article_content() helper。 無需 Playwright，標準 requests.get() 即可。

Note Creator Source Guard（二手聚合源截斷修復模式）

問題模式

• note.com RSS preview 以 ...続きをみる 結尾（endswith，非 equals）→ 舊 truncation guard plain_desc in ("続きをみる","") 漏判 → _fetch_article_content 永不呼叫
• 全文中含「🔗詳細・申込み」embedded official URL 未萃取
• 投稿者 creator DB metadata location（如教室地址）套到外部活動公告 → _auto_lock_location 自動 FC 鎖定錯誤地點

修復設計（note_creators.py + base.py）

1. _is_truncated(text): text.endswith("続きをみる") or len(text) < _NOTE_THIN_CHARS(120)
2. extract_first_party_url(body, exclude_hosts) in base.py（共用）: 從全文萃取 official URL，排除報名平台（peatix/forms.gle/google/linktr.ee）；優先「🔗詳細/申込/公式」標記附近 URL
3. A2b: 當 official_url 為外部機構域（非報名平台）→ 設 effective_location_name=None 抑制投稿者 metadata location，讓 _auto_lock_location 跳過上鎖（if not event.location_name: continue）
4. tw_insecure_domain(url) in base.py（共用）: host endswith .edu.tw/.gov.tw → True（fetch_ref_text verify=False）
5. fetch_ref_text(url, verify_ssl=True) in base.py: 新增 verify_ssl 參數；既有 caller 預設 True，行為不變
6. A3 fail-safe: ref fetch 失敗 / < 200 字 → fallback 回 note 全文，永不阻斷活動建立
7. OWASP: verify=False 僅限 .edu.tw/.gov.tw 白名單域

LOCATION GATE 說明（annotator 不停用主事件）

annotator 的 LOCATION GATE（SYSTEM_PROMPT）是給 GPT 的指示文字，NOT Python code。 主事件 update_data 完全不含 is_active——re-annotate 不會停用主事件。 LOCATION GATE 僅影響 selection_reason 品質。正確設定 study_abroad/tourism 等 category 是資料正確性問題，非「過 gate 求存活」。

DB 修復模式（FC-first-then-annotate）

1. FC 鎖定所有結構欄位（category/event_form/official_url/organizer/location_*）
2. 寫入 enriched raw_description（note 全文 + 原始頁摘要）後設 annotation_status=pending
3. 跑一次 annotator（不帶 --id，保留 P0 non-null 保護）自動生成三語；FC 欄位被還原不被覆寫

note.com creator 追加手順（2 ステップ必須）：

1. CREATOR_META に {"slug": "<creator_slug>", "category": "<category>", "location": "<prefecture>"} を追加
2. DB research_sources の対応行を status=implemented に更新（scraper_source_name = 'note_creators' も確認） 事前確認：python main.py --dry-run --source note_creators 2>&1 | grep "events found" で件数増加を確認してから commit。

---

enrich_location.py — GPT Output Guard

enrich_location.py 使用 GPT 補充缺少的地址。接收 GPT 回傳後，寫入 DB 前必須套用以下 guard：

1. Identical address guard（Rule 6）：if addr.strip() == venue_name.strip(): skip + log warning。address == venue_name 是提取失敗的確定標誌（GPT 只是複製了場地名）。
2. Sub-venue address rule（Rule 7）：子場地（如 ○○ビル2階、○○カフェ（寺内））需用親設施的地址，不得用子場地名作為 address。
3. SELECT location_name：query 必須 SELECT location_name，才能執行 identical address guard。
4. 雙重防護原則：SYSTEM_PROMPT 規則（讓 GPT 返回 null）+ 程式碼 guard（兜底攔截）都必須存在；不能只靠 GPT 自律。

# enrich_location.py — 寫入前 guard 範例
if location_address and location_address.strip() == (location_name or "").strip():
    logger.warning("SKIP: address == venue_name for event %s (%s)", eid, location_address)
    continue

Reference incident: 2026-05-05 — GPT extracted 仙六屋カフェ from 会場：仙六屋カフェ as address → identical guard added (commit 628e3e7).

---

koryu-specific

• location_address fallback: _extract_location_address() searches for 所在地/住所 sections. When absent (common for 後援-type posts), set location_address = None — do NOT fall back to the venue name. The annotator will fill the address via PARENT VENUE ADDRESS RULE. Old pattern or (venue if venue else None) was removed (commit 9d6e0fc) because it echoed venue name as address, blocking annotator correction.
• 404 on old koryu URLs: When a koryu event page returns 404, main_text will be a redirect message with no venue section. _extract_venue returns None, so location_address is also None. This is acceptable — the event is stale.
• Single-day end_date: Taiwan Kyokai events are single-day ceremonies/lectures. For koryu-only events, set end_date = start_date at the end of _extract_event_fields.
• Publish-date false positive: The page body starts with the article publish date (2026年4月20日) before the actual event content. Do NOT rely solely on the generic YYYY年MM月DD日 fallback — it will pick up the publish date if no structured 日時： field exists.
• DOW-qualified date extraction: Dates like 5月16日（土） (with day-of-week) are actual event dates. Extract these BEFORE the generic fallback, then infer the year from the nearest 20XX年 in the text.