fix(backend): resolve SQLite deadlock in tunnel entry updates (#334)

- Fix deadlock when updating tunnel entries with offline nodes
- Add test file for tunnel entry SQLite operations
- Update contract tests for entry port conflict and limiter sync
- Add plan documents for SQLite deadlock fix and contract semantics

plans/042-sqlite-tunnel-entry-update-deadlock.md

@@ -0,0 +1,49 @@
+# 042 - SQLite 隧道编辑添加入口节点卡死排查
+
+## Issue
+- 现象：SQLite 数据库下，编辑已有隧道并新增入口节点时接口卡住；PostgreSQL 下同样操作正常。
+- 初步判断：`tunnelUpdate` 在事务尚未提交时触发了额外 repository 读查询，SQLite 配置 `MaxOpenConns(1)`，容易在同一请求内形成自锁等待。
+
+## Goal
+- 找出 SQLite 与 PostgreSQL 行为差异的根因。
+- 修复隧道编辑新增入口节点时的阻塞问题，同时不破坏现有的入口端口冲突校验。
+- 补充最小回归测试，锁定“事务内校验不可再次占用根连接”的场景。
+
+## Checklist
+- [x] 复核 `tunnelUpdate` 在新增入口节点路径上的调用链，确认事务内哪些查询绕过了 `tx`。
+- [x] 为相关 repository 查询补齐 `Tx` 版本，避免 SQLite 单连接下的自锁等待。
+- [x] 调整 handler 中入口端口冲突校验，保证事务内全程复用同一个 `tx`。
+- [x] 增加针对 SQLite 的回归测试，验证事务内校验不会阻塞。
+- [x] 运行相关 handler/backend 测试并记录结果。
+
+## Notes
+- 重点关注 `validateTunnelEntryPortConflictsForNewEntries`：当前它在 `tx.Commit()` 前执行，但内部调用 `ListForwardsByTunnel` / `ListForwardPorts` / `HasOtherForwardOnNodePort` 等非事务查询。
+- SQLite 在 `go-backend/internal/store/repo/repository.go` 中显式设置了 `SetMaxOpenConns(1)`，因此这种模式在 SQLite 下会比 PostgreSQL 更容易表现为“卡死”。
+
+## 实际改动
+- `go-backend/internal/store/repo/repository_control.go`
+  - 新增 `ListForwardsByTunnelTx`、`ListForwardPortsTx`、`HasOtherForwardOnNodePortTx`，并让原有非事务方法复用统一实现。
+- `go-backend/internal/http/handler/mutations.go`
+  - `tunnelUpdate` 在事务内执行入口端口冲突校验时显式传入当前 `tx`。
+  - `validateTunnelEntryPortConflictsForNewEntries` 改为全程使用事务查询。
+  - 新增 `validateForwardPortAvailabilityTx`，避免事务内回落到根连接查询。
+- `go-backend/internal/http/handler/tunnel_entry_sqlite_test.go`
+  - 新增 SQLite 回归测试，验证开启事务后执行新增入口校验不会阻塞。
+
+## 测试结果
+
+### 通过
+```bash
+cd go-backend && go test ./internal/http/handler/...
+```
+- 结果：通过。
+
+### 额外检查
+```bash
+cd go-backend && go test ./tests/contract/...
+```
+- 结果：未全绿；当前失败集中在既有的入口端口语义合同用例：
+  - `TestIssue313_EntryPortCrossTunnelConflictContract`
+  - `TestTunnelUpdateChangesEntryNodeButLeavesOldForwardRuntimeContract`
+  - `TestTunnelUpdateEntryTransitionsCleanupForwardRuntimeContract`
+- 备注：这些失败反映的是“新增/切换入口时端口校验预期”与现有合同用例之间的行为差异，不是本次 SQLite 事务自锁修复本身的编译或阻塞问题。

plans/043-entry-contract-semantics-alignment.md

@@ -0,0 +1,49 @@
+# 043 - Entry Transition Contract Semantics Alignment
+
+## Issue
+- SQLite 阻塞修复完成后，`go test ./tests/contract/...` 暴露出 3 个入口变更相关合同用例失败。
+- 失败原因分成两类：
+  - Issue 313 用例的数据构造没有真正制造“新增入口节点已被其他转发占用”的冲突。
+  - Issue 281 回归用例在后续引入“入口端口必须落在节点端口范围内”后，仍沿用旧的非重叠端口范围数据，和当前产品语义不一致。
+
+## Goal
+- 对齐这 3 个合同测试与当前后端语义。
+- 保持 SQLite 自锁修复不回退。
+- 让入口节点切换/新增相关合同测试重新稳定通过。
+
+## Checklist
+- [x] 复核 3 个失败用例的测试数据与当前后端校验语义差异。
+- [x] 调整 Issue 313 用例，确保新增入口节点确实命中“其他转发已占用同节点同端口”。
+- [x] 调整 Issue 281 两个回归用例，使入口切换场景使用与保留端口兼容的节点端口范围。
+- [x] 运行相关合同测试与 handler 测试并记录结果。
+
+## Notes
+- `validateTunnelEntryPortConflictsForNewEntries` 的占用判定复用 `HasOtherForwardOnNodePort`，语义是“同节点 + 同端口 + 其他转发”，不是全局无节点维度的端口唯一性。
+- 入口切换测试当前更关注 `forward_port` 重建和旧节点运行时清理，因此测试数据应避免被端口范围校验提前拦截。
+
+## 实际调整
+- `go-backend/tests/contract/issue313_entry_port_conflict_contract_test.go`
+  - 将隧道 A 的入口节点改为复用即将添加到隧道 B 的 `entryB2`，确保新增入口时真正命中“同节点同端口已被其他转发占用”。
+  - 修正错误消息断言，直接检查 `out.Msg`，避免 JSON 解码后再读 `res.Body` 导致误判。
+- `go-backend/tests/contract/limiter_sync_failure_contract_test.go`
+  - 将 issue 281 的新入口节点端口范围调整为包含原有保留端口，保持测试关注点在运行时清理/同步，而不是被后续引入的端口范围校验拦截。
+
+## 测试结果
+
+### 定向回归
+```bash
+cd go-backend && go test ./tests/contract/... -run 'TestIssue313_EntryPortCrossTunnelConflictContract|TestTunnelUpdateChangesEntryNodeButLeavesOldForwardRuntimeContract|TestTunnelUpdateEntryTransitionsCleanupForwardRuntimeContract' -v
+```
+- 结果：3/3 通过。
+
+### Handler
+```bash
+cd go-backend && go test ./internal/http/handler/...
+```
+- 结果：通过。
+
+### 全量合同测试
+```bash
+cd go-backend && go test ./tests/contract/...
+```
+- 结果：通过。