Kg.SeaTime/AGENTS.md

AGENTS.md

Guidelines for AI agents working in this SeaTime (航海时代) codebase.

Project Structure

Full-stack web game with two components:

• Web/: Nuxt 4 (Vue 3 + TypeScript) frontend
• Service/: .NET 10 Web API backend using Photon.Core framework

Build Commands

Web (Frontend)

cd Web
npm install      # Install dependencies
npm run dev      # Start dev server on port 5068
npm run build    # Production build
npm run generate # Static site generation
npm run preview  # Preview production build
npm run postinstall # Nuxt prepare (runs automatically after install)

Service (Backend)

cd Service
dotnet build                           # Build solution
dotnet run --project Application.Web   # Run web API
dotnet watch --project Application.Web # Run with hot reload

Testing Commands

No test framework configured yet. To add tests:

• Web: Install Vitest or Jest for unit tests
• Service: Use dotnet test after adding xUnit/NUnit test projects

When tests are added, run them with:

# Web (Vitest example)
npm run test              # Run all tests
npm run test:unit         # Run unit tests only
npm run test -- <file>    # Run single test file

# Service
dotnet test               # Run all tests
dotnet test --filter "FullyQualifiedName~ClassName"  # Run specific test class

Code Style Guidelines

TypeScript / Vue (Web)

• Imports: Use ~/ alias for src directory imports (e.g., import type { IUserInfo } from '~/types/user')
• Vue SFCs: Use <script setup lang="ts"> composition API
• Naming Conventions:
  • Stores: useXxxStore in stores/ (e.g., useUserStore)
  • Composables: useXxx in composables/ (e.g., useAuth)
  • Services: XxxSERVICE class in services/ (e.g., UserSERVICE)
  • Extends: xxxEXTEND class in extends/ (e.g., RequestEXTEND)
  • Types: IXxx interface in types/ (e.g., IUserInfo)
  • Pages: kebab-case in pages/ (e.g., auth/login.vue)
• Auto-imports: stores, composables, extends, services are auto-imported (see nuxt.config.ts)
• TypeScript: Strict mode enabled, always define return types for public functions
• Comments: Use Chinese for business logic documentation
• API Pattern: Services check response.code !== 200 && response.code !== 0 for errors
• State Management: Pinia stores use state/getters/actions pattern with persist for localStorage
• Persistence: Only persist token and userInfo to localStorage via piniaPluginPersistedstate.localStorage()

C# (Service)

• Target framework: .NET 10
• Nullable reference types enabled
• Implicit usings enabled
• Standard C# naming: PascalCase for classes/methods, camelCase for locals
• Controllers use [ApiExplorerSettings(GroupName = "...")] for Swagger grouping
• Route pattern: [Route("[controller]/[action]")]
• Return IPoAction / PoAction.Ok() from controllers
• Request params in Application.Domain/RequestParms/ folder
• Global usings defined in Application.Web/GlobalUsings.cs
• Uses Photon.Core framework (DI via Inject*, JWT, SqlSugar, Timer)

Error Handling

Web

• Services: Wrap API calls in try-catch, log errors with console.error, re-throw or return false
• Components: Use showToast/showFailToast/showSuccessToast from Vant for user feedback
• Always check typeof window !== 'undefined' for client-side only code
• Navigation: Use navigateTo() for programmatic navigation

Service

• Use standard .NET exception handling middleware
• Return consistent response models with code/message/data structure
• CORS policy "all" configured for cross-origin requests

Key Technologies

• Frontend: Nuxt 4, Vue 3, Pinia, Vant UI, TypeScript
• Backend: .NET 10 Web API, Photon.Core framework
• State Management: Pinia with pinia-plugin-persistedstate (localStorage)
• HTTP Client: Custom RequestEXTEND class based on native fetch
• Auth: JWT with custom JwtHandle validator
• Timer: AutoJob hosted service with TimerJobManager

Project Conventions

• Source directory: Web/src/
• Pages use file-based routing (Nuxt convention)
• Layouts in Web/src/layouts/
• Layout constants in composables/layout.ts as layout object (e.g., layout.empty)
• Use definePageMeta({ layout: layout.empty }) for page layout configuration
• Store persistence: Only token and userInfo are persisted to localStorage
• No ESLint/Prettier configured yet - follow existing code patterns

Existing Rules

No Cursor rules (.cursorrules or .cursor/rules/) or Copilot instructions (.github/copilot-instructions.md) found in this repository.