主题
GIS引擎底座 详细设计文档
文档版本：1.15 ｜ 最近核对日期：2026-11-10
2026-11-10 前期业务空间接入实现：补齐前期业务空间受控发布服务（
GisPreliminaryFeatureService），支持 EPSG:3857 采集候选 WKT 向 EPSG:4326 GeoJSON 与经纬度 BBox 转换，发布到 PRELIMINARY 业务图层并绑定PRELIMINARY_OBJECT；通用 GIS 要素维护接口已增加防绕审保护，拒绝直接修改前期受控要素。
本文规定 GIS 的页面、路由目标、交互、权限和服务契约。业务规则以需求分析为准，架构见概要设计，表结构与字段见数据库设计。
2026-10-26 线网地图场景化（当前有效）：原“监管中心”更名为“线网地图”，并作为系统默认地图场景（
SYSTEM_DEFAULT）运行。默认入口和显式场景入口共用同一场景解析；地图接口一次下发场景目录（图纸、图层、范围、样式、初始显隐），不再由前端逐图纸取目录。场景支持全部图层/自选图层、底图注记、工程范围适配/固定视角；工程范围适配按主体范围剔除离群图层，并保留完整范围入口。2026-10-23 本期实施口径（历史）：常规入口为 4 页，专业和标段不进入 GIS，本期不做专题。上传只解析原始 CAD 平面，配准在版本工作台完成并派生 EPSG:4326 成果；旧坐标/转换页面、图纸级配准、同步导入、后端高德候选和 GIS 专题已退出。此段为当时口径，当前设计以本页现行章节为准。
文档控制
| 项目 | 内容 |
|---|---|
| 实现范围说明 | 当前 4 个常规入口及检查/对比/场景预览等子页面；图纸异步接收、原始平面解析、版本级高德配准、检查/生效、数据管理、底图服务配置和地图场景配置（全部/自选图层、注记、默认视角）可用。原始整文件下载按功能权＋工程范围联合鉴权；原 CAD kkFileView 在线预览已于 2026-10-24 退役（签发/回源/代理接口与专用配置删除）；原始/派生清单使用图层内有界分块；换版影响哈希按当前修订计算。专业范围权限已取消；要素几何编辑、真实进度、驾驶舱、三维和图元级换版差异仍待实施 |
| 编写及最近核对日期 | 2026-10-26 |
| 设计依据 | 用户要求补齐页面体系、直接维护六类文档中的详细设计和数据库设计，以及“图层管理按线路/工点导航并就地上传 CAD”的补充 |
| 代码核对范围 | 当前工作树 GIS 前端、API 类型、Controller、Service、Entity/Mapper；开发库 18 张 GIS_ 表 |
| 本轮范围 | 页面、子页面、权限码与接口已实现；业务执行链和验收口径未全部完成 |
1. 信息架构与页面边界
1.1 菜单结构
以下是本期已登记菜单结构。
text
GIS
├─ 线网地图 纯查看地图工作台
├─ 数据管理 图纸/版本/任务/图层，左线路→物理工点
├─ 底图服务配置
└─ 地图场景配置4 个叶子菜单按用户功能权显示。普通查看人员通常使用“线网地图”；图纸与图层维护人员使用“数据管理”；配置人员使用“底图服务配置”和“地图场景配置”。专业权限和专题本期不进入菜单。按钮权限按页面归属：仅跨页面通用的 gis:drawing:list、gis:layer:list、gis:feature:query 挂在 GIS 根目录，其余查询和写操作挂在所属页面下。
数据管理内的工程导航是 PBS 的“线路 → 物理工点”，不是旧版“项目/包段/标段/工点”单棵树。标段和专业本期不进入 GIS 目录、表单和查询；工程主数据只选择和引用，不在 GIS 自建名称台账。
1.2 菜单页面与路由目标
以下为本期菜单和已存在的组件。旧四页、坐标系、转换方案、旧配准和专题页面已从代码、路由和 SYS_MENU 删除，不再作为入口。组件路径均相对前端 src/views/。
| 页面编号 | 页面 | 目标路径 | 目标组件 | 页面模式 |
|---|---|---|---|---|
| P-GIS-001 | 线网地图 | /gis/scene/index | gis/scene/index.vue | immersive，纯查看 |
| P-GIS-002 | 数据管理 | /gis/data/index | gis/data/index.vue | viewport，左目录右图纸/图层 |
| P-GIS-006 | 底图服务配置 | /gis/base-map/index | gis/base-map/index.vue | viewport |
| P-GIS-009 | 地图场景配置 | /gis/scene-config/index | gis/scene-config/index.vue | viewport |
“viewport/scroll/immersive”分别对应平台共享工作区模式。页面视觉沿用界面规范，不新增 GIS 专用后台主题。
1.3 复杂操作子页面
| 编号 | 子页面 | 目标路径 | 上级菜单与用途 |
|---|---|---|---|
| D-GIS-001 | 图纸详情 | /gis/drawing/detail/:drawingId | 数据管理；基础信息、版本、任务、文件及引用 |
| D-GIS-002 | 图纸成果检查 | /gis/drawing/check/:drawingId/:versionId | 数据管理；内容、坐标、缺项及候选生效 |
| D-GIS-003 | 图纸版本对比 | /gis/drawing/compare/:drawingId | 数据管理；查询参数指定旧/新版本，图层级差异 |
| D-GIS-004 | 转换任务详情 | /gis/task/detail/:attemptId | 数据管理；输入快照、阶段、检查结果及重试链 |
| D-GIS-007 | 场景预览 | /gis/scene-config/preview/:sceneId | 地图场景配置；当前账号下的受控展示检查，始终只读 |
这些子页面不单独占用侧栏菜单。内部路由要显式注册，带登录校验、父菜单高亮和返回地址；复制地址、刷新仍可进入。缺少资源权限时显示不可访问，不向普通用户返回资源名称。返回地址仅接受本站受控路径。
1.4 轻操作承载
| 交互 | 承载 | 结果 |
|---|---|---|
| 上传 CAD/上传新版本 | 共用分步对话框，工程归属 → 文件与图层范围 → 确认 | 创建源版本和任务，立即提供版本/检查入口 |
| 图层基本信息、样式 | 图层页表单与样式预览弹窗 | 保存公共定义；地图临时偏好不写入 |
| 要素属性、业务绑定 | 详情抽屉或详情页内表单 | 使用同一资源版本和保存服务 |
| 底图服务、场景基本信息 | 管理页表单弹窗；复杂结果打开子页面 | 保存、校验、引用检查分别反馈 |
| 未保存、停用、删除、候选生效 | 确认弹窗 | 明确影响对象，不创建审批流 |
1.5 按钮权限归属
SYS_MENU 中 GIS 按钮权限按实际使用页面挂载，不在每个页面重复登记同一权限：
| 父节点 | 按钮权限 |
|---|---|
| GIS（根目录，仅通用查看） | 图纸查看 gis:drawing:list、图层查看 gis:layer:list、要素查看 gis:feature:query |
| 数据管理 | 图纸详情查看 gis:drawing:query、图纸修改 gis:drawing:edit、图纸下载 gis:drawing:download、图纸导入 gis:drawing:upload、任务列表 gis:task:list、任务查询 gis:task:query、任务重试 gis:task:submit、图层详情 gis:layer:query、图层显示配置 gis:layer:edit |
| 底图服务配置 | 底图查询/新增/修改/删除 gis:baseMap:* |
| 地图场景配置 | 场景查询/新增/修改/删除 gis:sceneConfig:* |
隐藏子页面不生成按钮权限；坐标/转换、要素维护/导出、专题和专业授权等已退出页面的按钮权限不再登记。权限码仍须与后端注解和前端 v-hasPermi 逐字一致。
2. 页面共同交互
- 列表页使用“查询卡 → 列表卡（左标题、右操作 → 表格 → 分页）”；默认每页 10 条。所有数量、筛选候选项在后端过滤后返回。
- 工程选择优先沿用当前页面上下文；涉及专属成果时必须有有效标段工点组合。项目名、线路名、工点名是 ID 的展示信息，不作为写入关联键。
- 纯浏览不要求具备配置维护权；地图取得经过过滤的可用配置，不读取整个管理接口。按钮隐藏与接口权限分别执行。
- 详情使用描述列表，长表单和详情采用 scroll；检查、校准、地图预览采用 immersive，侧栏可收起。桌面 1920×900 与收缩视口 1600×760 下内容可达，不通过裁切隐藏操作。
- 有未保存变更时切换工程、离开或关闭必须提供保存/放弃/继续编辑；保存失败保留输入。权限撤销后停止展示和提交无权内容，不能把其转为公开草稿。
- 异步任务可离开页面；任务阶段替代无限 loading。没有可靠总进度时显示阶段、已处理数与耗时，不伪造百分比。
- 返回列表恢复原查询、页码、工程和已展开节点；写入后刷新受影响区域。跨页传稳定资源 ID 和版本，不传完整几何、密钥或前端权限判定。
- 配置使用“可用/停用”等可用性与“未验证/待资料/通过/不通过”等验证结果分开表达，不把保存成功当作验证通过。不引入审批状态。
3. 各菜单页面规格
3.1 P-GIS-001 线网地图
用途与布局：平台导航内的纯查看地图工作台，也是系统默认地图场景。中央是地图；左侧是合并后的“地图控制”浮动面板，顶部提供“查看完整范围”和刷新，其下为搜索框，保持统一边距并与图纸列表留出间隔；中间按图纸卡片分组展示可滚动的图层列表，每张图纸卡片的副标题行右侧提供该图纸的“全部显示/全部隐藏”，底部集中展示底图切换、注记/加载状态和默认底图提示；缩放按钮位于地图右上角。本期不设工程目录、不提供几何编辑和进度专题；编辑能力见后续阶段，不作为当前入口。
| 区域 | 内容及操作 | 行为 |
|---|---|---|
| 图层 | 图纸展开/收起、图层显隐、定位、按图纸全部显示/隐藏和刷新 | 按场景配置初始化：全部图层模式使用“打开时显示全部图层”开关，自选图层模式使用每层初始显隐；图纸卡片的“全部显示/全部隐藏”只作用于该图纸下的图层，覆盖其目录中全部图层且不受搜索筛选影响；刷新保留用户显隐选择，从其他页面返回时重新取场景目录并同步公共配置；显式图层定位显示目标层，临时显隐不写公共配置 |
| 图元 | 点击图元查看图纸、源图层、源 handle 和文字 | 只读；弹窗不替代完整业务详情 |
| 底图 | 面板底部选择场景允许底图、注记开关、加载状态和重试 | 注记初始值来自场景配置；仅对带独立注记层的 WMTS 底图生效，矢量样式在界面上明确提示；默认底图不可用或允许底图为空时面板明确提示，不静默切换；底图不按工程/专业过滤，底图异常不卸载 CAD 图层 |
| 视野 | “查看完整范围”和默认视角 | 工程范围适配使用场景 fitExtent（已剔除离群图层），面板提示忽略数量；完整范围使用 fullExtent，包含离群图层；固定视角使用场景中心/范围/初始缩放 |
线网地图不提供图纸配准入口，只展示当前有效版本的派生成果；配准维护在数据管理的版本工作台。默认入口直接解析 SYSTEM_DEFAULT 场景，使用场景名称、允许/默认底图、注记、图层组合和视角；无该场景时才回退 YAML 空场景。场景接口一次下发本场景可读图纸、图层、范围、样式和初始显隐；地图只加载与当前视野相交且达到最小层级的图层，同一图纸批量取图并限制并发，避免全部图层模式一次性请求所有内容。
数据管理（当前）：左侧为“线路 → 物理工点”线路工程导航，右侧为“图纸 / 图层”页签。图纸行提供详情、版本、检查、任务、更多及删除操作；状态标签与原因单行展示，长原因悬停可读。图层页签内左侧增加可搜索的图纸目录，分页加载工程范围内全部可读图纸，选中后按 drawingId 筛选并重置页码，切换工程范围清除图纸筛选；右侧图层行提供查看、样式、移动和定位。版本配准打开全屏工作台，上排原始 CAD 平面与浏览器直连高德地图左右等宽，下排业务区横向铺满，分为搜索候选、点对表、结果与确认三个区域；支持线路名＋站名多候选、选候选后点 CAD 成对、手工取点和微调、预览、保存、确认和清除。候选列表在业务分区内有界滚动，不遮挡地图；点对表保留全部列。上传只选线路/工点，不再选择标段、专业或坐标方案；目录样式参考物理工点台账，图纸/图层台账在 1920×911 视口下平铺展示关键列。
删除图纸：图纸行删除按钮及 DELETE /gis/drawings/{drawingId} 均使用 gis:drawing:edit，服务端复核工程范围。确认后逻辑删除图纸，图纸及附属图层、要素从列表、地图及详情读取入口移除；存在业务绑定或 QUEUED/RUNNING 任务时返回冲突，不进行部分删除。历史版本、不可变修订、绑定历史和源文件保留，不物理级联删除业务单据。成功后刷新图纸、图层和图纸目录，并清除已删除图纸的筛选。
版本配准：有 gis:drawing:edit 的用户在数据管理图纸行“更多 → 版本 → 配准”进入。先在原始 CAD 上点地物，再选高德候选或手工点底图同一点；支持相似变换（至少 3 点）和仿射变换（至少 4 点）。高德 JS SDK、PlaceSearch 和瓦片由浏览器直连，Web 服务 Key 不下发。保存前显示拟合 RMS/最大残差；服务端重新拟合，参数保存在版本 GEOREF_CONFIG，状态为 REFERENCE，不宣称测量精度。保存时派生 EPSG:4326 成果，地图只投影到 3857，不再二次套配准；清除本版配准后地图不再显示该版几何，版本和源文件保留。
高德浏览器配置：GET /gis/amap/js-config 供图纸配准和物理工点线路预览共用，拥有 gis:drawing:edit 或 business:siteMaster:edit 任一权限即可读取。接口返回浏览器 JS Key、安全码、搜索城市和 SDK 版本。图纸数据和配准操作仍由各自的 GIS 接口单独鉴权。
跳转与验收：底图切换、图层定位、图元详情及底图故障恢复可用；验收 AC-GIS-001、002、007、008、014～018。
以下 3.2–3.5 的独立图层/图纸/任务/要素页面是历史设计，已合并为“数据管理”（P-GIS-002）。规格保留用于数据模型和后续能力参考，对应菜单路由已删除，不再作为入口。
3.2 P-GIS-004 图层管理（历史设计，已合并）
这是工程 CAD 入图和业务图层组织的主要入口。
text
左：线路 → 工点 右上：当前工程范围／必要标段／专业筛选
线路 A 查询：图层名、来源、专业、可用性
工点 A1 工具：新增标绘图层、上传 CAD、刷新
工点 A2 列表：图层、来源、专业、要素、显示规则、操作
线路 B 选中图层 → 详情、源层映射、样式预览| 内容 | 规格 |
|---|---|
| 左导航 | 使用 PBS 线路/物理工点 ID，按授权过滤；仅展开当前线路。受限人员可见线路导航但不因此有整线成果权 |
| 右侧上下文 | 显示当前线路/工点；专属资源再选择有效标段，必要时选择单位工程；不要求用户重填名称 |
| 筛选 | 名称/编码、专业、来源（CAD/标绘）、关联图纸、可用性；工程由左导航约束 |
| 列表 | 图层名称、工程归属、专业/用途、来源图纸/版本、源层名、可见要素数、默认显隐/可选/锁定、顺序、可用性、操作 |
| 工具栏 | 新增标绘图层、上传 CAD、刷新；有维护权才显示写入动作 |
| 行操作 | 查看、修改、样式、源层映射、地图定位；未被引用的空人工图层才允许删除 |
| 基本表单 | 名称、实际工程范围、专业、用途、默认顺序/透明度/显隐/可选/锁定、有效缩放范围；编码由规则生成或校验唯一 |
| 样式 | 点符号、线色/线宽/线型、面填充/边线、文字字段与样式，按几何类型显示；图例预览使用可读样本 |
上传行为：
- 选择工点后点击上传，自动带入线路和工点；有效标段不唯一时要求选择，不能用首条标段默认落库。
- 选线路节点上传时，须有相应整线处理权才可声明“整线完整成果”；受限人员进入其合法工点范围后操作。不能把仅在某工点选择上传的全线图纸视为工点专属文件。
- 上传表单默认当前工程、允许专业和适用坐标方案。允许多专业图纸进入受控检查，单个专业预选不等于确认整份 CAD 只有该专业。
- 文件接收后进入任务页/检查页；图层列表可查看对应任务状态，未合格成果不能自动成为正式业务图层。
- 源层名称只作解析来源；经检查映射到一个或多个实际业务图层，混合专业源层需按要素分类。不得从“土建/电气”等名称关键字推断最终授权。
- 映射及分类变更必须重新检查源/目标工程和专业、引用和当前授权；保存映射不等于允许整包下载。
图层管理与地图使用同一图层 ID。进入图纸详情、任务详情、地图定位后可返回原工点及筛选。工程归属带入解决登记与定位，后端联合授权、混合文件检查仍须执行。对应 AC-GIS-010～013、021、024。
3.3 P-GIS-002 CAD 图纸管理（历史设计，已合并）
用途：跨已授权范围查询文件资产、版本和处理情况。不是第二套图层组织工具；上传复用图层管理的同一流程，缺工程上下文时先选择合法归属。
| 内容 | 规格 |
|---|---|
| 筛选 | 图纸名称/编码、线路、工点、有效标段、专业、文件格式、版本使用情况、处理结果、上传时间 |
| 列表 | 图纸名/编码、工程范围、受控专业、当前有效版本、最新处理情况、源格式、图层/要素数、上传人/时间、操作 |
| 工具栏 | 上传 CAD、刷新；不提供未经核对的“全库导入/清空” |
| 行操作 | 详情、上传新版、成果检查、版本对比、地图定位；源文件下载单独鉴权 |
| 上传表单 | 工程范围、图纸名、文件、坐标定义/转换方案、专业声明；新版本选择已有资产并带预期当前版本 |
| 反馈 | 接收成功返回版本/任务 ID，跳任务或图纸详情；格式/内容/权限失败保留已填字段；不能提示“正式入图成功” |
D-GIS-001 使用基础信息、版本记录、处理记录和引用区域。每个版本显示源摘要、处理方案版本、合格情况及使用关系，支持查看对应 D-GIS-002/003/004。原文件和完整预览检查整体处理/下载范围，不返回本机存储路径。
D-GIS-002 为“左检查项与源层映射、中原图/候选受控预览、右问题及来源属性”的检查工作台。检查项涵盖文件依赖/图元完整性、工程范围、专业分类、坐标及误差、人工覆盖/关联冲突。未通过项显示具体原因与处理入口；只有完整条件满足且有图纸维护权时可“设为当前有效成果”，后端再次验证并原子切换。
D-GIS-003 选择同资产两个版本，查看新增/删除/变化图元、来源映射和人工覆盖冲突。差异表与地图联动；可确认迁移或保留冲突，不提供默认全部接受。操作不改写旧版本。图元拆分合并不得凭新 handle 重绑旧业务。
验收：候选/失败记录可查，离页不丢任务；新版失败保留旧有效版，部分专业人员不能整包读取；AC-GIS-003～006、009、012、021。
3.4 P-GIS-003 转换任务管理（历史设计，已合并）
| 内容 | 规格 |
|---|---|
| 筛选 | 任务号、图纸、线路/工点、状态、阶段、提交时间 |
| 列表 | 任务号、图纸/版本、工程、转换方案版本、阶段/状态、处理数/缺项数、提交/开始/结束时间、耗时、操作 |
| 操作 | 详情、查看图纸、失败/待处理后的受控重试；无“强制成功”按钮 |
| 重试 | 显示失败输入及补正项，固定新输入快照；生成新尝试并关联上一尝试，不能覆盖历史结果 |
| 自动刷新 | 仅有运行中任务时有限轮询；离页停止轮询，服务端继续；没有可靠进度时只显示阶段 |
D-GIS-004 显示输入文件摘要、解析器及参数版本、阶段/耗时、原对象/输出/失败分类统计、缺项明细和尝试链。缺项明细至少包含实体类型、图层、源实体句柄、模型空间坐标或包围盒、原因及适用时的环/段号，支持复制坐标和句柄；错误信息同步带出前几条可定位摘要，完整明细以结构化列表展示。明细读取任务版本引用的原始清单 stats.issues[].details，不新增数据库列；任务列表不读取清单，只有任务详情填充 issues。日志只显示脱敏诊断。重试成功后进入检查，不自动切换有效成果。权限变化后任务详情和结果需重新鉴权。
验收：排队、处理、待资料、成功和失败各有可理解状态；同任务双击重试不产生重复尝试，旧回调不覆盖新结果；AC-GIS-017、019、021。
3.5 P-GIS-005 要素成果管理（历史设计，已合并）
| 内容 | 规格 |
|---|---|
| 筛选 | 名称/ID、线路/工点、标段、专业、业务图层、来源图纸、几何类型、是否关联业务 |
| 列表 | 名称/稳定 ID、工程/专业、图层、几何类型、来源/版本、关联摘要、资源版本、更新时间、操作 |
| 操作 | 查看、地图定位、维护属性/绑定、导出所选或查询范围；几何调整跳转至“线网地图” |
| 详情 | 当前属性和样式、CAD 来源及派生关系、坐标/高程说明、人工覆盖、修订与业务关联 |
| 业务绑定 | 选择受支持业务类型，再查询该工程/专业内有权业务对象；支持解除 GIS 关联，不删除原业务单 |
| 导出 | 明确范围、文件格式/坐标、数量与任务结果；后端按当前授权输出，不能导出页面未授权的全层 |
属性、关联和地图几何共用资源版本检查。当前 GIS_FEATURE 的存量 ID 迁移时保留；历史源 handle 不是稳定业务键。台账分页不把视口内前若干条冒充完整查询。对应 AC-GIS-007～014、024。
3.6 P-GIS-006 底图服务配置
| 内容 | 规格 |
|---|---|
| 筛选与列表 | 服务名称/提供方、协议、可用性、验证情况；显示坐标系、底图/注记组合、坐标/矩阵、覆盖/层级摘要、引用场景、最近检查时间 |
| 基本表单 | 编码、名称、提供方、协议 WMTS/VECTOR_STYLE/JKT_TILE、源坐标系下拉框、初始镜头高度、受控服务地址、使用条件与署名；坐标选项取自启用的内部 3857/4490 定义，WMTS/VECTOR_STYLE 使用 3857，JKT_TILE 使用 4490，初始镜头高度默认 13 级 |
| 图层参数 | 基础层与注记各自的 layer/style/format/matrixSet、矩阵标识/分辨率、范围和层级；自动读取后仍可核对来源 |
| 调用配置 | 浏览器直连/受控服务端代理、鉴权类型和凭据配置引用；不提供服务器 Key 明文读取框 |
| 操作 | 新增/修改、读取能力、出图预览、引用检查、停用；仅无引用定义可删除 |
能力文档读取只能访问受控目标，不能成为任意 URL 代理。元数据读取成功、服务端取瓦片和浏览器网络/CORS/实际出图分别显示结果；无可访问网络时记录未验证。服务变更保存前显示引用场景及默认底图影响，校验失败不替换当前可用配置。
天地图 Key 从私有根 README 的“其他服务与外部集成 → 国家地理信息公共服务平台（天地图）”取得，通过环境配置注入；数据库只存引用名。浏览器端 Key 在获准直连调用时按需交给地图客户端，不能将其描述为浏览器不可见；服务器端 Key 始终由服务端读取。
未来三维服务在条件满足后扩充适配；本期不为此注册虚假的可用 3D 服务。对应 AC-GIS-001、017、020、023。
交开投影像适配
GET /gis/base-maps/crs-options复用gis:baseMap:list，返回字符串 ID、编码和名称，不重新开放通用 CRS 管理。JKT_TILE使用JKT_GEOGRAPHIC_HEX_V1固定网格，JSON 仅允许gridProfile及一个 BASE 图层名称；原点为[-400,399.99935]（纬度含 2026-11-08 实测校准 −0.00065°：供应方影像内容相对天地图真值恒定北偏约 72m，按恒定平移南移校正），19 项分辨率索引为源层级 0～18，瓦片 256×256，行列按八位小写十六进制编码。- 浏览器以平台登录态调用
/gis/base-maps/{serviceId}/tiles（gis:scene:query鉴权、no-store），上游地址、账号与 token 全程留在服务端。服务按credentialRef从环境变量或GIS_JKT_CREDENTIALS_FILE指定的私有文件读取JKT_MAP_USERNAME与JKT_MAP_PASSWORD_MD5（或JKT_MAP_PASSWORD）。 - 服务端代理固定精确 origin 白名单（
gis.basemap.jkt-allowed-origins，默认当前上游），管理端不能将代理用作任意地址转发；瓦片响应限 2MB 并校验 PNG 魔数与 256×256 尺寸，异常信息不含上游地址、账号或 token。 - 服务端换取 token 后按来源与凭据维度缓存，按 JWT
exp提前一分钟刷新；瓦片返回 401、403 或明确的 token 过期、失效信息时刷新并重试一次。 - 底图配置的检查动作由服务端实取一张瓦片验证连通与凭据。服务与代理入口已恢复注册；生产需开通后端到上游
113.207.1.170:5005的出方向访问（2026-11-08 实测华为云 VPC 三台主机均未放行，开通前生产交开投底图无法出图）。 - 前端使用现有 OpenLayers 的 ImageTileSource、自定义 TileGrid 和 4490↔3857 显示近似转换，参与原底图显隐、加载状态、重试与销毁。无独立注记，切换沿用当前视角与业务图层。
3.7 坐标系与转换方案（已退出）
2026-10-23 已删除坐标系定义、转换方案和校准页面/API。GIS_CRS 仅作为内部标准定义目录保留 EPSG_3857/EPSG_4326/EPSG_4490 及底图引用，不向用户提供维护入口，也不作为上传前置条件。
3.8 转换方案校准（已退出）
全局方案校准不再存在；配准点对、参数、残差和确认记录随图纸版本保存在 GIS_DRAWING_VERSION.GEOREF_CONFIG。
3.9 P-GIS-009 地图场景配置
| 内容 | 规格 |
|---|---|
| 筛选与列表 | 名称/编码、用途（主系统/既有驾驶舱）、工程范围、可用性；显示默认底图、图层组合（全部/自选 N 层）、版本与更新时间；系统默认场景带“系统默认”标识 |
| 配置区域 | 基本信息、允许底图/默认底图、业务图层组合、初始视图 |
| 图层组合 | 单选“全部图层/自选图层”。全部图层模式自动纳入场景工程范围内全部已发布、当前账号可读图层，不写逐层关系，提供“打开时显示全部图层”开关；自选图层模式配置场景内顺序、初始显隐/透明度/可选性，不复制图层/几何 |
| 底图注记 | 场景初始是否显示底图独立注记；仅对带独立注记层的 WMTS 底图生效，矢量样式底图明确提示随样式 |
| 初始视图 | 优先工程范围适配；需要固定视图时明确范围/中心、初始缩放和缩放上下限，不能固定示例区域。工程范围适配使用主体范围并剔除离群图层 |
| 操作 | 新增/修改、预览、受控启停；保存时校验引用、图层场景范围、版本和系统默认场景保护 |
配置优先级：源 CAD 样式 → 图层公共样式 → 场景显示覆盖 → 当前用户临时偏好；场景覆盖不能把业务只读资源变为可编辑。
D-GIS-007 预览显示所用配置版本并以当前账号权限加载；不提供前端“模拟管理员”开关。保存失败保留输入；保存成功后明确后续打开/刷新采用新配置，不打断正在编辑的会话。公共场景也不意味着其工程图层公开。对应 AC-GIS-016、021、023。
场景范围与默认场景：保存、预览和运行均校验图层是否属于场景的线路/工点范围；非 PUBLIC 场景打开前校验当前账号是否具备对应整线或工点范围，不通过返回 403。SYSTEM_DEFAULT 为线网地图入口：编码不可修改，不能新建、停用或删除；默认底图必须在允许集合内且启用。全部图层模式只返回当前账号可读的已发布当前版本图层，不因“全部”扩大权限。
3.10 进度专题配置（本期取消）
本期 GIS 不提供专题页面、专题数据源注册/占位适配、场景允许/默认专题、专题统计和专属权限。后续专题由对应业务模块建设，GIS 场景只配置底图、图层组合、样式覆盖和初始视图。
3.11 P-GIS-011 专业权限管理（本期移出）
布局：主体查询/列表 → 该主体的真实工程范围 → 专业操作矩阵与授权结果。先按用户主体落地；不默认引入角色继承或组织自动授权，扩充主体类型需先解决 Q-GIS-004。
| 内容 | 规格 |
|---|---|
| 主体查询 | 登录账号/姓名、当前授权情况；组织只作查找，不等于按组织授予数据 |
| 工程范围 | 只读取得平台真实整线/标段工点组合或共享资源范围；提供既有工程授权入口，不在 GIS 修改工程授权 |
| 专业矩阵 | 每条完整工程单元内选择现有专业代码及查看、维护、导出、下载；只读参考与维护分开 |
| 整体文件处理 | 对指定图纸版本授予检查/归类范围，单独展示；不把它混为一个名叫“全部专业”的普通授权 |
| 操作 | 查看、保存、撤销已授范围、验证指定资源的当前判定；保存带授权修订号 |
| 反馈 | 显示有效授权与因上游工程范围不足而未生效的项，不暗中扩大工程范围；并发冲突保留草稿 |
维护专业包含新增/修改/删除的专业范围许可，实际执行仍须对应功能动作权；导出/下载必须单独授予。读取也受工程上限约束。综合专业、父子专业不自动包含，默认不做可扩张继承。
授权验证调用真实服务端判定，展示有权管理范围内的“功能权/工程范围/专业动作”结果，不能伪造目标用户身份下载其数据。A 工程电气＋B 工程土建不能变成 A 工程土建。完整文件处理权不用于普通地图分发或替代下载权。对应 AC-GIS-010～013、024。
4. 页面间核心链路
| 链路 | 跳转条件与结果 |
|---|---|
| 图层管理 → 上传 → 任务 | 带工程 ID/合法组合和允许专业；服务端重新判定，返回图纸版本/任务标识 |
| 任务 → 成果检查 → 有效版本 | 成功任务只产生候选；缺项、配准或权限不合格不能切换 |
| 版本配准 → 预览/保存/确认 | 服务端重新拟合，按版本修订条件保存；确认只推进修订，不重新派生 |
| 版本对比 → 生效 → 地图 | 更新来源与对应修订，保留稳定业务 ID；旧会话保存明确冲突 |
| 要素台账 ↔ 地图 | 带要素 ID/版本、工程上下文与本站返回路径，不带前端几何覆盖事实 |
| 配置 → 场景预览 → 使用 | 预览验证当前配置和当前账号；场景只是展示组合，不授予权限 |
5. 页面服务契约与状态
5.1 当前接口兼容边界
线网地图读取使用 GET /gis/scene（默认系统场景）和 GET /gis/scene/{sceneId}（显式场景）。响应在原有底图、中心/缩放之外增加 viewMode、extent、fitExtent、fullExtent、fitExcludedLayerCount、defaultServiceId、baseMapNotice、layerScope、allLayerVisible、annotationVisible、catalogApplied、drawings 和 layers；layers 已按当前账号和场景范围过滤，并携带图纸名、版本、样式、最小/最大层级和初始显隐。显式场景打开前校验场景工程范围，不通过返回 403。底图运行时返回 annotationSupported，标记是否支持独立注记开关。
要素读取保留 GET /gis/drawings/{drawingId}/features（按图纸一次取回勾选图层，线网地图使用）和 GET /gis/layers/{layerId}/features（单层读取，保留给其他调用方）；GET /gis/drawings 与 GET /gis/drawings/{drawingId}/layers 继续服务数据管理，不在地图打开时逐图纸调用。场景候选 GET /gis/scene-configs/options 增加 lineId、siteId、resourceType，按当前场景工程范围过滤。接收使用 POST /gis/drawings/receive，版本配准使用 /gis/drawings/{drawingId}/versions/{versionId}/cad 与 /georef 系列接口。旧同步 /gis/drawings/import、图纸级 /georef 和后端高德候选接口已退出，不再保留兼容实现。
当前上传使用合法工程 ID、原始 CAD 解析和异步任务，不再传坐标方案或近似参数；版本配准绑定 drawingVersionId、输入尝试和源摘要，服务端重新拟合。当前仅成功图纸列表不复用为完整图纸台账，视口限量查询不复用为要素台账分页。
5.2 目标接口族
本表固定页面所需的语义字段，具体 HTTP DTO/路径实施时按平台规范补齐；不把目标接口写成现有事实。
| 接口族 | 必要输入 | 必要输出 | 事务与约束 |
|---|---|---|---|
| 工程导航/上下文 | 当前用户、受控搜索条件 | 合法线路/工点、组合候选和可执行能力 | 服务端按当前工程授权过滤，不能读取全树再隐藏 |
| 图层维护 | 工程范围、专业、来源、显示定义、预期修订 | 同一图层 ID/最新修订及引用影响 | 改归属检查源和目标，更新缓存；不搬动源 CAD |
| 图纸接收/新版 | 文件、资产/版本上下文、真实工程 ID、图层范围、请求标识 | drawingId、versionId、attemptId、接收状态 | 文件暂存与记录补偿；任务持久化，接收不等于生效 |
| 任务/检查/重试 | 任务或版本 ID、补正输入、预期状态、请求标识 | 阶段、缺项分页、候选与新尝试关系 | 当前权限和整体处理范围；失败不改旧有效版 |
| 版本配准 | 点对、方法、输入尝试/源摘要/配准修订 | 参数、残差、派生清单引用和状态 | 服务端重新拟合；客户端矩阵不作权威；按修订条件保存 |
| 场景/服务配置 | 各自定义、引用 ID、预期修订 | 配置版本、可用性与校验结果、引用影响 | 凭据不入 DTO；引用真实存在且获准，更新原子化；不配置专题 |
| 要素/业务绑定 | 完整要素 ID/修订、有效目标业务 ID、变更集 | 最新修订及服务端结果 | 源/目标权限、几何有效性、幂等和并发 |
| 专业授权 | 用户、完整工程单元、专业操作或指定文件处理项、授权修订 | 新修订及有效授权 | 不增加上游工程权；多行原子保存，不做独立维度并集 |
查询分页与错误响应沿用平台 PageQuery/PageResult、R 和异常机制。ID 保持 string | number 原值。坐标、单位、枚举、日期及版本在 DTO 中明确；不使用 any 或 JSON 任意透传替代业务校验。界面仅展示白名单脱敏错误。
5.3 目标 HTTP 组织与写入信封
以下为后续新增接口目标，不表示已存在。现有五个接口保留兼容；新列表均返回平台分页结构，详情/保存返回 R。标准资源按照 GET /list、GET /{id}、POST、PUT、DELETE /{ids} 组织；不支持的删除不能因套生成器而出现。
| 接口族目标 | 查询/写入边界 | 页面与权限资源 |
|---|---|---|
| /gis/drawings/list、/gis/drawings/ | 完整受控台账/资产详情，区别旧成功目录 | 图纸管理；gis:drawing |
| POST /gis/drawings/receive | 共用 multipart 文件接收；固定工程、图层范围和请求标识，返回版本/任务 | 数据管理；gis:drawing:upload |
| /gis/drawings/{drawingId}/versions | 版本列表/受控检查，具体 versionId 路由需验证资产归属 | 图纸检查/对比；gis:drawing:query |
| POST /gis/drawings/{drawingId}/versions/{versionId}/activate | 预期当前版本、修订及请求标识；原子生效 | 图纸检查；gis:drawing:edit |
| GET /gis/drawings/{drawingId}/versions/{versionId}/cad、/cad/features | 原始 CAD 层目录与分页实体；绑定版本、输入尝试和清单摘要 | 数据管理版本配准；gis:drawing:query |
| GET/PUT/DELETE /gis/drawings/{drawingId}/versions/{versionId}/georef、POST /georef/preview、/georef/confirm | 版本点对、拟合、保存、确认和清除；服务端重新拟合并按 georefRevision 条件更新 | 数据管理版本配准；gis:drawing:edit |
| /gis/tasks/list、/gis/tasks/ | 当前授权下的任务与脱敏报告；详情额外返回 issues（类型、图层、句柄、坐标/包围盒、原因、环/段号），列表不读取原始清单 | 转换任务；gis:task:list/query |
| POST /gis/tasks/{attemptId}/retry | 补正输入/预期状态/请求标识，返回新 attemptId | 任务详情；gis:task:submit |
| /gis/layers/list 及标准维护接口 | 业务图层及其工程/专业/样式；源映射与元数据分开校验 | 图层管理；gis:layer |
| /gis/features/list、/gis/features/ | 台账分页与完整要素，不能复用限量视口结果当总量 | 要素成果；gis:feature:list/query |
| POST /gis/features/changes | 包含几何/属性/绑定的原子变更集 | 地图与要素；逐项校验 add/edit/remove |
| POST /gis/features/export | 查询范围/所选 ID 及明确格式/坐标；受控结果引用 | 要素成果；gis:feature:export |
| /gis/base-maps | 底图服务维护，传预期配置修订；坐标只接受内部标准 EPSG_3857 | 配置；gis:baseMap |
| /gis/scene-configs | 场景维护及引用查询，区分运行配置白名单；不含专题字段 | 配置；gis:sceneConfig |
| /gis/authorizations/ | GET 当前 GIS 授权与修订；PUT 完整变更集，不能改工程授权 | 专业权限；gis:authorization:query/edit |
普通地图继续通过 /gis/scene 的运行契约取得其可用配置；场景运行不查询专题表或返回专题槽位。完整文件读取增加基于真实版本/业务资源的受控入口并核对既有 OSS 旁路，不能在表单直接拼任意下载 URL。原始 CAD 的 kkFileView 预览（/preview 签发、/preview-view 代理、/preview-source 回源）已于 2026-10-24 整体退役：上述接口不再存在，旧地址不返回文件；源文件仅保留受控下载。后续原始 CAD 预览由 BIM 引擎承担，本期未实现。
变更集顶层包含 requestId、工程上下文和 changes；每项包含 action、稳定资源 ID（新增时由服务器生成）、expectedRevision，以及该动作允许的几何/属性/归属/绑定字段。服务端按资源实际值验证，不接受客户端自报的原归属、操作人或可编辑状态。新增、编辑和删除分别检查功能动作权；混合集合一次提交不能部分成功。
配置保存包含记录 ID、expectedRevision 和受允许的定义字段；复合场景保存同时更新默认引用与允许集合。专业授权保存带主体 expectedRevision 及新增/修改/撤销项，未出现在变更集中的授权不删除。坐标定义/方案新版本使用新 ID，并关联同编码版本序列。
失败至少区分：输入/几何错误、无权、资源不存在或不可访问、并发冲突、资料/校核不足、受引用不能删除、外部依赖失败、任务已过期及请求结果待确认。沿用平台错误响应；冲突采用现有 409 语义，资源存在性信息按权限隐藏，错误明细只返回有权字段。每个写入接口在实际实施时将字段可空、限制、枚举及幂等窗口补成对应 BO/VO 契约，并与数据库矩阵逐项核对。
5.4 最小状态/权限矩阵
| 当前条件 | 可见/可操作 | 动作结果及失败恢复 |
|---|---|---|
| 只有地图查看权且范围命中 | 看授权图层和允许详情 | 不显示配置/编辑动作，直接写接口仍拒绝 |
| 具备功能编辑权但专业只读 | 参考与定位，不能修改 | 保留只读提示，不把锁定按钮当权限开关 |
| 已选工点且有上传及处理范围 | 上传绑定该工程，必要时选标段 | 接收后跳任务；后台任务不因离页停止 |
| 图纸未分类且无整体处理权 | 不返回完整原图、预览及检查项 | 显示无权处理，不因上传者身份放行 |
| 图纸候选有缺项/近似坐标 | 有权检查者可查问题，不能设为合格 | 补正新尝试，保留旧有效版本 |
| 成果合格且有维护权 | 可确认设为当前有效版本 | 再次检查当前指针与关联，冲突不静默覆盖 |
| 已使用坐标定义/方案 | 只读该版，可创建新版本 | 历史成果不自动变化 |
| 配置正在被场景引用 | 可查影响；删除被阻止，停用需处理默认引用 | 不制造静默失效或切换到未授权公网服务 |
| 保存冲突/请求结果未知 | 保留输入与原请求标识 | 重读或确认结果，不盲目新增 |
| 权限撤销 | 停止读取、展示与自动保存无权资源 | 缓存和幂等结果读取同样拒绝 |
6. 页面权限与数据范围
以下为目标权限契约，除概要标明的五个已实现动作外尚需实施登记；不表示已创建菜单或按钮。动作只使用平台白名单，后端/菜单/前端逐字一致。
| 页面/资源 | 读取 | 维护及其他动作 | 数据范围 |
|---|---|---|---|
| 地图与场景运行 | gis:scene:query | 要素/图层按各自动作 | 普通用户可用配置白名单＋工程/专业过滤 |
| 图层 | gis:layer:list、query | gis:layer:add、edit、remove | 实际工程类别＋专业，源层映射含完整处理权 |
| 图纸 | gis:drawing:list、query | gis:drawing:upload、edit、download | 图纸整体范围；详情、检查与下载分别检查 |
| 转换任务 | gis:task:list、query | gis:task:submit（提交重试） | 继承所属图纸版本范围，检查结果可能需整体处理权 |
| 要素 | gis:feature:list、query | gis:feature:add、edit、remove、export | 真实要素工程＋专业，绑定额外检查业务域 |
| 底图服务 | gis:baseMap:list、query | gis:baseMap:add、edit、remove | 纯公共元数据按功能权，工程受控服务额外范围；凭据不下发 |
| 场景配置 | gis:sceneConfig:list、query | gis:sceneConfig:add、edit、remove | 配置维护权限与运行 gis:scene:query 分开；引用资源逐项鉴权 |
| 专业授权 | gis:authorization:query | gis:authorization:edit | 管理者可授予上限；不依靠自身普通图形编辑权授予 |
表内逗号后的动作沿用该行前缀，例如“gis:layer:list、query”表示 gis:layer:list 与 gis:layer:query。场景渲染不要求普通查看者取得管理配置接口权；服务端运行接口仅返回其可读结果。
2026-10-24 专业范围权限取消：整体文件处理授权（FILE_PROCESS）与专业授权已整体退出，不再作为任何入口的访问条件或待完成事项；原始整文件下载/预览/回源按“功能权＋完整工程范围”执行（GisFileAccessGuard），专业代码、专业授权记录与归类证据不参与判定。授权检查发生在过滤、计数、预览、导出、文件读取及变更保存全链路，不能只为左侧导航过滤。本节及数据库设计中关于专业授权存储/判定的描述转为历史设计，对应表保留存量数据不再被读取。
7. 配置引用、事务与失败处理
| 场景 | 处理 |
|---|---|
| 图层/场景/专业策略并发维护 | 带预期修订并条件更新；冲突保持草稿，重新读取后处理 |
| 一份 CAD 多专业/多工程 | 保留完整源文件与版本的范围清单，按源层/要素形成受控成果；一个工点入口不授予整图权 |
| 版本配准修正 | 服务端重新拟合 → 派生新对象 → 按 georefRevision 条件保存 → 当前版原子切换；禁止批量 UPDATE 旧几何。整版图元按块批量写入，不得按图元逐条往返 |
| 同版重配准修订 | 当前有效版每次重配准均新增不可变 GEOREF 修订，不下载旧几何 CLOB 作判等；保留人工属性、名称、覆盖信息与业务绑定，并以 REVISION / CURRENT_REVISION_ID 条件切换当前修订。其他版本生效入口仍保留原有几何判等 |
| 请求内派生分块复用 | 新生成分块按请求暂存，累计字节上限 32 MiB；复用字节仍执行与读取侧相同的 SHA-256、大小、归属、范围、数量及稳定键边界校验。超限分块继续从存储读取校验，不放宽校验、不使用跨请求缓存 |
| 原始清单与分块读取缓存 | 读取侧按摘要（无摘要时按对象路径）在进程内缓存原始字节，合计上限 48 MiB、单条 8 MiB，按最久未使用淘汰。命中只省去对象存储读取，仍逐次执行摘要、大小、归属、范围、数量及稳定键边界校验；写入侧派生分块的请求内复用仍按上一行处理 |
| 地图按图纸取图 | 线网地图一张图纸一次请求取回其勾选图层（GET /gis/drawings/{drawingId}/features），不再逐层往返；单层无权或不属于当前版本时列入 skipped，不阻断其余图层。图层要素几何按 layerId + versionId + georefRevision + layerRevision 缓存在进程内（合计上限 64 MiB、单层 8 MiB，LRU）；重配准、重建派生或图层修订变化即失效重读，超出单次上限的不完整集合不进入缓存。缓存命中只省去几何 CLOB 读取与 JSON 解析，返回仍按请求上限截断；客户端按图层范围记录覆盖 bbox，图纸范围内平移缩放不重复取图 |
| 图纸删除与维护并发 | 删除沿用 gis:drawing:edit；图纸逻辑删除后附属图层、要素、版本、下载和任务入口均不可访问，历史修订与源文件保留。当前要素有业务绑定或任一版本仍有排队/运行解析任务时拒绝删除；删除、版本生效、重配准、接收新版本、任务重试、异步任务领取和人工绑定保存先锁父图纸行，再改子对象 |
| 同一版本重复提交配准 | 按版本串行：重建进行中的重复请求立即返回 409「该版本配准正在保存」，不重复重建；单次保存耗时随图元数增长，页面保持等待状态而不是超时后立即重试 |
| 场景引用失效 | 保存时检查并明确缺项；运行时跳过无权工程内容且不泄露名称，对必要底图错误明确提示 |
| 文件存储成功但记录失败 | 按任务/请求标识回收本次可确认孤立对象，不删除旧文件；后续重试可追溯 |
| 重复上传/保存/重试 | 主体＋业务上下文＋请求标识＋内容摘要约束；同标识异内容拒绝 |
| 元数据正常但浏览器无法出图 | 独立记录实际网络/鉴权/CORS验证结果，保留可用配置，有限重试 |
| 公共配置停用 | 阻止新引用；默认使用中的引用先替换/解除再停用；历史版本只读保留 |
| 业务接口失败 | 几何事实保留；业务覆盖显示失败而不是正常；不回滚先前成功的几何保存 |
8. 页面实施与验收顺序
当前已交付 4 页：线网地图（纯查看）、数据管理（图纸/任务/图层及版本级配准）、底图服务配置、地图场景配置。联合权限、上传/原始解析、多候选配准、检查/生效和三套底图已实现；要素几何编辑、专业权限、专题、驾驶舱和三维仍是后续能力，不得把历史 UI 用例中的编辑或专业动作当作本期可用。页面验收不得只提交菜单、表格空壳和 Mock 成功提示。
| 用例 | 用户动作 | 预期 |
|---|---|---|
| UI-GIS-001 | 在图层管理选工点上传 CAD，离页后打开任务 | 工程 ID 正确、必要组合明确，任务继续、可追溯回原图层上下文 |
| UI-GIS-002 | 受限工点人员选线路节点，尝试上传全线完整 CAD | 不能凭线路导航/客户端参数获得全线处理权 |
| UI-GIS-003 | 在图层和图纸两处上传相同业务请求 | 共用服务和幂等，图纸资产/任务不会因入口不同重复 |
| UI-GIS-004 | 检查未分类/缺字体/坐标待定成果 | 缺项具体可见，未合格不能成为正式有效版本 |
| UI-GIS-005（已退役） | 旧转换方案/校准入口已退出 | 标准坐标定义只内部读取；版本配准按点对在前端工作台完成 |
| UI-GIS-006 | 完成新版对比，遇到人工覆盖与来源拆分 | 不错误重绑，旧有效版与人工成果保留 |
| UI-GIS-007 | 管理图层公共样式，再在地图临时调显隐 | 公共配置与个人临时状态按优先级生效，授权不变化 |
| UI-GIS-008 | 从要素台账定位、编辑、保存、返回 | 同一 ID/版本与关联，查询和工程上下文可恢复 |
| UI-GIS-009 | 管理 WMTS 并预览，停用被默认引用的服务 | 真实出图与元数据验证分开，引用影响明确 |
| UI-GIS-010 | 普通账号打开无专题场景 | 看授权成果，无配置维护能力也能消费底图/图层/初始视图；无专题请求或字段 |
| UI-GIS-011 | 配置专业权限，直接请求异工程/异专业资源及混合原图 | 原始整文件后端按功能权、工程范围、专业/文件整体授权联合拒绝；图层/要素全面专业过滤仍待 Q-GIS-004 政策确认（专业授权页面未进入本期菜单） |
| UI-GIS-013 | 在数据管理版本行取多个 CAD/高德点对，保存/确认后刷新；再同版重配准和清除 | 预览和刷新按版本参数显示，线网地图无配准入口；同版重配准保持 ID/样式/归属/绑定；清除后地图不再显示该版几何 |
| UI-GIS-012 | 复制子页面地址、刷新、返回，或修改资源 ID | 合法入口可达；无权不能绕过；返回恢复原筛选 |
| UI-GIS-013 | 并发保存、超时重试、授权撤销 | 草稿保留，无重复新增、静默覆盖或幂等缓存泄露 |
| UI-GIS-014 | 在基准/收缩视口和浅深主题检查地图、列表及复杂检查页 | 工程导航、列表状态、操作、地图和返回均可达，无裁切 |
以上为后续实施用例，尚未执行页面验收。本轮核对范围为文档内容、导航、链接和与既有代码/实际表结构的差异。
2026-10-23 交互与存储补充
配准工作台（2026-10-23 版本级高德路线）
- 入口：数据管理 → 图纸行“更多” → 版本 → 该版本“配准”。图纸级“更多 → 配准”、上传“坐标方案”、旧坐标/转换页和旧专题页均已退出。
- 布局：全屏对话框，左侧为原始 CAD 平面 SVG（前端按原始 bbox 自适应、滚轮缩放、拖动平移），中间固定高德 JS API 地图，右侧 480px 操作区；底部操作栏固定可见且不换行。
- 数据来源：
GET /gis/drawings/{drawingId}/versions/{versionId}/cad返回原始层目录、bbox、单位和原始清单摘要；GET .../cad/features?sourceLayerKey&cursor&limit分页读取原始实体。前端只缓存已加载图元并在截断时明确提示。打开工作台时模型值与图纸版本两个监听会同轮触发初始化，按“图纸＋版本”合并为一次加载；原始图层按 4 路并发拉取、层内仍按游标顺序分页且保持图层顺序，左侧平面就绪即撤掉加载提示，不再等待高德 SDK。 - 查询：浏览器
AMap.PlaceSearch，城市限定重庆；线路名默认带入图纸所属线路，先查“线路名＋站名”，无匹配可仅按站名重查。候选按 POI ID 去重，展示名称、区县/地址、类型；不自动选第一条，不把输入线路伪造成返回线路。 - 配对：选用候选即成为待配底图点，右图落标记；在 CAD 上点同一位置形成一对，无需再次点底图。支持先 CAD 后底图、地图手工取点、单侧重选和删除；选中候选后可拖动标记或在附近点击微调，来源标“人工调整”并保留原 POI。已完成点对在 CAD 和高德地图上显示 P1/P2/P3 同号标记，点对表使用同一编号，当前修改行高亮。
- 预览/保存：至少 3 对相似或 4 对仿射；
POST .../georef/preview只计算返回参数、RMS 和残差，不持久化；PUT .../georef服务端重新拟合、遍历完整原始几何、派生 WGS84 清单并条件保存。客户端矩阵/残差不得作为权威。 - 确认/清除：
POST .../georef/confirm只确认已保存的本版成果，记录人/时间/修订；DELETE .../georef清除本版配准，当前版同时删除地图输出但保留版本和源文件。 - 状态：版本
REFERENCE（参考定位）/VERIFIED（已人工确认）/UNVERIFIED（未配准）；版本状态是唯一权威，图纸资产不保存镜像。确认不代表测量精度。 - 坐标链：拟合平面
GCJ02_WEB_MERCATOR（内部标识，不是标准 3857）；派生链为CAD x/y → 配准矩阵 → GCJ 墨卡托 → 反投影 GCJ → 本地近似逆算 WGS84。高德预览不先转 WGS84 再由浏览器加偏移；地图显示只把派生 WGS84 投到 3857，不再套图纸级配准。 - 网络：生产后端不出网；JS SDK、PlaceSearch、瓦片由浏览器直连高德，
securityJsCode按官方支持的浏览器方式在加载前设置并记录其可见性；Web 服务 Key 不下发浏览器。客户端无网时保留 CAD 和已完成点对，明确提示地图/搜索不可用。 - 已知边界：原始清单使用
CHUNKED_V2，同一图层按 2000 图元或约 2 MiB 继续切块，根清单记录块范围、数量、引用和摘要；开发库单图层 12,200 个 LINE 实测 7 个块，分页只读取覆盖目标范围的块。同版重配准已保留图层/要素稳定 ID、样式、手工属性和绑定；生效仍按当前 versions 条件写入显示层。旧CHUNKED_V1清单需重新解析。
版本级接口、状态与生效
| 接口 | 权限 | 说明 |
|---|---|---|
GET /gis/drawings/{drawingId}/versions/{versionId}/cad | gis:drawing:query + 工程范围 | 原始层目录、bbox、单位、inputAttemptId、rawManifestSha |
GET .../cad/features | 同上 | 原始实体分页，cursor 绑定原始清单 |
GET .../georef | 同上 | 本版配准状态、修订和已保存参数 |
POST .../georef/preview | gis:drawing:edit | 唯一服务端拟合，不持久化 |
PUT .../georef | 同上 + expectedGeorefRevision | 重新拟合、派生、条件保存 |
POST .../georef/confirm | 同上 + expectedGeorefRevision | 记录人工确认，递增修订 |
DELETE .../georef | 同上 + expectedGeorefRevision | 清除本版；当前版同步清地图输出 |
生效入口仍为 POST /gis/drawings/{drawingId}/versions/{versionId}/activate。V2 版本先在事务外读取并校验派生清单，再在事务内按源层名/实体键原地写入当前版本图层/要素并原子切换 CURRENT_VERSION_ID；校验失败不动旧当前版。检查页对 V2 增加“尚未保存高德配准成果”阻断项。
版本化图层、台账与场景覆盖（P5/P6 增量）
- V2 生效不再按
drawingId删除整份当前成果，而是只替换本版本DRAWING_VERSION_ID的图层与要素；旧版本图层/要素保留。当前版重配准、重复生效和当前版清除都只作用于本版本。 listLayers、要素查询、要素台账/导出/详情按当前 V2 版本过滤：图层必须DRAWING_VERSION_ID = CURRENT_VERSION_ID；旧版 null 或他版图层不返回/不可查看。历史版本仍可在数据库中追溯，但不进入当前地图和业务台账。- 场景运行响应新增
compositionApplied和当前账号可读layers（含visibleFlag、opacity、selectableFlag、排序和样式覆盖字段）。前端显式场景按compositionApplied区分“未配置图层”和“明确无可读图层”，不再把空组合自动展开为全部主线；已加载图层应用显隐、透明度和可选性。 - 底图配置固定 Web Mercator（EPSG:3857），服务端拒绝 4326/4490 等不匹配网格；底图页面不再请求通用 CRS 列表。
- 旧“坐标系与转换方案”菜单、坐标/转换页面、旧同步
/gis/drawings/import、图纸级配准和后端高德候选接口均已退出；退役表和列已物理删除。 - 仍未完成：要素稳定 ID 与版本关系、业务绑定/影响计数的完整当前版去重、样式覆盖 JSON 的实际渲染、原始清单分块。
线网地图
- 检索图纸、线路和图层；逐层状态为隐藏、加载中、显示中、需放大、部分、失败、无图元；失败就地重试。
- 刷新按图纸和图层 ID 合并，保留勾选、展开和镜头；“查看全部图纸范围”只改变镜头。
- 点选先高亮，多对象给出候选列表；详情展示图层、图纸、源 Handle 和文字。
数据管理与检查
- 图纸列表分“地图当前使用”和“最近一次处理”；动作收敛为详情、状态动作和更多。
- 返回恢复范围、页签和页码；请求序号防止旧响应覆盖。
- 检查页四状态与“换版将失效”清单；生效统一走检查页。
图层
- 运行时保存样式优先于源层名默认规则；样式保存为 revision 条件更新。
- 样式弹窗提供临时预览；“移动”更名为“调整归属”，线路根目录为显式选项。
存储与配置
- 源文件保存为
oss:gis/versions/<versionId>.<ext>；Worker 下载到storageRoot/tmp解析后清理；下载落临时文件后按需打开并在关闭时清理。 - 启动时迁移历史本地源文件；迁移失败的记录仍按本地路径读取。
- 天地图 Key 保存在
GIS_BASEMAP_SERVICE.CREDENTIAL_VALUE，管理接口不回显，运行接口按服务下发。 - 运行参数从
SYS_CONFIG读取：gis.cad.max-file-size-mb、gis.cad.worker-timeout-seconds、gis.georef.amap-city。 - 场景：
GET /gis/scene/{sceneId}返回允许底图、默认底图和视图；线网地图按layerIds启用场景图层；无 sceneId 时使用SYSTEM_DEFAULT场景视图。
2026-10-25 简化优化交互
数据管理主列表
- 图纸行只显示一个五态标签：处理中、待定位、待发布、已发布、失败；技术状态不再进入主列表。
- 每行只显示一个主按钮，由后端
primaryAction决定：VIEW_PROGRESS→ 查看进度；GO_LOCATE→ 去定位；PUBLISH→ 发布到地图；VIEW_ON_MAP→ 在地图查看；VIEW_FAILURE→ 查看原因。
- 已发布资产存在更新候选时，状态仍为“已发布”，旁边显示“新版本待定位/待发布/失败”徽标；主按钮仍为“在地图查看”。
- “更多”固定包含处理详情、版本、任务、检查、详情；处理详情抽屉显示来源、当前/最新版本、状态说明、失败原因和可用动作。
- 处理中的行每 5 秒刷新一次；页面失活/离页停止。
- 失败行提供“重试解析”和“重新上传”；重试不新建图纸资产，重新上传带入原线路/工点/图纸名称。
定位工作台
- 模式由图纸
siteId/resourceType决定，不在弹窗中让用户选：- 全线：
AMap.LineSearch搜线路 → 归并上下行/一期二期 → 站点去重 → 默认 3 个跨线站点 → 点 M1/M2/M3 → 在 CAD 点同一位置； - 工点：站名/工点名/地址搜索 → 选 3 个地物 → 在 CAD 点同一位置。
- 全线：
- 固定 3 点相似；不显示“相似/仿射”单选。第 3 点后自动调用
POST .../georef/preview，不需要“预览”按钮。 - 单点残差明显异常时提示重选该点；三点最大残差 >20m 或距离比例差 >1% 时提示“这张图可能不是等比缩放”，提供“改用四点仿射”；切换后保留前三点，补第 4 点。
- 主面板只显示比例、旋转、第 3 点偏差；“详情”抽屉显示拟合空间、RMS、最大残差、各点残差、参数、保存/确认人和时间。
- “确认位置”调用
PUT /gis/drawings/{drawingId}/versions/{versionId}/georef/confirm，一次完成保存+确认；成功后行变为“待发布”。 - “清除配准”移到“更多”。
接口与状态
| 接口 | 权限 | 说明 |
|---|---|---|
GET /gis/drawings/list | gis:drawing:list | 行内新增 displayState、primaryAction、stateDetail、statusReason、pendingVersionState、latestVersionId/latestVersionNo |
PUT .../georef/confirm | gis:drawing:edit | 组合保存+确认；请求体同 GisVersionGeorefBo |
GET /gis/scene/state | gis:scene:query | 当前账号有权范围的五态计数和 emptyReason；不返回未授权数量 |
PUT .../georef、POST .../georef/confirm | gis:drawing:edit | 保留为内部实现/回滚手段，页面不再直接调用两步 |
线网地图空态
- 无图时只显示一个空态卡片，按
emptyReason：NO_DRAWING：当前范围还没有已发布图纸 → 去数据管理；PENDING_PUBLISH：有 N 张图纸待定位/待发布 → 去处理；FAILED：有 N 张图纸处理失败 → 查看原因；PROCESSING：有 N 张图纸处理中 → 刷新；BASEMAP_ERROR：底图服务不可用 → 重试；- 搜索无匹配：清除搜索。
- 逐层状态仍在图层面板内展示（隐藏/加载中/需放大/部分/失败/无图元），不占顶层错误条。
- 统计只覆盖有权范围，空态文案不暴露未授权图纸名称或数量。
CAD 视图支撑
- 左侧 SVG 渲染 TEXT/MTEXT 文字，按高度和旋转变换；缩放不足时隐藏。
- 图层面板支持按源图层显隐和“只看中心线”；初始视野使用 2%–98% 分位 bbox，避免离群实体撑大视野。
- 保留 20,000 图元上限；超出时明确提示“未显示部分不参与取点”。
现行 CAD 解析与配准实现补充
- 新版本以
CAD_LOCAL_PLANE记录源空间，解析器从 DXF$INSUNITS读取单位；无法识别时为UNKNOWN。原始清单使用CHUNKED_V2，按源层及层内有界分块记录范围、数量、引用和 SHA-256，读取时核验；配准派生遍历完整源几何。CHUNKED_V1原始清单不支持重新配准，须按既有上传和换版流程处理；2026-10-24 回读时部分旧有效版本仍可展示已有派生成果，不能将其理解为旧原始清单已兼容。 - 服务端在
GCJ02_WEB_MERCATOR拟合人工控制点：相似变换需三对、仿射变换需四对；该拟合平面不等同标准 EPSG:3857。结果逆算为 WGS84 并生成EPSG:4326派生成果，地图再投影显示；人工确认不等于测量精度验收。 COORDINATE_STATUS以版本为权威，保存、确认和清除分别推进GEOREF_REVISION；确认沿用已有派生成果，不重复派生。请求级存储命名空间与条件更新避免失败请求清理其他请求成果，异常时只清理本次未引用对象。- 同版重配准以源层名和实体稳定键匹配，保留图层/要素 ID、人工样式、归属、属性和绑定；实体键以块实例路径和源 handle 为基础，缺失 handle 时使用类型与序号，写入前检查唯一。换版不按名称或最近距离自动迁移人工数据。
- CAD 解析按实例展开 MINSERT；HATCH 边界无法可靠解释时记录缺项，检查阶段不能静默当作完整成果。任务详情使用原始清单的问题明细展示可定位信息，旧清单无明细时展示摘要。
- 本期源文件下载按功能权限与完整工程范围校验；原始 CAD 的 kkFileView 预览链路已经退役。普通地图显示按当前有效图层的线路/工点归属过滤；可查看局部图层不等于获得整份源文件下载权限。
CAD 运行时选择
解析器和 DWG 转换器以显式配置优先；未显式配置时尝试 GIS 模块 runtime/ 运行时，仍不可用则按应用配置解析。环境变量 GIS_PYTHON_COMMAND、GIS_DWG2DXF_COMMAND 可指定实际命令；裸命令通过 PATH 解析，项目相对路径相对项目根解析。随仓库的 Windows 运行时不代表 Linux/macOS 环境可直接使用，生产使用的运行时及依赖须按目标环境核验。2026-10-26 的验证范围见测试与验收。
前期来源点面增量设计
本节为前期管理已确认业务的待实施接入，不改变历史CAD已交付事实；需求见GIS前期接入，具体审核算法见前期详细设计。当前前期几何及读取分支均未实现、未查库、未联调。
- 来源采用PRELIMINARY，与当前真实CAD来源并存。前期图层按真实line/bid/site＋业务类别组织，界面分四类逻辑组；图层元数据明确来源/类别，不从任意名字猜。人工业务层无CAD图纸时不伪造drawingId或drawingVersionId，真实列可空差异按数据库增量核实后处理。
- CAD原分支保留图纸当前版本、AMAP_V2及原工点共享读取。PRELIMINARY分支以当前有效要素修订和前期APPROVED版本为正式依据，读取前验证具体单位工程对应pair及前期业务权，不能直接继承CAD按site共享策略。
- 读写必须覆盖图层目录、scene组合/运行、要素列表/详情/导出、bbox与地图取图、名称和业务绑定反查、发布和修订。当前GIS_FEATURE查询inner join图纸会过滤无图纸对象，不是加一个SOURCE_TYPE就完成。通用GIS修改/绑定/移动/删除入口不可绕前期审核；原CAD允许动作不因本增量删除。
- 候选WKT采集为EPSG:3857，crsCode为EPSG_3857。发布转换为现GIS正式EPSG:4326 GeoJSON及经纬度bbox；地图继续dataProjection=4326→featureProjection=3857投影一次，不能直接把米制坐标写GeoJSON或再次套用高德偏移/CAD配准。
- 发布优先同应用GIS窄Java服务，参与前期外层同源事务，不HTTP自调用、REQUIRES_NEW、Async/AFTER_COMMIT。内部发布须核实可信业务审核上下文，不以普通gis:feature:edit或客户端reviewed=true放行。实际数据源和引擎回滚以故障测试证明。
- 新图形用稳定spatialKey；修改从原publishedFeatureId解析有效existingFeatureId及当前revision。只有几何或图层真实变化才发布新修订，普通计划/附件修订沿用原正式要素，不重复造点/绑定。保留PROJECT/SITE/BID及已有revision语义。
- 地图DTO/点击事件显式区分来源。人工要素没有drawingId时不执行String(undefined)后跳CAD详情；以业务类型和objectId定位前期详情。图层显隐只改变展示，不授予工程权限或写审批状态。
验收增加：候选已知坐标发布往返同位置；同工点A仅有A标段授权不能读B前期点面而原共享CAD仍可用；只改计划不新增要素修订；普通GIS接口不能解除前期受控绑定；审核退回或发布失败保持旧图。对应前期T43–T46，全部待执行。文档1.04→1.14反映新增来源读写设计，不表示能力已发布。