From e72345a95878160522afc331b60d662b242780a7 Mon Sep 17 00:00:00 2001 From: admin Date: Sun, 25 Oct 2026 05:58:20 +0800 Subject: [PATCH] =?UTF-8?q?fix(console):=20schema=20DDL=20=E7=A7=BB?= =?UTF-8?q?=E5=87=BA=20web=20root=EF=BC=8C=E5=85=9C=E5=BA=95=E8=A1=8C?= =?UTF-8?q?=E4=B8=BA=E6=8A=BD=E8=BF=9B=20lib=20=E5=B9=B6=E9=94=81=E8=BF=9B?= =?UTF-8?q?=20CI?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - static/migrate.sql ⇒ schema/migrate.sql(编译期内嵌不变,运行期不在 web root) ⇒ 大小写 / %2E / 尾斜杠 / 双斜杠等路径变体全部拿不到 DDL - 404 与 SPA 兜底从二进制 crate 抽进 lib(src/routes/fallback.rs) ⇒ /api 与 /api/ 统一回 404 JSON,SPA 深链回 index.html - 新增 tests/spa_fallback.rs:6 条断言锁住兜底行为 - README 整段重写为现行 18 实体 CRUD + 鉴权面 + 上游 SPA 托管 - build-frontend.sh 可执行;产物目录缺失时回落 npm 构建路径 - registry::validate() 挪到 PGlite::open 之前,注册表写坏即秒退 - mw.rs 注释点明两套 4xx 形状并存是刻意分歧 Co-Authored-By: Claude Sonnet 5.5 --- README.md | 150 ++++++++++++++------------------- {static => schema}/migrate.sql | 0 scripts/build-frontend.sh | 17 ++-- scripts/gen-migrate.sh | 13 +-- scripts/reset-data.sh | 2 +- src/db.rs | 7 +- src/main.rs | 52 +++++------- src/routes/fallback.rs | 127 ++++++++++++++++++++++++++++ src/routes/mod.rs | 1 + src/routes/mw.rs | 14 +++ tests/spa_fallback.rs | 133 +++++++++++++++++++++++++++++ 11 files changed, 379 insertions(+), 137 deletions(-) rename {static => schema}/migrate.sql (100%) mode change 100644 => 100755 scripts/build-frontend.sh create mode 100644 src/routes/fallback.rs create mode 100644 tests/spa_fallback.rs diff --git a/README.md b/README.md index 5fdd89f..be367c3 100644 --- a/README.md +++ b/README.md @@ -1,70 +1,21 @@ -# TDC 数据接入连接器 · Rust + 静态 HTML + PGlite(MVP) +# TDC 数据接入连接器 · Rust + 上游前端 SPA + PGlite 把 `ssw-mvp/boot/ssw-tdc`(Spring Boot / JNPF 重底座的「数据接入连接器」子系统)重做成 **本地优先、零外部服务**的 MVP: -- **Rust (axum)** —— 控制面 + 数据面 + 静态托管 + TDC→TDS 的 HTTP 契约网关 -- **静态 HTML + 原生 JS** —— 操作员控制台(零构建,经 HTTP API 读写数据库) +- **Rust (axum)** —— 控制面 + 数据面 + 静态托管 + 契约网关 +- **上游(Java/Vue)完整前端的构建产物** —— 托管在 `static/`,**零自研前端、零构建步骤** - **PGlite(pglite-rs,进程内原生 PostgreSQL)** —— 内嵌在 Rust 进程里,承载全部 `tdc_*` 业务数据, 数据落在 `data/tdc.pg/`(磁盘持久化,非浏览器 WASM/IndexedDB) > 关键点:PGlite 用的是 **pglite-rs**(`crate pglite-rs`,import 为 `pglite`)—— > 把 postgres-pglite 编译成原生静态库、链接进二进制,是**真实 PostgreSQL 语义** > (类型 / MVCC / 事务 / 扩展 / 线协议),进程内单 backend 运行,无服务器、无 Docker。 -> 前端控制台只发 REST 请求,不直接持有数据库。 +> 前端只发 REST 请求,不直接持有数据库。 -> 红线:原 TDC 与 TDS **只走 HTTP 契约、不编译期耦合**;本实现用 `/api/ssw/tdc/tds/*` -> 代理网关还原该解耦,未配 `SSW_TDS_BASE_URL` 时走 **Noop 降级**(对应原 `NoopTdcTdsClient`)。 - -## 接入真实 TDS(跨方契约调试) - -连接器与 TDS 的契约严格对齐原 `TdcTdsClient`(`HttpTdcTdsClient`)。**真实 TDS 的鉴权/契约细节**: - -- **读概览 / 审计 / 留痕** `.../Bridge/**`:需请求头 **`App-Code: tdc`**(`TdsBridgeInternalController` - 白名单只放行 `tdc`)。`X-Internal-Token` 仅在 `tds.internal-secret` 非空时校验(默认空=免 token)。 - 代理对 `Bridge/**` 自动注入 `App-Code`,并跳过客户端自带的该头以避免重复。 -- **真实 TDS 用 HTTP 200 + body `code` 表达业务错误**(如 `code:600` 登录过期);连接器据此判定成败,不再只看 HTTP 状态。 -- **注册** `POST .../Connector/Register`:**真实 TDS 并无此端点**(连接器由运营方 CRUD 侧建档)。 - 连接器如实返回 `registerStatus: UNSUPPORTED_BY_TDS`,不伪造成功。 -- 其余:`POST {base}/api/ssw/tds/Bridge/{AuditChain,ChainEvidence,AuditRecord,AuditTrail}`、 - `POST {base}/api/ssw/tds/NodeReport`。 - -### 启动真实 TDS(`ssw-mvp/boot/ssw-admin`,JNPF 底座) - -TDS 不是独立服务,而是 `ssw-admin` 的**角色 profile**:`--spring.profiles.active=dev,full` -同时装载 TDS + TDC + SSWFLOW。依赖本机已有的 `jnpf-postgres`(15432) / `jnpf-redis`(16379) 容器 -与 `j7 / tdc / tds / sswflow` 四库(PostgreSQL,均已在运行)。 - -```bash -# 1) 打包:full 是默认 profile,但用 -pl 时必须显式 -P full 才会把 ssw-tds 打进 fat jar -mvn -f boot/pom.xml -P full -pl ssw-admin -am package -DskipTests - -# 2) 运行:端口避开连接器的 30000;中和 fisco / k8s / kbs 等本机未启的外部依赖 -DB_HOST=127.0.0.1 DB_PORT=15432 REDIS_HOST=127.0.0.1 REDIS_PORT=16379 \ -java -Xmx2g -jar boot/ssw-admin/target/ssw-admin-7.0.0-RELEASE.jar \ - --spring.profiles.active=dev,full --server.port=30040 \ - --fisco.enabled=false --k8s.enabled=false --kbs.url= \ - --ssw.security-plane.base-url=http://127.0.0.1:1 -``` - -启动约 30s(`Started SswAdminApplication`);`Tomcat started on port 30040`。跨方算力(30011)、 -scard 安全平面(8443) 等未启只报非致命告警,不影响 TDS 主链路。 - -### 连接器指向真实 TDS - -```bash -SSW_TDS_BASE_URL=http://127.0.0.1:30040 PORT=30000 ./target/debug/tdc-connector -``` - -实测:`/api/ssw/tdc/tds/Bridge/Contract/{id}` 经连接器返回真实合约(如 `CT-CRT-yxkcm`); -`Bridge/Connector/{id}` 返回真实连接器(如「吉利汽车 TEE 连接器 / ONLINE」)——数据与 `tds` 库一致。 - -**本地 TDS 桩(无 TDS 时的降级对端):** `tds-stub/server.js` 零依赖实现上述契约: - -```bash -cd tds-stub && node server.js # 监听 :30100 -# SSW_TDS_BASE_URL=http://127.0.0.1:30100 SSW_TDS_TOKEN=internal-test-token PORT=30000 ./target/debug/tdc-connector -``` +> 红线:原 TDC 与 TDS **只走 HTTP 契约、不编译期耦合**。 +> 本实现**不代理** TDS(TDS 侧出向客户端属后续任务);前端登录走 JNPF 门户账号 +> (`POST /api/oauth/Login`),该端点属后续任务。 ## 运行 @@ -76,9 +27,29 @@ PORT=30000 ./target/debug/tdc-connector ``` - 启动即初始化:Rust 进程内 `PGlite::open(data/tdc.pg)`,若 `tdc_identity` 不存在则执行 - 内嵌的 `migrate.sql`(`include_str!` 进二进制,19 张表 + 6 条内置脱敏规则 + 默认开发环境空间)。 -- 侧边栏「生成身份」→ Rust 用 ed25519 本地签发连接器身份(私钥仅落盘 `data/node-identity.json`,API 不回传)。 -- 数据全部落在 Rust 进程内嵌库;控制台通过 `/api/db/*` 读写。 + 内嵌的 `schema/migrate.sql`(`include_str!` 进二进制,30 张表 + 6 条内置脱敏规则 + 默认开发环境空间)。 +- 数据全部落在 Rust 进程内嵌库;控制台(上游 SPA)通过 `/api/ssw/tdc/*` 读写。 +- schema DDL 在 `schema/migrate.sql`(**编译期内嵌**,**刻意不在 web root**)⇒ 不可从 HTTP 下载。 + +## 控制台(前端) + +前端 = **上游(Java/Vue)完整版的构建产物**,托管在 `static/`: + +``` +static/ +├── index.html # SPA 外壳(vite base=/ ⇒ 引用 /assets/...) +├── logo.png +└── assets/ # index-*.js / index-*.css / tdc-*.js / vendor-*.js / Login-*.js … +``` + +- 产物由 `scripts/build-frontend.sh` 落盘(可重放;默认走「搬运已构建好的 dist」, + `SKIP_NPM=0` 才跑 `npm ci` + `VITE_SSW_APP=tdc npx vite build`)。 +- **SPA 深链**(`/tdc/home`、`/login` …)回退到 `index.html`(200 `text/html`),前端路由接管。 +- **`/api/**` 未命中**回 **404 + JSON**(`{"success":false,"code":404,"msg":"接口不存在"}`), + **不是** SPA 的 HTML —— 前端 axios 错误分支据此显示「接口不存在」; + 若回 HTML,前端会判 `body.code === undefined` 而**不 reject** ⇒ 静默渲染空表, + 把「接口没了」误读成「没有数据」。 +- 🔴 保留红线:**前端不直接持有数据库**(它只发 REST 请求)。 ## 编译缓存(按 dev-cache-layout 规范) @@ -91,25 +62,30 @@ sccache 0.18 经 `~/.cargo/config.toml` 的 `[build] rustc-wrapper` + `[env] SCC | 方法 | 路径 | 说明 | | --- | --- | --- | -| GET | `/api/health` | 健康检查(含 DB 模式) | -| GET | `/api/db/tables` | 列出 public 下所有表 | -| GET | `/api/db/table/{name}/columns` | 某表列信息(表名白名单校验,防注入) | -| GET | `/api/db/table/{name}/rows?limit=` | 某表行(`SELECT * LIMIT n`,不假定 `f_delete_mark` 列,默认 200 / 上限 1000) | -| POST | `/api/db/query` | 只读查询;任意 SELECT 用 `row_to_json(q)::text` 包成标准 JSON 数组返回 | -| POST | `/api/db/exec` | 写操作(INSERT/UPDATE/DELETE/DDL),原样 exec | -| GET/POST | `/api/ssw/tdc/node/identity` | 连接器身份(生成/读取,ed25519 软 PKI) | -| POST | `/api/ssw/tdc/node/identity/register` | 向 TDS 注册;真实 TDS 无 `/Connector/Register` 则如实返回 `UNSUPPORTED_BY_TDS`;Noop 模式本地置 APPROVED | -| POST | `/api/ssw/tdc/node/identity/heartbeat` | 心跳(置 ONLINE;配 base-url 时一并上报 TDS `NodeReport`) | -| ANY | `/api/ssw/tdc/tds/{*path}` | TDC→TDS 契约代理(剥离逐跳头 + `Bridge/**` 注入 `App-Code: tdc` + 可选 `X-Internal-Token`;无 base-url 时 501 Noop) | +| GET | `/api/health` | 健康检查(`tables: 30`) | +| POST | `/api/ssw/tdc/Auth/Login` | 连接器身份登录(软 PKI,签发会话令牌) | +| GET | `/api/ssw/tdc/Auth/Me` | 当前身份视图(**去敏**:不含私钥/一次性密钥) | +| GET | `/api/ssw/tdc/Auth/Spaces` | 环境空间列表 | +| GET | `/api/ssw/tdc/Auth/SsoConfig` | SSO 配置(上游前端登录页用) | +| GET / POST | `/api/ssw/tdc/{Entity}` | 18 个实体的列表 / 新建 | +| GET | `/api/ssw/tdc/{Entity}/All` | 不分页全量 | +| GET / PUT / DELETE | `/api/ssw/tdc/{Entity}/{id}` | 详情 / 修改 / 逻辑删除 | +| GET | `/api/ssw/tdc/Resource/{id}/Detail`、`/api/ssw/tdc/Dataset/{id}/Detail` | 资源 / 数据集聚合详情 | -> 查询结果统一用 `SELECT row_to_json(q)::text AS _row FROM () q` 包裹, -> 后端 `get::>` 取文本后再 `serde_json::from_str`,**规避逐列类型映射**且得到标准 JSON。 -> 内嵌库为单 in-process backend,所有 DB 访问由 `tokio::Mutex` 串行化。 +`{Entity}` 的 18 个全名: + +`ApiConsumeLog` / `AuditLog` / `Contract` / `Credential` / `DataInterface` / `Dataset` / +`Datasource` / `DeliveryLog` / `DeliveryTask` / `DestroyLog` / `Identity` / `Notification` / +`Order` / `Policy` / `PolicyCheckLog` / `PolicyTemplate` / `Product` / `Resource` + +> 鉴权:`X-Internal-Token`(内部令牌通道)或 `X-Auth-Token` / `Authorization: bearer `(会话通道)。 +> 业务失败一律 **HTTP 200 + `{code,msg,data}`**;鉴权失败是另一种形状: +> **HTTP 401/403 + `{"success":false,"code":401,"msg":"…"}`**(**无 `data` 键**)。 +> 内部库为单 in-process backend,所有 DB 访问由 `tokio::Mutex` 串行化。 ## 已实现范围 -**19 张表**(忠实移植原 `tdc_*` schema,含 9 系统列 / 逻辑删除 / partial 唯一索引): - +**30 张表**(上游 `tdc_*` schema 的生成产物,含 9 系统列 / 逻辑删除 / partial 唯一索引): 身份、数据源、资源、资源字段、脱敏规则、产品、需求、订单、合约、使用控制策略、 策略校验记录、API 交付服务、交付任务、交付日志、TDS 同步日志、审计日志、环境空间、成员、机密文件。 @@ -123,29 +99,27 @@ sccache 0.18 经 `~/.cargo/config.toml` 的 `[build] rustc-wrapper` + `[env] SCC - 订单:通过 / 驳回 / 签署 - 合约:生效 / 终止 - 交付任务:策略校验(写 `tdc_policy_check_log`)/ 完成 / 取消 / 销毁(留证写 `tdc_delivery_log`) -- 身份(Rust 侧):生成 / 注册 / 心跳 +- 身份(Rust 侧):登录 / 会话 / 空间列表 ## 明确不在 MVP 内(原 `ssw-tdc` 的隐私计算作业) 原 `NaxJob / Nax2PJob / TeeJob / Sandbox / Privacy / AnnotationTask / Notebook / VizChart / -Quality* / HostingJob` 等控制器依赖 **Nax 隐私计算引擎**与 **scard 安全平面(软 PKI + 软 TPM)**, +Quality* / HostingJob` 等控制器依赖 **Nax 隐私计算引擎**与 **scard 安全平面(软 PKI / 软 TPM)**, 未纳入本次重做。若需这部分,应保留原 Java/Scala 服务,或将其作为独立后端通过 HTTP 契约接入本连接器。 ## 目录 ``` tdc-rs/ -├── AGENTS.md # 给 AI 编码代理的项目约定(架构/红线/命令/踩坑) ├── Cargo.toml # 含 pglite-rs = "0.2" -├── src/main.rs # axum:内嵌 PGlite + 静态托管 + 身份 + TDS 代理 + /api/db/* -├── static/ -│ ├── index.html # SPA 外壳(纯前端,无 import map) -│ ├── app.js # 调 /api/db/* 的通用 CRUD + 生命周期 -│ ├── style.css -│ └── migrate.sql # tdc_* schema(编译期内嵌进二进制) -├── docs/ -│ └── TDC-TDS-CONTRACT.md # TDC↔TDS 跨方契约参考(对齐原 HttpTdcTdsClient) -├── tds-stub/ -│ └── server.js # 本地 TDS 契约桩(零依赖,仅供端到端调试) -└── data/ # 运行期:tdc.pg/(内嵌 PG 数据)+ node-identity.json(含私钥,已 gitignore) +├── src/ +│ ├── main.rs # axum:内嵌 PGlite + 路由装配 + 中间件 +│ └── routes/ # 按域装配:health / auth / crud / mw(405 改写)/ fallback(404 + SPA 兜底) +├── static/ # 上游 SPA 构建产物(index.html + logo.png + assets/) +├── schema/ +│ └── migrate.sql # tdc_* schema(include_str! 内嵌进二进制;**不在 web root**) +├── scripts/ # build-frontend.sh(前端产物)/ gen-migrate.sh(schema 生成)/ reset-data.sh +├── docs/ # 补充文档 +├── tds-stub/ # 本地 TDS 契约桩(零依赖,仅供端到端调试) +└── data/ # 运行期数据(tdc.pg/,已 gitignore) ``` diff --git a/static/migrate.sql b/schema/migrate.sql similarity index 100% rename from static/migrate.sql rename to schema/migrate.sql diff --git a/scripts/build-frontend.sh b/scripts/build-frontend.sh old mode 100644 new mode 100755 index 79a16fd..d85b160 --- a/scripts/build-frontend.sh +++ b/scripts/build-frontend.sh @@ -5,18 +5,19 @@ # UPSTREAM_REPO=/path/to/ssw-tdc ./scripts/build-frontend.sh # # ⚠️ 只写 static/index.html、static/assets/、static/logo.png —— -# **绝不碰 static/migrate.sql**(编译期内嵌的 schema 唯一来源)。 +# **绝不碰 schema/migrate.sql**(编译期内嵌的 schema 唯一来源, +# 且**刻意不在 web root** —— 放进 static/ 就等于挂到 HTTP 上)。 # ⚠️ 旧产物按约束 13 挪进访达回收站(不 rm)。 # # 🔴 **免 npm 模式**(默认走它):上游前端已经在上游装好了依赖, # 且本机对「从外部拷贝来的代码跑 npm install」有权限闸门 ⇒ 允许直接用 # **已构建好的 dist** 落盘(`PREBUILT_DIST` 指向该目录)。 -# 设 `SKIP_NPM=0` 才真的跑 `npm ci` + `vite build`(可重放路径)。 +# `PREBUILT_DIST` 不存在时**自动回落**到 `SKIP_NPM=0`(跑 npm ci + vite build)。 # # 环境变量: # UPSTREAM_REPO 上游仓库根目录(默认 /tmp/sswtdc-probe) # PREBUILT_DIST 已构建好的 dist 目录(默认 /.superpowers/sdd/.../spa-dist) -# SKIP_NPM 1 = 直接搬运 PREBUILT_DIST(默认);0 = 跑 npm ci + vite build +# SKIP_NPM 1 = 优先直接搬运 PREBUILT_DIST(默认);0 = 强制走 npm 构建 set -euo pipefail ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" @@ -27,11 +28,13 @@ WORK="$(mktemp -d)" STAMP="$(date +%Y%m%d-%H%M%S).$$" +# 「免 npm」模式下,产物目录不存在 ⇒ 回落去跑 npm 构建(而不是直接 exit 1)。 +if [ "${SKIP_NPM}" = "1" ] && [ ! -d "${PREBUILT_DIST}" ]; then + echo "[build-frontend] 已构建产物不存在:${PREBUILT_DIST} ⇒ 回落到 npm 构建路径" + SKIP_NPM=0 +fi + if [ "${SKIP_NPM}" = "1" ]; then - if [ ! -d "${PREBUILT_DIST}" ]; then - echo "已构建产物不存在:${PREBUILT_DIST}(设 SKIP_NPM=0 走 npm 构建路径)" >&2 - exit 1 - fi DIST="${PREBUILT_DIST}" echo "[build-frontend] 直接搬运已构建产物:${DIST}" else diff --git a/scripts/gen-migrate.sh b/scripts/gen-migrate.sh index de4123f..6a6ecfa 100755 --- a/scripts/gen-migrate.sh +++ b/scripts/gen-migrate.sh @@ -1,5 +1,5 @@ #!/usr/bin/env bash -# 从上游 ssw-tdc 的迁移脚本重新生成 static/migrate.sql。 +# 从上游 ssw-tdc 的迁移脚本重新生成 schema/migrate.sql。 # # 做法:按 (major, minor, patch, 文件名) 排序打进一个空 PostgreSQL,再 pg_dump --schema-only。 # ⚠️ boot/db/ 根目录的 6 个(V1.0.4 ~ V1.0.9)容易漏 —— 它们建 tdc_order / tdc_api_consume_log / @@ -8,7 +8,7 @@ # # 🔴 本脚本**不会** DROP / 重建目标库:目标库 public schema 非空时直接快速失败, # 由调用方自己准备空库(未授权的破坏性数据库操作不做)。 -# 🔴 自检在**落盘之前**做:生成物先写进一次性临时目录,表数校验通过后才覆盖 static/migrate.sql, +# 🔴 自检在**落盘之前**做:生成物先写进一次性临时目录,表数校验通过后才覆盖 schema/migrate.sql, # 避免一次顺序错误的运行把已入库的 schema 写坏。 # # 用法: @@ -19,8 +19,9 @@ set -euo pipefail ROOT="$(cd "$(dirname "$0")/.." && pwd)" UPSTREAM_REPO="${UPSTREAM_REPO:-/tmp/sswtdc-probe}" -OUT="${ROOT}/static/migrate.sql" -mkdir -p "${ROOT}/target" +OUT="${ROOT}/schema/migrate.sql" +# 🔴 产物落在 schema/(**不在 web root**)—— static/ 会被挂到 HTTP 上。 +mkdir -p "${ROOT}/schema" "${ROOT}/target" # 一次性工作目录:失败时保留,便于排查(不做 rm) WORK="$(mktemp -d "${ROOT}/target/gen-migrate.XXXXXX")" @@ -73,13 +74,13 @@ while IFS= read -r f; do fi done < "${WORK}/migrations.txt" -# ④ 导出 schema 到临时文件(先不碰 static/migrate.sql) +# ④ 导出 schema 到临时文件(先不碰 schema/migrate.sql) pg_dump --schema-only --no-owner --no-privileges > "${WORK}/raw.sql" # ⑤ 剥掉 pg_dump 前言(restrict/unrestrict/SET/set_config) grep -vE '^\\restrict|^\\unrestrict|^SET |^SELECT pg_catalog\.set_config' "${WORK}/raw.sql" > "${WORK}/migrate.sql" -# ⑥ 自检:表数不对就中止,绝不覆盖已入库的 static/migrate.sql +# ⑥ 自检:表数不对就中止,绝不覆盖已入库的 schema/migrate.sql TABLES="$(grep -cE '^CREATE TABLE public\.' "${WORK}/migrate.sql" || true)" if [ "${TABLES}" != "30" ]; then echo "[gen-migrate] ⚠️ 表数是 ${TABLES}(应为 30),请复核迁移顺序;已中止,未改动 ${OUT}。" >&2 diff --git a/scripts/reset-data.sh b/scripts/reset-data.sh index 40fe1bb..b37b53d 100755 --- a/scripts/reset-data.sh +++ b/scripts/reset-data.sh @@ -38,5 +38,5 @@ done if [ "${moved}" -eq 0 ]; then echo "[reset-data] 无需重置:${DATA_DIR} 里没有 tdc.pg / node-identity.json" else - echo "[reset-data] 下次启动会按 static/migrate.sql 重新建表(30 张表)" + echo "[reset-data] 下次启动会按 schema/migrate.sql 重新建表(30 张表)" fi diff --git a/src/db.rs b/src/db.rs index 417864d..b497c03 100644 --- a/src/db.rs +++ b/src/db.rs @@ -12,7 +12,10 @@ use pglite::{Error as PgError, PGlite, ToSql}; use serde_json::Value; /// 首次初始化执行的 schema(上游 82 个迁移的生成产物:30 张 tdc_* 表) -pub const MIGRATE_SQL: &str = include_str!("../static/migrate.sql"); +/// +/// 🔴 文件在 `schema/`,**不在 `static/`(web root)** —— 编译期 `include_str!` 内嵌进二进制, +/// 运行期不需要它在磁盘上 ⇒ 把它放进 web root 就等于把它挂到 HTTP 上(DDL 泄露)。 +pub const MIGRATE_SQL: &str = include_str!("../schema/migrate.sql"); /// 逻辑未删除谓词(对齐上游 `TdcCrudController.ALIVE`)。 pub const ALIVE: &str = "(f_delete_mark IS NULL OR f_delete_mark = 0)"; @@ -25,7 +28,7 @@ pub const ALIVE: &str = "(f_delete_mark IS NULL OR f_delete_mark = 0)"; /// - `--` 行注释内的 `;` 不切分;`/* */` 块注释整体忽略(注释文本保留在语句里, /// 但纯注释块不会被当成一条语句发出去)。 /// -/// ⚠️ 必须字面量感知:`static/migrate.sql` 里 `tdc_policy.f_priority` 的 COMMENT 文本含 `;`, +/// ⚠️ 必须字面量感知:`schema/migrate.sql` 里 `tdc_policy.f_priority` 的 COMMENT 文本含 `;`, /// 朴素 `split(';')` 会把那条语句打断,导致建表失败。 /// ⚠️ 将来上游若带函数(pg_dump 会输出 `$$ … $$` 函数体),不认识 dollar-quoting 会把函数体切开。 pub fn split_sql_statements(sql: &str) -> Vec { diff --git a/src/main.rs b/src/main.rs index cb5ab64..81f516f 100644 --- a/src/main.rs +++ b/src/main.rs @@ -19,40 +19,20 @@ use std::path::PathBuf; use std::sync::Arc; -use axum::{response::IntoResponse, routing::any, Router}; +use axum::{routing::any, Router}; use pglite::PGlite; use tower_http::cors::CorsLayer; -use tower_http::services::{ServeDir, ServeFile}; use tdc_connector::auth::{auth_middleware, AuthState}; use tdc_connector::config::Config; use tdc_connector::db::ensure_schema; use tdc_connector::routes::build_router; +use tdc_connector::routes::fallback::{api_not_found, spa_fallback}; use tdc_connector::session::SessionStore; use tdc_connector::state::{AppState, BootstrapIdentity}; const APP_VERSION: &str = env!("CARGO_PKG_VERSION"); -// ---------------- 404 兜底 ---------------- - -/// `/api/**` 未命中 ⇒ 404 + JSON(**不**返回 SPA 的 HTML)。 -/// -/// 🔴 形状与 `auth::reject` 同族(裸三字段、**无 `data` 键**): -/// 前端 axios 错误分支 `Promise.reject(new Error(body.msg || …))` ⇒ 「接口不存在」如实显示。 -/// 若这里回 HTML(200 + `text/html`)⇒ 前端拦截器判 `body.code === undefined` -/// ⇒ **不 reject** ⇒ 视图静默渲染成「空表且不报错」⇒ 把「接口没了」误读成「没有数据」。 -async fn api_not_found() -> axum::response::Response { - ( - axum::http::StatusCode::NOT_FOUND, - axum::Json(serde_json::json!({ - "success": false, - "code": 404, - "msg": "接口不存在" - })), - ) - .into_response() -} - // ---------------- 启动 ---------------- /// 解析项目根目录:从可执行文件所在目录向上查找含 `static/index.html` 的目录, @@ -81,6 +61,14 @@ async fn main() { let data_dir = config.data_dir.clone(); std::fs::create_dir_all(&data_dir).ok(); + // 注册表自检:表名/列名不过白名单 ⇒ 启动即失败(fail fast),别拖到运行期。 + // 🔴 放在 `PGlite::open` **之前**:注册表写坏时要「秒退」, + // 不该先付一次内嵌 PG 的 initdb 成本再退出。 + if let Err(msg) = tdc_connector::registry::validate() { + eprintln!("[tdc-connector] 注册表自检失败: {}", msg); + std::process::exit(1); + } + // 内嵌 PostgreSQL:首次 open 会在 data/tdc.pg 执行 initdb(含 MVCC/事务/类型,真实 PG 语义) let pg_dir = data_dir.join("tdc.pg"); let db = Arc::new(match PGlite::open(pg_dir.clone()).await { @@ -100,12 +88,6 @@ async fn main() { } println!("[tdc-connector] 内嵌 PGlite 就绪 @ {}", pg_dir.display()); - // 注册表自检:表名/列名不过白名单 ⇒ 启动即失败(fail fast),别拖到运行期 - if let Err(msg) = tdc_connector::registry::validate() { - eprintln!("[tdc-connector] 注册表自检失败: {}", msg); - std::process::exit(1); - } - let sessions = Arc::new(SessionStore::new()); // ⚠️ pglite-rs **每进程只允许一个 PGlite 实例**(crate 内部 `static OPEN`), @@ -148,7 +130,6 @@ async fn main() { }; let static_dir = project_dir.join("static"); - let index_file = static_dir.join("index.html"); // 🔴 `.with_state(state)` 必须是**链上的最后一步**:它把 `AppState` 烤进**此前已挂的** // 所有 endpoint(含 fallback_service)。放早了 ⇒ 之后新增的路由拿不到 state。 @@ -159,13 +140,18 @@ async fn main() { // 静态段优先于 `/api/{*rest}`;`/{id}` / `/{id}/Detail` / `/All` 三者共存不冲突。 .route("/api", any(api_not_found)) .route("/api/{*rest}", any(api_not_found)) - // ② `static/migrate.sql` 是编译期内嵌的 schema 唯一来源(99 KB 全量 DDL) + // ② `schema/migrate.sql` 是编译期内嵌的 schema 唯一来源(99 KB 全量 DDL) // ⇒ **绝不能**从 HTTP 下载(上游部署里 DDL 不在 web root)。 - // 在 ServeDir 兜底之前显式注册 ⇒ 路由优先于 `fallback_service`。 + // 🔴 该文件**已移出 web root**(现在在 `schema/`)⇒ ServeDir 根本读不到它; + // 这里再显式注册一条路由是**纵深防御**:万一有人日后把它放回 `static/`, + // 这个字面路径也回不去。 .route("/migrate.sql", any(api_not_found)) // ③ 静态托管挂**根**(vite base 是 `/`,产物引用 `/assets/...`) - // `fallback` ⇒ 任何非 /api 的未匹配路径回 index.html(SPA 深链不白屏)。 - .fallback_service(ServeDir::new(&static_dir).fallback(ServeFile::new(index_file))) + // 兜底服务(`routes::fallback::spa_fallback`): + // - 命中 `static/` 里的真实文件 ⇒ 直接出(`/assets/*.js`、`/logo.png` …) + // - `/api`、`/api/`、`/api/**` ⇒ 404 + JSON(**不是** SPA 的 HTML) + // - 其余(`/tdc/home`、`/login` 等 SPA 深链)⇒ 200 + `index.html` + .fallback_service(spa_fallback(static_dir)) // ④ 空体 405 ⇒ 业务信封(保留原 headers,含 `Allow`)。 // 🔴 必须放链尾:`Router::layer` 只作用于**调用时已注册**的路由。 .layer(axum::middleware::from_fn( diff --git a/src/routes/fallback.rs b/src/routes/fallback.rs new file mode 100644 index 0000000..0e4af5b --- /dev/null +++ b/src/routes/fallback.rs @@ -0,0 +1,127 @@ +//! 404 / SPA 兜底。 +//! +//! 本模块把「未命中路径」的处理从二进制 crate(`src/main.rs`)搬进 lib, +//! 于是集成测试(`tests/spa_fallback.rs`)能**直接**对它 `oneshot` 断言行为。 +//! +//! ## 语义 +//! +//! | 请求路径 | 响应 | +//! |---|---| +//! | `/api`、`/api/`、`/api/**` | **404 + JSON**(`api_not_found()`) | +//! | schema DDL 文件名(`migrate.sql` 及其大小写 / `%2E` / 尾斜杠 / 双斜杠变体) | **404 + JSON** | +//! | 其余(`/tdc/home`、`/login` 等 SPA 深链) | **200 + `text/html`**(`static/index.html`) | +//! | 命中 `static/` 里的真实文件(`/assets/*.js`、`/logo.png` …) | 由 `ServeDir` 直接出 | +//! +//! ## 为什么 DDL 要单独判 +//! +//! 🔴 `static/migrate.sql` **已被移出 web root**(现在在 `schema/`,编译期 `include_str!` 内嵌), +//! 所以 `ServeDir` 根本读不到它 ⇒ 「文件不在 web root」才是根因修复。 +//! 这里的判定是**纵深防御**:即便有人日后把 DDL 放回 `static/`, +//! 也**不会**被任何路径变体(大小写 / `%2E` / 尾斜杠 / 双斜杠)下载走。 +//! +//! ## 为什么 `/api` 用「精确前缀」而不是裸 `starts_with` +//! +//! `/apifoo` 这类**非** `/api` 命名空间的 SPA 深链仍应回 `index.html`(前端路由接管), +//! 不能被误吞成 404 JSON。 + +use std::path::{Path, PathBuf}; + +use axum::http::{header, StatusCode, Uri}; +use axum::response::{IntoResponse, Response}; +use axum::routing::any; +use axum::Router; +use serde_json::json; +use tower_http::services::ServeDir; + +/// schema DDL 的文件名(**绝不能**从 web root 下载)。 +const DDL_FILENAME: &str = "migrate.sql"; + +/// `/api/**` 未命中 ⇒ 404 + JSON(**不**返回 SPA 的 HTML)。 +/// +/// 🔴 形状与 `auth::reject` 同族(裸三字段、**无 `data` 键**): +/// 前端 axios 错误分支 `Promise.reject(new Error(body.msg || …))` ⇒ 「接口不存在」如实显示。 +/// 若这里回 HTML(200 + `text/html`)⇒ 前端拦截器判 `body.code === undefined` +/// ⇒ **不 reject** ⇒ 视图静默渲染成「空表且不报错」⇒ 把「接口没了」误读成「没有数据」。 +pub async fn api_not_found() -> Response { + ( + StatusCode::NOT_FOUND, + axum::Json(json!({ + "success": false, + "code": 404, + "msg": "接口不存在" + })), + ) + .into_response() +} + +/// 兜底服务:`ServeDir`(出 `static/` 里的真实文件)+ **找不到文件时**的决策层。 +/// +/// 决策层是一个内层 `Router<()>`(`Router` 本身就是 `Service`,可直接当 `ServeDir` 的 fallback): +/// `/api` 命名空间与 DDL 文件名 ⇒ 404 JSON;其余 ⇒ `static/index.html`(200 `text/html`)。 +/// +/// ⚠️ 为什么不用 `tower::service_fn`:`tower` 只是 **dev-dependency**, +/// **lib 代码里不许用** `tower::service_fn` / `ServiceExt` ⇒ 用 axum 自己的 `any(handler)`。 +pub fn spa_fallback(static_dir: impl Into) -> ServeDir { + let static_dir = static_dir.into(); + let index_file = static_dir.join("index.html"); + // 内层 Router:把「找不到文件」的决策交给 handler(`Router<()>` ⇒ 状态类型被钉死为 `()`)。 + let decision: Router = Router::new().fallback(any(move |uri: Uri| { + let index_file = index_file.clone(); + async move { fallback_response(&index_file, &uri).await } + })); + ServeDir::new(&static_dir).fallback(decision) +} + +/// 兜底决策:`/api` 命名空间 / DDL ⇒ 404 JSON;否则 ⇒ `index.html`。 +async fn fallback_response(index_file: &Path, uri: &Uri) -> Response { + let path = uri.path(); + if is_api_path(path) || is_ddl_path(path) { + return api_not_found().await; + } + // SPA 深链 ⇒ 回 index.html(前端路由接管)。 + match tokio::fs::read(index_file).await { + Ok(bytes) => ([(header::CONTENT_TYPE, "text/html")], bytes).into_response(), + Err(_) => ( + StatusCode::INTERNAL_SERVER_ERROR, + [(header::CONTENT_TYPE, "text/plain; charset=utf-8")], + "index.html missing", + ) + .into_response(), + } +} + +/// 是否落在 `/api` 命名空间(`/api`、`/api/`、`/api/**`)。 +/// +/// 🔴 用 `== "/api" || starts_with("/api/")` 而不是裸 `starts_with("/api")`: +/// 后者会把 `/apifoo` 这类**非** API 的 SPA 深链也吞成 404 JSON。 +fn is_api_path(path: &str) -> bool { + path == "/api" || path.starts_with("/api/") +} + +/// 路径的**最后一段**(去尾斜杠、percent-decode、忽略大小写)是否等于 DDL 文件名。 +fn is_ddl_path(path: &str) -> bool { + let trimmed = path.trim_end_matches('/'); + let last = trimmed.rsplit('/').next().unwrap_or(""); + percent_decode(last).eq_ignore_ascii_case(DDL_FILENAME) +} + +/// 最小实现的 percent-decode(只处理 `%XX`;非法的 `%` 原样保留)。 +fn percent_decode(s: &str) -> String { + let bytes = s.as_bytes(); + let mut out: Vec = Vec::with_capacity(bytes.len()); + let mut i = 0usize; + while i < bytes.len() { + if bytes[i] == b'%' && i + 2 < bytes.len() { + let hi = (bytes[i + 1] as char).to_digit(16); + let lo = (bytes[i + 2] as char).to_digit(16); + if let (Some(hi), Some(lo)) = (hi, lo) { + out.push((hi * 16 + lo) as u8); + i += 3; + continue; + } + } + out.push(bytes[i]); + i += 1; + } + String::from_utf8_lossy(&out).into_owned() +} diff --git a/src/routes/mod.rs b/src/routes/mod.rs index 010897e..2f1a714 100644 --- a/src/routes/mod.rs +++ b/src/routes/mod.rs @@ -3,6 +3,7 @@ pub mod auth; pub mod body; pub mod crud; +pub mod fallback; pub mod health; pub mod mw; diff --git a/src/routes/mw.rs b/src/routes/mw.rs index bfd43bb..f987f6b 100644 --- a/src/routes/mw.rs +++ b/src/routes/mw.rs @@ -24,6 +24,20 @@ //! - 动作:把 body 换成 `{"code":405,"msg":"方法不被允许","data":null}`, //! **保留** `parts.headers`(`Allow` 就在里面),并把 `Content-Type` 置为 `application/json`。 //! - body **非空**的 405 **原样返回**(不要覆盖别人已经写好的 JSON 错误体)。 +//! +//! ## ⚠️ 本仓**并存两套 4xx 形状** —— 这是**刻意分歧**,不要"顺手统一" +//! +//! | 场景 | HTTP | body | 来源 | +//! |---|---|---|---| +//! | 鉴权失败(401/403) | 401/403 | `{"success":false,"code":401,"msg":"…"}`(**无 `data`**) | `auth::reject` | +//! | 404(`/api/**` 未命中) | 404 | `{"success":false,"code":404,"msg":"接口不存在"}`(**无 `data`**) | `routes::fallback::api_not_found` | +//! | 405(方法不允许) | 405 | `{"code":405,"msg":"方法不被允许","data":null}`(**有 `data`、无 `success`**) | 本模块 | +//! | 业务失败(400/600 等) | **200** | `{"code":…,"msg":…,"data":…}` | `envelope::ActionResult` | +//! +//! 前两类是**鉴权/路由族**(裸三字段、无 `data`,与上游 `auth::reject` 同族), +//! 后两类是**业务族**(有 `data`)。 +//! 两族的形状分别来自 `task-10-audit.md` §C 与 `task-10-addendum.md` §H.2, +//! 前端 axios 两种都能吃 ⇒ **本轮刻意不统一**,后人若要统一须同时改前端契约。 use axum::body::{Body, HttpBody}; use axum::extract::Request; diff --git a/tests/spa_fallback.rs b/tests/spa_fallback.rs new file mode 100644 index 0000000..f36d520 --- /dev/null +++ b/tests/spa_fallback.rs @@ -0,0 +1,133 @@ +//! 兜底服务(404 / SPA 深链)的行为锁定。 +//! +//! ⚠️ **只测兜底服务本身**(对它 `oneshot`),**不接鉴权中间件** +//! (接了就会先吃 401,测不到 404)。 +//! ⚠️ 本测试二进制**不需要 PGlite**(兜底不碰 DB)⇒ 不建 PGlite 实例。 + +use std::path::PathBuf; + +use axum::body::Body; +use axum::http::{header, Request, StatusCode}; +use http_body_util::BodyExt; +use tower::ServiceExt; + +use tdc_connector::routes::fallback::spa_fallback; + +/// 仓库里的 `static/`(SPA 构建产物)。 +fn static_dir() -> PathBuf { + PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("static") +} + +/// 打一个请求到兜底服务,返回 `(状态码, content-type, body 文本)`。 +async fn call(uri: &str) -> (StatusCode, String, String) { + let svc = spa_fallback(static_dir()); + let req = Request::builder() + .uri(uri) + .body(Body::empty()) + .expect("构造请求失败"); + let resp = svc.oneshot(req).await.expect("兜底服务不应出错"); + let status = resp.status(); + let ct = resp + .headers() + .get(header::CONTENT_TYPE) + .and_then(|v| v.to_str().ok()) + .unwrap_or("") + .to_string(); + let bytes = resp + .into_body() + .collect() + .await + .expect("读取 body 失败") + .to_bytes(); + let text = String::from_utf8_lossy(&bytes).to_string(); + (status, ct, text) +} + +/// `/api/**` 未命中 ⇒ 404 + JSON(**无 `data` 键**)。 +#[tokio::test] +async fn api_prefix_returns_404_json_without_data_key() { + let (status, ct, body) = call("/api/anything").await; + assert_eq!(status, StatusCode::NOT_FOUND, "body={}", body); + assert_eq!(ct, "application/json", "body={}", body); + let v: serde_json::Value = serde_json::from_str(&body).expect("body 必须是 JSON"); + assert_eq!(v["code"], 404); + assert_eq!(v["msg"], "接口不存在"); + assert!( + v.get("data").is_none(), + "404 信封不得有 data 键(与 auth::reject 同族):{:?}", + v + ); +} + +/// `/api/`(**带尾斜杠**)⇒ 404 + JSON。 +/// +/// 🔴 这条是回归点:matchit 的 `{*rest}` **不匹配空 rest** ⇒ 旧实现里它落到 SPA 兜底回 HTML。 +#[tokio::test] +async fn api_prefix_with_trailing_slash_returns_404_json() { + let (status, ct, body) = call("/api/").await; + assert_eq!(status, StatusCode::NOT_FOUND, "body={}", body); + assert_eq!(ct, "application/json", "body={}", body); + let v: serde_json::Value = serde_json::from_str(&body).expect("body 必须是 JSON"); + assert_eq!(v["code"], 404); +} + +/// `/migrate.sql` ⇒ 404,且**响应体不含 `CREATE TABLE`**(不得泄露 DDL)。 +#[tokio::test] +async fn migrate_sql_is_not_downloadable() { + let (status, _ct, body) = call("/migrate.sql").await; + assert_eq!(status, StatusCode::NOT_FOUND, "body={}", body); + assert!( + !body.contains("CREATE TABLE"), + "响应体不得含 DDL:{}", + &body[..body.len().min(200)] + ); +} + +/// `/MIGRATE.SQL`(**大小写变体**)⇒ 响应体不得含 `CREATE TABLE`。 +/// +/// 🔴 这条是回归点:macOS 文件系统大小写不敏感 ⇒ 旧实现里它能下到完整 DDL。 +#[tokio::test] +async fn migrate_sql_case_variant_is_not_downloadable() { + let (status, _ct, body) = call("/MIGRATE.SQL").await; + assert!( + !body.contains("CREATE TABLE"), + "大小写变体不得泄露 DDL:{}", + &body[..body.len().min(200)] + ); + assert_ne!(status, StatusCode::OK, "大小写变体不应 200"); +} + +/// SPA 深链 ⇒ 200 + `text/html`(内容是上游 SPA 外壳)。 +#[tokio::test] +async fn spa_deep_link_returns_index_html() { + let (status, ct, body) = call("/tdc/home").await; + assert_eq!(status, StatusCode::OK, "body={}", body); + assert!( + ct.starts_with("text/html"), + "content-type 应为 text/html,实际 {:?}", + ct + ); + assert!( + body.contains("尚数网可信数据空间(连接器)"), + "应是上游 SPA 外壳:{}", + &body[..body.len().min(200)] + ); +} + +/// 静态资源(`/assets/*.js`)⇒ 200(由 `ServeDir` 直接出,不走兜底)。 +#[tokio::test] +async fn static_assets_are_still_served() { + let asset = std::fs::read_dir(static_dir().join("assets")) + .expect("读 static/assets 失败") + .filter_map(|e| e.ok()) + .map(|e| e.file_name().to_string_lossy().into_owned()) + .find(|n| n.starts_with("index-") && n.ends_with(".js")) + .expect("static/assets 里应有 index-*.js"); + let (status, _ct, body) = call(&format!("/assets/{}", asset)).await; + assert_eq!( + status, + StatusCode::OK, + "body={}", + &body[..body.len().min(200)] + ); +}