# pgsman

**Repository Path**: jcstone/pgsman

## Basic Information

- **Project Name**: pgsman
- **Description**: 基于pgs地理信息数据服务的地理新数据管理系统。
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-16
- **Last Updated**: 2026-10-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# pgsman

基于 PyQGIS 的独立桌面应用：pgs 后端（Go+Gin+PostGIS）的 DDL 管理与
PostGIS 地图数据编辑客户端。

当前能力：QGIS 应用初始化、登录 pgs（支持多服务器）、数据源树（库 -> 模式 -> 表）、
双击表经 **单 API 通道**（pgs REST API 拉要素 GeoJSON）上图、坐标/比例尺状态栏、
QML 样式、编辑会话与批量提交（含**编辑独占锁**）、属性面板、编辑/选择/导航三条工具条、
图层面板右键菜单（缩放/顺序/重命名/样式导入导出/导出 GeoJSON·XLSX·SHP）、
天地图底图叠加（6 种图层，可多选共存、彼此独立）。

## 环境要求

- QGIS 3.28+/3.34 LTR（含 Python 绑定：qgis.core / qgis.gui）
- Python 3.9 - 3.12（与 QGIS 绑定的解释器版本一致）
- requests
- pgs 后端服务（默认 http://127.0.0.1:17000，Redis 需可用）
- 天地图 Key（可选：仅使用「地图底图」时需要，填在系统配置 -> app.tianditu_key）

> 单 API 通道架构：**不需要任何本地数据库账号**，渲染/编辑/DDL 全部经 pgs REST API。

## 打包产物运行（dist\pgsman）

完成 `build.cmd` 打包后，产物在 `dist\pgsman\`（pgsman.exe + _internal + runtime）。

**Windows 下请双击 `run_pgsman.cmd` 启动，不要直接双击 pgsman.exe**：
本机存在 qianfan 桌面沙箱（lightsandbox）注入的外部 python313.dll，直接双击 exe 时
PyInstaller bootloader 会误载该 DLL，在窗口出现前即崩溃（0xC0000005，无任何提示）；
`run_pgsman.cmd` 先把 PATH 重置为干净集合再启动 exe，可正常打开主窗口
（已验证：explorer 双击启动器 -> 进程存活、模块全部命中产物 _internal/runtime）。

> 其他无 qianfan 沙箱的机器通常可直接双击 pgsman.exe（未经本机以外实测）。

## 快速开始

### 方式一：调试模式运行（推荐，源码开发用）

**解释器必须使用 QGIS 自带的 `python-qgis-ltr.bat`**（本机：
`C:\Program Files\QGIS 3.44.9\bin\python-qgis-ltr.bat`），它负责注入
`QGIS_PREFIX_PATH`、`PYTHONPATH`、`QT_PLUGIN_PATH` 等整套 QGIS 运行时环境，
`import qgis` 才能成功；直接调用 `bin\python.exe` 会缺少这些环境变量。


```bat
:: Windows cmd（QGIS 3.44.9 示例）
"C:\Program Files\QGIS 3.44.9\bin\python-qgis-ltr.bat" main.py

:: Git Bash
"/c/Program Files/QGIS 3.44.9/bin/python-qgis-ltr.bat" main.py

:: PowerShell
& "C:\Program Files\QGIS 3.44.9\bin\python-qgis-ltr.bat" main.py

```

> PyCharm 配置：新建 Python 解释器 -> 选择 System Interpreter ->
> 指向 `bin\python-qgis-ltr.bat`（QGIS 安装时会提供
> `python-qgis-ltr-pycharm.bat`）；或直接用该批处理在终端启动。

### 方式二：设置 QGIS 前缀后启动（等价写法）

```bash
# 1. 复制配置模板并按环境修改
cp config.example.jsonc config.jsonc

# 2. 设置 QGIS 前缀（或配置 config.jsonc -> app.qgis_prefix）
export QGIS_PREFIX_PATH="C:/Program Files/QGIS 3.34.5/apps/qgis"

# 3. 启动（此时要求解释器本身已能 import qgis，建议直接用方式一）
python main.py
```

启动后点击菜单「文件 -> 登录」，使用 pgs 后端账号登录；
登录成功后数据源树自动加载数据库列表，展开 库 -> 模式 -> 表：

- **双击空间表** -> 上图（单 API 通道：带 token 拉要素 GeoJSON 建临时图层）
- **双击非空间表** -> 查看表结构信息（字段 / 几何列 / 范围）
- **右键表节点** -> 添加图层到地图 / 查看元数据 / 刷新（admin 可强制刷新服务端缓存）
- **编辑**：图层面板选中图层 -> 开始编辑（自动取服务端编辑独占锁）-> 编辑 -> 保存 / 放弃
- **视图 -> 缩放到全图**；工具条提供平移 / 缩放到图层 / 缩放到所选；状态栏实时坐标与比例尺
- **图层 -> 地图底图**：勾选天地图图层（需系统配置填写 Key；**6 种图层彼此独立**，
  注记无需先加载对应瓦片），可多图层叠加共存

> 渲染与编辑的数据获取、DDL 与数据写入**全部经 pgs REST API**（单 API 通道），
> 不存在本地数据库直连。

## 工程结构

```
pgsman/
├─ main.py                      入口：QgsApplication 初始化 + 启动预检 + 打包环境引导
├─ App/                         GUI 壳：主窗体、配置、会话
│  ├─ MainWindow.py             主窗体：画布、三个 Dock（数据源/图层/属性）、菜单+三条工具条、状态栏
│  ├─ Config.py                 JSONC 配置：servers[] 多服务器 + app + edit_lock
│  └─ Session.py                登录/token/角色/当前连接上下文
├─ Core/                        服务层（UI 无关优先）
│  ├─ PgsClient.py              pgs REST API 门面（auth/meta/ddl/features/editlock）
│  ├─ api/                      http.py + endpoints/{auth,metadata,ddl,features,editlock}.py
│  ├─ MetaService.py            元数据拉取与会话内缓存
│  ├─ Threads.py                Worker + 线程池（阻塞调用不在 UI 线程）
│  ├─ render/                   渲染与底图
│  │  ├─ LayerSpec.py           TableInfo -> 图层规格（几何列/SRID/范围）
│  │  ├─ LayerFactory.py        拉要素 GeoJSON -> 临时文件 + ogr provider 建层
│  │  ├─ RenderService.py       图层生命周期（project_mode 挂 QgsProject）
│  │  ├─ BasemapService.py      天地图 WMTS 底图（叠加/依赖/重排/移除）
│  │  └─ errors.py              RenderError
│  └─ layers/                   编辑会话核心
│     ├─ state.py               9 态状态机
│     ├─ changeset.py           变更集分桶与抵消
│     ├─ edit_session.py        撤销栈 + editBuffer 只读提取
│     ├─ submit.py              批量提交管线（BATCH_SIZE=500）
│     ├─ table_layer.py         TableLayer 聚合根
│     └─ edit_lock.py           EditLockManager（/api/edit_session/*）
├─ Widgets/
│  ├─ DataSourceTree.py         数据源浏览器（库->模式->表 三级树 + 库/模式过滤）
│  ├─ MapCanvas.py              QgsMapCanvas 封装（坐标/比例尺 + zoom_to_bbox CRS 转换）
│  ├─ LayerTreeView.py          QgsLayerTreeView + Model + 画布桥接器
│  ├─ LayerPanel.py             登记模型 + 树视图（右键菜单）+ 控制器（会话/工具/锁编排）
│  ├─ EditTools.py              添加点线面/选择/顶点编辑 + 要素表单 + 应用内剪贴板
│  ├─ SelectTools.py            单击/框选/按值选择（不依赖编辑会话）
│  ├─ AttributePanel.py         属性面板（单要素 + 多要素批量）
│  ├─ MessageBox.py             可复制消息框（全工程统一弹窗）
│  ├─ QgisIcons.py              QGIS 官方主题图标
│  └─ dialogs/                  Login / SystemConfig / AddServer / TableInfo
├─ MapTools/                    编辑工具集（预留，从 PMAP 迁移改造）
├─ templates/                   建表字段模板（P1，占位）
├─ styles/                      QML 样式库（{schema}__{table}.qml 或 {table}.qml）+ icons/
├─ tests/                       纯逻辑单测
├─ probe_*.py                   调试/回归探针（QGIS 环境跑，不入库）
└─ docs/                        完整设计方案 / CONTEXT / DEVELOPMENT
```

## 功能与验收范围

- 启动：QGIS 独立初始化（无 QGIS 主程序依赖）+ 服务器预检（未配置/连不上/降级分别引导）
- 登录：多服务器下拉选择，登录成功后展开 库 -> 模式 -> 表（可按 `database/schema` 过滤）
- 上图：双击/右键空间表 → 单 API 通道拉 GeoJSON 建临时图层（层名 `{schema}.{table}`），
  同表自动去重；非空间表落到元数据查看
- 编辑：开始编辑（先取服务端编辑独占锁）→ 添加/选择/顶点/属性编辑 → 保存（批量提交）
  /放弃；提交成功刷新只读层，失败保留会话可重试；锁失效自动退出并提示
- 面板：图层面板（内置 QGIS 树，右键缩放/顺序/重命名/样式/导出）、属性面板（随会话切权限）
- 底图：图层 → 地图底图（天地图 6 图层多选叠加、彼此独立，需在系统配置填写 Key）
- 视图：缩放到全图/图层/所选；状态栏实时坐标与比例尺

> 渲染与编辑均走 pgs REST API（单 API 通道），**无任何本地 PostGIS 直连**。
> 架构、硬约束与排查表详见 `docs/CONTEXT.md`，进度与验证矩阵见 `docs/DEVELOPMENT.md`。