# 04-故障排除 - AI驱动软件著作权申请材料生成系统

📚 **学习路径第4步** | 🔧 **目标**：诊断和解决系统使用过程中的常见问题

> 🗺️ **完整学习路径**：00-文档导航 → 01-快速开始 → 02-安装指南 → 03-使用说明 → **04-故障排除** → 05-FAQ

## 🔍 快速诊断

### 自动化诊断（推荐）

使用内置检查脚本快速诊断问题：

```bash
# 快速诊断（30秒内完成）
python3 /path/to/AI-Copyright-Application-Generator/scripts/validators/check_project.py --quick

# 完整诊断（包含语法和功能测试）
python3 /path/to/AI-Copyright-Application-Generator/scripts/validators/check_project.py

# 核心功能测试
python3 /path/to/AI-Copyright-Application-Generator/scripts/validators/run_tests.py
```

**根据结果判断**：
- ✅ **健康度 > 90%** - 系统正常，问题可能在使用方法
- ⚠️ **健康度 80-90%** - 有警告，查看具体警告信息
- ❌ **健康度 < 80%** - 有错误，查看错误详情并修复

### 手动诊断检查清单

如果自动诊断无法运行，请按以下顺序检查：

1. **环境检查**
   ```bash
   python3 --version  # 确认Python版本3.6+
   pwd                 # 确认在正确的目录中
   ls ai-copyright-config.json   # 确认配置文件存在
   ls specs_docs/      # 确认核心文件存在
   ```

2. **权限检查**
   ```bash
   ls -la *.py *.sh    # 确认脚本有执行权限
   ```

3. **文件完整性检查**
   ```bash
   ls system_prompts/  # 确认8个AI提示词文件存在
   wc -l system_prompts/*.md  # 确认文件不为空
   ```

## 安装和初始化问题

### 问题1：脚本无法执行

**症状**：
- `Permission denied` 错误
- `Command not found` 错误

**原因分析**：
- 脚本没有执行权限
- Python环境配置问题

**解决方案**：
```bash
# 方案1：添加执行权限
chmod +x init_project.py
chmod +x init_project.sh

# 方案2：直接使用Python运行
python3 /path/to/AI-Copyright-Application-Generator/scripts/init/init_project.py project-name

# 方案3：检查Python安装
which python3
python3 --version
```

### 问题2：找不到源文件目录

**症状**：
```
错误：源文件目录 'specs_doc' 不存在
```

**原因分析**：
- 不在项目根目录中运行脚本
- 项目文件不完整

**解决方案**：
```bash
# 确认当前位置
pwd
ls -la

# 导航到正确目录
cd AI-Copyright-Application-Generator

# 验证目录结构
ls specs_docs/
ls system_prompts/
```

### 问题3：项目创建失败

**症状**：
- 目录创建失败
- 文件复制错误

**原因分析**：
- 磁盘空间不足
- 目标目录权限问题
- 目标目录已存在

**解决方案**：
```bash
# 检查磁盘空间
df -h

# 检查目标目录
ls -la 目标目录名/

# 强制覆盖（Python版本）
cd AI-Copyright-Application-Generator
python3 scripts/init/init_project.py project-name --force

# 手动清理后重试
rm -rf 目标目录名
python3 /path/to/AI-Copyright-Application-Generator/scripts/init/init_project.py project-name
```

## 检查脚本问题

### 问题：检查脚本无法运行

**症状**：
- `check_project.py` 执行失败
- `run_tests.py` 报错

**解决方案**：
```bash
# 检查Python版本
python3 --version  # 需要3.6+

# 检查脚本权限
chmod +x check_project.py run_tests.py

# 尝试直接运行
python3 /path/to/AI-Copyright-Application-Generator/scripts/validators/check_project.py --quick
```

### 问题：检查结果显示错误

**症状**：
- 健康度 < 80%
- 显示文件缺失或配置错误

**解决方案**：
```bash
# 查看详细错误信息
python3 /path/to/AI-Copyright-Application-Generator/scripts/validators/check_project.py

# 根据错误类型处理：
# 1. 文件缺失 - 重新克隆项目
# 2. 配置错误 - 检查 ai-copyright-config.json
# 3. 权限问题 - chmod +x *.py *.sh
```

### 问题：自动化测试失败

**症状**：
- `run_tests.py` 显示测试失败
- 成功率 < 100%

**解决方案**：
```bash
# 查看具体失败测试
python3 /path/to/AI-Copyright-Application-Generator/scripts/validators/run_tests.py

# 常见解决方法：
# 1. 语法错误 - 检查脚本文件
# 2. 文件缺失 - 补充缺失文件
# 3. 配置问题 - 修复配置文件
```

## 配置和使用问题

### 问题4：ai-copyright-config.json格式错误

**症状**：
- JSON解析错误
- 配置读取失败

**原因分析**：
- JSON语法错误
- 编码问题

**解决方案**：
```bash
# 验证JSON格式
python3 -c "import json; print(json.load(open('ai-copyright-config.json')))"

# 查找语法错误
cat ai-copyright-config.json | python3 -m json.tool
```

**标准ai-copyright-config.json模板**：
```json
{
  "title": "您的软件系统完整名称",
  "short_title": "系统简称",
  "front": "JavaScript",
  "backend": "Java",
  "requirements_description": "requires_docs/需求文档.md"
}
```

### 问题5：需求文档不完整

**症状**：
- 生成的材料质量差
- 内容不符合预期

**原因分析**：
- 需求文档信息不够详细
- 缺少关键信息

**解决方案**：
1. **检查必要信息**：
   - 系统概述和核心功能
   - 具体功能需求描述
   - 技术架构要求
   - 特色功能和创新点

2. **参考完整模板**：
   ```bash
   # 查看需求文档模板
   cat requires_docs/需求文档.md
   ```

### 问题6：AI提示词执行问题

**症状**：
- AI生成内容质量不佳
- 生成内容不符合软著要求

**原因分析**：
- 提示词使用方法不当
- 输入信息不够详细

**解决方案**：
1. **检查提示词完整性**：
   ```bash
   ls system_prompts/
   # 应该包含8个.md文件
   ```

2. **按六阶段优化流程使用提示词**：
   - **阶段一**：01-软著框架系统提示词.md → 框架设计文档
   - **阶段二**：02-页面规划系统提示词.md → 页面清单，03-界面设计系统提示词.md → 界面设计方案
   - **阶段三**：04-网页代码生成系统提示词.md → 前端代码
   - **阶段四**：05-数据库代码生成系统提示词.md → 数据库设计，06-后端代码生成系统提示词.md → 后端代码
   - **阶段五**：07-用户手册系统提示词.md → 用户手册，08-软件著作权登记信息表系统提示词.md → 申请表格
   - **阶段六**：材料整理和质量验收

## 代码生成问题

### 问题7：代码生成脚本错误

**症状**：
```
FileNotFoundError: No such file or directory
```

**原因分析**：
- 源代码文件不存在
- 目录结构不正确

**解决方案**：
```bash
# 检查源代码目录
ls -la output_sourcecode/
ls -la output_sourcecode/front/
ls -la output_sourcecode/backend/

# 确保有源代码文件后再运行生成脚本
python3 /path/to/AI-Copyright-Application-Generator/scripts/generators/merge_frontend_simple.py
python3 /path/to/AI-Copyright-Application-Generator/scripts/generators/merge_backend_simple.py
python3 /path/to/AI-Copyright-Application-Generator/scripts/generators/merge_all_simple.py
```

### 问题8：生成的源代码文档为空

**症状**：
- 生成的.txt文档内容很少
- 缺少代码内容

**原因分析**：
- 源代码目录中文件不足
- 文件编码问题

**解决方案**：
```bash
# 检查源代码文件数量和内容
find output_sourcecode/ -name "*.html" -o -name "*.java" -o -name "*.js" | wc -l
find output_sourcecode/ -name "*.html" -exec wc -l {} \;

# 建议的文件数量：
# 前端：10-12个HTML文件
# 后端：15-20个Java文件（包含Controller、Service、Entity等）
```

## 输出文件问题

### 问题9：输出文档格式不正确

**症状**：
- 文档格式不符合软著要求
- 文件编码错误

**解决方案**：
```bash
# 检查文件编码
file output_docs/*.txt
file output_docs/*.md

# 转换编码（如果需要）
iconv -f UTF-8 -t GBK input_file > output_file
```

### 问题10：材料不完整

**症状**：
- 缺少必需的申请文档
- 文件内容过少

**解决方案**：
1. **检查必需文件清单**：
   ```bash
   # 必需的软著申请材料
   ls output_docs/软件著作权登记信息表.md
   ls output_docs/数据库代码.txt
   ls output_docs/用户手册.txt
   ls output_docs/前端源代码.txt
   ls output_docs/后端源代码.txt
   ```

2. **验证文件内容充实度**：
   ```bash
   # 检查文件行数（参考标准）
   wc -l output_docs/前端源代码.txt  # 建议>500行
   wc -l output_docs/后端源代码.txt  # 建议>800行
   wc -l output_docs/数据库代码.txt  # 建议>100行
   ```

## 系统兼容性问题

### 问题11：Windows系统兼容性

**症状**：
- 路径分隔符错误
- 编码显示问题

**解决方案**：
```bash
# 使用Python脚本（推荐）
python init_project.py project-name

# 设置正确的编码环境
chcp 65001  # Windows命令行设置UTF-8编码
```

### 问题12：macOS权限问题

**症状**：
- 脚本执行被阻止
- 文件访问权限错误

**解决方案**：
```bash
# 在系统偏好设置 > 安全性与隐私中允许脚本执行
# 或使用以下命令
sudo xattr -rd com.apple.quarantine AI-Copyright-Application-Generator/

# 修复权限
sudo chown -R $(whoami) AI-Copyright-Application-Generator/
chmod -R 755 AI-Copyright-Application-Generator/
```

## 性能和资源问题

### 问题13：生成过程缓慢

**原因分析**：
- 文件数量过多
- 系统资源不足

**解决方案**：
```bash
# 检查系统资源
free -h    # Linux内存使用
top        # 系统进程状态

# 分阶段生成，避免一次性处理过多文件
python3 /path/to/AI-Copyright-Application-Generator/scripts/generators/merge_frontend_simple.py
# 等待完成后再执行下一步
python3 /path/to/AI-Copyright-Application-Generator/scripts/generators/merge_backend_simple.py
```

## 获取帮助

### 问题诊断信息收集

当需要技术支持时，请提供以下信息：

```bash
# 系统环境信息
uname -a                 # 操作系统信息
python3 --version        # Python版本
pwd                      # 当前目录

# 项目状态信息
ls -la                   # 文件列表
ls system_prompts/  # AI提示词文件
ls output_sourcecode/    # 源代码状态
ls output_docs/          # 输出文档状态

# 错误信息
# 请提供完整的错误消息和执行的命令
```

### 常见错误代码含义

- **权限错误 (Permission denied)**：文件权限不足
- **文件未找到 (No such file or directory)**：路径错误或文件缺失
- **JSON解析错误**：配置文件格式问题
- **编码错误**：文件编码不匹配

### 重置和重新开始

如果问题无法解决，可以完全重置：

```bash
# 备份重要的需求文档
cp requires_docs/需求文档.md backup_需求文档.md

# 重新初始化项目
rm -rf output_docs/ output_sourcecode/ process_docs/
mkdir -p output_docs output_sourcecode/front output_sourcecode/backend process_docs

# 恢复需求文档
cp backup_需求文档.md requires_docs/需求文档.md

# 重新开始生成流程
```

---

**如果问题仍未解决，请参考其他文档或创建详细的问题报告，包含系统环境、执行步骤和完整错误信息。**