296 lines
8.6 KiB
Markdown
296 lines
8.6 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. ESLint + Prettier configured with recommended rules
|
|
6. GitLab CI pipeline: 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"
|
|
|
|
## Tasks / Subtasks
|
|
|
|
- [ ] Task 1: Initialize TanStack Start project (AC: 1)
|
|
- [x] Create new TanStack Start project with `pnpm create @tanstack/start`
|
|
- [ ] Configure `tsconfig.json` with strict mode enabled
|
|
- [ ] Configure path aliases (`@/` pointing to `src/`)
|
|
- [ ] Verify TypeScript strict compilation works
|
|
|
|
- [ ] Task 2: Setup Docker environment (AC: 2, 7)
|
|
- [ ] Create `docker/` directory
|
|
- [ ] Create `docker/Dockerfile` with multi-stage build (builder + runner)
|
|
- [ ] Create `docker/docker-compose.yml` with app and postgres services
|
|
- [ ] Create `docker/docker-compose.dev.yml` for local development (postgres only)
|
|
- [ ] Configure PostgreSQL 16-alpine with healthcheck
|
|
- [ ] Test database connectivity
|
|
|
|
- [ ] Task 3: Configure Prisma ORM (AC: 3)
|
|
- [ ] Install Prisma dependencies (`prisma`, `@prisma/client`)
|
|
- [ ] Initialize Prisma with `pnpm prisma init`
|
|
- [ ] 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 GitLab CI/CD pipeline (AC: 6)
|
|
- [ ] Create `.gitlab-ci.yml` with stages: test, build, deploy
|
|
- [ ] Configure test stage: lint, typecheck, test
|
|
- [ ] Configure build stage: Docker image build and push
|
|
- [ ] Configure deploy stages (staging/production) with manual triggers
|
|
- [ ] Add caching for node_modules
|
|
|
|
- [ ] 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: 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
|
|
- GitLab CI
|
|
|
|
**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/
|
|
├── docker/
|
|
│ ├── Dockerfile
|
|
│ └── docker-compose.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
|
|
│ ├── 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)
|
|
|
|
### GitLab CI/CD [Source: architecture/14-deployment-architecture.md#gitlab-cicd-pipeline]
|
|
|
|
**Stages:** test, build, deploy
|
|
|
|
**Test stage:**
|
|
|
|
- image: node:20-alpine
|
|
- Commands: pnpm lint, pnpm typecheck, pnpm test
|
|
- Cache node_modules
|
|
|
|
**Build stage:**
|
|
|
|
- image: docker:24
|
|
- Build and push Docker image to registry
|
|
- Only on main/develop branches
|
|
|
|
### 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
|
|
|
|
### Important Discrepancy Note
|
|
|
|
AC #5 specifies "ESLint + Prettier" but the architecture documents (3-technology-stack.md) specify **Biome** for linting and formatting. Recommend following the architecture document and using Biome instead, as it's the project standard.
|
|
|
|
## 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 |
|
|
|
|
---
|
|
|
|
## 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_
|