上海学校目录、招生资料与家庭择校信息整理工具。基于 React 19、TypeScript、Vite 6 和 Tailwind CSS 3,数据随前端源码一起构建。
当前为开发预览版 2026.09.11-governance-alpha.3,不是已完成官方事实核验的招生查询服务。 可以运行、构建和研究代码;构建成功不代表学校信息准确或具备正式发布条件。此仓库独立来自网页版,不包含微信小程序或其较新数据发布包,也不会自动与小程序同步。
使用 Node.js 22 和 npm(CI 使用 Node.js 22;本次本地检查环境为 Node.js 25.6.1 / npm 11.9.0)。
git clone https://github.com/pauloking/shanghai-school-web.git
cd shanghai-school-web
npm ci
cp .env.example .env.local
npm run dev私有仓库需先通过 GitHub 账号取得访问权限。打开终端显示的地址,默认端口为 5173。当前开发服务器配置 host: true,会监听网络接口;仅需本机访问可用 npm run dev -- --host 127.0.0.1。
地图配置可以留空。 无 Key 不影响构建及本地目录数据的使用,但地图、POI 搜索、地理编码及依赖它们的流程不可用,相关界面可能出现未配置提示。
| 项目 | 当前设置与操作 |
|---|---|
| 地图(可选,暂不接入) | .env.local 中的 VITE_AMAP_WEB_KEY、VITE_AMAP_SECURITY_CODE 默认为空;未来启用时在部署平台设置同名变量并重新构建。代码保留现有地图集成,本次未联调。 |
| 数据 | 数据文件在 src/data/,版本与日期在 src/data/dataManifest.ts;更新数据、证据和版本后执行校验,不会在线自动刷新。 |
| 静态托管 | 构建命令 npm ci && npm run ci,发布目录 dist/,默认部署在域名根路径。无需数据库或云函数。 |
| 子路径托管 | 如部署到 /shanghai-school-web/,构建时使用 npm run build -- --base=/shanghai-school-web/,或在 vite.config.ts 配置对应 base。 |
| GitHub Actions | 仓库允许 Actions 后,推送及 PR 自动执行数据校验、类型检查与构建;只需代码读取权限,不需要地图或云服务密钥。 |
| 正式数据发布 | 必须另行通过 npm run validate:prod,当前版本预期会被阻止;不能以普通 CI 通过代替此门禁。 |
Vite 的 VITE_* 变量会进入浏览器产物,不能存放服务端私密凭证。未来接入地图时需要处理域名限制、配额和安全方案;此仓库仅保留空配置示例。.env.local、其他真实环境文件、依赖目录和构建产物均不提交。
本次仅上传源码并配置构建检查,未开通 GitHub Pages、未发布网站、未部署后端。仓库私有与网站访问权限是两件事,后续部署时需单独设置访问控制。
npm run validate:data # 数据结构、隔离规则、核验状态检查
npm run ci # 上述校验 + TypeScript + Vite 构建
npm run build # 仅类型检查和构建,不检查正式数据发布资格
npm run preview # 本机预览 dist,非生产服务器
npm run validate:prod # 正式数据门禁:当前应返回 RELEASE_BLOCKED,退出码 2验证脚本使用 /tmp 和 POSIX 环境变量语法,适用于 macOS/Linux;Windows 建议在 WSL 中运行。Python 脚本不属于正常安装或构建步骤。
以下数字来自 2026-10-23 对仓库现有数据执行 npm run ci 的实际结果:
| 指标 | 结果 |
|---|---|
| 学校目录 | 289 所,已逐条核验 0 所 |
| 原始划片记录 | 50 条:44 条通过结构校验、6 条隔离 |
| 已核验招生关系 | 0 条;44 条可见记录仍缺官方证据 |
| 没有可见划片记录的区 | 宝山区、嘉定区、青浦区 |
| 已核验房价 / FAQ | 均为 0 |
| 可用于录取条件核对的划片记录 | 0 |
| 已发现官方文件链接 | 16 条、覆盖 16 区;发现链接不等于核验事实 |
- 目录覆盖不等于完整收录或招生资格确认。 学校名称、地址与坐标也需要复核;资料面向特定年度,不保证当前仍有效。
- 未核验学校的性质、费用、梯队、评分、招生等事实由现有数据净化逻辑隐藏或标记待核验;相关对比、推荐、条件核对可能为空或不可用。这些限制应保留。
- 原始数据及历史生成脚本仍含编辑性评价、旧字段和推定值;源码中的字段不能直接作为官方事实。结构校验不是逐条原文核验,不检验链接当前可访问性,也不能证明所有页面都无误。
- 没有实时招生、房价或录取概率数据;不提供录取保证。智能顾问是前端规则和现有数据组成的界面,未接入大模型服务。
- 收藏、对比、笔记、讨论及点赞使用浏览器
localStorage。没有服务端账号、跨设备同步、备份或真正的多人社区;清理浏览器数据或更换域名可能导致记录不可见。预置讨论不是实际用户证言。 - 官方网页由第三方维护,可能失效或调整;本次没有逐一联网复核来源。地图未配置或网络不通时,不保证依赖地图的流程可用。
- 本次完成数据校验、类型检查和构建验证,未进行全浏览器、移动端或地图端到端验收。
- 源码上传不代表获得第三方材料的再分发授权;当前未附加开源许可证。
完整核验原则见 DATA_GOVERNANCE.md。
整理于 2026-10-23,依据小程序 Git b51288a、数据发布 2026.09.22-preview.13 及研究来源台账。这里只迁入资料导航,没有把小程序数据、校区映射、归档阅读器或核验结果迁入网页版;上方“当前项目限制”的网页版数据仍然有效。
| 用途 | 官方入口 | 使用边界 |
|---|---|---|
| 2026 义务教育总政策 | 上海市教委实施意见 | 市级框架;具体地段、材料与办理要求继续查区级文件。 |
| 2026 幼儿入园总政策 | 市教委学前教育阶段适龄幼儿入园通知 | 信息登记、报名验证和录取通知是不同环节,不能互相替代。 |
| 义务教育办理 | 上海市义务教育入学报名系统 | 实际开放时间与可办理事项以系统当年度公告为准,本项目不代报名。 |
| 政务办理 | 上海一网通办 | 按当年度入学/入园专栏办理,不把历史归档当作正在开放的入口。 |
| 幼儿园机构身份核对 | 上海市学前教育机构一览 | 用于园名、园部、地址等目录核对;机构目录不是招生范围表,早教中心也不能直接当作幼儿园。 |
上述两份市级政策与机构目录入口在整理当天已成功读取页面;这不代表全部链接、附件或报名流程都经过实时验收。2026 招生资料与 2025 学年统计均是指定年度材料,不自动适用于下一年。
每区选取小学与幼儿园各一个已收集入口。表中保留原文件名:有的是范围表,有的是包含附件的实施意见或办理指南,不能一律理解为精确对口表。更多招生计划、人户分离细则、初中材料、学校名录、乡镇公告及附件见后面的完整台账。
- 官方资料链接台账:按市级和 16 区列出 257 个原始 URL 去重后的官方链接,另保留 129 条政策目录与来源对应关系。
- 机器可读来源索引:保留 547 条出处记录及来源 ID、原始状态、采集日期和已记录的文件摘要;同一链接来自多个台账时保留多条出处。
- 范围为小程序当前发布的来源文件及 12 份指定研究台账,包含其中明确列出的附件;不是本地全部下载文件清单。原发布源共有 178 条来源记录,其中非政府/教育资料(如地图服务文档)不列入本官方链接汇总。
- 129 条目录记录、257 个 URL、学校数量、关系数量和官方文件数量是不同口径,不能相互替代。同名文件与不同来源 URL 均保留,不凭网页日期猜测谁是修订版。
discovered表示发现;snapshotted表示保存快照;parsed_pending_review表示已解析待复核;official_source_pending_review表示带官方来源、事实仍待核验。只有经过适当人工核验才可标记verified。本次整理不提升任何核验状态。
- 先查已有材料:按原始 URL、文件摘要和年度检查台账,区分“没采集”“已有原件但没解析”“已解析但没接入页面”,避免重复爬取全市资料。
- 保存原件和上下文:记录原发/收录页面及附件 URL、文件标题、发布机构、招生年度、发布日期、采集日期、SHA-256;无法确定的字段留空,不用采集日填发布日期。
- 按真实格式解析:HTML 表格保留合并单元格;PDF 检查跨页续表与脚注;扫描件保留原图并核对 OCR;Excel 保留工作表、行号与完整门牌。不能只提取名字列表。
- 先定语义再关联实体:区分精确地段、部分范围、统筹、摇号、验证服务区及主要对应街道;按学校主体—校区—学段—年度关联,歧义项隔离。
- 逐条连接证据:每条关系能回到具体文件、页/表/行或段落,结果保留完整限制条件;不要把门户首页当作证明某条关系的证据。
- 分开检查与发布:先验证结构、覆盖与引用,再进行原文复核和界面验收。文字阅读、事实核验、自动资格判断分别设边界;数据变更需独立审阅和可回滚的发布。
src/components/:学校列表、地图、资料、对比和家庭决策界面。src/data/、src/types/:内置数据和类型定义。src/utils/schoolDataQuality.ts:未核验学校字段的净化规则。src/services/amapService.ts:可选地图集成。scripts/validate-data.ts:普通校验及生产数据门禁。scripts/exportToCloud.ts:历史小程序导出工具,会向相邻的shanghai-school-miniprogram/clouddata和miniprogram/data写文件;不由构建运行,使用前必须检查路径与覆盖范围。scripts/generate_all_schools.py、scripts/build_full_shanghai_database.py:历史数据生成资料,不是官方同步程序;不要为启动项目而运行,避免用旧材料覆盖当前数据。
后续正式使用前,应优先补齐当年度官方原文、逐字段证据及人工核验,确认各区覆盖范围,再处理地图接入和产品验收。不要通过删除生产门禁或把记录批量标记为 verified 绕过数据限制。