# 跨平台单实例锁

## Purpose

TBD - 提供跨平台单实例文件锁机制，使用 `github.com/gofrs/flock` 封装，支持 Windows、macOS、Linux 三平台。

## Requirements

### Requirement: 跨平台单实例文件锁

系统 SHALL 提供跨平台的单实例文件锁机制，使用 `github.com/gofrs/flock` 实现，在 Windows、macOS、Linux 上均可正常工作。

#### Scenario: 首次加锁成功
- **WHEN** 调用 `NewSingletonLock(lockPath)` 创建锁实例并调用 `Lock()`
- **AND** 锁文件未被其他进程持有
- **THEN** 加锁成功，返回 `nil`

#### Scenario: 重复加锁失败
- **WHEN** 另一个进程已持有同一锁文件的排他锁
- **AND** 调用 `Lock()`
- **THEN** 加锁失败，返回错误

#### Scenario: 释放锁
- **WHEN** 调用 `Unlock()`
- **THEN** 排他锁被释放
- **AND** 其他进程可以成功加锁

#### Scenario: 进程崩溃后锁自动释放
- **WHEN** 持有锁的进程异常退出（崩溃、kill）
- **THEN** 操作系统自动释放文件锁
- **AND** 新进程可以成功加锁

> 注：此场景由操作系统和 `gofrs/flock` 库保证，无需显式单元测试。

### Requirement: 锁路径参数化

`SingletonLock` SHALL 通过构造函数参数接收锁文件路径，支持不同运行上下文使用不同锁文件。

#### Scenario: 正式运行锁路径
- **WHEN** 桌面应用正常启动
- **THEN** 使用 `%TEMP%/nex-gateway.lock` 作为锁文件路径

#### Scenario: 测试运行锁路径
- **WHEN** 运行 `go test`
- **THEN** 测试代码使用独立的锁文件路径（如 `%TEMP%/nex-gateway-test.lock`）
- **AND** 与正式版锁文件互不影响

#### Scenario: 锁路径隔离
- **WHEN** 正式版桌面应用正在运行
- **AND** 同时执行 `go test`
- **THEN** 正式版持有 `nex-gateway.lock`
- **AND** 测试持有 `nex-gateway-test.lock`
- **AND** 两者互不阻塞