消息

AGENTS.md

@@ -0,0 +1,122 @@
+# 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.