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

npm install

Build And Dev Commands

Common Development

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

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

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

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.