ExplorationMaps

勘探地图

基于浏览器的矿产勘探地图构建工具：搜索省级矿权登记信息，导入钻探／地质数据，设计适合投资者的地图，并导出为 PNG／SVG／PDF。在线地址：explorationmaps.com。

技术栈

• 前端： React 18 + Vite 5 单页应用（src/），Leaflet 地图引擎
• 后端： Supabase（身份验证、Postgres、RLS）+ Vercel 无服务器函数（api/）
• 静态营销内容： 位于 public/ 下的生成式博客和公司页面 （参见 scripts/generate-blog.js 和 scripts/pseo/）

要求

• Node 20+（Vite 5 的要求；已在 Node 20/22 上验证开发／CI）
• npm（已提交 package-lock.json；请使用 npm ci 以确保安装可复现）

开发

npm ci                 # install exactly the locked dependencies
cp .env.example .env   # fill in the VITE_ variables (see below)
npm run dev            # Vite dev server on http://localhost:5173

api/ 下的无服务器函数运行于 Vercel。要在本地运行完整栈，请使用 vercel dev；使用普通的 npm run dev 时，矿权搜索和分析端点不可用（界面会优雅降级）。

命令

命令	功能
npm run dev	Vite 开发服务器
npm run build	生成博客，构建到 dist/，并复制管理后台框架
npm test	运行 Vitest（CI 模式）
npm run test:watch	Vitest 监视模式
npm run pseo:fixture	使用 fixture 数据运行 pSEO 公司页面流水线

环境变量

文档见 .env.example。摘要：

公开变量（VITE_ — 会编译到客户端构建包中，绝非机密）：

• VITE_SUPABASE_URL、VITE_SUPABASE_ANON_KEY — Supabase 项目和匿名密钥 （生产环境必需；未设置时，身份验证／云端功能会自动停用）
• VITE_ADMIN_EMAIL — 仅控制管理面板的可见性；实际授权在服务端进行（admin_users 表 + is_admin()）

仅限服务端的机密（在 Vercel 中设置，绝不由客户端代码引用）：

• SUPABASE_SERVICE_ROLE_KEY — 供 /api/track 用于分析数据采集。 应用迁移 20260710000004 后，生产环境必需。
• ADMIN_API_SECRET — 可选；通过 x-admin-secret 请求头启用生产环境中的矿权 API 诊断模式。
• SUPABASE_URL / SUPABASE_ANON_KEY — 可选的服务端别名；api/claims.js（Quebec）和 api/track.js 会回退使用带 VITE_ 前缀的值。
• STRIPE_SECRET_KEY、STRIPE_WEBHOOK_SECRET、STRIPE_PRICE_MONTHLY_ID、 STRIPE_PRICE_YEARLY_ID — Pro 订阅计费（参见 docs/billing.md）。 在设置这些变量之前，计费端点会返回 503，所有套餐检查均会默认放行 — 可先安全部署代码，再配置 Stripe。

架构说明

矿权监测器（/tenure-monitor）

监控已保存的 B.C. 矿权组合：跟踪各项矿权距离其有效截止日的剩余天数、发送电子邮件提醒、检测变更，并可一键交接到地图编辑器。对政府交易为只读 — 绝不会代替用户操作 MTO。

• 数据： DataBC MTA_ACQUIRED_TENURE_SVW 图层的镜像，由 GitHub Actions 中的 scripts/tenure-sync/ 加载（每晚全量同步 + 每日两次定向同步）。如果政府响应不完整或失败，将中止且不写入数据， 因此省级政府数据源出现问题时，不会损坏已存储的矿权组合。
• 提醒： 每日运行 scripts/tenure-alerts/。通过数据库唯一约束而非应用逻辑进行去重。
• 截止日期始终按 America/Vancouver 计算 （src/utils/tenureDates.js），绝不使用浏览器时区。
• 开发者文档：docs/tenure-monitor.md。 用户帮助：docs/tenure-monitor-help.md。

无服务器 API（api/）

• api/claims.js — 多省份矿权搜索代理（BC WFS、安大略省/萨斯喀彻温省/马尼托巴省/纽芬兰与拉布拉多省/育空地区的 ArcGIS，以及通过可自托管 Supabase 表提供的魁北克省数据）。支持完整分页，并准确返回 meta: { totalKnown, returned, truncated, pagesFetched, provider }；有速率限制；限制 CORS；错误信息经过清理。
• api/bc-claims.js — 仅限 BC 的 WFS 代理（附近矿权边界框 + 旧版搜索）。
• api/tenure-search.js — 通过 B.C. 矿权登记簿的 Exploration Maps 镜像提供 Tenure Monitor 搜索（矿权编号、粘贴的列表、所有者名称、客户编号、地图范围、几何图形）。适用于匿名访问，有速率限制，且每个响应都会注明镜像上次同步的时间。使用 ANON 密钥并遵循公开读取策略进行读取，绝不使用 service role。
• api/track.js — 所有分析数据的接收入口（页面浏览、在线状态 ping、产品/搜索事件、落地页点击、潜在客户）。强制执行事件名称允许列表、载荷大小/深度限制和会话 ID 格式；从边缘请求头推导地理位置（绝不使用请求正文）；通过经验证的 Supabase 访问令牌解析用户身份；使用 service role 写入；按 IP 限速。若没有 SUPABASE_SERVICE_ROLE_KEY，则接收后丢弃，因此分析功能绝不会影响应用运行。在任何写入操作前丢弃已识别的自动化浏览器。管理员报告也会排除管理员账号和标记为内部的浏览器；打开管理仪表板会标记该浏览器，而 ?em_internal=1 和 ?em_internal=0 可用于显式设置/清除标记。
• api/stripe-checkout.js / api/stripe-portal.js / api/stripe-webhook.js — Pro 订阅计费（Stripe Checkout + 客户门户 + 用于同步 public.user_plans 的签名验证 webhook）。已获保留资格的账号（发布前创建）绝不会被降级。参见 docs/billing.md。
• api/_lib/ — 共享辅助工具（分页、请求防护、esri→GeoJSON）；路径中的下划线表示 Vercel 不会将其公开为端点。

共享地图

共享链接的格式为 /map/<id>，其中 <id> 是由客户端生成的 crypto.randomUUID()（122 位随机令牌）。通过 get_shared_map(share_id) RPC 读取——表级 SELECT 权限已撤销，因此无法通过公共客户端枚举 shared_maps。旧链接仍可使用：该 ID 仍是查询键。

身份验证与管理员

Supabase 身份验证（默认使用 magic link，密码作为备用方式）。管理员权限由 public.admin_users 中的一条记录授予，并在 SECURITY DEFINER 报告函数内通过 is_admin() 检查；所有定义者函数都固定了 search_path，并显式授予执行权限。添加管理员：

insert into public.admin_users (user_id, note)
select id, 'added by <you>' from auth.users where email = '<email>';

本地项目存储

src/utils/projectStorage.js：项目和工作草稿存储在 localStorage 中，使用 deflate 压缩（gz1: 前缀），并带有架构版本和确定性迁移。损坏的记录会保存在 .recovery 键下（绝不会自动删除），并提供手动导出/丢弃辅助工具。写入会返回结构化结果——写入失败时，UI 绝不会声称成功。登录后，本地项目会迁移到云端，并按项目提供状态 + 重试功能（src/utils/cloudMigration.js）。

导入格式

CSV（通过 Papa Parse 遵循 RFC 4180；自动检测纬度/经度列，钻孔轨迹还支持方位角、倾角和长度）、GeoJSON（经过验证）、压缩的 shapefile、散装的 .shp/.dbf/.prj/.shx 文件集（遵循 .prj 文件的设定——使用 proj4 将投影文件重新投影到 WGS84）、KML、KMZ（限制条目数、解压后大小和路径遍历），以及地理配准图像（.png/.jpg/.gif/.webp，需配有 world 文件或手动输入边界，可使用纬度/经度或 UTM；重采样至 2048 px 并存储在项目中）。已发布的瓦片（{z}/{x}/{y}）和 WMS 服务可作为图层添加到 Reference Overlays 下。

权属登记库

加拿大：BC（WFS）、Ontario/Saskatchewan/Manitoba/Newfoundland & Labrador/Yukon（官方 ArcGIS 服务）、Quebec（每周同步的 Supabase 镜像）。美国：面向 11 个西部州的联邦 BLM MLRS 权属数据，由 VITE_ENABLE_US_CLAIMS 控制——仅包含联邦权属数据，不包含州管理的土地权益（不含 Alaska 州权属数据）；边界是 BLM 的概略表示，并非法律测绘数据。有关数据来源、字段映射和部署后验证清单，请参阅 docs/us-claims.md。

数据库迁移

带时间戳的增量迁移位于 supabase/migrations/。仓库根目录中的旧版 supabase-*.sql 文件是历史手动运行的设置脚本——它们记录了现有生产环境状态；所有新更改都只能放在 supabase/migrations/ 中。

应用顺序很重要——其中两个迁移与部署紧密关联：

步骤	操作	时间
1	20260710000001_shared_map_lookup_rpc.sql	任意时间（增量）
2	20260710000003_live_pings_read_lockdown.sql	任意时间（已部署的应用从不读取 live_pings）
3	20260710000005_admin_authorization.sql	任意时间（增量；为当前管理员创建种子数据）
4	部署前端（使用 get_shared_map + /api/track），并在 Vercel 中设置 SUPABASE_SERVICE_ROLE_KEY	—
5	20260710000002_shared_maps_lockdown.sql	仅限步骤 4 之后
6	20260710000004_analytics_ingest_lockdown.sql	仅限步骤 4 之后

每个迁移文件头部都包含回滚说明。应用后，请以匿名客户端、普通已验证用户和管理员身份验证 RLS——验证查询内嵌在 ...000005 中。

20260901000001_shared_rate_limit.sql 是增量迁移，可在任意时间应用，但在应用之前， api/_lib/guard.js 中的跨实例速率限制器没有可调用的函数，并会默认放行（仅应用每实例的速率限制器）。 还必须重新部署 send-welcome 边缘函数（supabase functions deploy send-welcome），以启用其线索行检查。

部署与回滚

推送到 main 后会通过 Vercel 部署（npm run build → dist/，以及 api/ 函数）。回滚 = 重新部署之前的 Vercel 部署（即时生效）；如果在回滚的部署之后应用了与部署紧密关联的迁移， 还需运行该迁移文件头部的回滚 SQL。

测试

Vitest + React Testing Library（tests/，配置位于 vitest.config.js）。 覆盖范围侧重于防止回归：保存/自动保存竞态条件、权属数据请求顺序/取消、提供方分页、shapefile 投影 + CSV/GeoJSON 解析、存储故障/损坏处理、本地→云端迁移重试、API 加固、ArcGIS 几何转换， 以及共享地图访问。