xtraderClient/.cursor/skills/project-framework/SKILL.md

name, description

name	description
project-framework	Defines the PolyClientVuetify project's framework, structure, and coding conventions. Use when adding or modifying any code in this repository so that changes follow the same stack, patterns, and style.

项目框架规范

在新增或修改本仓库内任何代码时，按以下规范执行，保证风格与架构一致。

技术栈

• 框架：Vue 3（Composition API）+ TypeScript
• 构建：Vite 7，路径别名 @/* → ./src/*
• UI：Vuetify 4（v-app、v-card、v-btn 等）
• 状态：Pinia
• 路由：Vue Router 5（createWebHistory）
• 代码质量：ESLint + Prettier + oxlint；单测 Vitest，E2E Playwright

目录与文件放置

用途	目录/文件	说明
页面级视图	src/views/	对应路由，一个路由一个 Vue 文件
可复用组件	src/components/	被多个 view 或其它组件引用
接口与类型	src/api/	请求封装、接口函数、响应/请求类型
全局状态	src/stores/	Pinia store，按领域拆分
路由配置	src/router/index.ts	集中声明 routes
入口与插件	src/main.ts、src/plugins/	不随意新增顶级文件

• 新页面：在 views/ 新增 .vue，并在 router/index.ts 增加 path、name、component。
• 新接口：在 api/ 下合适模块（如 event.ts）或新建 xxx.ts，复用 request.ts 的 get/post，并导出类型与函数。

Vue 组件规范

1. 单文件结构顺序：<template> → <script setup lang="ts"> → <style scoped>。
2. Script：一律使用 <script setup lang="ts">，不用 Options API。
3. Props：用 defineProps({ ... }) 声明，带 type 与必要时 default；在 script 中通过 props.xxx 访问。
4. Emits：用 defineEmits<{ eventName: [arg1Type, arg2?] }>() 做类型声明，再 emit('eventName', ...)。
5. 组合式用法：从 vue 按需导入 ref、computed、watch 等；从 vue-router 用 useRouter/useRoute；从 @/stores/xxx 用对应 useXxxStore()。
6. 组件命名：文件名 PascalCase（如 MarketCard.vue），在模板或路由中可写为 PascalCase 或 kebab-case。

模板与样式

• 模板：优先使用 Vuetify 组件；自定义类名用 kebab-case（如 market-card、semi-progress-wrap）。
• 样式：使用 <style scoped>，类名与模板中的 class 一致；需要时可加简短注释区分区块（如 /* Top Section */）。
• 多语言：当前为中文 + 英文混用，文案风格与现有页面保持一致即可。

API 层规范

• 基础请求：统一通过 src/api/request.ts 的 get<T>(path, params?, config?) 等；鉴权在 config.headers['x-token'] 传入。
• 接口模块：每个接口文件导出：
  • 请求/响应用到的 TypeScript 接口（如 XxxListItem、XxxResponse、PageResult<T>）；
  • 对外调用的 异步函数（如 getXxxList(params)），函数上方用注释标明 GET /Xxx/Yyy 或 POST /Xxx/Yyy。
• 命名：列表项类型 XxxListItem，分页结果 PageResult<T>，统一响应体 XxxResponse；与现有 event.ts 保持一致。

状态（Pinia）

• 使用 setup 写法：defineStore('storeName', () => { ... return { state, getters, actions } })。
• 状态用 ref，派生用 computed，方法直接定义为函数并 return。
• 需要持久化的（如登录态）在 store 内用 localStorage 读写，键名常量化。

路由

• 路由表在 src/router/index.ts 中集中配置；每个路由包含 path、name、component。
• 页面跳转使用 router.push() 或 router.replace()；需要带参时用 path + query 或 params（如 /trade-detail/:id）。

格式与规范

• Prettier：已配置；无分号、单引号、printWidth 100。修改或新增代码后保持格式化（项目内可运行 npm run format）。
• TypeScript：启用严格类型；新接口、函数需有明确类型，避免 any。
• 命名：
  • 文件名：组件/视图 PascalCase，其余 camelCase 或 kebab-case 与现有一致；
  • 变量/函数：camelCase；
  • 常量：全大写下划线或 camelCase 与现有文件一致；
  • 类型/接口：PascalCase。

修改与新增时的自检

• 新页面已加入 router/index.ts，组件放在 views/ 或 components/ 正确位置。
• 新接口在 api/ 中实现，使用 request.ts 并导出类型与函数。
• Vue 文件使用 <script setup lang="ts">，Props/Emits 有类型。
• 样式使用 scoped，类名 kebab-case。
• 符合现有 Prettier/ESLint 配置，无新增 lint 报错。

遵循本规范可保证与本项目现有架构和风格一致；涉及接口文档与接口实现细节时，可结合 xtrader-api-docs skill 使用。