AiSolv 智解

Appearance

开发指南 ​

开发环境搭建 ​

系统要求 ​

  • 操作系统: macOS / Windows / Linux
  • Node.js: >= 18.0.0
  • 包管理器: npm >= 9.0.0 或 pnpm >= 8.0.0
  • Git: >= 2.30.0

推荐工具 ​

  • IDE: VSCode / WebStorm
  • 浏览器: Chrome / Edge / Safari（最新版）
  • 移动端调试: Chrome DevTools / Safari DevTools

项目架构 ​

技术栈 ​

层级技术
前端框架Vue 3 + TypeScript
状态管理Pinia
路由Vue Router
UI 组件Ant Design Vue
构建工具Vite
移动端UniApp
工作流引擎自研流程引擎
AI 能力OpenAI / 自研模型
服务端Node.js / Java
数据库MySQL / Redis / Elasticsearch
消息队列RabbitMQ / Kafka

目录结构 ​

aisolv/
├── apps/                    # 应用层
│   ├── admin/              # 管理后台
│   ├── mobile/             # 移动端（UniApp）
│   ├── miniapp/            # 小程序
│   └── web/                # Web 端
├── packages/               # 共享包
│   ├── sdk/                # 工单 SDK
│   ├── ui/                 # UI 组件库
│   ├── workflow/           # 工作流引擎
│   ├── shared/             # 共享工具
│   └── types/              # 类型定义
├── server/                 # 服务端
│   ├── gateway/            # API 网关
│   ├── ticket/             # 工单服务
│   ├── workflow/           # 工作流服务
│   ├── ai/                 # AI 服务
│   └── notify/             # 通知服务
├── docs/                   # 文档
└── scripts/                # 脚本工具

开发规范 ​

代码规范 ​

  • 使用 ESLint + Prettier 进行代码格式化
  • 遵循 Vue 3 组合式 API 风格
  • TypeScript 严格模式启用
  • 组件命名使用 PascalCase
  • 函数命名使用 camelCase

Git 规范 ​

类型(scope): 简短描述

详细描述（可选）

Footer（可选）

类型说明：

  • feat: 新功能
  • fix: 修复
  • docs: 文档
  • style: 格式
  • refactor: 重构
  • perf: 性能优化
  • test: 测试
  • chore: 构建/工具

示例：

feat(ticket): 添加 AI 智能建单功能

- 支持自然语言描述创建工单
- AI 自动提取关键信息
- 支持语音描述建单

Closes #123

分支管理 ​

  • main: 主分支，稳定版本
  • develop: 开发分支
  • feature/*: 功能分支
  • hotfix/*: 紧急修复
  • release/*: 发布分支

模块开发 ​

SDK 开发 ​

typescript
// packages/sdk/src/core/client.ts
export class AiSolvClient {
  private ws: WebSocket
  private options: ClientOptions
  private eventEmitter: EventEmitter

  constructor(options: ClientOptions) {
    this.options = options
    this.eventEmitter = new EventEmitter()
  }

  async connect(): Promise<void> {
    this.ws = new WebSocket(this.options.wsUrl)
    this.ws.onopen = () => this.eventEmitter.emit('connect')
    this.ws.onmessage = (e) => this.handleMessage(e.data)
    this.ws.onclose = () => this.eventEmitter.emit('disconnect')
  }

  async createTicketByAI(description: string): Promise<Ticket> {
    const response = await this.http.post('/api/tickets/ai-create', {
      description
    })
    return response.data
  }

  onTicketCreated(handler: TicketHandler): void {
    this.eventEmitter.on('ticket:created', handler)
  }
}

工作流引擎开发 ​

typescript
// packages/workflow/src/engine.ts
export class WorkflowEngine {
  private nodes: Map<string, WorkflowNode>
  private context: WorkflowContext

  async execute(workflowId: string, ticket: Ticket): Promise<void> {
    const workflow = await this.loadWorkflow(workflowId)
    const startNode = workflow.getStartNode()
    await this.executeNode(startNode, ticket)
  }

  private async executeNode(node: WorkflowNode, ticket: Ticket): Promise<void> {
    switch (node.type) {
      case 'approval':
        await this.executeApprovalNode(node, ticket)
        break
      case 'condition':
        await this.executeConditionNode(node, ticket)
        break
      case 'notification':
        await this.executeNotificationNode(node, ticket)
        break
    }
  }
}

UI 组件开发 ​

vue
<!-- packages/ui/src/components/TicketCard.vue -->
<template>
  <div class="ticket-card" :class="`priority-${ticket.priority}`">
    <div class="header">
      <span class="id">#{{ ticket.id }}</span>
      <Tag :color="statusColor">{{ ticket.status }}</Tag>
    </div>
    <div class="title">{{ ticket.title }}</div>
    <div class="meta">
      <span>{{ ticket.assignee }}</span>
      <span>{{ formatTime(ticket.createdAt) }}</span>
    </div>
  </div>
</template>

<script setup lang="ts">
interface Props {
  ticket: Ticket
}

defineProps<Props>()

const statusColor = computed(() => {
  const map: Record<string, string> = {
    open: 'blue',
    in_progress: 'orange',
    pending_review: 'purple',
    completed: 'green',
    closed: 'default'
  }
  return map[props.ticket.status] || 'default'
})
</script>

页面开发 ​

vue
<!-- apps/admin/src/pages/ticket/list.vue -->
<template>
  <div class="ticket-list-page">
    <PageHeader title="工单管理">
      <template #extra>
        <a-button type="primary" @click="showAICreate = true">
          🤖 AI 建单
        </a-button>
        <a-button @click="showTemplateCreate = true">
          📋 模板建单
        </a-button>
      </template>
    </PageHeader>
    <TicketFilter @change="handleFilterChange" />
    <TicketTable
      :tickets="tickets"
      :loading="loading"
      @row-click="handleRowClick"
    />
    <AICreateModal v-model:visible="showAICreate" @created="refresh" />
  </div>
</template>

<script setup lang="ts">
import { ref, onMounted } from 'vue'
import { useTicketStore } from '@/stores/ticket'

const ticketStore = useTicketStore()
const tickets = ref<Ticket[]>([])
const loading = ref(false)
const showAICreate = ref(false)
const showTemplateCreate = ref(false)

onMounted(async () => {
  await ticketStore.loadTickets()
  tickets.value = ticketStore.tickets
})

const refresh = async () => {
  loading.value = true
  await ticketStore.loadTickets()
  tickets.value = ticketStore.tickets
  loading.value = false
}
</script>

调试技巧 ​

Web 端调试 ​

  1. Vue DevTools: 安装浏览器扩展
  2. Network: 查看 API 请求与 WebSocket 连接状态
  3. Console: 查看 SDK 日志输出

移动端调试 ​

bash
# H5 调试
npm run dev:h5

# 微信小程序调试
npm run dev:mp-weixin

# APP 调试
npm run dev:app

测试 ​

单元测试 ​

bash
# 运行所有测试
npm run test

# 运行指定模块测试
npm run test -- packages/sdk

# 覆盖率报告
npm run test:coverage

E2E 测试 ​

bash
# 运行 E2E 测试
npm run test:e2e

# headed 模式
npm run test:e2e -- --headed

性能优化 ​

前端优化 ​

  1. 虚拟列表: 长工单列表使用虚拟滚动
  2. 按需加载: 工作流设计器等大组件按需加载
  3. 数据分页: 工单列表分页加载
  4. 缓存策略: 工单详情数据本地缓存

服务端优化 ​

  1. 连接池: 数据库连接池管理
  2. 缓存策略: Redis 缓存热点数据
  3. 消息队列: 通知推送异步处理
  4. 索引优化: 工单查询索引优化

部署 ​

Docker 部署 ​

bash
# 构建镜像
docker build -t aisolv:latest .

# 运行容器
docker run -d -p 8080:8080 aisolv:latest

Kubernetes 部署 ​

bash
# 应用配置
kubectl apply -f k8s/

# 查看状态
kubectl get pods -n aisolv

常见问题 ​

Q: AI 建单不准确？ ​

A: 检查：

  1. AI 模型配置是否正确
  2. 描述信息是否足够清晰
  3. 工单模板字段映射是否正确

Q: 工作流执行异常？ ​

A: 检查：

  1. 流程节点配置是否完整
  2. 条件分支表达式是否正确
  3. 审批人/处理人是否已配置

Q: 通知推送失败？ ​

A: 检查：

  1. 通知渠道配置是否正确
  2. 通知模板是否已设置
  3. 用户通知偏好是否开启

相关资源 ​