# tianwafang

**Repository Path**: pyxstudy/tianwafang

## Basic Information

- **Project Name**: tianwafang
- **Description**: 填挖方系统
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-15
- **Last Updated**: 2026-10-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# tianwafang

#### 介绍
填挖方系统

#### 软件架构
软件架构说明


#### 环境

- Node.js（前端与 Electron）
- Python 3.12（后端 Sidecar；Windows 建议 `py -3.12`）

首次准备：

```powershell
cd backend
py -3.12 -m venv .venv
.venv\Scripts\python -m pip install -r requirements.txt

cd ..\frontend
npm install
```

macOS / Linux 把解释器换成 `python3 -m venv .venv`，后续用 `.venv/bin/python`、`.venv/bin/pip`。

#### 网页调试

浏览器里跑渲染进程，热更新由 Vite 提供。后端要单独起在固定端口，Vite 把 `/api` 代理过去（默认 `8765`，可用 `WTF_SIDECAR_PORT` 改）。

```powershell
# 终端 1：后端
cd backend
.venv\Scripts\python -m app.main --port 8765 --data-dir $env:TEMP\wtf-dev-data

# 终端 2：前端
cd frontend
$env:WTF_SIDECAR_PORT = "8765"
npm run dev
```

浏览器打开 `http://localhost:5273`。接口请求走相对路径 `/api`，由开发服务器转发到 `http://127.0.0.1:8765`。页面问题用浏览器开发者工具看；后端日志在终端 1。

#### 桌面模式调试

Electron 主进程会自己拉起 `backend/.venv` 里的 Sidecar（动态端口），不必再手工启动后端。渲染进程仍用 Vite，这样改界面可以热更新。

主进程源码有改动时先编译一次：

```powershell
cd frontend
npm run build:electron
```

然后两个终端：

```powershell
# 终端 1：渲染进程开发服务器
cd frontend
npm run dev

# 终端 2：桌面壳，加载上面的开发服务器
cd frontend
$env:WTF_DEV_SERVER = "http://localhost:5273"
npx electron .
```

Sidecar 的标准输出会出现在终端 2，前缀为 `[sidecar]`。界面拿到的接口地址来自主进程（`getBootstrap` 的 `apiBase`），不再走 Vite 代理。

不需要热更新、只想看打包前的桌面效果时，一条命令即可（会先构建渲染进程和主进程，再打开窗口，加载的是 `dist/`，没有热更新）：

```powershell
cd frontend
npm start
```

可选环境变量：

| 变量 | 作用 |
| --- | --- |
| `WTF_DEV_SERVER` | 桌面壳加载该地址，而不是 `dist/index.html` |
| `WTF_API_BASE` | 连接已经手工启动的 Sidecar，主进程不再自启动后端 |
| `WTF_SIDECAR_CMD` | 自定义 Sidecar 启动命令（空格分隔） |
| `WTF_SIDECAR_PORT` | 仅 `npm run dev` 使用，指定 Vite 代理的后端端口 |

#### 打包

安装包包含 Electron 壳、前端构建产物，以及 PyInstaller 打出的 Python Sidecar。Sidecar 不能交叉编译：Windows 安装包必须在 Windows 上打。

```powershell
cd backend
.venv\Scripts\python -m pip install -r requirements.txt -r requirements-build.txt

cd ..\frontend
npm ci
$env:ELECTRON_MIRROR = "https://npmmirror.com/mirrors/electron/"
npm run dist:win
```

`npm run dist:win` 依次执行：渲染进程构建、主进程编译、Sidecar 打包、electron-builder（NSIS，x64）。产物在 `frontend/release/WtfMineSurvey-<版本>-win-x64.exe`。

macOS 上在对应机器执行 `npm run dist:mac`，产物为 `frontend/release/WtfMineSurvey-<版本>-mac-<arch>.dmg`。

打包后可在 `frontend` 目录验收：

```powershell
npm run verify:size
npm run verify:bundle
```

更细的说明见 `frontend/README.md` 与 `backend/README.md`。

#### 参与贡献

1.  Fork 本仓库
2.  新建 Feat_xxx 分支
3.  提交代码
4.  新建 Pull Request


#### 特技

1.  使用 Readme\_XXX.md 来支持不同的语言，例如 Readme\_en.md, Readme\_zh.md
2.  Gitee 官方博客 [blog.gitee.com](https://blog.gitee.com)
3.  你可以 [https://gitee.com/explore](https://gitee.com/explore) 这个地址来了解 Gitee 上的优秀开源项目
4.  [GVP](https://gitee.com/gvp) 全称是 Gitee 最有价值开源项目，是综合评定出的优秀开源项目
5.  Gitee 官方提供的使用手册 [https://gitee.com/help](https://gitee.com/help)
6.  Gitee 封面人物是一档用来展示 Gitee 会员风采的栏目 [https://gitee.com/gitee-stars/](https://gitee.com/gitee-stars/)