# 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#)
- **Frontend**: Vue 3 + TypeScript + Vite + Element Plus

---

## 1. Build, Lint, and Test Commands

### Backend (.NET API)

```bash
# Build the solution (from Build_God_Api directory)
dotnet build Build_God_Api/Build_God_Api.csproj

# Run the API
dotnet run --project Build_God_Api/Build_God_Api.csproj
```

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

### Frontend (Vue 3)

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

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

---

## 2. Code Style Guidelines

### Backend (.NET/C#)

#### Conventions
- Use **file-scoped namespaces** (`namespace Build_God_Api.Controllers;`)
- Enable **nullable reference types**
- Use **primary constructors** for dependency injection
- Use **async/await** for all I/O operations

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

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

#### Error Handling
- Return `BadRequest("error message")` for validation errors
- Return `Ok(result)` for successful operations
- Use try-catch with `ILogger<T>` for error logging

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

---

### Frontend (Vue 3 + TypeScript)

#### Conventions
- Use **Composition API** with `<script setup lang="ts">`
- Use **path aliases**: `@/` maps to `src/`

#### Naming
- **Components**: PascalCase (`LoginView.vue`, `Sidebar.vue`)
- **Variables/functions**: camelCase (`handleLogin`, `userName`)
- **Types/Interfaces**: PascalCase (`LoginRequest`, `User`)

#### Project Structure
```
src/
  api/           # API calls
  components/    # Reusable components
  views/         # Page components
  stores/        # Pinia stores
  router/        # Vue Router configuration
```

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

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

#### Vue Component Pattern
```vue
<script setup lang="ts">
import { ref } 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)
  return { token, isAuthenticated }
})
```

---

## 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`
- 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.csproj`
2. **Start Frontend**: `npm run dev` (in `Build_God_Admin_Frontend/Frontend/`)
3. **Access**: Frontend at `http://localhost:5173`

---

## 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. Create API module in `src/api/`
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 login**: `admin` / `love_god.123`
- **Test account**: `Tom` / `123456` (email: 976802198@qq.com)
- Backend runs on port **5091**
- Frontend uses Vite proxy for API calls
- Always use `await` with async operations
- Run `npm run type-check` before committing