# 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)

```bash
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)

```bash
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:
```bash
# 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.