123 lines
4.6 KiB
Markdown
123 lines
4.6 KiB
Markdown
# 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.
|