cleanarch

2.0.7

modules/ai-guide/Write-AiGuide-Web.ps1

param(
    [string]   $ProjectName,
    [string]   $OutputPath
)

. (Join-Path (Split-Path $MyInvocation.MyCommand.Path) "..\core\Utils.ps1")

$guideDir = Join-Path $OutputPath "ai-guide"
function Write-Guide($fileName, $content) {
    Write-CoreFile (Join-Path $guideDir $fileName) $content
}

$webGuideContent = @'
# Web Application AI Developer Guide
 
You are an AI assistant helping developers build the React Frontend Web Application of the {P} solution.
The frontend is built using React (Vite + TypeScript), Vanilla CSS for styling, and fetch-based services for API communication.
 
---
 
## Strict Web Application Rules
 
1. **Independent Standalone Layout:** The web project resides inside `{P}-web/` and is completely decoupled. It does not reference or depend on any monorepo workspaces or parent packages.
2. **Service-Based API Calls:** Use dedicated service files (e.g. `authService.ts`, `productService.ts`) for all API requests. Do not write `fetch()` calls directly in components.
3. **Auth Flow:** Use `AuthContext` for authentication state. Tokens are stored in `localStorage` via `authService.saveSession()` and read via `authService.getToken()`.
4. **No Runtime Localization Packages:** Do not use `i18next` at runtime. The UI texts are statically scaffolded in the chosen language.
5. **API Base URL:** Always read from `import.meta.env.VITE_API_URL` with fallback to `http://localhost:8080/api`.
 
---
 
## Folder Structure
 
```
{P}-web/
+-- App.tsx <- Router and providers
+-- main.tsx <- Entry point
+-- index.html
+-- context/
| +-- AuthContext.tsx <- Authentication state provider (useAuth hook)
+-- services/
| +-- authService.ts <- Login, logout, token storage (localStorage)
| +-- {entity}Service.ts <- Entity-specific API calls (with Bearer token)
+-- components/
| +-- auth/ <- LoginForm
| +-- common/ <- Button, Input, Alert
| +-- {entity}/ <- EntityForm, EntityTable
+-- pages/
| +-- LoginPage.tsx <- Authentication screen
| +-- {Entity}Page.tsx <- Entity management screen
+-- types/
| +-- index.ts <- TypeScript interfaces (Product, User, LoginRequest...)
+-- vite.config.ts / tsconfig.json
```
 
---
 
## How to Add a Feature
 
When adding a new entity (e.g., `Category`):
 
### 1. TypeScript Interface
Add interface definitions to `types/index.ts`:
```typescript
export interface Category {
  id: number;
  name: string;
  createdAt: string;
}
```
 
### 2. Service File
Create `services/categoryService.ts`. Always inject the Bearer token via `authHeaders()`:
```typescript
// {P}-web/services/categoryService.ts
const API_BASE = import.meta.env.VITE_API_URL ?? 'http://localhost:8080/api';
const authHeaders = () => ({
  'Content-Type': 'application/json',
  Authorization: `Bearer ${localStorage.getItem('token')}`,
});
 
export const categoryService = {
  getPaged: async (page = 1, size = 20) => {
    const res = await fetch(`${API_BASE}/Categories/paged?page=${page}&size=${size}`, { headers: authHeaders() });
    if (res.status === 401) throw new Error('UNAUTHORIZED');
    if (!res.ok) throw new Error('Failed to load categories.');
    return res.json();
  },
  add: async (name: string) => {
    const res = await fetch(`${API_BASE}/Categories`, {
      method: 'POST',
      headers: authHeaders(),
      body: JSON.stringify({ name }),
    });
    if (!res.ok) throw new Error('Failed to add category.');
    return res.json();
  },
};
```
 
### 3. Auth Context (already scaffolded)
`AuthContext.tsx` provides `useAuth()` hook with `{ username, isAuthenticated, login, logout }`:
```typescript
// Usage in any component:
import { useAuth } from '../context/AuthContext';
const { isAuthenticated, logout } = useAuth();
```
 
### 4. Auth Service (already scaffolded)
`authService.ts` handles token persistence:
```typescript
// authService stores token in localStorage
authService.saveSession({ token, username }); // called after login
authService.getToken(); // returns JWT token string
authService.logout(); // clears localStorage
```
'@.Replace("{P}", $ProjectName)

Write-Guide "web-guide.md" $webGuideContent