---
name: project-framework
description: 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 使用。