# cross-border-manager-ksh

**Repository Path**: Suwanbin/cross-border-manager-ksh

## Basic Information

- **Project Name**: cross-border-manager-ksh
- **Description**: 可视化系统，基于 https://gitee.com/yudaocode/yudao-ui-admin-vue3 进行精简提炼、扩展的（和后台同源，方便业务拓展）
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: https://doc.iocoder.cn/
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 7812
- **Created**: 2026-07-13
- **Last Updated**: 2026-07-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# cross-border-manager-ksh

`cross-border-manager-yudao` 的全屏 GIS / 态势可视化端，基于 Vue 3 + Vite。它与同级 `cross-border-manager-web` 共用 `cross-border-manager-server` 的 `/admin-api`、账号体系和业务数据，但保持固定前端路由，不读取后台动态菜单。

当前代码仍处于“通用底座已复制、业务数据待接入”阶段：总览页展示明确标记的模拟指标；同级后端已经提供争议点位分页、详情、八类统计和 GeoJSON 等接口，可作为第一批真实可视化数据源。具体契约与接入边界见 `docs/ai/cross-project-integration.md`。

## 已提供能力

- 账号密码、租户、验证码、短信、注册、找回密码、社交登录与原 OAuth 授权确认入口；
- Token、租户 Header、可选请求加密、401 并发刷新、用户权限信息与只读字典预加载；
- 固定可视化页面注册表、`/visualization` 单例父布局和深色科技风驾驶舱工作区；
- `VisualizationWorkspace` 的左右 `PanelShell`、中部 `SceneHost`、覆盖层与窄屏抽屉；
- 页面级刷新协调器：取消旧周期、latest-wins、局部失败保留上次成功数据、可选 5 分钟调度与页面可见性暂停；
- 受控 `DataTableShell`、列表/详情双层 Dialog Shell，以及 0/1/多条统一钻取控制器；
- Vitest + Vue Test Utils 单元测试底座；
- OAuth 2.0 Authorization Code + PKCE S256 的前端发起/回调基础代码；同级后台 relay 与后端 public SPA PKCE 配套尚未发现，当前不能视为已联通；
- 通用 `GisMap` 门面 + Vue Cesium/天地图 adapter，Cesium 1.128.0 完整运行时由本地依赖同源发布；支持 WGS84 点位、拾取、飞行及模拟指标详情闭环。
- ECharts / TechUI Sifi / 数字翻牌器继续使用局部适配边界。

## 启动与构建

```bash
pnpm install
pnpm dev:local
pnpm test:unit
pnpm ts:check
pnpm build:local
```

`dev:local` 与 `build:local` 使用 Vite 的 `development` mode，并自动叠加 `.env.local`。该文件已忽略且不得重新跟踪；使用 `.env.example` 创建或核对本地配置，不要提交密钥、Token、账号密码、地图 Key 或真实生产地址。

## 架构入口

- 页面注册：`src/visualization/registry/pages.ts`
- 页面实现：`src/visualization/pages/**`
- 驾驶舱父布局：`src/visualization/layout/VisualizationLayout.vue`
- 三栏工作区：`src/visualization/layout/VisualizationWorkspace.vue`
- 场景挂载：`src/visualization/components/SceneHost.vue`
- 标准面板：`src/visualization/components/PanelShell.vue`
- 列表与弹窗：`src/visualization/components/DataTableShell.vue`、`src/visualization/components/dialogs/**`
- 页面刷新与交互运行时：`src/visualization/runtime/**`
- 图表与视觉面板适配：`src/visualization/adapters/**`
- 通用 GIS 门面与引擎适配：`src/visualization/gis/**`
- GIS 使用指南：`docs/ai/frontend-gis-integration.md`
- 登录与 Token：`src/views/Login/Login.vue`、`src/utils/auth.ts`
- 字典：`src/api/system/dict/dict.data.ts`、`src/store/modules/dict.ts`、`src/utils/dict.ts`
- OAuth PKCE：`src/views/Auth/*`、`src/visualization/auth/*`

新增驾驶舱页需要在 `src/visualization/pages/**` 创建页面组件并在前端页面注册表登记；页面不再包裹 `VisualizationLayout`，由父路由统一提供。导航注册不修改后端 `system_menu`。需要周期刷新时使用 `defineRefreshTasks()`、`useRefreshCoordinator()` 和 `useVisualizationPageRuntime()`；列表、详情和钻取使用对应 runtime/Shell，不在页面复制请求取消或叠层关闭逻辑。权限信息仍由 `/system/auth/get-permission-info` 返回，用于接口鉴权、用户展示和未来面板按钮控制；认证后会异步加载 `/system/dict-data/simple-list`，供面板和图表转换后端字典值。

## OAuth PKCE 配套状态

当前仓库只确认了可视化前端代码。以下事项尚未在同级 `cross-border-manager-web` / `cross-border-manager-server` 中找到对应实现，完成前应使用本站账号登录，不应开放“从管理后台免密进入”入口：

1. 后端创建认证方式为 `none` 的 public OAuth 客户端，仅启用 `authorization_code`、`refresh_token`。
2. 配置 `visualization.access` scope 并加入自动授权 scope。
3. 精确登记各环境可视化 `/auth/callback` redirect URI。
4. 可视化站点通过 `VITE_OAUTH_SOURCES` 登记来源 relay、public client ID 与 scope。
5. 来源后台实现固定 relay，并登记相同 client、redirect URI 与 scope，再配置“进入可视化”入口。
6. 后端 CORS 仅允许实际可视化 Origin；跨 Origin 调用不依赖 Cookie 或共享 localStorage。

浏览器端不配置 OAuth client secret，也不通过 URL、`postMessage` 或 localStorage 转交来源系统 Bearer Token。

## 部署注意

项目使用 Vue Router history 模式。Nginx、网关或静态托管必须把未知前端路径回退到 `index.html`，否则直接访问或刷新 `/visualization/overview`、`/auth/callback` 等子路由会返回 404。

完整接入、环境变量和排障说明见 `docs/ai/visualization-foundation.md`；兄弟工程现状见 `docs/ai/cross-project-integration.md`。修改代码后先运行 `pnpm docs:impact`，再按 `docs/ai/maintenance.md` 同步项目内和上级整体文档。