swimmingUni/AGENTS.md

AGENTS.md - Swimming uni-app Project

Build & Development Commands

Development Servers

npm run dev:h5              # Run H5 development server
npm run dev:mp-weixin       # Run WeChat mini-program development
npm run dev:app             # Run app development
npm run dev:app-android     # Run Android app development
npm run dev:app-ios         # Run iOS app development
npm run dev:mp-alipay       # Run Alipay mini-program
npm run dev:mp-baidu        # Run Baidu mini-program
npm run dev:mp-qq           # Run QQ mini-program
npm run dev:mp-toutiao      # Run Toutiao mini-program

Build Commands

npm run build:h5            # Build for H5
npm run build:mp-weixin     # Build for WeChat mini-program
npm run build:app           # Build for app
npm run build:app-android   # Build for Android
npm run build:app-ios       # Build for iOS

Type Checking

npm run type-check          # Run TypeScript type checking (vue-tsc --noEmit)

Testing

• Note: No test framework configured in this project yet.

Code Style Guidelines

Imports & Path Aliases

• Use @/ alias for imports from src/ directory (configured in tsconfig.json)
• Example: import { Service } from '@/Service/Service'
• Import Vue composition API functions from 'vue'
• Import uni-app lifecycle hooks from @dcloudio/uni-app

File Structure

src/
├── pages/           # Page components (with sub-packages)
├── components/      # Reusable Vue components
├── Service/         # API services and utilities
├── common/          # Common utilities and helpers
├── static/          # Static assets (images, etc.)
├── types/           # TypeScript type definitions
├── uni_modules/     # Uni-app modules
└── colorui/         # ColorUI CSS framework

Naming Conventions

• Files: PascalCase for components (e.g., ImageCropper.vue), camelCase for utilities
• Components: PascalCase for component names
• Variables: camelCase for local variables and functions
• Constants: UPPER_SNAKE_CASE for constants
• Classes: PascalCase for class names (e.g., Service)
• CSS Classes: kebab-case (e.g., home-container, timer-card)

TypeScript

• Use lang="ts" in Vue SFC <script> tags
• Use <script setup> syntax for Vue 3 composition API
• Type function parameters and return values
• Use any sparingly, prefer proper type definitions
• Path alias: @/* maps to ./src/*

Vue Component Structure

<template>
  <!-- Template with tabs for indentation -->
</template>

<script setup lang="ts">
  // Imports first
  // Composition API logic
  // Functions
  // Lifecycle hooks
</script>

<style lang="scss" scoped>
  /* SCSS styles with nested structure */
</style>

Formatting

• Indentation: Use tabs (not spaces) for indentation
• Quotes: Single quotes for strings in TypeScript/JavaScript
• Semicolons: Optional but consistent (project uses semicolons)
• Line endings: CRLF (Windows)
• SCSS: Use nested selectors, kebab-case class names

Error Handling

• Use Service.Msg() for toast messages
• Use Service.Alert() for modal dialogs
• API requests through Service.Request() handle 401 (token expired) automatically
• Return ResultData objects from service methods
• Clean up intervals in onUnmounted() lifecycle hook

UI Components

• Use uview-plus as primary UI component library
• Use ColorUI for CSS framework and icons
• Component prefix: u- for uview-plus components (e.g., <u-icon>, <u-button>)

Service Layer Pattern

• Extend BaseConfig for service classes
• Use static methods for utility functions
• Service class provides:
  • API requests: Service.Request()
  • Navigation: Service.GoPage(), Service.GoPageTab(), Service.GoPageBack()
  • Storage: Service.SetStorageCache(), Service.GetStorageCache()
  • Messages: Service.Msg(), Service.Alert()
  • Loading: Service.LoadIng(), Service.LoadClose()

uni-app Specifics

• Use uni. API for platform-specific operations
• Pages registered in src/pages.json
• Tab bar configured in src/pages.json
• Use rpx units for responsive design
• Global styles in src/App.vue and src/uni.scss

Git & Commit

• .gitignore includes node_modules/, dist/, unpackage/
• Commit messages should be descriptive (in Chinese or English)

Key Dependencies

• Vue 3.4.21
• TypeScript 4.9.4
• Vite 5.2.8
• uni-app 3.0.0
• uview-plus 3.3.54
• dayjs (date manipulation)
• echarts (charts)
• vue-i18n (internationalization)

No Existing Rules

• No .cursor/rules/ or .cursorrules found
• No .github/copilot-instructions.md found
• No ESLint or Prettier configuration found
• Follow existing code patterns when making changes