swimmingUni/AGENTS.md

# AGENTS.md - Swimming uni-app Project

## Scope
- This file applies to the entire repository rooted at `D:\Project\游泳\swimming`.
- There are currently no deeper `AGENTS.md` files in subdirectories.
- No `.cursor/rules/`, `.cursorrules`, or `.github/copilot-instructions.md` files exist in this repo.

## Project Overview
- This is a `uni-app` + Vue 3 + TypeScript project built with Vite.
- Main app source lives under `src/`.
- The app appears to target H5, app, and multiple mini-program platforms.
- Primary UI library is `uview-plus`.
- Charting-related code exists under `src/uni_modules/qiun-data-charts` and `src/uni_modules/lime-echart`.
- Service-layer code is centralized under `src/Service/`.

## Tooling Snapshot
- Package manager: `npm`.
- Bundler/dev server: `vite` via `@dcloudio/vite-plugin-uni`.
- Type checking: `vue-tsc --noEmit`.
- Language level: TypeScript `^4.9.4`.
- Framework: Vue `^3.4.21`.
- No ESLint config is present.
- No Prettier config is present.
- No unit or e2e test runner config is present.

## Install
```bash
npm install
```

## Build And Dev Commands

### Common Development
```bash
npm run dev:h5
npm run dev:h5:ssr
npm run dev:app
npm run dev:app-android
npm run dev:app-ios
npm run dev:mp-weixin
npm run dev:mp-alipay
npm run dev:mp-baidu
npm run dev:mp-jd
npm run dev:mp-kuaishou
npm run dev:mp-lark
npm run dev:mp-qq
npm run dev:mp-toutiao
npm run dev:mp-xhs
npm run dev:quickapp-webview
npm run dev:quickapp-webview-huawei
npm run dev:quickapp-webview-union
```

### Common Build
```bash
npm run build:h5
npm run build:h5:ssr
npm run build:app
npm run build:app-android
npm run build:app-ios
npm run build:mp-weixin
npm run build:mp-alipay
npm run build:mp-baidu
npm run build:mp-jd
npm run build:mp-kuaishou
npm run build:mp-lark
npm run build:mp-qq
npm run build:mp-toutiao
npm run build:mp-xhs
npm run build:quickapp-webview
npm run build:quickapp-webview-huawei
npm run build:quickapp-webview-union
```

### Validation
```bash
npm run type-check
```

## Lint And Test Status
- There is no configured lint command in `package.json`.
- There is no ESLint or Prettier configuration in the repository root.
- There is no configured test framework such as Vitest, Jest, Playwright, Cypress, Mocha, or Ava.
- There are no repository test files matching `*.spec.*` or `*.test.*` in app code.
- Because no test runner exists, there is currently no supported command for running a single test.
- For validation, prefer `npm run type-check` and, when relevant, a targeted platform build such as `npm run build:h5`.

## Single-Test Guidance
- Single-test execution is not available in the current repo state.
- If a future test runner is added, update this file with:
  - the root test command,
  - the single-test command pattern,
  - any platform-specific test setup,
  - and the location/naming convention for test files.

## Important Paths
- `src/main.ts` bootstraps the app and registers `uview-plus`.
- `src/App.vue` contains global app shell styles and setup.
- `src/pages.json` defines pages and tab bar configuration.
- `src/uni.scss` contains shared uni-app styling variables and theme-level styles.
- `src/Service/` contains application services and shared app behavior.
- `src/common/` contains shared domain models and utilities.
- `src/components/` contains reusable Vue components.
- `src/pages/` contains page-level Vue SFCs.
- `src/uni_modules/` contains vendored or external uni-app modules.

## Source Layout Conventions
```text
src/
├── Service/         Service classes and base config
├── common/          Shared utilities and domain models
├── components/      Reusable Vue SFC components
├── pages/           Routed uni-app pages
├── static/          Static assets
├── types/           Type declarations
├── uni_modules/     Third-party or packaged uni modules
├── colorui/         ColorUI-related assets/components
├── App.vue          Root application component
├── main.ts          App bootstrap
├── pages.json       Route and tab-bar registration
└── uni.scss         Global uni-app SCSS
```

## Imports And Module Usage
- Use the `@/` alias for imports rooted in `src/`.
- `tsconfig.json` maps `@/*` to `./src/*`.
- Prefer alias imports for app code instead of long relative paths.
- Import Vue composition helpers from `vue`.
- Import uni-app page lifecycle APIs from `@dcloudio/uni-app` when needed.
- Keep imports grouped with framework imports first, then app services/types, then local modules.
- Existing code sometimes re-exports shared utilities from `src/common/Common.ts`; preserve that pattern where it already exists.

## Vue SFC Conventions
- Use Vue 3 `<script setup lang="ts">` for page and component SFCs.
- Keep file sections in the order: `<template>`, `<script setup lang="ts">`, `<style lang="scss" scoped>`.
- Use `scoped` styles for page/component-local styling unless a global rule is required.
- Prefer reactive state via `ref` and `reactive` from Vue.
- Use uni-app page lifecycle hooks such as `onLoad` from `@dcloudio/uni-app`.
- Clean up timers or intervals in `onUnmounted()`.

## TypeScript Guidelines
- Use `lang="ts"` in Vue SFC scripts.
- Add explicit parameter types and return types for exported functions and service methods where practical.
- Prefer concrete interfaces or domain models over `any`.
- Existing code uses `any` in several places; reduce new `any` usage instead of expanding it.
- Keep class names in PascalCase.
- Preserve existing static-service patterns unless there is a strong reason to refactor more broadly.

## Service Layer Patterns
- Base configuration lives in `src/Service/BaseConfig.ts`.
- Shared service helpers live in `src/Service/Service.ts`.
- Feature services under `src/Service/swimming/` usually:
  - define endpoint path constants as `private static` fields,
  - expose `static` methods,
  - delegate network calls to `Service.Request()`,
  - and export both the service class and `Service` where existing files already do so.
- `Service.Request()` wraps request handling and normalizes API responses into `ResultData`.
- `ResultData` lives in `src/common/Domain/ResultData.ts`.

## Error Handling And User Feedback
- Use `Service.Msg()` for toast-style user feedback.
- Use `Service.Alert()` or `Service.Confirm()` for modal interactions.
- Route authenticated API requests through `Service.Request()`.
- Be aware that `Service.Request()` already handles several auth and permission codes such as `401`, `40101`, `1004`, and `40188`.
- When adding new service methods, return the request promise rather than swallowing errors silently.
- Follow existing user-facing Chinese messaging style unless the surrounding screen uses a different language.

## Naming Conventions
- Vue component filenames: PascalCase, for example `ImageCropper.vue`.
- Utility and service helper filenames: usually camelCase or existing established names; match nearby files.
- Service classes: PascalCase for class names, for example `PlanService`.
- Some existing service class identifiers start lowercase, such as `studentService`; preserve existing public names unless a broader refactor is requested.
- Local variables and functions: camelCase.
- Constants: UPPER_SNAKE_CASE when they are true constants.
- CSS class names: kebab-case.
- Route paths must match entries in `src/pages.json`.

## Formatting Expectations
- Repository convention is tabs for indentation in source files.
- Existing project code mostly uses single quotes in application TypeScript, though some files contain double quotes; prefer the dominant local style in the file you touch.
- Semicolons are used frequently enough that new changes should stay consistent within the edited file.
- Keep line endings as CRLF on Windows-oriented files when possible.
- Use nested SCSS selectors where that is already the local pattern.
- Avoid introducing broad formatting-only diffs.

## Styling And UI
- Prefer `uview-plus` components where the project already uses them.
- ColorUI assets/components are also present; preserve established usage where relevant.
- Use `rpx` units for responsive uni-app layouts.
- Keep mobile-first layout assumptions.
- Match the visual language already present on the page you are editing rather than redesigning unrelated UI.

## Platform And Runtime Notes
- Use `uni.*` APIs for platform-specific behavior.
- Navigation typically goes through `Service.GoPage()`, `Service.GoPageTab()`, `Service.GoPageBack()`, or `Service.GoPageDelse()`.
- App state and auth token access are commonly wrapped by `Service.GetStorageCache()` and related helpers.
- Be careful when changing files inside `src/uni_modules/`; many are third-party modules and should only be edited when necessary.

## Agent Guidance
- Before changing code, inspect nearby files and follow their existing conventions.
- Keep edits focused and minimal; do not refactor unrelated areas opportunistically.
- Do not invent lint or test commands that are not actually configured.
- When describing validation, use real commands from `package.json`.
- If you add a test framework or lint setup later, update this file immediately.
- If you touch vendored `uni_modules`, call that out explicitly in your final summary.

## Current Gaps To Remember
- No lint pipeline is configured.
- No automated test pipeline is configured.
- No single-test command exists yet.
- No Cursor or Copilot repository instruction files exist.
- Agents should rely on local code patterns plus this file when making changes.