# JSON Parser 使用文档

## 功能说明

通过 IPC 调用 `json-parser.js` 进行 JSON 文件的创建、读取、更新和存在性检查。

**重要：** 所有文件只能保存在 `static` 目录下，使用相对路径即可。如果传入 `jason/testjson`，实际文件路径为 `static/jason/testjson.json`。

## 操作类型

### 1. create - 创建 JSON 文件

创建新的 JSON 文件。

**参数：**
- `operation`: `'create'`
- `filePath`: JSON 文件相对路径（相对于 `static` 目录），如 `jason/testjson`，会自动添加 `.json` 扩展名
- `jsonString`: JSON 数据（字符串格式）

**示例：**
```javascript
const response = JSON.parse((await window.electronAPI.runNodejsScript('json-parser', 'create', 'jason/testjson', JSON.stringify({devices: [], settings: {}}))).stdout)
```

**返回：**
```json
{
  "success": true,
  "message": "JSON file created successfully"
}
```

### 2. read - 读取 JSON 文件

读取 JSON 文件内容。如果文件不存在，返回 `{ success: true, data: null }`。

**参数：**
- `operation`: `'read'`
- `filePath`: JSON 文件相对路径（相对于 `static` 目录），如 `jason/testjson`
- `keyPathJson`: （可选）键路径数组，如 `JSON.stringify(['devices', 0, 'ip'])`

**示例：**
```javascript
// 读取整个文件
const readResult = await window.electronAPI.runNodejsScript('json-parser', 'read', 'device_list.json')
const readResponse = JSON.parse(readResult.stdout)
const data = readResponse.data

// 如果文件不存在（data 为 null），则创建
if (data === null) {
    const createResult = await window.electronAPI.runNodejsScript('json-parser', 'create', 'device_list.json', JSON.stringify({devices: []}))
}

// 读取特定路径
const ip = JSON.parse((await window.electronAPI.runNodejsScript('json-parser', 'read', 'jason/testjson', JSON.stringify(['devices', 0, 'ip']))).stdout).data
```

**返回：**
```json
// 文件存在时
{
  "success": true,
  "data": {...}
}

// 文件不存在时
{
  "success": true,
  "data": null
}
```

### 3. update - 更新 JSON 文件

更新 JSON 文件内容。

**参数：**
- `operation`: `'update'`
- `filePath`: JSON 文件相对路径（相对于 `static` 目录），如 `jason/testjson`
- `jsonString`: 要更新的 JSON 数据（字符串格式）
- `keyPathJson`: （可选）键路径数组，用于更新特定路径

**示例：**
```javascript
// 更新整个文件（合并）
const response = JSON.parse((await window.electronAPI.runNodejsScript('json-parser', 'update', 'jason/testjson', JSON.stringify({newKey: 'value'}))).stdout)

// 更新特定路径
const response = JSON.parse((await window.electronAPI.runNodejsScript('json-parser', 'update', 'jason/testjson', JSON.stringify(true), JSON.stringify(['settings', 'autoConnect']))).stdout)
```

**返回：**
```json
{
  "success": true,
  "message": "JSON file updated successfully"
}
```

### 4. check - 检查文件是否存在

检查 JSON 文件是否存在。

**参数：**
- `operation`: `'check'`
- `filePath`: JSON 文件相对路径（相对于 `static` 目录），如 `jason/testjson`

**示例：**
```javascript
const exists = JSON.parse((await window.electronAPI.runNodejsScript('json-parser', 'check', 'jason/testjson')).stdout).exists
```

**返回：**
```json
{
  "success": true,
  "exists": true
}
```

## 封装函数使用（推荐）

在 `device.js` 中已提供封装函数，使用更简洁：

```javascript
import { 
  createJsonFile, 
  readJsonFile, 
  updateJsonFile, 
  checkJsonFileExists 
} from './device.js'

// 创建 JSON 文件
const result = await createJsonFile('jason/testjson', {devices: []})

// 读取整个文件
const data = await readJsonFile('jason/testjson')

// 读取特定路径
const ip = await readJsonFile('jason/testjson', ['devices', 0, 'ip'])

// 更新整个文件
const result = await updateJsonFile('jason/testjson', {newKey: 'value'})

// 更新特定路径
const result = await updateJsonFile('jason/testjson', true, ['settings', 'autoConnect'])

// 检查文件是否存在
const exists = await checkJsonFileExists('jason/testjson')
```

## 键路径格式

键路径使用数组格式，然后通过 `JSON.stringify()` 序列化：

```javascript
// 访问 devices[0].ip
JSON.stringify(['devices', 0, 'ip'])

// 访问 settings.theme
JSON.stringify(['settings', 'theme'])

// 访问 users[1].profile.name
JSON.stringify(['users', 1, 'profile', 'name'])
```

## 注意事项

1. **文件路径**：使用相对路径（相对于 `static` 目录），如 `jason/testjson` 会保存为 `static/jason/testjson.json`
2. **自动添加扩展名**：如果路径没有 `.json` 扩展名，会自动添加
3. **路径安全**：禁止使用 `..` 或绝对路径，所有文件只能在 `static` 目录下
4. **JSON 序列化**：所有 JSON 数据必须使用 `JSON.stringify()` 序列化
5. **返回值解析**：脚本返回的 `stdout` 是 JSON 字符串，需要 `JSON.parse()` 解析
6. **错误处理**：检查返回的 `success` 字段判断操作是否成功
7. **自动创建目录**：如果文件所在目录不存在，会自动创建
8. **read 操作特性**：文件不存在时返回 `{ success: true, data: null }`，可通过 `data === null` 判断文件是否存在

## 实际应用示例

### 读取或创建文件

```javascript
const readResult = await window.electronAPI.runNodejsScript('json-parser', 'read', 'device_list.json')
const readResponse = JSON.parse(readResult.stdout)
let jsonData = readResponse.data

if (jsonData === null) {
    const createResult = await window.electronAPI.runNodejsScript('json-parser', 'create', 'device_list.json', JSON.stringify({devices: []}))
    const createResponse = JSON.parse(createResult.stdout)
    if (createResponse.success) {
        jsonData = {devices: []}
    }
}
```

## 错误示例

```json
{
  "success": false,
  "error": "Missing jsonString parameter for create operation"
}
```

```json
{
  "success": false,
  "error": "Invalid file path"
}
```
