[Chore] 노선 topology 신선도 정책을 P1D에서 P7D 만료 안전망으로 전환 by AquilaXk · Pull Request #3024 · AquilaXk/easysubway

AquilaXk · 2026-10-02T15:23:32Z

작업 배경 / Summary

Problem: 노선 topology 원천(route_graph_topology 클래스: 수도권 topology, Korail 광역 시간표 파일, 광주·부산·대전·대구 1~3호선 topology, 인천 역정보)의 재검증 주기가 P1D입니다. 그래서 원천을 매일 다시 수집·등록하지 않으면 팩이 만료됩니다. 첫 전국 팩(releaseSequence 124)도 수집 하루 뒤인 2026-10-03T06:03:36Z에 만료됩니다. 상용 지하철 서비스는 개통·역명 변경·시간표 개정 같은 이벤트가 있을 때 topology를 갱신합니다. 업계에서 공표된 "30일" 같은 표준 주기도 없습니다.
Outcome: QA 승인(2026-10-02, "전부 승인")에 따라 topology 신선도를 이벤트 기반 갱신과 P7D 만료 안전망으로 바꿨습니다. 재검증이 일주일 내내 실패하면, stale 데이터를 조용히 제공하지 않고 만료로 막습니다. 일일 재확인 주기(monitoring.manualCheckCadence, scheduledPipeline.cadence = P1D)는 그대로 둡니다. data 레포는 이 PR이 병합된 뒤 별도 PR에서 lock pin을 올립니다([Fix] data 신선도 계약을 data 레포 정책과 동기화해 release 신선도 판정 누락 해소 #3023 → data#887과 같은 절차).

작업 내용 / Changes

release/product-gates/datapack-freshness-sla.json: route_graph_topology.reverificationCadence를 P1D에서 P7D로 바꿨습니다. 다른 클래스와 필드는 바꾸지 않았습니다.
contracts/bundles/data-contracts-v1.0.0.json, data-contracts-v1.1.0.json: node tools/repo/build-data-contract-bundle.mjs --write all로 재생성했습니다. 손으로 고치지 않았습니다. 새 v1.0.0 sha256은 13c9bd12609352d4dca7df996e661bc3415dbe1faaeb37c0aed71fcd6fdb100c입니다.
tools/repo/data-contract-bundle.test.mjs: 정책과 두 번들의 route_graph_topology 주기가 P7D인지 고정했습니다. 일일 재확인 주기 P1D가 유지되는지도 고정했습니다.

P1D 전수 조사(Hub, 변경 전 `63737fd7`)

위치	성격	이번 PR
`datapack-freshness-sla.json` `route_graph_topology.reverificationCadence`	topology 만료 주기	`P7D`로 변경
`datapack-freshness-sla.json` `monitoring.manualCheckCadence`, `scheduledPipeline.cadence`	일일 재확인 주기(만료 아님)	유지(QA 결정: 일일 재확인은 계속)
`contracts/bundles/data-contracts-v1.0.0/1.1.0.json`	위 정책 사본	재생성
`contracts/bundles/backend-contracts-v1.0.0.json`	historical bytes 보존 대상(테스트로 고정)	유지
`tools/datapack/source-inventory.json`, `apps/mobile/assets/datapacks/source-inventory.json`, `tools/datapack/source-candidates.json`의 `updateFrequency`/`reverificationCadence` `P1D`	Hub 쪽 과거 사본(capital topology·Korail 파일 메타데이터). data release 판정 입력이 아님	유지
`post-launch-operations-review-gate.json`, `support-incident-response-gate.json`, `post-publish-ad-event-expiry-e2e.json`	운영·지원 SLA(원천 신선도와 무관)	유지

Scope

Included

route_graph_topology 재검증 주기를 P7D로 바꾸는 계약 변경, 공식 생성기로 만든 data 계약 번들 재생성, 계약 테스트

Excluded

data 레포의 contracts.lock.json pin 상향, data 사본 정책, topology 수집기·검증기의 스냅샷 freshUntil 규칙(+1D → 컷오버 이후 +7D). 이 PR이 병합된 뒤 data 레포 PR에서 함께 처리합니다.
일일 재확인 자동화(내용 변화가 있을 때만 새로 발행). data#870에서 기록하고 다룹니다.
시간표·접근성 등 다른 클래스의 주기. QA 승인 범위가 topology뿐입니다.

Ownership / dependencies

Accountable owner or plan: [Refactor] 데이터 파이프라인 운영 방식 전환: 자동 갱신·개발/발행 게이트 분리·생성 산출물 축소 easysubway-data#870(데이터 파이프라인 운영 전환), [Fix] 전국 후보 기준으로 데이터 릴리스 파이프라인 복구(상위 이슈) easysubway-data#862(첫 전국 발행)
Required predecessor output: 없음. 이 PR이 data 레포 pin 상향 PR의 선행입니다.
Concurrent work overlap: None

Documentation impact

영향 resource ID 또는 NONE: NONE. node tools/repo/refresh-documentation-fragment.mjs --check 결과는 IN SYNC입니다(바뀐 파일 중 fragment 등록 resource 없음).
resourceClass: 해당 없음
documentationFamily: 해당 없음
lifecycle/evidence 영향: 없음

검증 / Verification

Check	Result / Evidence
Focused RED → GREEN	테스트를 먼저 추가하고 `node --test tools/repo/data-contract-bundle.test.mjs`를 돌렸습니다. 변경 전에는 `actual: 'P1D'`, `expected: 'P7D'`로 실패했습니다. 정책을 바꾸고 번들을 재생성한 뒤 tests 9 / pass 9 / fail 0입니다
Affected integration	`node --test tools/repo/*.test.mjs`: tests 347 / pass 346 / fail 0. `node --test tools/ci/check-contracts.test.mjs tools/ci/datapack-release-workflow.test.mjs tools/repo/sync-component-mirrors.test.mjs`: tests 197 / pass 197. `node tools/ci/check-contracts.mjs --workspace contracts/workspaces/hub.json --current-only --local-contracts-only`: exit 0. `node tools/repo/build-data-contract-bundle.mjs --check all`: exit 0
Cross-repo 확인	data main(`e89d9939`)에서 새 v1.0.0 번들의 신선도 리소스로 required CI와 같은 인자를 실행했습니다(`validate-source-inventory.mjs --inventory tools/datapack/source-inventory.json --scope release/product-gates/production-datapack-scope.json --governance-policy tools/datapack/source-governance-policy.json --freshness-policy <새 번들 신선도>`). 결과는 exit 0입니다
Required CI	head `8399ee62`에서 required check 6개가 모두 pass입니다: Repository CI, Android CI, Backend CI, Mobile App CI, Changes ×2. run: https://github.com/AquilaXk/easysubway/actions/runs/37026654681 . Release Gate Consistency, SonarCloud Code Analysis도 pass입니다
Manual / production-like	Not required — reason: 계약 JSON과 번들 바이트만 바뀝니다. release 동작은 data pin 상향 PR이 병합된 뒤 data main의 Data Pack Release run으로 확인합니다
Security / privacy / accessibility	Not applicable — reason: 시크릿·인증·권한 경계와 UI 변경이 없습니다

실행한 명령과 결과: 위 표에 적었습니다.

검증 증거

증거 불필요 사유(UI): 화면 변경이 없는 계약 파일 변경입니다.
명령 출력과 CI run(https://github.com/AquilaXk/easysubway/actions/runs/37026654681)이 증거입니다. 위 검증 표의 테스트, 생성기 --check, 교차 레포 검증 결과가 이 PR의 계약 변경이 생성기 산출물과 일치함을 보여 줍니다.

Version impact

Route commercialization gate impact

route-commercialization-gate.json 영향 없음
route ETA accuracy, realtime coverage, accessibility regression, route v2 contract report를 갱신했다.
상용 경로/ETA claim을 추가하거나 변경하지 않는다.

Route release readiness tracker impact

route-release-readiness-tracker.json 영향 없음
[Release Blocker][P0] Journey V3·3-artifact 독립 compatibility/claim audit #1414 하위 release blocker issue 또는 production evidence 완료 조건을 갱신했다.
실시간/교통약자 길찾기 출시 준비 완료 claim을 추가하거나 변경하지 않는다.

Version decision

mobile versionName / versionCode: 변경 없음
datapack version: 변경 없음. 다음 발행부터 새로 등록된 topology 스냅샷 기준 P7D가 적용됩니다
route / realtime contract: 변경 없음
backend identity: 변경 없음

Not run

Check: None
Reason: 해당 없음
Rerun owner / condition: 해당 없음

리뷰어 메모 / Review focus

리뷰어가 먼저 봐야 할 지점: monitoring·scheduledPipeline의 P1D는 일부러 남겼습니다. 이 값들은 만료 주기가 아니라 일일 재확인 주기입니다. 원장에 이미 있는 topology 행(freshnessExpiresAt = 수집+1D)은 연장되지 않습니다. data 쪽 governance 평가는 저장값이 유도값보다 짧으면 SOURCE_FRESHNESS_POLICY_MISSING으로 막습니다. 따라서 data pin을 올린 뒤에는 topology 원천을 새로 수집·등록해야 다음 발행이 가능합니다(data PR에 명령 기록 예정).

리스크 / Risk

Level: High
Main risk: 만료 주기가 길어져 topology 변경 반영이 늦어질 수 있습니다. 완화책은 두 가지입니다. 일일 재확인(P1D)은 유지되고, 변경 발행 SLA(changePublishSla P3D)와 이벤트 트리거도 그대로입니다.
Failure behavior: 재검증이 7일 동안 실패하면 SOURCE_SNAPSHOT_EXPIRED로 막히고, 앱과 서버는 만료 상태를 명시적으로 드러냅니다.
State mutation on failure: 없음(계약 파일만 변경)
Fallback or degraded-success path introduced: No

Rollout / Recovery

Rollout or activation: 이 PR이 병합된 뒤 data 레포가 contracts.lock.json을 이 병합 커밋 번들로 올리면 적용됩니다.
Monitoring / success signal: data main Data Pack Release run의 Validate source inventory 통과, 다음 발행 manifest expiresAt가 새 topology 스냅샷 수집 시각 + 7일 이내
Rollback or recovery: 이 커밋을 revert하고 번들을 재생성한 뒤, data pin을 이전 커밋(63737fd7)으로 되돌립니다.
Data / config compatibility after rollback: 7일 주기로 등록된 원장 행은 P1D 정책에서 저장값이 유도값보다 길어 extension 근거가 없으면 거부됩니다. 이 경우 topology를 다시 등록해야 합니다.

체크리스트 / Checklist

PR 본문은 이 템플릿 섹션을 삭제하지 않고 모두 채웠다.
이슈 범위와 실제 diff가 일치하며 관련 없는 변경을 포함하지 않았다.
위험에 필요한 검증과 미실행 사유를 기록했다.
CodeRabbit 리뷰를 확인했다.
GitHub PR Review 객체가 있는지 확인했다. CodeRabbit status check만으로는 리뷰 완료로 보지 않는다.
CodeRabbit 실행이 불가능하거나 PR Review 객체가 없으면 Codex CLI code review를 단일 PR review로 게시했다.
CodeRabbit 봇과의 추가 질의응답을 포함하여 모든 Review thread가 해결(Resolve conversation)되었는지 확인했다.
배포 영향이 있는 경우 CD 상태를 확인했다.

QA 승인(2026-10-02): topology 원천은 개통·명칭 변경·시간표 개정 같은 이벤트로 갱신되므로 매일 만료시키지 않는다. 재검증 실패가 일주일 이어지면 만료로 막는 P7D 안전망을 두고, 일일 재확인 주기(monitoring·scheduledPipeline P1D)는 유지한다. - route_graph_topology.reverificationCadence P1D -> P7D - data-contracts v1.0.0/v1.1.0 번들을 build-data-contract-bundle로 재생성 - 계약 테스트가 정책과 두 번들의 P7D, 일일 재확인 P1D 유지를 고정 Refs #862 Refs #870

coderabbitai · 2026-10-02T15:23:41Z

Important

🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Repository: AquilaXk/easysubway/.coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 408b1cbe-22e0-4925-8474-233ba6093e40

Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

sonarqubecloud · 2026-10-02T15:25:34Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

AquilaXk

Actionable comments posted: 1

🎯 Linked issue & acceptance criteria audit

Linked issue: #870 Data pipeline operating model transition (parent issue, data repo)
Goal summary: Automate collection, block only at publish; topology gets P7D expiry backstop.
Acceptance criteria verified: 3/3

ID	Acceptance criterion	Status	Evidence
C1	Only route_graph_topology cadence moves from P1D to P7D	PASS	`release/product-gates/datapack-freshness-sla.json:184 is the only policy change`
C2	Bundles regenerated by the official generator, consistent with policy	PASS	`contracts/bundles/data-contracts-v1.0.0.json differs by one line; --check all exits 0`
C3	Contract test pins P7D for the policy and both bundles	PASS	`tools/repo/data-contract-bundle.test.mjs:263 asserts P7D for policy and each bundle`

🛡️ Adversarial audit evidence

Falsifiability verified: Yes (New assertions compare policy and both bundles to P7D;
the PR reports RED on P1D before the change)
Hollow assertions detected: 0
Production backdoors detected: 0
Ground-truth sources verified:
- build-data-contract-bundle --check all (generator, exit 0)
- refresh-documentation-fragment --check (IN SYNC)
- SLA policy JSON

🤖 Prompt for all review comments with AI agents

Could we verify each finding against the current code and keep only those that
still apply? Could we make the smallest validated fix and briefly note why any
finding no longer applies?

Inline comments:
- `@release/product-gates/datapack-freshness-sla.json:184-184`
  Could the QA decision and the P7D rationale be appended to the body of data#870 (and
  data#862) before merge, so the Excluded item and this contract change agree?

---

Outside diff comments:
None.

ℹ️ Review info

⚙️ Run configuration

Configuration used: CLAUDE.md and ~/.claude/CLAUDE.md of the hub checkout plus aquila-review skill defaults

Review profile: ASSERTIVE

Plan: Aquila fallback

Run ID: N/A (Aquila fallback)

Review source: Aquila CLI

Repository visibility: public GitHub repository

Trigger:
QA-requested discovery review of PR 3024 at head 8399ee6

Base:
main@63737fd7f91888dff5c5a6eb48e846e473ebdc22

Head:
chore/topology-freshness-p7d-870@8399ee6226cb15eb4cead101d67e138e6d778db6

Command:
aquila-review discovery via post-review.mjs on AquilaXk/easysubway PR 3024

📥 Commits

Reviewing files changed in this pull request between:

Base: 63737fd7f91888dff5c5a6eb48e846e473ebdc22
Head: 8399ee6226cb15eb4cead101d67e138e6d778db6

📒 Files selected for processing (4)

contracts/bundles/data-contracts-v1.0.0.json
contracts/bundles/data-contracts-v1.1.0.json
release/product-gates/datapack-freshness-sla.json
tools/repo/data-contract-bundle.test.mjs

📜 Review details

contracts.lock.json의 url·sha256과 stage-contracts의 bundle URL·sha256을 AquilaXk/easysubway#3024 병합 커밋(506306c6) 번들로 올렸다. release가 판정에 쓰는 고정 Hub 신선도 정책의 route_graph_topology 주기(P7D)가 data 사본·lib 컷오버 규칙과 다시 맞는다. Refs #862 Refs #870

* [Test] 노선 topology 신선도 컷오버(P1D→P7D) 경계값 실패 테스트 추가 QA 승인(2026-10-02)으로 topology 신선도가 이벤트 기반 갱신 + P7D 만료 안전망으로 바뀐다. 2026-10-03T00:00:00.000Z 컷오버 이전 수집분은 P1D, 이후 수집분은 P7D 창을 정확값으로 갖는지 수집기(수도권·광주·부산·대구·인천 station-info), 검증기 (current topology admission, 대전 materializer), 정책 유도, 수도권 등록기 원장 행, 고정 Hub 번들 stage 검사에서 경계값으로 고정한다. Refs #862 Refs #870 * [Chore] 노선 topology 신선도를 컷오버 이후 P7D 창으로 전환 - datapack-freshness-sla route_graph_topology P1D -> P7D (Hub 계약과 바이트 동일) - lib/topology-freshness-cutover: 컷오버 2026-10-03T00:00:00.000Z 이전 수집분은 P1D, 이후 수집분은 P7D를 정확값으로 쓰는 단일 규칙 - 정책 유도(deriveFreshnessExpiresAt)가 컷오버 이전 topology basis에 P1D를 적용해 커밋된 과거 스냅샷·원장 행이 그대로 유효하다(연장 없음) - topology 수집기 5개와 검증기(부산·인천 station-info·대전·current topology admission·수도권 재검증)가 같은 규칙을 쓴다. 대구 시간표 등 비topology 수집 창(+1D)은 그대로다 - 수도권·대구 등록기의 주기 고정값과 수도권 candidate freshness 메타데이터를 P7D로 - stage-contracts가 고정 Hub 번들의 topology 주기가 lib와 다르면 막는다 Refs #862 Refs #870 * [Chore] Hub topology P7D 계약 병합 커밋으로 data 계약 번들 pin 상향 contracts.lock.json의 url·sha256과 stage-contracts의 bundle URL·sha256을 AquilaXk/easysubway#3024 병합 커밋(506306c6) 번들로 올렸다. release가 판정에 쓰는 고정 Hub 신선도 정책의 route_graph_topology 주기(P7D)가 data 사본·lib 컷오버 규칙과 다시 맞는다. Refs #862 Refs #870 * [Docs] build-datapack 변경에 맞춰 문서 파편 동기화 (#870)

AquilaXk marked this pull request as ready for review October 2, 2026 15:40

AquilaXk commented Oct 2, 2026

View reviewed changes

Comment thread release/product-gates/datapack-freshness-sla.json

AquilaXk added the automerge FIFO 병합 큐 대상 — 코디네이터가 순서대로 update-branch 후 auto-merge label Oct 2, 2026

AquilaXk merged commit 506306c into main Oct 2, 2026
50 of 52 checks passed

AquilaXk deleted the chore/topology-freshness-p7d-870 branch October 2, 2026 15:44

AquilaXk mentioned this pull request Oct 2, 2026

[Chore] 노선 topology 신선도를 컷오버 이후 P7D 창으로 전환하고 Hub 계약 pin 상향 AquilaXk/easysubway-data#904

Merged

12 of 20 tasks

AquilaXk mentioned this pull request Oct 2, 2026

[Chore] 계획 시간표 신선도 클래스에 KRIC 역별 시간표 원천 추가 #3025

Merged

8 of 22 tasks

Navigation Menu

Repository navigation

[Chore] 노선 topology 신선도 정책을 P1D에서 P7D 만료 안전망으로 전환 - #3024

[Chore] 노선 topology 신선도 정책을 P1D에서 P7D 만료 안전망으로 전환#3024
AquilaXk merged 1 commit into
mainfrom
chore/topology-freshness-p7d-870

AquilaXk commented Oct 2, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Oct 2, 2026 •

edited

Loading

Uh oh!

sonarqubecloud Bot commented Oct 2, 2026

Uh oh!

AquilaXk left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

AquilaXk commented Oct 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

관련 이슈 / Related issue

작업 배경 / Summary

작업 내용 / Changes

P1D 전수 조사(Hub, 변경 전 63737fd7)

Scope

Included

Excluded

Ownership / dependencies

Documentation impact

검증 / Verification

검증 증거

Version impact

Route commercialization gate impact

Route release readiness tracker impact

Version decision

Not run

리뷰어 메모 / Review focus

리스크 / Risk

Rollout / Recovery

체크리스트 / Checklist

Uh oh!

coderabbitai Bot commented Oct 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sonarqubecloud Bot commented Oct 2, 2026

Quality Gate passed

Uh oh!

AquilaXk left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

AquilaXk commented Oct 2, 2026 •

edited

Loading

P1D 전수 조사(Hub, 변경 전 `63737fd7`)

coderabbitai Bot commented Oct 2, 2026 •

edited

Loading