file-starter/docs/solution-design-test-guide.md

方案设计功能测试指南

功能概述

方案设计模块提供了完整的文档方案设计、章节管理、AI辅助修改和最终文档生成功能。支持上传大文件（Word/PDF），根据需求描述生成方案，章节灵活组建，AI辅助修改，最终合并输出为Word或PDF格式。

API端点

1. 方案设计管理

• GET /api/v1/solution-designs - 获取方案设计列表
• POST /api/v1/solution-designs - 创建方案设计
• GET /api/v1/solution-designs/{id} - 获取方案设计详情
• PUT /api/v1/solution-designs/{id} - 更新方案设计
• DELETE /api/v1/solution-designs/{id} - 删除方案设计
• POST /api/v1/solution-designs/{id}/generate - 生成最终文档

2. 章节管理

• GET /api/v1/solution-designs/{id}/chapters - 获取章节列表
• POST /api/v1/solution-designs/{id}/chapters - 添加章节

3. AI辅助功能

• POST /api/v1/solution-designs/{id}/chapters/{chapterId}/ai-suggestions - 获取AI修改建议
• POST /api/v1/solution-designs/{id}/chapters/{chapterId}/apply-ai - 应用AI修改

测试流程

步骤1: 创建方案设计

curl -X POST http://localhost:3000/api/v1/solution-designs \
  -H "Authorization: Bearer <your_jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "智慧城市建设项目方案",
    "description": "针对智慧城市建设的完整解决方案",
    "requirements": "需要包含物联网设备部署、数据分析平台和用户界面设计",
    "outputFormat": "docx"
  }'

步骤2: 添加章节

curl -X POST http://localhost:3000/api/v1/solution-designs/1/chapters \
  -H "Authorization: Bearer <your_jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "chapterNumber": 1,
    "title": "项目概述",
    "content": "本项目旨在建设智慧城市基础设施...",
    "modificationInstructions": "请优化这段文字，使其更加专业"
  }'

步骤3: 获取AI修改建议

curl -X POST http://localhost:3000/api/v1/solution-designs/1/chapters/1/ai-suggestions \
  -H "Authorization: Bearer <your_jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "请优化这段文字，使其更加专业和具有说服力"
  }'

步骤4: 应用AI修改

curl -X POST http://localhost:3000/api/v1/solution-designs/1/chapters/1/apply-ai \
  -H "Authorization: Bearer <your_jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "suggestions": ["建议增加具体数据支持", "优化段落结构"],
    "revisedContent": "优化后的项目概述内容...",
    "confidence": 0.85
  }'

步骤5: 生成最终文档

curl -X POST http://localhost:3000/api/v1/solution-designs/1/generate \
  -H "Authorization: Bearer <your_jwt_token>"

管理后台访问

1. 启动开发服务器：npm run dev
2. 访问管理后台：http://localhost:5173/admin
3. 登录后左侧菜单会出现"方案设计"菜单项
4. 点击进入方案设计管理页面

功能特性

✅ 已实现功能

• 方案设计创建和管理
• 章节管理和编辑
• AI辅助修改建议
• 文档格式转换（DOCX/PDF）
• 进度跟踪和状态管理
• 管理后台界面集成
• 权限控制和用户隔离

🔧 技术特性

• 文档处理: 基于mammoth、pdf-lib、docxtemplater
• AI集成: OpenAI GPT模型辅助修改
• 文件存储: MinIO对象存储 + base64回退
• 数据库: MySQL + TypeORM实体管理
• API规范: Hono + Zod OpenAPI标准

环境要求

1. 数据库: MySQL 5.7+
2. 对象存储: MinIO（可选，支持base64回退）
3. AI服务: OpenAI API Key（可选，支持模拟模式）
4. Node.js: 18+
5. 依赖库: 见package.json

配置说明

环境变量

# 数据库配置
DB_HOST=localhost
DB_PORT=3306
DB_USERNAME=root
DB_PASSWORD=
DB_DATABASE=d8dai

# MinIO配置（可选）
MINIO_ENDPOINT=localhost
MINIO_PORT=9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
MINIO_USE_SSL=false

# OpenAI配置（可选）
OPENAI_API_KEY=your_openai_api_key

故障排除

常见问题

1. 数据库连接失败: 检查MySQL服务是否启动
2. MinIO连接失败: 系统会自动使用base64回退
3. OpenAI服务不可用: 系统会使用模拟AI响应
4. 文件上传问题: 检查存储配置和权限

日志查看

查看控制台输出获取详细错误信息：

npm run dev 2>&1 | grep -i "solution\|error"

后续优化建议

1. 性能优化: 大文档分块处理
2. 模板系统: 预定义方案模板
3. 协作功能: 多用户协同编辑
4. 版本控制: 文档版本历史
5. 批量操作: 批量导入导出