lobster-memory-sync/README.md

# 🦐 龙虾记忆同步系统

一个用于同步和管理龙虾记忆文件的前后端分离系统，提供文件树展示、差异对比和双向同步功能。

## 📋 目录

- [项目概述](#项目概述)
- [技术栈](#技术栈)
- [功能特性](#功能特性)
- [项目结构](#项目结构)
- [快速开始](#快速开始)
- [API 文档](#api-文档)
- [开发指南](#开发指南)
- [部署说明](#部署说明)
- [开发日志](#开发日志)

## 项目概述

龙虾记忆同步系统是一个专为 OpenClaw 龙虾设计的记忆文件管理工具，支持：
- 扫描龙虾记忆目录
- 检查文件差异
- 双向同步（本地 ↔ 数据库）
- 版本历史追踪
- 统计信息展示

## 技术栈

### 后端
- Django 4.x
- Django REST Framework
- PostgreSQL 15
- Python 3.11

### 前端
- React 18
- Ant Design 5.x
- react-diff-viewer-continued
- Axios

### 部署
- Docker
- Docker Compose
- Nginx

## 功能特性

- ✅ **文件树展示**：可视化展示龙虾记忆文件结构
- ✅ **差异对比**：直观对比本地文件和数据库文件
- ✅ **双向同步**：支持本地→数据库和数据库→本地同步
- ✅ **版本历史**：追踪文件的修改历史
- ✅ **统计信息**：展示文件数量、大小等统计信息
- ✅ **REST API**：完整的 RESTful API 接口

## 项目结构

```
lobster-memory-sync/
├── backend/                    # Django 后端
│   ├── manage.py              # Django 管理脚本
│   ├── requirements.txt       # Python 依赖
│   ├── Dockerfile             # 后端 Docker 配置
│   ├── memory_sync/           # Django 项目配置
│   │   ├── settings.py        # 项目设置
│   │   ├── urls.py            # 主路由
│   │   └── wsgi.py            # WSGI 配置
│   └── memory_app/            # 核心应用
│       ├── models.py          # 数据模型
│       ├── serializers.py     # 序列化器
│       ├── views.py           # 视图
│       ├── urls.py            # 应用路由
│       └── services.py        # 业务逻辑
├── frontend/                   # React 前端
│   ├── package.json           # Node 依赖
│   ├── Dockerfile             # 前端 Docker 配置
│   ├── public/                # 静态资源
│   └── src/                   # 源代码
│       ├── api/               # API 客户端
│       │   └── index.js
│       ├── components/        # React 组件
│       │   ├── FileTree.js    # 文件树
│       │   └── FileDiff.js    # 差异对比
│       ├── App.js             # 主应用
│       └── index.js           # 入口文件
├── docker-compose.yml         # Docker Compose 配置
├── README.md                  # 项目文档
└── DEPLOY.md                  # 部署文档
```

## 快速开始

### 前置条件

- Docker
- Docker Compose
- 端口占用检查：8086（前端）、8087（后端）、5432（数据库）

### 一键启动

```bash
# 克隆项目
cd /home/node/.openclaw/workspace/daotong/lobster-memory-sync

# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down
```

### 访问地址

- 前端：http://localhost:8086
- 后端 API：http://localhost:8087/api/
- PostgreSQL：localhost:5432

## API 文档

### 扫描文件

```
GET /api/scan/?lobster_id=daotong
```

**响应示例：**
```json
{
  "files": [
    {
      "name": "MEMORY.md",
      "path": "MEMORY.md",
      "type": "file",
      "size": 1234,
      "last_modified": "2026-04-05T12:00:00Z"
    }
  ]
}
```

### 检查同步状态

```
GET /api/status/?lobster_id=daotong&file_path=MEMORY.md
```

**响应示例：**
```json
{
  "synced": false,
  "has_difference": true,
  "difference": "+ 新增内容\n- 删除内容"
}
```

### 获取文件差异

```
GET /api/diff/?lobster_id=daotong&file_path=MEMORY.md
```

### 同步到数据库

```
POST /api/sync/db/
Content-Type: application/json

{
  "lobster_id": "daotong",
  "file_path": "MEMORY.md"
}
```

### 同步到本地

```
POST /api/sync/local/
Content-Type: application/json

{
  "lobster_id": "daotong",
  "file_path": "MEMORY.md"
}
```

## 开发指南

### 后端开发

```bash
# 进入后端容器
docker exec -it lobster-backend bash

# 创建迁移
python manage.py makemigrations memory_app
python manage.py migrate

# 创建超级用户
python manage.py createsuperuser

# 运行开发服务器
python manage.py runserver 0.0.0.0:8087
```

### 前端开发

```bash
# 本地开发（不使用 Docker）
cd frontend
npm install
npm start

# 构建生产版本
npm run build
```

## 部署说明

详细部署文档请参考 [DEPLOY.md](DEPLOY.md)

### 生产环境部署

1. 修改 `docker-compose.yml` 中的环境变量
2. 配置 Nginx 反向代理
3. 启用 HTTPS
4. 配置数据库备份

### 故障排查

```bash
# 查看日志
docker-compose logs -f backend
docker-compose logs -f frontend

# 重启服务
docker-compose restart

# 清理数据
docker-compose down -v
docker-compose up -d
```

## 开发日志

- **2026-04-05**: 项目初始化
  - 完成后端核心功能（Django + DRF + PostgreSQL）
  - 完成前端核心功能（React + Ant Design）
  - 完成部署配置（Docker Compose）
  - 推送到 Git 仓库：https://xjp.datalibstar.com/daotong/lobster-memory-sync.git

## 📝 License

MIT

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！