Qingdao needs the same airport-settlement path as the other Wunderground-backed APAC cities, so the registry, aliases, timezone, prewarm, official links, market focus, and tests now point to ZSQD / Qingdao Jiaodong International Airport.
Constraint: User supplied Wunderground Qingdao/ZSQD settlement URL.
Rejected: Add a partial registry-only entry | it would show in APIs without frontend links, prewarm coverage, or alias support.
Confidence: high
Scope-risk: narrow
Reversibility: clean
Tested: pytest tests/test_country_networks.py tests/test_web_observability.py::test_cities_endpoint_includes_new_wunderground_cities -q
Tested: npm run build
Not-tested: Live Wunderground fetch for ZSQD in production.
The decision card now exposes deterministic guard state, data freshness, AI readiness and market sync directly in the card header so users can understand whether they are looking at fresh evidence, a fallback, or a stale/exception case before reading the full explanation.
Constraint: Keep the first useful read available while DeepSeek airport/HKO details are still streaming.\nRejected: Add another expanded evidence panel | header-level badges are faster to scan and avoid increasing card depth.\nConfidence: high\nScope-risk: narrow\nReversibility: clean\nTested: npm run build\nNot-tested: Browser visual QA on production data.
The scan terminal service had grown into a 3.5k-line file that mixed endpoint orchestration, AI provider calls, fallback copy, JSON repair, and deterministic evidence guards. This extracts the city-AI helper layer into a focused module while preserving the old private names through imports for existing tests and callers.
Constraint: Keep behavior unchanged after the previous evidence-guard fixes and avoid a broad service rewrite.
Rejected: Split every scan-terminal concern at once | too much regression risk for this maintenance pass.
Confidence: high
Scope-risk: narrow
Tested: pytest tests/test_web_observability.py -q
Tested: npm run build
DeepSeek can return a polished city forecast that conflicts with already-computed stale-observation, observed-break, or peak-window evidence. The completion path now carries the deterministic fallback guard state and overwrites only the critical fields when provider text or numbers contradict those local facts.
Constraint: Airport-read latency optimization keeps provider output narrow, so backend completion remains the authority for final highs and evidence conflicts.
Rejected: Trust provider final wording when present | it can reintroduce stale METAR anchors or miss observed high breaks.
Confidence: high
Scope-risk: narrow
Tested: pytest tests/test_web_observability.py -q
Tested: npm run build
City-card fallback reads now stop using stale METAR or official observations as strong live anchors. A stale observation no longer forces high/low revisions, and both backend and browser AI cache keys include the observation fingerprint so updated report times, receipt times, temperatures, or stale status invalidate old AI text.
Constraint: Cached city AI reads must not survive a material observation update
Rejected: Let stale METAR trigger observed-break revisions | stale reports can be older than the active temperature path
Confidence: high
Scope-risk: moderate
Tested: pytest tests/test_web_observability.py -q
Tested: npm run build
Fallback city-card reads now distinguish three cases that previously collapsed into the generic fast-evidence copy: observed highs above the model path, observed highs still lagging after the peak window, and low observations before the peak window that should wait for confirmation rather than down-revise immediately. The same pass removes three unused private helpers from the scan terminal service.
Constraint: Fallback output must be useful before the full AI airport-bulletin read returns
Rejected: Treat any low latest METAR as a down-revision | early-day observations can be below the forecast before the peak window
Rejected: Keep unused helper wrappers | they were unreferenced and added noise to an already large module
Confidence: high
Scope-risk: moderate
Tested: pytest tests/test_web_observability.py -q
Tested: npm run build
Fast evidence mode should not say DEB and models support the center when the latest METAR has already exceeded that center or the model upper edge. The fallback now treats the live observation as a lower bound for the daily high and explains the upward revision pressure.
Constraint: Fallback output must remain useful before the full AI bulletin read returns
Rejected: Keep the original DEB center until AI completes | it can be lower than an already-observed temperature
Confidence: high
Scope-risk: narrow
Tested: pytest tests/test_web_observability.py::test_city_ai_fallback_revises_up_when_latest_metar_breaks_above_models tests/test_web_observability.py::test_city_ai_fallback_reasoning_identifies_fast_evidence_mode tests/test_web_observability.py::test_city_ai_stream_request_only_asks_provider_for_observation_read -q
Tested: npm run build
The city card only needs the provider to interpret the latest METAR or official observation. Deterministic fields such as the high-temperature center, model cluster note and fallback risks are already available server-side, so the stream request now asks DeepSeek for only the observation read and concise reasoning.
Constraint: City cards still need a complete payload for both Chinese and English UI modes
Rejected: Keep generating the full decision schema in the stream | too much model output for every card
Rejected: Retry failed streams by default | it can double latency and the fallback can use partial streamed text
Confidence: high
Scope-risk: moderate
Tested: pytest tests/test_web_observability.py::test_city_ai_stream_request_only_asks_provider_for_observation_read tests/test_web_observability.py::test_city_ai_fallback_reasoning_identifies_fast_evidence_mode tests/test_web_observability.py::test_city_ai_partial_json_trims_dangling_taf_clause tests/test_web_observability.py::test_city_ai_schema_completion_trims_dangling_taf_clause -q
Tested: npm run build
The city decision fallback path is generated when the full DeepSeek city-airport read has not completed, so the reasoning copy now labels the state as fast evidence mode instead of saying the AI read is normal.
Constraint: Fallback output may use only DEB, model cluster, and latest observation evidence
Rejected: Keep 'AI read normal' wording | it implies a completed AI interpretation when the fallback path is active
Confidence: high
Scope-risk: narrow
Tested: pytest tests/test_web_observability.py::test_city_ai_fallback_reasoning_identifies_fast_evidence_mode tests/test_web_observability.py::test_city_ai_partial_json_trims_dangling_taf_clause tests/test_web_observability.py::test_city_ai_schema_completion_trims_dangling_taf_clause -q
The prior label said the weather decision layer had no market price connected, which could be read as a broken market integration. The card now says weather-first read with market prices shown separately.
Constraint: Market price layer is already rendered below the weather decision band
Rejected: Keep 'no market price input' | accurate internally but misleading in user-facing Chinese copy
Confidence: high
Scope-risk: narrow
Tested: npm run build
Not-tested: Visual screenshot review
City AI can return a partially streamed JSON string when the provider truncates output. The fallback previously kept an unfinished clause such as '但TAF显示', which made the forecast explanation look broken even though earlier evidence was usable.
Constraint: Provider JSON can be truncated after useful fields have already streamed
Rejected: Drop all partial AI text | would lose valid METAR interpretation already returned before truncation
Confidence: high
Scope-risk: narrow
Tested: pytest city AI truncation regression tests
Tested: npm run build
Not-tested: Live DeepSeek provider response
The calendar local-time and AI airport-read fixes are a numbered product release rather than a temporary snapshot, so the changelog and package/version metadata now use 1.5.5 consistently.
Constraint: Existing snapshot tag was already pushed before the numbered release correction
Rejected: Keep snapshot label in changelog | user clarified this should be the 1.5.5 version
Confidence: high
Scope-risk: narrow
Tested: Reviewed git diff for CHANGELOG, VERSION, frontend package metadata
Not-tested: No runtime tests; metadata-only version correction
The release snapshot is no longer unreleased, so the changelog now names the published calendar-local-time tag and records the AI wording and actionable-window behavior.
Constraint: Existing snapshot tag was already pushed before this documentation correction
Confidence: high
Scope-risk: narrow
Tested: Documentation-only change reviewed with git diff
Not-tested: No runtime tests; changelog-only update
2569718930@qq.com