# AGENTS.md - Build God Project

Guidelines for agentic coding agents working on this repository.

## Project Overview

- **Backend**: ASP.NET Core 8.0 Web API (C#) with PostgreSQL and SqlSugar ORM
- **Admin Frontend**: Vue 3 + TypeScript + Vite + Element Plus (port 5173)
- **Game Frontend**: Vue 3 + TypeScript + Vite + Element Plus + TailwindCSS + Three.js (port 5174)

---

## 1. Build, Lint, and Test Commands

### Backend (.NET API)

```bash
# Build the solution
dotnet build Build_God_Api/Build_God_Api/Build_God_Api.csproj

# Run the API (launches on https://localhost:59447, http://localhost:59448)
dotnet run --project Build_God_Api/Build_God_Api/Build_God_Api.csproj

# Run with specific URL
dotnet run --urls "http://localhost:5091"
```

**Note**: No test framework or linting is currently configured for the backend.

### Admin Frontend (Build_God_Admin_Frontend/Frontend)

```bash
# Install dependencies
npm install

# Start development server (http://localhost:5173)
npm run dev

# Build for production
npm run build

# Type-check only
npm run type-check

# Preview production build
npm run preview
```

### Game Frontend (Build_God_Game)

```bash
# Install dependencies
npm install

# Start development server (http://localhost:5174)
npm run dev

# Build for production
npm run build

# Type-check only
vue-tsc --build
```

**Note**: No test framework or ESLint is configured for either frontend.

---

## 2. Code Style Guidelines

### Backend (.NET/C#)

#### Conventions
- Use **file-scoped namespaces** (`namespace Build_God_Api.Controllers;`)
- Enable **nullable reference types** (`<Nullable>enable</Nullable>`)
- Use **primary constructors** for dependency injection
- Use **async/await** for all I/O operations
- Use **region** sparingly - prefer natural code organization

#### Naming
- **Classes/Types**: PascalCase (`AccountController`, `AccountService`)
- **Methods/Properties**: PascalCase (`GetAccount`, `UserName`)
- **Local variables/Parameters**: camelCase (`accountId`, `emailAddress`)
- **Interfaces**: Prefix with `I` (`IAccountService`)
- **DTOs**: Postfix with `Cmd` for commands, `Dto` for responses

#### Project Structure
```
Build_God_Api/Build_God_Api/
  Controllers/           # API endpoints
  Services/              # Business logic interfaces
  Services/Game/         # Game-specific services
  DB/                    # Database entities (extend BaseEntity)
  Dto/                   # Data transfer objects
  Common/                # Utilities and helpers
  Hubs/                  # SignalR hubs
```

#### Error Handling
- Return `BadRequest("error message")` for validation errors
- Return `Ok(result)` for successful operations
- Use try-catch with `Console.WriteLine` for error logging
- Validate inputs at controller level using DataAnnotations

#### Route Conventions
- Use `[Route("api/god/[controller]")]`
- Use `[ApiController]` and HTTP method attributes (`[HttpGet]`, `[HttpPost]`)

#### Database Entities (SqlSugar)
- All entities extend `BaseEntity` which provides `Id`, `CreatedOn`, `UpdatedOn`, `CreatedBy`, `UpdatedBy`
- Use `[SugarColumn(IsPrimaryKey = true, IsIdentity = true)]` for auto-increment primary keys

---

### Frontend (Vue 3 + TypeScript)

#### Conventions
- Use **Composition API** with `<script setup lang="ts">`
- Use **path aliases**: `@/` maps to `src/`
- Admin: Plain CSS (`<style scoped lang="css">`)
- Game: Tailwind CSS utility classes

#### Naming
- **Components**: PascalCase (`LoginView.vue`, `Sidebar.vue`)
- **Variables/functions**: camelCase (`handleLogin`, `userName`)
- **Types/Interfaces**: PascalCase (`LoginRequest`, `User`)
- **Store names**: kebab-case in defineStore (`defineStore('auth', ...)`)

#### Project Structure
```
Admin Frontend (src/):
  api/              # API modules
  components/       # Reusable components
  views/            # Page components (subdir: admin/)
  stores/           # Pinia stores
  router/           # Vue Router config
  assets/           # Static assets

Game Frontend (src/):
  api/              # API modules
  components/       # Reusable components
  composables/      # Vue composables
  views/            # Page components
  stores/            # Pinia stores
  router/           # Vue Router config
```

#### Imports
- Use `@/` alias: `import { useAuthStore } from '@/stores/auth'`
- Order: external libs → internal imports → types/interfaces

#### TypeScript Settings (tsconfig.app.json)
```json
{
  "strict": false,
  "strictNullChecks": false,
  "noUnusedLocals": false,
  "noUnusedParameters": false
}
```

#### TypeScript Patterns
- Define types/interfaces for all API payloads
- Use `ref<T>` and `computed<T>` for reactive state
- Use `unknown` or proper types instead of `any`

#### Vue Component Pattern
```vue
<script setup lang="ts">
import { ref, computed } from 'vue'
import { useRouter } from 'vue-router'
import { ElMessage } from 'element-plus'

const router = useRouter()
const loading = ref(false)
</script>

<template>
  <!-- Element Plus components -->
</template>

<style scoped lang="css">
/* Component styles */
</style>
```

#### Pinia Store Pattern
```typescript
import { defineStore } from 'pinia'
import { ref, computed } from 'vue'

export const useAuthStore = defineStore('auth', () => {
  const token = ref('')
  const isAuthenticated = computed(() => !!token.value)
  
  const login = async (credentials: LoginRequest): Promise<boolean> => {
    // implementation
  }
  
  return { token, isAuthenticated, login }
})
```

#### API Module Pattern
All API modules share a centralized axios instance from `api/index.ts`.

**`src/api/index.ts`** - Shared axios instance (one per frontend):
```typescript
import axios from 'axios'

const instance = axios.create({
  baseURL: import.meta.env.VITE_API_URL || 'http://localhost:5091/api/god/',
  timeout: 10000,
  headers: { 'Content-Type': 'application/json' }
})

instance.interceptors.request.use((config) => {
  const token = localStorage.getItem('auth_token') // or sessionStorage for Admin
  if (token) config.headers.Authorization = `Bearer ${token}`
  return config
})

instance.interceptors.response.use(
  (response) => response.data,
  (error) => {
    if (error.response?.status === 401) {
      localStorage.removeItem('auth_token')
      window.location.href = '/login'
    }
    return Promise.reject(error.response?.data || error.message)
  }
)

export default instance
```

**`src/api/{entity}.ts`** - Individual API modules (import from index):
```typescript
import http from './index'

export interface CharacterDto { ... }

export const characterApi = {
  getList: (): Promise<CharacterDto[]> => {
    return http.get('/character/list')
  }
}
```

---

## 3. API Integration

### Base URL
- Development: `http://localhost:5091/api/god/`
- Routes: `api/god/{entity}` (e.g., `api/god/account/login`)

### Authentication
- JWT Bearer tokens
- Store in `localStorage` as `auth_token` (Game) or `sessionStorage` (Admin)
- Header: `Authorization: Bearer {token}`

### Key Endpoints
- POST `/api/god/account/register` - Register account
- POST `/api/god/account/login` - User login
- POST `/api/god/account/login/admin` - Admin login

---

## 4. Development Workflow

1. **Start Backend**: `dotnet run --project Build_God_Api/Build_God_Api/Build_God_Api.csproj`
2. **Start Admin Frontend**: `npm run dev` (in `Build_God_Admin_Frontend/Frontend/`)
3. **Start Game Frontend**: `npm run dev` (in `Build_God_Game/`)

---

## 5. Adding New Features

### Backend
1. Create model in `DB/` (extend `BaseEntity`)
2. Create interface in `Services/`
3. Implement service in `Services/`
4. Create controller in `Controllers/`
5. Register service in `Program.cs`

### Frontend
1. Add API function in `src/api/{entity}.ts` (import `http` from `./index`)
2. Add Pinia store in `src/stores/` if needed
3. Create view component in `src/views/`
4. Add route in `src/router/index.ts`

---

## 6. Important Notes

- **Admin credentials**: `admin` / `love_god.123`
- **Test account**: `Tom` / `123456` (email: 976802198@qq.com)
- Backend runs on ports **59447** (HTTPS) and **59448** (HTTP)
- Admin Frontend uses sessionStorage; Game Frontend uses localStorage
- Always use `await` with async operations
- Run type-check before committing