npm package: @lcap/spec-client-store
Description: Vue3 reactive store for spec client state management
Latest version: 0.0.1

# Spec Client Store

Vue3 reactive store for spec client state management.

## 安装

```bash
npm install @codewave/spec-client-store
# 或
pnpm add @codewave/spec-client-store
# 或
yarn add @codewave/spec-client-store
```

## 功能特性

- **文件管理** (`files`): 文件系统状态管理，支持增量同步和文件监听
- **沙箱管理** (`sandbox`): 沙箱连接和状态管理
- **聊天管理** (`chat`): 会话和消息管理，支持历史消息加载
- **编辑器管理** (`editor`): 文档编辑状态管理，支持自动保存和冲突检测
- **需求管理** (`spec`): 需求文档和技术文档管理，支持文件解析和状态同步

## 使用

### 在 Vue 组件中使用（推荐）

```vue
<script setup lang="ts">
import { createStore, useStore, type FileAPI, type SandboxAPI } from '@codewave/spec-client-store';

// 在根组件中创建 store
// createStore 会自动通过 provide 向下传递 store
// 并在 onBeforeMount 时自动初始化所有 stores
const store = createStore({
  fileAPI,
  sandboxAPI,
  sandboxCallbacks: {
    onConnect: () => console.log('沙箱已连接'),
    onDisconnect: () => console.log('沙箱已断开'),
  },
  editorCallbacks: {
    onBeforeSave: (filePath, content) => {
      console.log('保存前:', filePath);
    },
    onAfterSave: (filePath, content) => {
      console.log('保存后:', filePath);
    },
    onSaveConflict: (filePath, documentLastModified, fileLastModified) => {
      console.warn('保存冲突:', filePath);
    },
  },
});

// 在子组件中使用 useStore 获取 store
const store = useStore();

// 访问 state
store.files.state.files; // 文件列表
store.sandbox.state.status; // 'close' | 'connected' | 'connecting' | 'disconnect'
store.chat.state.sessions; // 会话列表
store.editor.state.documents; // 文档列表
store.spec.state.specs; // 需求列表

// 调用 actions
await store.files.saveFile('path/to/file', 'content');
await store.chat.sendMessage('sessionId', 'message');
await store.editor.loadDocument('path/to/file');
await store.spec.addSpec('需求名称');
</script>
```

### 直接使用（非组件环境）

```typescript
import { createStore, type FileAPI, type SandboxAPI, type Logger } from '@codewave/spec-client-store';

// 实现 FileAPI 接口
const fileAPI: FileAPI = {
  async getAppFiles() {
    // 实现获取应用文件的逻辑
    return {};
  },
  async getFile(path: string) {
    // 实现获取指定文件的逻辑
    return null;
  },
  async instruct(actions) {
    // 实现写入文件的逻辑
    return { lastModified: Date.now() };
  },
};

// 实现 SandboxAPI 接口
const sandboxAPI: SandboxAPI = {
  async createSandbox() {
    // 实现创建沙箱的逻辑
    return { url: 'http://localhost:3030', sandboxId: 'sandbox-id' };
  },
  async checkSandboxReady(url: string, sandboxId?: string) {
    // 实现检查沙箱就绪状态的逻辑
    return true;
  },
};

// 可选：自定义 logger
const logger: Logger = {
  debug: (...args) => console.debug('[DEBUG]', ...args),
  info: (...args) => console.info('[INFO]', ...args),
  warn: (...args) => console.warn('[WARN]', ...args),
  error: (...args) => console.error('[ERROR]', ...args),
};

// 创建 store 实例
// 注意：在非组件环境中，需要手动调用各个 store 的 init 方法
const store = createStore({ 
  fileAPI, 
  sandboxAPI,
  logger, // 可选，默认为 console
});

// 手动初始化所有 stores（在组件环境中会自动执行）
await store.files.init();
await store.spec.init();
await store.chat.init(store.spec.state.specs); // 需要传入 specs 数组
await store.sandbox.init();
```

## API 说明

### `createStore(options: CreateStoreOptions): Store`

创建并初始化所有的 store。

**特性：**
- 自动通过 Vue 的 `provide` 向下传递 store
- 自动在 `onBeforeMount` 时初始化所有 stores（按顺序：files → spec → chat → sandbox）
- 必须在 Vue 组件的 `setup` 函数中调用

**参数：**
- `fileAPI: FileAPI` - 文件 API 接口
- `sandboxAPI: SandboxAPI` - 沙箱 API 接口
- `logger?: Logger` - 日志接口（可选，默认为 console）
- `sandboxCallbacks?: SandboxSocketCallbacks` - 沙箱连接事件回调（可选）
- `editorCallbacks?: EditorCallbacks` - 编辑器事件回调（可选）

### `useStore(): Store`

在子组件中获取 store 实例。

**注意：**
- 必须在 `createStore` 的子组件中使用
- 必须在 Vue 组件的 `setup` 函数中调用
- 如果找不到 store，会抛出错误

## Store 说明

### Files Store

文件系统状态管理，支持：
- 文件增删改查
- 增量同步（通过 sandbox 文件监听）
- 批量操作

### Sandbox Store

沙箱连接和状态管理，支持：
- 自动连接和重连
- 连接状态监听
- 沙箱客户端实例管理

### Chat Store

会话和消息管理，支持：
- 会话创建和管理
- 消息发送和接收
- 历史消息加载（支持异步加载）
- 消息中止功能

### Editor Store

文档编辑状态管理，支持：
- 文档加载和同步
- 自动保存（60秒防抖）
- 保存冲突检测
- 未保存文件追踪

### Spec Store

需求文档和技术文档管理，支持：
- 需求创建和管理
- 文件系统解析（requirements、plan、tasks）
- 状态同步（500ms 防抖）
- 增量更新

## 开发

```bash
# 安装依赖
pnpm install

# 类型检查
pnpm type-check

# 构建
pnpm build

# 开发模式（watch）
pnpm dev
```

## 项目结构

```
src/
  ├── types/          # 类型定义
  │   ├── files.ts    # 文件相关类型
  │   ├── sandbox.ts  # 沙箱相关类型
  │   ├── chat.ts     # 聊天相关类型
  │   ├── editor.ts   # 编辑器相关类型
  │   ├── spec.ts     # 需求相关类型
  │   └── store.ts    # Store 配置类型
  ├── stores/         # Store 实现
  │   ├── files.ts    # 文件状态管理
  │   ├── sandbox.ts  # 沙箱状态管理
  │   ├── chat.ts     # 聊天状态管理
  │   ├── editor.ts   # 编辑器状态管理
  │   └── spec.ts     # 需求状态管理
  ├── utils/          # 工具函数
  │   ├── parse.ts    # 解析相关工具
  │   └── spec.ts     # 需求相关工具
  └── index.ts        # 主入口文件
```