huhan3000/unified-docs/USER_GUIDE.md

# 胡汉三千年统一文档管理系统用户指南

## 概述

统一文档管理系统旨在整合胡汉三千年项目中分散的文档资源，包括 `core-docs`、`thematic-research` 等目录，提供统一的文档管理、搜索、版本控制和索引功能。

## 系统架构

### 目录结构
```
unified-docs/
├── README.md                 # 系统概述
├── unified-index.md         # 统一索引文件
├── start-system.sh          # 系统启动脚本
├── config/
│   └── settings.json        # 系统配置
├── tools/
│   ├── doc-indexer.py       # 文档索引工具
│   ├── search-tool.py        # 搜索工具
│   ├── version-manager.py    # 版本管理工具
│   └── doc-migrator.py       # 文档迁移工具
└── .versions/               # 版本数据库
```

### 主要分类目录
1. **01-core-theory** - 核心理论文档
2. **02-thematic-research** - 专题研究文档
3. **03-historical-analysis** - 历史分析文档
4. **04-cultural-comparison** - 文化比较文档
5. **05-technical-implementation** - 技术实现文档
6. **06-project-docs** - 项目文档

## 快速开始

### 1. 系统状态检查
```bash
cd /home/ben/code/huhan3000/unified-docs
./start-system.sh status
```

### 2. 文档迁移（首次使用）
```bash
# 模拟迁移（预览迁移计划）
./start-system.sh migrate

# 实际迁移（需要确认）
# 系统会询问是否继续实际迁移
```

### 3. 更新文档索引
```bash
./start-system.sh index
```

### 4. 搜索文档
```bash
./start-system.sh search "音韵"
./start-system.sh search "文明传播"
```

### 5. 查看版本统计
```bash
./start-system.sh versions
```

## 工具使用说明

### 文档索引工具 (doc-indexer.py)

**功能**：自动扫描文档目录，生成统一的索引文件

**使用方法**：
```bash
cd /home/ben/code/huhan3000/unified-docs
python tools/doc-indexer.py
```

**输出文件**：
- `unified-index.json` - JSON格式索引
- `unified-index.md` - Markdown格式索引

### 搜索工具 (search-tool.py)

**功能**：提供全文搜索、关键词检索、标题搜索等功能

**使用方法**：
```bash
# 交互式搜索
python tools/search-tool.py

# 命令行搜索
python tools/search-tool.py "搜索关键词"
```

**搜索模式**：
- `full_text` - 全文搜索
- `keyword` - 关键词搜索
- `title` - 标题搜索
- `category` - 分类搜索

### 版本管理工具 (version-manager.py)

**功能**：文档版本控制、变更记录、版本比较和恢复

**使用方法**：
```bash
# 创建版本
python tools/version-manager.py create 文档路径 "版本注释"

# 列出版本
python tools/version-manager.py list [文档路径]

# 比较版本
python tools/version-manager.py compare 文档路径 版本1 版本2

# 恢复版本
python tools/version-manager.py restore 文档路径 版本号

# 查看统计
python tools/version-manager.py stats

# 批量创建版本
python tools/version-manager.py batch 目录路径 "批量注释"
```

### 文档迁移工具 (doc-migrator.py)

**功能**：从现有目录迁移文档到统一系统

**使用方法**：
```bash
# 完整迁移
python tools/doc-migrator.py migrate [--dry-run]

# 仅迁移core-docs
python tools/doc-migrator.py migrate-core [--dry-run]

# 仅迁移thematic-research
python tools/doc-migrator.py migrate-thematic [--dry-run]

# 查看迁移摘要
python tools/doc-migrator.py summary
```

## 分类规则

### 自动分类规则
系统根据文件路径和内容关键词自动分类：

| 关键词 | 目标分类 |
|--------|----------|
| 音韵 | 01-core-theory/01-phonological-archaeology |
| 文明 | 01-core-theory/02-civilization-diffusion |
| 方法 | 01-core-theory/03-methodology |
| 理论 | 01-core-theory/05-theoretical-framework |
| 实证 | 02-thematic-research/01-empirical-studies |
| 历史 | 03-historical-analysis/01-historical-events |
| 文化 | 04-cultural-comparison/01-cross-cultural |
| 技术 | 05-technical-implementation/01-tools |
| 项目 | 06-project-docs/01-management |

### 手动分类
如需手动调整分类，可以：
1. 移动文件到正确的分类目录
2. 运行索引工具更新索引
3. 创建版本记录变更

## 维护指南

### 日常维护
1. **定期更新索引**：文档变更后运行索引工具
2. **版本控制**：重要修改前创建版本
3. **备份**：系统自动维护版本备份

### 故障排除

**问题**：搜索工具找不到文档
**解决**：运行索引工具更新索引

**问题**：版本管理工具报错
**解决**：检查版本数据库文件完整性

**问题**：迁移工具分类错误
**解决**：手动移动文件并更新索引

### 性能优化
- 索引文件较大时，使用分类过滤搜索
- 定期清理旧版本（保留30天内的版本）
- 使用批量操作减少工具调用次数

## 最佳实践

### 文档命名规范
- 使用中文描述性文件名
- 包含关键词便于自动分类
- 避免特殊字符和空格

### 版本管理策略
- 重大修改前创建版本
- 添加有意义的版本注释
- 定期查看版本统计

### 搜索优化
- 使用具体的关键词
- 结合分类过滤
- 利用标题搜索提高精度

## 技术支持

### 系统要求
- Python 3.6+
- 标准库：hashlib, json, pathlib, shutil, datetime

### 问题反馈
如遇系统问题，请检查：
1. 依赖包是否完整
2. 文件权限是否正确
3. 配置文件是否存在

## 更新日志

### v1.0.0 (2025-10-30)
- 初始版本发布
- 实现基本文档管理功能
- 提供完整的工具套件

---

*本指南将随系统更新而更新，请定期查看最新版本。*