# Nex

基于 [NeutralinoJS](https://neutralino.js.org) 的轻量级桌面应用框架，前端使用 React + TypeScript + Vite，后端使用 Go 作为 Native Extension。

## 项目结构

```
nex/
├── neutralino.config.json     # Neutralino 主配置文件
├── README.md
├── bin/                       # Neutralino 运行时二进制文件（各平台）
│   ├── neutralino-win_x64.exe
│   ├── neutralino-linux_x64
│   ├── neutralino-linux_arm64
│   ├── neutralino-linux_armhf
│   ├── neutralino-mac_x64
│   ├── neutralino-mac_arm64
│   └── neutralino-mac_universal
├── frontend/                  # 前端项目（React + TypeScript + Vite）
│   ├── package.json
│   ├── index.html             # Vite 入口 HTML
│   ├── vite.config.ts
│   ├── tsconfig.json
│   ├── biome.json             # Biome 格式化配置
│   ├── eslint.config.js       # ESLint 配置
│   ├── public/                # 静态资源
│   │   └── favicon.svg
│   ├── dist/                  # 构建产物（由 vite build 生成）
│   └── src/
│       ├── main.tsx           # 应用入口，初始化 React 和 Neutralino
│       ├── App.tsx            # 根组件
│       ├── components/        # 可复用 UI 组件
│       ├── pages/             # 页面组件
│       ├── hooks/             # 自定义 React Hooks
│       ├── utils/             # 工具函数
│       ├── types/             # TypeScript 类型定义
│       └── styles/
│           └── global.scss    # 全局样式
└── backend/                   # 后端项目（Go Native Extension）
    ├── go.mod / go.sum        # Go 模块依赖
    ├── build.sh               # macOS / Linux 构建脚本
    ├── build.cmd              # Windows 构建脚本
    ├── cmd/
    │   └── nex/
    │       └── main.go        # Go 扩展入口，定义事件处理与业务逻辑
    └── internal/
        └── neutralino/
            └── client.go     # Neutralino WebSocket 客户端通信库
```

## 技术栈

| 层级 | 技术 |
|------|------|
| 桌面框架 | NeutralinoJS 6.7.0 |
| 前端 | React 19 + TypeScript 6 |
| 构建工具 | Vite 8 + Bun |
| 样式 | SCSS |
| 代码检查 | ESLint + Biome |
| 后端 | Go 1.22 |
| 后端通信 | WebSocket (gorilla/websocket) |

## 架构说明

本项目采用 Neutralino Extension 架构，前后端通过 WebSocket 进行异步通信：

```
┌─────────────────┐    WebSocket    ┌──────────────┐
│  React Frontend  │ ◄────────────► │  Go Backend   │
│  (浏览器渲染)     │                │  (Extension)  │
└─────────────────┘                 └──────────────┘
        │                                   │
   @neutralinojs/lib               internal/neutralino
   (JS API 调用)                   (WSClient)
```

- **前端** 通过 `@neutralinojs/lib` 的 `init()` 初始化 Neutralino 运行时，使用 `Neutralino.events` 发送和监听事件。
- **后端** 作为 Neutralino Extension 启动，通过 WebSocket 与 Neutralino 核心通信，接收前端事件并响应。
- 所有事件通信均为异步，事件队列保证不丢失。

## 快速开始

### 环境要求

- [Go](https://go.dev/dl/) >= 1.22
- [Bun](https://bun.sh/)（推荐）或 Node.js >= 18
- [Neutralino CLI](https://neutralino.js.org/docs/cli/neu-cli/)：`npm install -g @neutralinojs/neu`

### 1. 安装前端依赖

```bash
cd frontend
bun install
```

### 2. 编译 Go 后端

```bash
cd backend

# macOS / Linux
./build.sh

# Windows
build.cmd
```

构建产物 `nex`（或 `nex.exe`）输出到 `backend/` 目录下。

### 3. 安装 Neutralino 二进制

```bash
neu update
```

### 4. 开发模式运行

```bash
neu run
```

此命令会启动 Vite 开发服务器（端口 5173）和 Neutralino 窗口，前端改动自动热更新。

### 5. 构建生产包

```bash
# 构建前端
cd frontend && bun run build

# 构建 Neutralino 应用
neu build
```

## 前端开发指引

### 路径别名

项目配置了 `@` 指向 `src/` 目录，在导入时可直接使用：

```ts
import App from "@/App.tsx";
import "@/styles/global.scss";
```

### 目录规范

| 目录 | 用途 |
|------|------|
| `src/components/` | 可复用 UI 组件，通过 `index.ts` 统一导出 |
| `src/pages/` | 页面级组件 |
| `src/hooks/` | 自定义 React Hooks |
| `src/utils/` | 工具函数 |
| `src/types/` | TypeScript 类型定义 |
| `src/styles/` | 全局及局部样式（SCSS） |

### 代码质量工具

```bash
# ESLint 检查
bun run lint

# ESLint 自动修复
bun run lint:fix

# Biome 格式化检查
bun run format:check

# Biome 格式化（写入）
bun run format

# TypeScript 类型检查
bun run typecheck
```

### 调用 Go 后端

前端通过 Neutralino 事件系统与 Go 后端通信：

```ts
// 发送事件到 Go 后端
Neutralino.events.dispatch("runGo", {
  function: "ping",
  parameter: "Hello from Frontend",
});

// 监听 Go 后端返回的事件
Neutralino.events.on("pingResult", (event) => {
  console.log(event.detail);
});
```

## 后端开发指引

### 目录结构

```
backend/
├── cmd/nex/main.go              # 入口，注册事件回调
├── internal/neutralino/client.go # WSClient 通信库
├── build.sh / build.cmd         # 构建脚本
└── go.mod / go.sum              # 依赖管理
```

### 添加新的 Go 函数

在 `cmd/nex/main.go` 的 `processAppEvent` 回调中添加新的函数分支：

```go
func processAppEvent(data neutralino.EventMessage) {
    if ext.IsEvent(data, "runGo") {
        if d, ok := data.Data.(map[string]interface{}); ok {
            if d["function"] == "myFunc" {
                result := make(map[string]interface{})
                result["result"] = "处理结果"
                ext.Send("myFuncResult", result)
            }
        }
    }
}
```

### WSClient API

| 方法 | 说明 |
|------|------|
| `Run(callback, debug)` | 启动扩展主循环，每条消息触发 callback |
| `IsEvent(data, eventName)` | 判断事件名是否匹配 |
| `Send(event, data)` | 向前端发送结构化事件（`map[string]interface{}`） |
| `SendMessageString(event, data)` | 向前端发送字符串事件 |

修改后端代码后需重新编译：

```bash
cd backend && ./build.sh   # 或 build.cmd
```

## Neutralino 配置说明

`neutralino.config.json` 关键配置：

| 字段 | 说明 |
|------|------|
| `applicationId` | 应用标识 `com.lanyuanxiaoyao.nex` |
| `defaultMode` | 默认以窗口模式运行 |
| `documentRoot` | 前端资源根路径 `/frontend/` |
| `cli.resourcesPath` | 构建时打包的前端产物路径 `/frontend/dist` |
| `cli.extensionsPath` | 后端扩展路径 `/backend/` |
| `extensions` | 扩展定义，指定各平台启动命令 |
| `nativeAllowList` | Native API 白名单 |

## 参考链接

- [NeutralinoJS 官方文档](https://neutralino.js.org/docs/)
- [React 官方文档](https://react.dev/)
- [Vite 官方文档](https://vite.dev/)
- [Go 官方文档](https://go.dev/doc/)