xwl2023/Yi.Framework

Fork 0

Files

ccnetcore 33937703c7 feat: 完成排行榜功能

2026-02-01 19:32:46 +08:00

8.4 KiB

Raw Blame History

CLAUDE.md

本文件为 Claude Code (claude.ai/code) 提供本项目代码开发指导。

项目简介

意心AI - 基于 Vue 3.5 + TypeScript 开发的企业级 AI 聊天应用模板，仿豆包/通义 AI 平台。支持流式对话、AI 模型库、文件上传、Mermaid 图表渲染等功能。

技术栈

框架: Vue 3.5+ (Composition API) + TypeScript 5.8+
构建工具: Vite 6.3+
UI 组件: Element Plus 2.10.4 + vue-element-plus-x 1.3.7
状态管理: Pinia 3.0 + pinia-plugin-persistedstate
HTTP 请求: hook-fetch（支持流式/SSE，替代 Axios）
CSS: UnoCSS + SCSS
路由: Vue Router 4

常用命令

# 安装依赖（必须用 pnpm）
pnpm install

# 启动开发服务器（端口 17001）
pnpm dev

# 生产构建
pnpm build

# 预览生产构建
pnpm preview

# 代码检查与修复
pnpm lint          # ESLint 检查
pnpm fix           # ESLint 自动修复
pnpm lint:stylelint # 样式检查

# 规范提交（使用 cz-git）
pnpm cz

如何新增页面

1. 创建页面文件

页面文件统一放在 src/pages/ 目录下：

src/pages/
├── chat/                    # 功能模块文件夹
│   ├── index.vue           # 父级布局页
│   ├── conversation/       # 子页面文件夹
│   │   └── index.vue       # 子页面
│   └── image/
│       └── index.vue
├── console/
│   └── index.vue
└── your-page/              # 新增页面在这里创建
    └── index.vue

单页面示例 (src/pages/your-page/index.vue):

<template>
  <div class="your-page">
    <h1>页面标题</h1>
  </div>
</template>

<script setup lang="ts">
// 自动导入 Vue API，无需手动 import
const route = useRoute()
const router = useRouter()

// 如需使用状态管理
const userStore = useUserStore()

onMounted(() => {
  console.log('页面加载')
})
</script>

<style scoped lang="scss">
.your-page {
  padding: 20px;
}
</style>

2. 配置路由

路由配置在 src/routers/modules/staticRouter.ts。

新增独立页面（添加到 layoutRouter 的 children 中）：

{
  path: 'your-page',           // URL 路径，最终为 /your-page
  name: 'yourPage',            // 路由名称，必须唯一
  component: () => import('@/pages/your-page/index.vue'),
  meta: {
    title: '页面标题',          // 页面标题，会显示在浏览器标签
    keepAlive: 0,              // 是否缓存页面：0=缓存，1=不缓存
    isDefaultChat: false,      // 是否为默认聊天页
    layout: 'default',         // 布局类型：default/blankPage
  },
}

新增带子路由的功能模块：

{
  path: 'module-name',
  name: 'moduleName',
  component: () => import('@/pages/module-name/index.vue'),  // 父级布局页
  redirect: '/module-name/sub-page',                          // 默认重定向
  meta: {
    title: '模块标题',
    icon: 'HomeFilled',      // Element Plus 图标名称
  },
  children: [
    {
      path: 'sub-page',
      name: 'subPage',
      component: () => import('@/pages/module-name/sub-page/index.vue'),
      meta: {
        title: '子页面标题',
      },
    },
    // 带参数的路由
    {
      path: 'detail/:id',
      name: 'detailPage',
      component: () => import('@/pages/module-name/detail/index.vue'),
      meta: {
        title: '详情页',
      },
    },
  ],
}

无需布局的独立页面（添加到 staticRouter）：

{
  path: '/test/page',
  name: 'testPage',
  component: () => import('@/pages/test/page.vue'),
  meta: {
    title: '测试页面',
  },
}

3. 页面 Meta 配置说明

属性	类型	说明
title	string	页面标题，显示在浏览器标签页
keepAlive	number	0=缓存页面，1=不缓存
layout	string	布局类型：'default' 使用默认布局，'blankPage' 使用空白布局
isDefaultChat	boolean	是否为默认聊天页面
icon	string	Element Plus 图标名称，用于菜单显示
isHide	string	'0'=在菜单中隐藏，'1'=显示
isKeepAlive	string	'0'=缓存，'1'=不缓存（字符串版）

4. 布局说明

布局组件位于 src/layouts/：

default: 默认布局，包含侧边栏、顶部导航等
blankPage: 空白布局，仅包含路由出口

在路由 meta 中通过 layout 字段指定：

meta: {
  layout: 'default',     // 使用默认布局（有侧边栏）
  // 或
  layout: 'blankPage',   // 使用空白布局（全屏页面）
}

5. 页面跳转示例

// 在 script setup 中使用
const router = useRouter()

// 跳转页面
router.push('/chat/conversation')
router.push({ name: 'chatConversation' })
router.push({ path: '/chat/conversation/:id', params: { id: '123' } })

// 获取路由参数
const route = useRoute()
console.log(route.params.id)

6. 完整新增页面示例

假设要新增一个"数据统计"页面：

步骤 1: 创建页面文件 src/pages/statistics/index.vue

<template>
  <div class="statistics-page">
    <el-card>
      <template #header>
        <span>数据统计</span>
      </template>
      <div>页面内容</div>
    </el-card>
  </div>
</template>

<script setup lang="ts">
const { data, loading } = useFetch('/api/statistics').get().json()
</script>

<style scoped lang="scss">
.statistics-page {
  padding: 20px;
}
</style>

步骤 2: 在 src/routers/modules/staticRouter.ts 中添加路由

{
  path: 'statistics',
  name: 'statistics',
  component: () => import('@/pages/statistics/index.vue'),
  meta: {
    title: '意心Ai-数据统计',
    keepAlive: 0,
    isDefaultChat: false,
    layout: 'default',
  },
}

步骤 3: 在菜单中添加入口（如需要）

如需在侧边栏显示，需在相应的位置添加菜单配置。

核心架构说明

HTTP 请求封装

位于 src/utils/request.ts，使用 hook-fetch：

import { get, post, put, del } from '@/utils/request'

// GET 请求
const { data } = await get('/api/endpoint').json()

// POST 请求
const result = await post('/api/endpoint', { key: 'value' }).json()

特点：

自动附加 JWT Token 到请求头
自动处理 401/403 错误
支持 Server-Sent Events (SSE) 流式响应

状态管理

Pinia stores 位于 src/stores/modules/：

Store	用途
user.ts	用户认证、登录状态
chat.ts	聊天消息、流式输出
session.ts	会话列表、当前会话
model.ts	AI 模型配置

使用方式：

const userStore = useUserStore()
userStore.setToken(token, refreshToken)
userStore.logout()

自动导入

项目已配置 unplugin-auto-import，以下 API 无需手动 import：

Vue API: ref, reactive, computed, watch, onMounted 等
Vue Router: useRoute, useRouter
Pinia: createPinia, storeToRefs
VueUse: useFetch, useStorage 等

路径别名

别名	对应路径
`@/`	`src/`
`@components/`	`src/vue-element-plus-y/components/`

环境变量

开发配置在 .env.development：

VITE_WEB_BASE_API=/dev-api           # API 前缀
VITE_API_URL=http://localhost:19001/api/app  # 后端地址
VITE_SSO_SEVER_URL=http://localhost:18001    # SSO 地址

Vite 开发服务器会自动将 /dev-api 代理到后端 API。

代码规范

提交规范

使用 pnpm cz 进行规范提交，类型包括：

feat: 新功能
fix: 修复
docs: 文档
style: 代码格式
refactor: 重构
perf: 性能优化
test: 测试
build: 构建
ci: CI/CD
revert: 回滚
chore: 其他

Git Hooks

pre-commit: 自动运行 ESLint 修复
commit-msg: 校验提交信息格式

构建优化

Vite 配置中的代码分割策略（vite.config.ts）：

Chunk 名称	包含内容
vue-vendor	Vue 核心库、Vue Router
pinia	Pinia 状态管理
element-plus	Element Plus UI 库
markdown	Markdown 解析相关
utils	Lodash、VueUse 工具库
highlight	代码高亮库
echarts	图表库
pdf	PDF 处理库

后端集成

后端为 .NET 8 项目，本地启动命令：

cd E:\devDemo\Yi\Yi.Abp.Net8\src\Yi.Abp.Web
dotnet run

前端开发时，后端默认运行在 http://localhost:19001。

8.4 KiB Raw Blame History Unescape Escape