内容
# GTFS 评分卡
> 您的交通机构的 GTFS 数据源质量如何？一个通俗易懂的质量评分， 三项需要修复的内容，以及每项对乘客的重要性。
[](https://github.com/ChelseaKR/gtfs-scorecard/actions/workflows/ci.yml)
[](LICENSE)
[](https://github.com/marketplace/actions/gtfs-scorecard-gate)
[](https://gtfsscorecard.org)
[](https://gtfsscorecard.org)
适用于小型交通机构的数据质量评分卡。它获取机构的 **GTFS Schedule** 数据源，当发布并配置了 **GTFS-Realtime** 数据源时，它会运行标准的 MobilityData 验证器，并将结果转化为一个评分等级，附带一份简短的修复清单，面向的是从供应商那里继承数据源的交通经理，而不是开发者。
试点机构： [Unitrans](https://unitrans.ucdavis.edu) （ASUCD / 戴维斯市）和 [Yolobus](https://yolobus.com) （约洛县交通区）。除了试点机构外，注册中心包含约 1,140 个精选数据源记录，主要在美国和加拿大，还有日本、澳大利亚和爱尔兰的官方初始测试（约 1,450 个已发布的评分卡页面）。评分每天刷新。数据源记录并不总是代表不同的交通机构：区域数据源、模式变体和已退休的别名被单独计算，而身份注册中心正在协调。
**实时访问：** [gtfsscorecard.org](https://gtfsscorecard.org/) — 每天由计划的流水线运行刷新。
**状态：** 测试版。每个已发布的评分卡都对三个时间表类别进行评分。当一个可用的实时数据源被配置和测量时，实时质量会被评分；否则，它会中立地显示为尚未测量。任何机构都可以通过 `agencies.yaml` 添加。
## 机构能获得什么
- 根据可测量的类别（正确性、时效性、乘客体验完整性和实时质量（如果可用））的总体评分。
- “前 3 项需要修复”，以通俗易懂的语言附带工作量提示。发现被表述为修复，而不是失败。
- 仅适用于美国机构的 NTD GTFS 准备就绪度读取（已发布、有效、当前）和可选的 `agency_id`/NTD ID 对齐标志。
- 趋势历史，每个机构每天一个 JSON 工件。
- 可嵌入的评分徽章（`<agency>/badge.svg`），机构可以将其放在自己的开发者页面上。
评分方法论，引用了加利福尼亚州交通数据指南 v4.0 和验证器的规则分类法，在 [docs/rubric.md](docs/rubric.md) 中。方法论变更受到管理：验证器版本升级必须附带 `scorecard canary` 的影子运行影响报告，然后才能实施（rubric.md，“管理升级”）。数据源来源和许可证在 [docs/feeds.md](docs/feeds.md) 中。 前瞻性规划分为两个部分：基础设施和扩展计划在 [docs/roadmap.md](docs/roadmap.md) 中，产品对用户的影响在 [docs/product-roadmap.md](docs/product-roadmap.md) 中。
## 网站内容
每个机构都有一个评分卡页面，以及为机构检查的不同部门编写的三个配套页面：一个董事会一页纸（`/agency/<id>/board/`），一个通话准备简报（`/brief/`），和一个修复日志（`/fixes/`）。围绕这些页面的是：
- **覆盖范围视图** - 覆盖范围概览（`/pulse/`），最常见的问题（`/problems/`），实时可靠性（`/realtime/`），新功能采用和无障碍数据覆盖（`/adoption/`），以及全球机构和路线地图（`/map/`，`/routes/`）。美国特有的 NTD 准备就绪度（`/ntd/`）和公平性（`/equity/`）作为区域模块提供。
- **程序页面**（`/program/<state>/`）适用于 46 个州和 DC 以及来自 [`rollups.yaml`](rollups.yaml) 的命名群体，每个群体都有共享的修复。
- **从业者工具** - 立即评分任意数据源（`/try.html`），在发布前检查数据源（`/check/`），比较两个机构（`/compare/`），在浏览器中使用 SQL 查询数据集（`/query/`），以及在供应商合同中提供数据源质量（`/procurement/`）。
- **修复知识库**（`/fix/<rule>/`，每个常见验证器发现一个通俗易懂的页面）和标准交叉参考（`/crosswalk/`）。
- **机器可读接口** - 版本化读取 API（[docs/api.md](docs/api.md)），用于批量 SQL 的 Parquet 表，每个机构的徽章和一致性标记，原子更改源，月度可引用数据集发布，以及只读 MCP 服务器（[docs/mcp.md](docs/mcp.md)）。
## 快速入门
需要 Python 3.12+，[uv](https://docs.astral.sh/uv/) 和 Java 17+（验证器 jar 在第一次运行时自动下载）。
```sh
cd pipeline
uv sync
uv run scorecard run --all
```
这会获取今天的每个已配置数据源的快照，验证并评分它，并将工件写入 `data/artifacts/<agency>/<date>.json` 以及 `latest.json` 和跨机构的 `index.json`。重新运行一天是幂等的。检查（从存储库根目录；镜像 CI 门）：
```sh
make verify
```
### 在本地运行 Web 应用程序
前端通过 HTTP 读取 JSON 工件。提供存储库根目录并通过 `http://` 打开页面，而不是通过双击文件：
```sh
cd .. # 存储库根目录，以便 data/artifacts/ 可访问
python3 -m http.server 8000
# 然后打开 http://localhost:8000/web/index.html
```
在 `file://` URL 下打开 `web/index.html` 会使页面卡在“加载评分卡…”，因为浏览器阻止了 ES 模块加载和 `file://` 上的 `fetch`，因此应用程序永远不会运行。任何静态服务器都有效；唯一的要求是 `data/artifacts/` 位于 `web/` 上一级，这是在 `web/src/app.js` 中期望的。
## 在 CI 中使用
通过已发布的动作控制自己的管道，获取数据源质量。 它会评分数据源，在作业日志中打印成绩和前 3 项修复，如果数据源低于 `min-grade` 或在 `min-days-to-expiry` 内过期，则会导致构建失败：
```yaml
- uses: ChelseaKR/gtfs-scorecard@v1
with:
feed-url: https://your-agency.example/google_transit.zip
country: CA
min-grade: C
min-days-to-expiry: 14
```
`country` 是数据源的分配的 ISO 3166-1 alpha-2 代码；它默认为现有工作流中的 `US`。两个阈值都是可选的；如果省略一个，则跳过该检查。完整的输入引用和完整的工作流在 [docs/ci-action.md](docs/ci-action.md) 中。
## 大规模运行
除了 `run` 之外，CLI 还带有滚动计划所需的命令：
```sh
scorecard sync --country US --state California # 从 Mobility Database 提出 agencies.yaml 条目
scorecard shards --count 4 # CI 的 JSON 扇出计划
scorecard reindex # 从磁盘重新构建 index.json
scorecard rollups # 发布程序汇总工件
scorecard render-site # 可爬取的静态页面 + 站点地图
scorecard alerts --out digest.md # 过期/回归摘要
scorecard notify # 每个订阅者的摘要（干运行）
```
`notify` 为 [`subscriptions.yaml`](subscriptions.yaml) 中的每个选择性订阅者构建一个数据源健康电子邮件，仅包含他们关注的机构，并且仅当需要关注时。 默认情况下，它会打印电子邮件；每日工作流会通过 SES 发送它们，一旦操作员验证发送者，应用 `infra/artifacts` 中的 SES 授权，并设置存储库变量 `SES_FROM`。
每日工作流将机构分散在并行矩阵中，可以将工件镜像到支持 CloudFront 的 S3 存储桶中（ADR 0002）。程序汇总在 [`rollups.yaml`](rollups.yaml) 中配置为命名群体（联络员的机构、地区、整个州），并在 `#/programs` 中显示；当数据源过期或评分下降时，机构会“需要关注”，而不仅仅是当它低于 B 时。已发布的 JSON 是一个记录的 API（[docs/api.md](docs/api.md)）；每个机构的目录（评分、评分、数据源 URL、到期天数、前 3 项修复）通过一个请求提供，而不是每个机构一个请求。
### 路线图状态：已构建 vs 已部署
[路线图](docs/roadmap.md) 计划了从两个试点数据源到具有全球能力的服务的路径。第一年的软件已构建、测试并大部分部署；[部署手册](docs/deploy.md) 介绍了 AWS 堆栈并携带了当前的部署状态。
| 路線圖項目 | 已在儲存庫中 | 状态 |
| --- | --- | --- |
| Mobility Database 同步 | `scorecard sync` (`mobilitydb.py`) | 按需运行 |
| 分片每日运行 | `scorecard shards` + CI 矩阵 | Actions 中实时运行 |
| 过期/回归警报 | `scorecard alerts`，`notify --send`，`infra/alerts` | 已应用并实时运行；SES 发送者已验证，摘要每日发送 |
| S3 + CloudFront 上的工件 | `infra/artifacts` | 已应用并实时运行；每日镜像正在运行，站点仍从 Pages 提供 |
| 自助提交表单 | `web/submit.html`，`infra/submit` | 已构建；端点需要 `terraform apply` |
| 即时评分 | `web/try.html`，`infra/instant-score` | 已构建；如果未应用（ADR 0029），则回退到问题表单路径 |
| 扇出计算（第二年） | `infra/compute`（SQS + 工作程序） | 已构建；当每日运行超出 Actions 矩阵时应用 |
从 Mobility Database 中提取的群体已经远远超出了加利福尼亚州的首次通过： [`agencies.yaml`](agencies.yaml) 现在包含约 1,140 个精选机构，主要分布在美国和加拿大，现在还有一个地理多样化的官方测试群体，每天进行评分（2026-07 减少了约 350 个重复记录，这些记录重复了已列出的数据源）。
## 添加您的机构
任何具有公共 GTFS 数据源的机构都可以通过在 [`agencies.yaml`](agencies.yaml) 中添加一个 YAML 块和一个拉取请求来添加；演练在 [docs/add-your-agency.md](docs/add-your-agency.md) 中。 [`web/submit.html`](web/submit.html) 中的网络表单在部署其无服务器端点（`infra/submit`）后，无需 YAML 即可执行相同的操作。
## 标准一致性
此存储库由存储在 [`docs/standards/`](docs/standards/) 中的共享投资组合标准管理（固定到标签 - 绝不本地编辑；参见该目录历史中的完整性注释）。根据 `docs/standards/README.md` 的一致性规则，这里声明了每个适用的标准；没有一个被默默跳过。
| 标准 | 适用？ |
|---|---|
| [代码质量](docs/standards/CODE-QUALITY-STANDARD.md) | 适用（Python；TS/Node 不适用 — `web/` 是无构建的纯 JS） |
| [安全性和供应链](docs/standards/SECURITY-AND-SUPPLY-CHAIN-STANDARD.md) | 适用（ASVS L1 形状：无身份验证，无 PII 存储） |
| [CI/CD](docs/standards/CI-CD-STANDARD.md) | 适用 |
| [可观察性](docs/standards/OBSERVABILITY-STANDARD.md) | 适用 — B 级（前端）+ C 级（批处理管道）；参见 [ADR 0031](docs/decisions/0031-observability-tier.md) |
| [无障碍](docs/standards/ACCESSIBILITY-STANDARD.md) | 完全适用 — 公民内容，自我声明的 WCAG 2.2 AAA（参见 [docs/accessibility.md](docs/accessibility.md)，[docs/vpat.md](docs/vpat.md)) |
| [国际化](docs/standards/INTERNATIONALIZATION-STANDARD.md) | 适用 — 公民交通数据，面向公众；不可用的路径不可用 |
| AI-EVALUATION | **不适用** — 任何用户界面或决策路径中没有模型推理（`AI-EVALUATION-STANDARD` §0）；MCP 服务器（`server.json`）是只读数据检索，没有 LLM SDK。在首次使用 LLM SDK 时变为适用。 |
| [质量和指标](docs/standards/QUALITY-AND-METRICS-STANDARD.md) | 适用（数据质量/血统为本存储库明确命名） |
| [文档](docs/standards/DOCUMENTATION-STANDARD.md) | 适用 |
| [发布和版本控制](docs/standards/RELEASE-AND-VERSIONING-STANDARD.md) | 适用 — 市场动作标签（`v1`/`v1.0.0`），每月数据集发布，MCP 注册条目 |
| [负责任的技术](docs/standards/RESPONSIBLE-TECH-FRAMEWORK.md) | 适用（审计 A-F；AI 治理行不适用 - 无 AI 系统） |
存储库中每个标准（截至最新一致性审计）的开放差距都跟踪在 [docs/standards-conformance-gaps.md](docs/standards-conformance-gaps.md) 中，而不是在此处重述。
## 可观察性
**B 级（前端）+ C 级（批处理管道）** — 而不是 `OBSERVABILITY-STANDARD` 的默认 A 级映射，因为本存储库的类别；参见 [ADR 0031](docs/decisions/0031-observability-tier.md) 了解原因。简而言之，已部署的系统是一个调度的 Actions 批处理作业 + 静态站点，而不是长期运行的托管服务（`infra/compute`，即会使其成为 A 级的部分，已构建但未应用）。C 级的健康/跟踪/SLO 控制不可用（无网络表面可探测）；B 级的核心 Web 重要性实验室门控适用，并作为开放工作跟踪（Lighthouse 当前仅断言无障碍）。由于设计原因，实时用户监控信标被拒绝 - 参见 ADR。
## 版本控制
SemVer。公共 API 表面是已发布的 JSON 模式（`schema_version`）、GitHub Action 的输入（`action.yml`）和 CLI（`docs/api.md`）。`pipeline/pyproject.toml` 的 `[project].version` 是单一的事实来源；`CITATION.cff` 和 `server.json` 镜像它，如果它们漂移，则 `pipeline/scripts/check_versions.py` 会导致 `make verify` 失败。支持版本策略：仅最新主要版本 - 这是一个单一部署的公民工具，而不是具有多个旧主要版本依赖的库。
此存储库还 **生成发布**: 市场 GitHub Action（标记为 `v1`），每月可引用数据集发布（`dataset-release.yml`）和 MCP 注册表条目（`server.json`）。
## 运行您自己的实例
州 DOT、国家 RTAP 或国家计划可以分叉此存储库，并建立自己的品牌实例 - 自己的域名、自己的机构注册中心、自己的组织名称 - 从配置和部署中，无需代码更改： [docs/fork-quickstart.md](docs/fork-quickstart.md)。
## 布局
```
agencies.yaml scorecard 跟踪的机构；在这里添加您的机构
instance.example.yaml 分叉品牌模板；复制到 instance.yaml 以重新品牌
rollups.yaml 程序汇总（跨多个机构的投资组合视图）
pipeline/ Python 管道：获取 -> 验证 -> 评分 -> 发布
web/ 静态前端；仅读取已发布的 JSON
infra/ Terraform：工件 CDN、提交功能、扇出计算
docs/ 数据源、评分标准、路线图、API、修复（知识库）、决策（ADR）
data/ 原始快照（忽略）和已发布的工件（提交）
```
## 适用于 Claude 代码
`CLAUDE.md` 是构建规范：产品框架、评分标准和质量栏。原始的四个构建阶段已经发货；当前方向存在于路线图和 [docs/ideation/](docs/ideation/) 中。硬规则：每个指标都附带其通俗易懂的解释；在 Web 应用程序中，无障碍（WCAG 2.2 AAA）是非强制性的；没有实时数据源的机构会中立地显示，而不是被责骂。
## 维护者
由 [Chelsea Kelly-Reif](https://chelseakr.com) 构建和维护，从加利福尼亚州戴维斯的交通系统开始。欢迎贡献和纠正；机构可以根据 [listing and removal policy](docs/listing-policy.md) 请求添加或删除。
