86 lines
5.0 KiB
Markdown
86 lines
5.0 KiB
Markdown
---
|
||
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 使用。
|