390 lines
11 KiB
Markdown
390 lines
11 KiB
Markdown
# Story 1.1: Project Setup & Infrastructure
|
|
|
|
## Status
|
|
|
|
Draft
|
|
|
|
## Story
|
|
|
|
**As a** developer,
|
|
**I want** a fully configured TanStack Start project with Docker and GitLab CI,
|
|
**so that** I can start development with a working local environment and deployment pipeline.
|
|
|
|
## Acceptance Criteria
|
|
|
|
1. TanStack Start project initialized with TypeScript strict mode
|
|
2. Docker Compose configuration with app service and PostgreSQL 16
|
|
3. Prisma configured and connected to PostgreSQL
|
|
4. shadcn/ui installed with base components (Button, Input, Card, Table)
|
|
5. Biome configured for linting and formatting
|
|
6. Gitea Actions workflow: build, lint, test stages
|
|
7. Dockerfile multi-stage pour production build
|
|
8. README avec instructions de setup local
|
|
9. Application démarre et affiche une page d'accueil "Dofus Manager"
|
|
10. Health check endpoint `/api/health` pour Docker healthcheck
|
|
|
|
## Tasks / Subtasks
|
|
|
|
- [x] Task 1: Initialize TanStack Start project (AC: 1)
|
|
- [x] Create new TanStack Start project with `pnpm create @tanstack/start`
|
|
- [x] Configure `tsconfig.json` with strict mode enabled
|
|
- [x] Configure path aliases (`@/` pointing to `src/`)
|
|
- [x] Verify TypeScript strict compilation works
|
|
|
|
- [x] Task 2: Setup Docker environment (AC: 2, 7)
|
|
- [x] Create `docker/` directory
|
|
- [x] Create `docker/Dockerfile` with multi-stage build (builder + runner)
|
|
- [x] Create `docker/docker-compose.yml` with app and postgres services
|
|
- [x] Create `docker/docker-compose.dev.yml` for local development (postgres only)
|
|
- [x] Configure PostgreSQL 16-alpine with healthcheck
|
|
- [x] Test database connectivity
|
|
|
|
- [ ] Task 3: Configure Prisma ORM (AC: 3)
|
|
- [x] Install Prisma dependencies (`prisma`, `@prisma/client`)
|
|
- [x] Initialize Prisma with `pnpm prisma init`
|
|
- [x] Configure `prisma/schema.prisma` with PostgreSQL provider
|
|
- [ ] Create `src/lib/server/db.ts` for Prisma client singleton
|
|
- [ ] Create `.env.example` with DATABASE_URL template
|
|
- [ ] Verify Prisma connects to database
|
|
|
|
- [ ] Task 4: Install and configure shadcn/ui (AC: 4)
|
|
- [ ] Install Tailwind CSS 4.x
|
|
- [ ] Initialize shadcn/ui with `pnpm dlx shadcn@latest init`
|
|
- [ ] Configure `components.json` for path aliases
|
|
- [ ] Install base components: Button, Input, Card, Table
|
|
- [ ] Create `src/lib/utils.ts` with `cn` utility function
|
|
- [ ] Install Lucide React for icons
|
|
|
|
- [ ] Task 5: Configure linting and formatting (AC: 5)
|
|
- [ ] Install Biome (as specified in tech stack, not ESLint+Prettier)
|
|
- [ ] Create `biome.json` with recommended rules
|
|
- [ ] Add lint and format scripts to `package.json`
|
|
- [ ] Verify linting works on project files
|
|
|
|
- [ ] Task 6: Setup Gitea Actions workflow (AC: 6)
|
|
- [ ] Create `.gitea/workflows/ci.yml`
|
|
- [ ] Configure test job: lint, typecheck, test
|
|
- [ ] Configure build job: Docker image build and push
|
|
- [ ] Configure deploy jobs (staging/production) with manual triggers
|
|
- [ ] Add caching for pnpm store
|
|
|
|
- [ ] Task 7: Create README documentation (AC: 8)
|
|
- [ ] Document project overview
|
|
- [ ] Document prerequisites (Node 20, pnpm, Docker)
|
|
- [ ] Document local development setup steps
|
|
- [ ] Document available npm scripts
|
|
- [ ] Document environment variables
|
|
|
|
- [ ] Task 8: Create home page (AC: 9)
|
|
- [ ] Create `src/routes/index.tsx` as home page
|
|
- [ ] Display "Dofus Manager" title
|
|
- [ ] Add basic layout structure
|
|
- [ ] Create `src/styles/globals.css` with Tailwind imports
|
|
- [ ] Verify application starts and renders correctly
|
|
|
|
- [ ] Task 9: Create health check endpoint (AC: 10)
|
|
- [ ] Create `src/routes/api/health.ts` server function
|
|
- [ ] Return JSON `{ status: "ok", timestamp: Date }`
|
|
- [ ] Optionally check database connectivity
|
|
- [ ] Verify endpoint responds at `GET /api/health`
|
|
|
|
- [ ] Task 10: Final verification
|
|
- [ ] Run `pnpm dev` and verify app starts
|
|
- [ ] Run `pnpm lint` and verify no errors
|
|
- [ ] Run `pnpm typecheck` and verify no errors
|
|
- [ ] Test Docker build locally
|
|
- [ ] Verify PostgreSQL connection via Prisma
|
|
|
|
## Dev Notes
|
|
|
|
### Technology Stack [Source: architecture/3-technology-stack.md]
|
|
|
|
**Frontend:**
|
|
|
|
- React 19.x
|
|
- TanStack Router 1.x (type-safe routing)
|
|
- TanStack Query 5.x (server state)
|
|
- Zustand 5.x (client state)
|
|
- Tailwind CSS 4.x
|
|
- shadcn/ui (component library)
|
|
- Lucide React (icons)
|
|
- React Hook Form 7.x
|
|
- Zod 3.x (validation)
|
|
|
|
**Backend:**
|
|
|
|
- TanStack Start 1.x (full-stack framework)
|
|
- Prisma 6.x (ORM)
|
|
- Zod 3.x
|
|
- node-cache 5.x
|
|
- Pino 9.x (logging)
|
|
|
|
**Database:** PostgreSQL 16.x
|
|
|
|
**DevOps:**
|
|
|
|
- Docker
|
|
- Docker Compose
|
|
- Gitea Actions
|
|
|
|
**Dev Tools:**
|
|
|
|
- TypeScript (strict mode)
|
|
- Biome (linting & formatting - NOT ESLint+Prettier as mentioned in AC)
|
|
- Vitest (unit testing)
|
|
- Playwright (E2E testing)
|
|
|
|
### Project Structure [Source: architecture/12-project-structure.md]
|
|
|
|
```
|
|
dofus-manager/
|
|
├── .gitea/
|
|
│ └── workflows/
|
|
│ └── ci.yml
|
|
├── docker/
|
|
│ ├── Dockerfile
|
|
│ ├── docker-compose.yml
|
|
│ └── docker-compose.dev.yml
|
|
├── prisma/
|
|
│ ├── schema.prisma
|
|
│ └── migrations/
|
|
├── public/
|
|
│ └── favicon.ico
|
|
├── src/
|
|
│ ├── components/
|
|
│ │ ├── ui/ # shadcn/ui components
|
|
│ │ ├── layout/ # Layout components
|
|
│ │ └── shared/ # Shared components
|
|
│ ├── lib/
|
|
│ │ ├── utils.ts # Utility functions (cn, etc.)
|
|
│ │ ├── errors.ts # Error types
|
|
│ │ ├── client/
|
|
│ │ │ ├── query-client.ts
|
|
│ │ │ └── stores/
|
|
│ │ └── server/
|
|
│ │ ├── db.ts # Prisma client
|
|
│ │ ├── cache.ts
|
|
│ │ └── logger.ts
|
|
│ ├── routes/
|
|
│ │ ├── __root.tsx
|
|
│ │ ├── index.tsx
|
|
│ │ └── api/
|
|
│ │ └── health.ts
|
|
│ ├── styles/
|
|
│ │ └── globals.css
|
|
│ └── app.tsx
|
|
├── tests/
|
|
│ ├── unit/
|
|
│ ├── integration/
|
|
│ └── e2e/
|
|
├── .env.example
|
|
├── .gitignore
|
|
├── biome.json
|
|
├── package.json
|
|
├── tsconfig.json
|
|
├── app.config.ts
|
|
└── README.md
|
|
```
|
|
|
|
### Docker Configuration [Source: architecture/14-deployment-architecture.md#docker-configuration]
|
|
|
|
**Dockerfile (multi-stage):**
|
|
|
|
- Build stage: node:20-alpine, pnpm, prisma generate, build
|
|
- Production stage: node:20-alpine, non-root user (app:nodejs), port 3000
|
|
- Entry point: `node .output/server/index.mjs`
|
|
|
|
**Docker Compose:**
|
|
|
|
- App service with DATABASE_URL, SESSION_SECRET
|
|
- PostgreSQL 16-alpine with healthcheck
|
|
- Traefik labels for reverse proxy (production)
|
|
|
|
### Gitea Actions [Adapted from architecture]
|
|
|
|
**Workflow file:** `.gitea/workflows/ci.yml`
|
|
|
|
**Jobs:** test, build, deploy
|
|
|
|
**Test job:**
|
|
|
|
- runs-on: ubuntu-latest
|
|
- Steps: checkout, setup pnpm, setup node, install, lint, typecheck, test
|
|
- Cache pnpm store
|
|
|
|
**Build job:**
|
|
|
|
- needs: test
|
|
- Build and push Docker image
|
|
- Only on main/develop branches
|
|
|
|
**Exemple de workflow:**
|
|
|
|
```yaml
|
|
name: CI
|
|
on:
|
|
push:
|
|
branches: [main, develop]
|
|
pull_request:
|
|
branches: [main]
|
|
|
|
jobs:
|
|
test:
|
|
runs-on: ubuntu-latest
|
|
steps:
|
|
- uses: actions/checkout@v4
|
|
- uses: pnpm/action-setup@v2
|
|
with:
|
|
version: 9
|
|
- uses: actions/setup-node@v4
|
|
with:
|
|
node-version: "20"
|
|
cache: "pnpm"
|
|
- run: pnpm install --frozen-lockfile
|
|
- run: pnpm lint
|
|
- run: pnpm typecheck
|
|
- run: pnpm test
|
|
|
|
build:
|
|
needs: test
|
|
runs-on: ubuntu-latest
|
|
if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/develop'
|
|
steps:
|
|
- uses: actions/checkout@v4
|
|
- uses: docker/setup-buildx-action@v3
|
|
- uses: docker/build-push-action@v5
|
|
with:
|
|
context: .
|
|
file: docker/Dockerfile
|
|
push: true
|
|
tags: registry.example.com/dofus-manager:${{ github.sha }}
|
|
```
|
|
|
|
### Environment Variables [Source: architecture/13-development-workflow.md#environment-variables]
|
|
|
|
```bash
|
|
# Database
|
|
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/dofus_manager?schema=public"
|
|
|
|
# App
|
|
APP_URL="http://localhost:3000"
|
|
NODE_ENV="development"
|
|
|
|
# Session
|
|
SESSION_SECRET="your-secret-key-min-32-chars"
|
|
```
|
|
|
|
### Coding Standards [Source: architecture/17-coding-standards.md]
|
|
|
|
**Key Rules:**
|
|
|
|
- Type sharing: Define types in `src/types/`, never duplicate
|
|
- Server functions only: No direct HTTP calls (fetch, axios)
|
|
- Named exports for components (no default exports except routes)
|
|
- Use type imports: `import type { X } from '...'`
|
|
|
|
**Naming Conventions:**
|
|
|
|
- Components: PascalCase
|
|
- Component files: kebab-case or PascalCase
|
|
- Server functions: camelCase
|
|
- Types/Interfaces: PascalCase
|
|
- Constants: SCREAMING_SNAKE_CASE
|
|
|
|
### Health Check Endpoint [Source: architecture/19-monitoring-observability.md]
|
|
|
|
**Endpoint:** `GET /api/health`
|
|
|
|
**Response:**
|
|
|
|
```json
|
|
{
|
|
"status": "ok",
|
|
"timestamp": "2026-01-19T10:00:00.000Z",
|
|
"database": "connected"
|
|
}
|
|
```
|
|
|
|
**Implementation avec TanStack Start:**
|
|
|
|
```typescript
|
|
// src/routes/api/health.ts
|
|
import { createAPIFileRoute } from "@tanstack/start/api";
|
|
import { prisma } from "@/lib/server/db";
|
|
|
|
export const Route = createAPIFileRoute("/api/health")({
|
|
GET: async () => {
|
|
let dbStatus = "disconnected";
|
|
try {
|
|
await prisma.$queryRaw`SELECT 1`;
|
|
dbStatus = "connected";
|
|
} catch {
|
|
dbStatus = "error";
|
|
}
|
|
|
|
return Response.json({
|
|
status: "ok",
|
|
timestamp: new Date().toISOString(),
|
|
database: dbStatus,
|
|
});
|
|
},
|
|
});
|
|
```
|
|
|
|
## Testing
|
|
|
|
### Testing Standards [Source: architecture/16-testing-strategy.md]
|
|
|
|
**Test Location:**
|
|
|
|
- Unit tests: `tests/unit/`
|
|
- Integration tests: `tests/integration/`
|
|
- E2E tests: `tests/e2e/`
|
|
|
|
**Testing Frameworks:**
|
|
|
|
- Vitest for unit and integration tests
|
|
- Playwright for E2E tests
|
|
|
|
**For this story (infrastructure setup):**
|
|
|
|
- Minimal testing required
|
|
- Verify Vitest configuration works
|
|
- Verify basic test can run
|
|
- Create placeholder test file structure
|
|
|
|
**Test file naming:** `*.test.ts` for unit/integration, `*.spec.ts` for E2E
|
|
|
|
## Change Log
|
|
|
|
| Date | Version | Description | Author |
|
|
| ---------- | ------- | --------------------------------------------- | -------- |
|
|
| 2026-01-19 | 1.0 | Initial story creation | SM Agent |
|
|
| 2026-01-19 | 1.1 | Gitea Actions, Biome, Health endpoint ajoutés | SM Agent |
|
|
|
|
---
|
|
|
|
## Dev Agent Record
|
|
|
|
### Agent Model Used
|
|
|
|
_To be filled by Dev Agent_
|
|
|
|
### Debug Log References
|
|
|
|
_To be filled by Dev Agent_
|
|
|
|
### Completion Notes List
|
|
|
|
_To be filled by Dev Agent_
|
|
|
|
### File List
|
|
|
|
_To be filled by Dev Agent_
|
|
|
|
---
|
|
|
|
## QA Results
|
|
|
|
_To be filled by QA Agent_
|