Build_God/AGENTS.md

# AGENTS.md - Build God Project

## Project Overview
- **Backend**: ASP.NET Core 8.0 + PostgreSQL + 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
```bash
dotnet build Build_God_Api/Build_God_Api/Build_God_Api.csproj
dotnet run --project Build_God_Api/Build_God_Api/Build_God_Api.csproj
dotnet run --urls "http://localhost:5091"
```
No test framework or linting configured.

### Admin Frontend
```bash
npm install
npm run dev              # http://localhost:5173
npm run build            # Production build
npm run type-check       # Type-check only
npm run preview          # Preview production build
```

### Game Frontend
```bash
npm install
npm run dev              # http://localhost:5174
npm run build            # Production build
vue-tsc --build          # Type-check only
```
No test framework or ESLint configured for frontends.

---

## 2. Code Style Guidelines

### Backend (.NET/C#)

**Conventions:**
- File-scoped namespaces (`namespace Build_God_Api.Controllers;`)
- Nullable reference types enabled (`<Nullable>enable</Nullable>`)
- Primary constructors for dependency injection
- Use `async/await` for all I/O operations
- Avoid `region` - prefer natural code organization

**Naming:**
- Classes/Types: PascalCase (`AccountController`)
- Methods/Properties: PascalCase (`GetAccount`)
- Local variables/Parameters: camelCase (`accountId`)
- 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 & implementations
  Services/Game/  # Game-specific services
  DB/             # Database entities (extend BaseEntity)
  Dto/            # Data transfer objects
  Common/         # Utilities
  Hubs/            # SignalR hubs
```

**Error Handling:**
- `BadRequest("message")` for validation errors
- `Ok(result)` for success
- Try-catch with `Console.WriteLine` for error logging
- Use DataAnnotations for input validation at controller level

**Route Conventions:**
- `[Route("api/god/[controller]")]`
- `[ApiController]` with `[HttpGet]`/`[HttpPost]` attributes

**Database (SqlSugar):**
- Entities extend `BaseEntity` (provides `Id`, `CreatedOn`, `UpdatedOn`, `CreatedBy`, `UpdatedBy`)
- Auto-increment PK: `[SugarColumn(IsPrimaryKey = true, IsIdentity = true)]`

---

### Frontend (Vue 3 + TypeScript)

**Conventions:**
- Composition API with `<script setup lang="ts">`
- Path alias: `@/` 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`)
- Types/Interfaces: PascalCase (`LoginRequest`)
- Store names: kebab-case in defineStore (`defineStore('auth', ...)`)

**Project Structure:**
```
Admin: src/api/, src/components/, src/views/, src/stores/, src/router/, src/assets/
Game:  src/api/, src/components/, src/composables/, src/views/, src/stores/, src/router/
```

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

**API Pattern (shared axios instance):**
```typescript
// src/api/index.ts
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) => { /* handle 401, reject with data */ }
)
export default instance

// src/api/{entity}.ts
import http from './index'
export const characterApi = {
  getList: (): Promise<CharacterDto[]> => http.get('/character/list')
}
```

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

---

## 3. API Integration

- **Base URL**: `http://localhost:5091/api/god/`
- **Auth**: JWT Bearer tokens
  - Game: `localStorage` as `auth_token`
  - Admin: `sessionStorage` as `auth_token`

**Key Endpoints:**
- POST `/api/god/account/register`
- POST `/api/god/account/login`
- POST `/api/god/account/login/admin`

---

## 4. Development Workflow

1. `dotnet run --project Build_God_Api/Build_God_Api/Build_God_Api.csproj`
2. `npm run dev` in `Build_God_Admin_Frontend/Frontend/`
3. `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`
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: ports 59447 (HTTPS), 59448 (HTTP)
- Always use `await` with async operations