gis-view-webgl2 0.1.1 → 0.1.2

package/docs//346/216/245/345/217/243/345/215/217/350/256/256.md

@@ -325,7 +325,7 @@ HTTP `409 Conflict` 示例：
   "channelId": "channel-a",
   "action": { "type": "splitGroups", "groupIds": ["channel-a", "channel-a::2"] },
   "groups": [
-    { "id": "channel-a", "lineIds": ["line-0", "line-1"], "path": [[18.0, 10.2], [20.5, 11.1]] },
+    { "id": "channel-a", "lineIds": ["line-0", "line-1"], "path": [[18.0, 10.2], [20.5, 11.1]], "waypointOffsets": { "1": [1.2, -0.8] } },
     { "id": "channel-a::2", "lineIds": ["line-2"], "path": [] }
   ],
   "baseVersion": 12,
@@ -337,10 +337,11 @@ HTTP `409 Conflict` 示例：
 | --- | --- | --- |
 | `channelId` | `string \| number` | 通道 id，必须与路径参数一致 |
 | `action` | `object` | 审计用动作：`splitGroups` / `mergeGroups` / `moveLine` / `addGroup` / `setGroups`；服务端不应依赖它恢复数据 |
-| `groups` | `Array<{ id, lineIds, path }>` | **整份**分组声明；顺序就是后续回线排布顺序 |
+| `groups` | `Array<{ id, lineIds, path, waypointOffsets? }>` | **整份**分组声明；顺序就是后续回线排布顺序 |
 | `groups[].id` | `string \| number` | 分组稳定 id |
 | `groups[].lineIds` | `Array<string \| number>` | 这一组包含的回线 id；同一条回线在整份声明里只能出现一次 |
 | `groups[].path` | `[number, number][]` | 分组公共骨架的中间拐点；`[]` 是合法的「直连」，不能当成没提交 |
+| `groups[].waypointOffsets` | `Record<string, [number, number] \| { x, y }>` | `vertex` 拖动的分组刚性偏移：键是含首尾端点的骨架顶点序号（只认中间拐点），值是组内所有回线共用的世界坐标增量；省略或空对象表示不带偏移 |
 
 `groups` 至少保留一组。若业务允许空通道，建议另走 `DELETE /gis/channels/{channelId}`，不要把空分组声明当作删除通道的隐式约定。
 
@@ -350,7 +351,7 @@ HTTP `409 Conflict` 示例：
 {
   "channelId": "channel-a",
   "groups": [
-    { "id": "channel-a", "lineIds": ["line-0", "line-1"], "path": [[18.0, 10.2], [20.5, 11.1]] },
+    { "id": "channel-a", "lineIds": ["line-0", "line-1"], "path": [[18.0, 10.2], [20.5, 11.1]], "waypointOffsets": { "1": [1.2, -0.8] } },
     { "id": "channel-a::2", "lineIds": ["line-2"], "path": [] }
   ],
   "groupCount": 2,
@@ -358,11 +359,11 @@ HTTP `409 Conflict` 示例：
 }
 ```
 
-服务端应校验 channel 存在、`lineIds` 全部属于这条通道且不重复、每个 `path` 点都是有限数值；返回落库后的整份快照，前端用 `groups` 覆盖本地对应通道。
+服务端应校验 channel 存在、`lineIds` 全部属于这条通道且不重复、每个 `path` 点都是有限数值，以及 `waypointOffsets` 的键都落在中间拐点、值都是有限增量；返回落库后的整份快照，前端用 `groups` 覆盖本地对应通道。
 
 ### 5.2 `PATCH /gis/channels/{channelId}/groups/waypoints`
 
-覆盖一条通道里某一组的**公共骨架**。`path` 只包含中间拐点，两端由通道绑定的节点补齐。拖动过程中 `phase: 'start' / 'move'` 不发请求，只在 `add` / `remove` / `end` 发一条。
+覆盖一条通道里某一组的**公共骨架与分组刚性偏移**。`path` 只包含中间拐点，两端由通道绑定的节点补齐；`waypointOffsets` 是 `channelWaypointDragMode: 'vertex'` 拖出来的按骨架序号偏移。拖动过程中 `phase: 'start' / 'move'` 不发请求，只在 `add` / `remove` / `end` 发一条。
 
 请求体：
 
@@ -372,6 +373,7 @@ HTTP `409 Conflict` 示例：
   "channelId": "channel-a",
   "groupId": "channel-a::2",
   "path": [[18.0, 10.2], [20.5, 11.1]],
+  "waypointOffsets": { "1": [1.2, -0.8] },
   "phase": "end",
   "scope": "group",
   "baseVersion": 12,
@@ -384,8 +386,9 @@ HTTP `409 Conflict` 示例：
 | `channelId` | `string \| number` | 通道 id |
 | `groupId` | `string \| number` | 分组 id |
 | `path` | `[number, number][]` | 整份公共骨架的中间拐点；空数组表示直连 |
+| `waypointOffsets` | `Record<string, [number, number] \| { x, y }>` | 分组刚性偏移：键按含首尾端点的骨架序号算，只接受中间拐点；省略或空对象表示普通平行骨架 |
 | `phase` | `'add' \| 'remove' \| 'end'` | 实际落地阶段；`select` / `start` / `move` 不应发请求 |
-| `scope` | `'group'` | 公共骨架的存储范围；组内每条回线的偏移拐点是由它派生的，不单独落库 |
+| `scope` | `'group'` | 公共骨架与分组刚性偏移的存储范围；组内每条回线的车道偏移是由它派生的，不单独落库 |
 
 响应 `data.result`：
 
@@ -393,10 +396,13 @@ HTTP `409 Conflict` 示例：
 {
   "target": { "type": "channelGroup", "channelId": "channel-a", "groupId": "channel-a::2", "scope": "group" },
   "path": [[18.0, 10.2], [20.5, 11.1]],
+  "waypointOffsets": { "1": [1.2, -0.8] },
   "pointCount": 2
 }
 ```
 
+服务端必须把 `path` 与 `waypointOffsets` 一起落库并一起返回：只收 `path` 会丢掉非平行拖动结果，刷新后分组又回到旧骨架。
+
 ### 5.3 `PATCH /gis/lines/{lineId}/path`
 
 覆盖独立线路的整条折线。与通道分组不同，这里 `path` **包含首尾端点**，因为独立线路不依赖通道节点补端点。
@@ -446,9 +452,9 @@ HTTP `409 Conflict` 示例：
 ### 6.3 通道分组 / 拐点
 
 1. 只在真实落地的 `add` / `remove` / `end` 发请求；`start` / `move` 的中间态不发。
-2. 请求体永远是操作完成后的**整份** `groups` 或 `path`，从 `view.getChannelGroups()` / `view.getChannelGroupWaypoints()` 重新读。
+2. 请求体永远是操作完成后的**整份** `groups`，或成对的 `path` + `waypointOffsets`，从 `view.getChannelGroups()` / `view.getChannelGroupWaypoints()` 重新读。
 3. 同一条通道的写请求串行发送；拖动期间只保留最后一个 `end`。
-4. 成功用响应里的 `groups` / `path` 覆盖本地快照；如果服务端做了归一化，以服务端为准。
+4. 成功用响应里的 `groups` / `path` / `waypointOffsets` 覆盖本地快照；如果服务端做了归一化，以服务端为准。
 5. 409 优先使用错误包里的 `data.current` 做局部恢复；没有 `current` 时先拉最新文档。
 
 ### 6.4 前端落地映射：拿到 `data.result` 之后
@@ -582,7 +588,7 @@ else {
 
 const opId = crypto.randomUUID()              // rebase 是一次新提交，不能复用旧 opId
 const nextBody = {
-  ...rebuildRequestFromCurrentView(),          // 从恢复后的视图重新读整份 groups / path
+  ...rebuildRequestFromCurrentView(),          // 从恢复后的视图重新读整份 groups / path + waypointOffsets
   baseVersion: failure.currentVersion,
   opId
 }
@@ -611,7 +617,7 @@ const nextBody = {
 - **事务边界**：成功应用与幂等记录、版本推进在同一个数据库事务里提交；否则会出现「数据已写但幂等表没写」的重复应用风险。
 - **稳定 id**：所有分组、线路、通道都优先按 id 对账，不要用数组下标当业务主键。客户端生成 id 时，后端要校验唯一性。
 - **空 `path`**：是合法值，表示直连。校验时只检查「是否是数组 + 坐标是否有限」，不要用 truthy 判断吞掉空数组。
-- **响应快照**：分组 / 拐点接口返回落库后的最新 `groups` / `path`；复制返回 `idMap`；合并返回事务实际涉及的 id 集合。
+- **响应快照**：分组 / 拐点接口返回落库后的最新 `groups` / `path` / `waypointOffsets`；复制返回 `idMap`；合并返回事务实际涉及的 id 集合。
 - **审计**：记录 `requestId` / `traceId` / `opId` / `transactionId` / `actor` / 资源 id，日志里不要只记一个 URL。
 - **顺序**：同文档的写请求按版本串行；客户端也应对同一条通道 / 同一份文档做串行化，避免多个成功响应相互覆盖。
 
@@ -622,7 +628,7 @@ const nextBody = {
 | 批量复制与合并 | 框选后复制 | `POST /gis/copies/batch` | `transactionId`、`created`、`counts`、`idMap` |
 | 批量复制与合并 | 拖拽 / 选中后合并 | `POST /gis/merges` | `retainedPointIds`、`removedPointIds`、删线 / 删通道 id |
 | 通道与数据 | 拆 / 并 / 挪回线 / 新建组 | `PATCH /gis/channels/{id}/groups` | `groups` 最新快照、`groupCount`、`lineCount` |
-| 通道与数据 | 通道分组加 / 删 / 拖拐点 | `PATCH /gis/channels/{id}/groups/waypoints` | `target`、`path`、`pointCount` |
+| 通道与数据 | 通道分组加 / 删 / 拖拐点 | `PATCH /gis/channels/{id}/groups/waypoints` | `target`、`path`、`waypointOffsets`、`pointCount` |
 | 通道与数据 | 独立线路拐点 | `PATCH /gis/lines/{id}/path` | `target`、`path`、`pointCount` |
 
 两个演示的面板都提供：正常 200、网络失败、服务端 500、版本冲突 409；“重试最近失败请求”保留原 `opId`，「重放最近成功请求」用于验证幂等回放不推进版本。请求预览区会同时打印请求头、body、HTTP 状态与完整响应包。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gis-view-webgl2",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "WebGL2 矢量视图：点、线与 GeoJSON / 图片背景层，无内置界面，点击 / 双击 / 拖拽可配置",
   "type": "module",
   "scripts": {
@@ -40,4 +40,4 @@
     "vite-plugin-lib-inject-css": "^2.2.2",
     "vue": "^3.5.32"
   }
-}
+}