# waterVis2026

**Repository Path**: caoln2003/water-vis2026

## Basic Information

- **Project Name**: waterVis2026
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-20
- **Last Updated**: 2026-09-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 威海市重点入海河流（黄垒河、沽河）总氮监测评估与可视化平台

基于 `skills/tianditu-swat-visualization` 技术方案 skill 实现：天地图承担地图可视化底座，SWAT 模拟结果、总氮评估、15N 同位素源解析等业务成果由本平台导入、存储、统计、可视化。

## 目录结构

```
watershed-viz-platform/
├── docs/                       需求分析 / 总体设计 / 数据库设计 / 模块详细设计 / 测试计划
├── database/schema.sql         PostgreSQL+PostGIS 建表脚本（与 backend Flyway 迁移一致）
├── backend/                    Spring Boot 3 后端（Java 17, Maven）
│   └── src/main/java/com/weihai/watershed/
│       ├── tianditu/           天地图代理 + 瓦片本地缓存（tk 仅后端持有）
│       ├── coordinate/         坐标转换（UTM Zone 51N -> CGCS2000）
│       ├── imports/            Shapefile / Excel 批量导入
│       ├── basin/ river/ station/   空间数据底座
│       ├── swat/               SWAT output.rch 结果
│       ├── evaluation/         总氮评估分级
│       └── sourceanalysis/     15N 源解析
├── frontend/                   Vue3 + 天地图JS API 4.0 + Cesium + ECharts 前端
└── test/                       （性能测试脚本产出目录，见 docs/05-测试计划.md）
```

## 关键设计约束（用户明确要求）

1. 天地图 tk 只在后端配置（`application.yml` / `sys_config` 表管理端热更新），前端运行时通过 `/api/tianditu/js-config` 获取，不写死在前端源码/构建产物。
2. 数据均为批量导入（Shapefile/Excel），不建设实时接入链路。
3. 源数据坐标系为 `EPSG:32651`（UTM Zone 51N，已通过黄垒河/沽河 `.prj` 文件确认），入库前统一转换为 `EPSG:4490`（CGCS2000，天地图坐标系）。
4. 天地图瓦片经后端代理后在本地磁盘缓存，命中缓存直接返回，未命中回源并落盘，定时 LRU 清理。
5. 涉及河流：黄垒河（HLH）、沽河（GH），均位于山东省威海市。

## 统一认证（对接门户 SSO）

本系统作为子系统接入统一门户：门户跳转本系统时通过 URL 携带一次性票据（`?ssoTicket=xxx`），本系统后端调用门户票据校验接口换取用户身份，签发本系统自己的短期 JWT；前端持该 JWT 访问 `/api/**`。完整流程、时序图、安全注意事项见 [`docs/02-总体设计.md`](docs/02-总体设计.md) 第10节，模块设计见 [`docs/04-模块详细设计.md`](docs/04-模块详细设计.md) 第9节。

对接前需要与门户团队确认/配置：

- `backend/src/main/resources/application.yml` 中 `sso.verify-ticket-url`（门户票据校验接口地址，建议通过环境变量 `SSO_VERIFY_TICKET_URL` 注入）与该接口的实际返回字段（当前假定为 `{userId, username, displayName, roles}`，如有差异需调整 `PortalUserInfo`/`SsoClient`）。
- `jwt.secret`（务必通过环境变量 `JWT_SECRET` 注入 ≥32 字符随机密钥，不使用默认值）。
- 前端 `.env`（参考 `frontend/.env.example`）中的 `VITE_PORTAL_URL`、`VITE_PORTAL_LOGIN_URL`。

## 快速开始（需在具备 JDK17/Maven/Node/PostgreSQL+PostGIS 的环境中执行）

```bash
# 1. 初始化数据库
createdb watershed
psql -d watershed -f database/schema.sql   # 或直接启动后端由 Flyway 自动迁移

# 2. 启动后端
cd backend
export TIANDITU_TK=你的天地图密钥
mvn spring-boot:run

# 3. 启动前端
cd frontend
npm install
npm run dev
```

## 已知限制与待办（本次开发环境约束说明）

本次开发所在的沙箱执行环境（Linux 子系统）在会话中不可用（VM 服务未能启动），因此：

- 未能用脚本读取 `.docx/.pptx/.pdf/.xlsx/.shp` 等二进制原始资料（`威海市重点入海河流总氮监测评估及精细化管控项目-技术部分-20250729.docx`、`可视化部分内容-要点(1).docx`、课题1/5科技报告 PDF、`黄垒河rch.xlsx`/`沽河rch.xlsx`、各流域 `.shp/.dbf`），需求与字段设计基于目录结构、`.prj` 坐标系文件（可读取，已确认 EPSG:32651）、SWAT 标准 `output.rch` 结构及项目名称本身的合理推断，**建议后续与原始技术方案文档、真实表头逐条核对**（`docs/03-数据库设计.md` 第4节、`docs/04-模块详细设计.md` 已标注具体待核实点）。
- 未能执行 `mvn compile/test`、`npm install/build`，代码基于人工审阅保证语法与依赖 API 的一致性，**首次构建前请预留时间处理编译报错**（重点关注 GeoTools 版本对应的包路径，30.x 版本部分类可能已从 `org.opengis` 迁移到 `org.geotools.api`，详见 `ShapefileImportService.java` 顶部注释）。
- Cesium 三维地形当前使用 `Cesium.EllipsoidTerrainProvider`（无地形起伏）占位，天地图三维地形服务需要天地图官方 Cesium 扩展脚本适配，详见 `frontend/src/components/Scene3D.vue` 注释。
- `SourceAnalysisService`/`ExcelImportService` 中子流域维度（`SUBBASIN`）目标解析留有占位（`resolveTargetId`），需补充 `SubbasinRepository` 按编号查询后完善。
- 管理端导入/配置接口（`/api/admin/**`）暂未接入用户鉴权，生产部署前需补充。

## 文档索引

- [需求分析](docs/01-需求分析.md)
- [总体设计](docs/02-总体设计.md)
- [数据库设计](docs/03-数据库设计.md)
- [模块详细设计](docs/04-模块详细设计.md)
- [测试计划](docs/05-测试计划.md)