diff --git a/docs/stories/1.1.story.md b/docs/stories/1.1.story.md new file mode 100644 index 0000000..f6dd447 --- /dev/null +++ b/docs/stories/1.1.story.md @@ -0,0 +1,295 @@ +# 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) + - [ ] 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_