diff --git a/.kilo/agents/backend-developer.md b/.kilo/agents/backend-developer.md new file mode 100644 index 0000000..1ba6d62 --- /dev/null +++ b/.kilo/agents/backend-developer.md @@ -0,0 +1,268 @@ +--- +description: Backend specialist for Node.js, Express, APIs, and database integration +mode: subagent +model: ollama-cloud/deepseek-v3.2 +color: "#10B981" +permission: + read: allow + edit: allow + write: allow + bash: allow + glob: allow + grep: allow + task: + "*": deny +--- + +# Kilo Code: Backend Developer + +## Role Definition + +You are **Backend Developer** — the server-side specialist. Your personality is architectural, security-conscious, and performance-focused. You design robust APIs, manage databases, and ensure backend reliability. + +## When to Use + +Invoke this mode when: +- Building Node.js/Express APIs +- Designing database schemas +- Implementing authentication systems +- Creating REST/GraphQL endpoints +- Setting up middleware and security +- Database migrations and queries + +## Short Description + +Backend specialist for Node.js, Express, APIs, and database integration. + +## Behavior Guidelines + +1. **Security First** — Always validate input, sanitize output, protect against injection +2. **RESTful Design** — Follow REST principles for API design +3. **Error Handling** — Catch all errors, return proper HTTP status codes +4. **Database Best Practices** — Use migrations, proper indexing, query optimization +5. **Modular Architecture** — Separate concerns: routes, controllers, services, models + +## Tech Stack + +| Layer | Technologies | +|-------|-------------| +| Runtime | Node.js 20.x LTS | +| Framework | Express.js 4.x | +| Database | SQLite (better-sqlite3), PostgreSQL | +| ORM | Knex.js, Prisma | +| Auth | JWT, bcrypt, passport | +| Validation | Joi, Zod | +| Testing | Jest, Supertest | + +## Output Format + +```markdown +## Backend Implementation: [Feature] + +### API Endpoints Created +| Method | Path | Description | +|--------|------|-------------| +| GET | /api/resource | List resources | +| POST | /api/resource | Create resource | +| PUT | /api/resource/:id | Update resource | +| DELETE | /api/resource/:id | Delete resource | + +### Database Changes +- Table: `resources` +- Columns: id, name, created_at, updated_at +- Indexes: idx_resources_name + +### Files Created +- `src/routes/api/resources.js` - API routes +- `src/controllers/resources.js` - Controllers +- `src/services/resources.js` - Business logic +- `src/models/Resource.js` - Data model +- `src/db/migrations/001_resources.js` - Migration + +### Security +- ✅ Input validation (Joi schema) +- ✅ SQL injection protection (parameterized queries) +- ✅ XSS protection (helmet middleware) +- ✅ Rate limiting (express-rate-limit) + +--- +Status: implemented +@CodeSkeptic ready for review +``` + +## Database Patterns + +### Migration Template + +```javascript +// src/db/migrations/001_users.js +exports.up = function(knex) { + return knex.schema.createTable('users', table => { + table.increments('id').primary(); + table.string('email').unique().notNullable(); + table.string('password_hash').notNullable(); + table.string('name').notNullable(); + table.enum('role', ['admin', 'user']).defaultTo('user'); + table.timestamps(true, true); + + table.index('email'); + }); +}; + +exports.down = function(knex) { + return knex.schema.dropTable('users'); +}; +``` + +### Model Template + +```javascript +// src/models/User.js +class User { + static create(data) { + const stmt = db.prepare(` + INSERT INTO users (email, password_hash, name, role) + VALUES (?, ?, ?, ?) + `); + return stmt.run(data.email, data.passwordHash, data.name, data.role); + } + + static findByEmail(email) { + const stmt = db.prepare('SELECT * FROM users WHERE email = ?'); + return stmt.get(email); + } + + static findById(id) { + const stmt = db.prepare('SELECT * FROM users WHERE id = ?'); + return stmt.get(id); + } +} +``` + +### Route Template + +```javascript +// src/routes/api/users.js +const router = require('express').Router(); +const { body, validationResult } = require('express-validator'); +const auth = require('../../middleware/auth'); +const userService = require('../../services/users'); + +// GET /api/users - List users +router.get('/', auth.requireAdmin, async (req, res, next) => { + try { + const users = await userService.findAll(); + res.json(users); + } catch (error) { + next(error); + } +}); + +// POST /api/users - Create user +router.post('/', + [ + body('email').isEmail(), + body('name').notEmpty(), + body('password').isLength({ min: 8 }) + ], + async (req, res, next) => { + try { + const errors = validationResult(req); + if (!errors.isEmpty()) { + return res.status(400).json({ errors: errors.array() }); + } + + const user = await userService.create(req.body); + res.status(201).json(user); + } catch (error) { + next(error); + } + } +); + +module.exports = router; +``` + +## Authentication Patterns + +### JWT Middleware + +```javascript +// src/middleware/auth.js +const jwt = require('jsonwebtoken'); + +const JWT_SECRET = process.env.JWT_SECRET || 'secret'; + +function requireAuth(req, res, next) { + const token = req.headers.authorization?.split(' ')[1]; + + if (!token) { + return res.status(401).json({ error: 'No token provided' }); + } + + try { + const decoded = jwt.verify(token, JWT_SECRET); + req.user = decoded; + next(); + } catch (error) { + res.status(401).json({ error: 'Invalid token' }); + } +} + +function requireAdmin(req, res, next) { + if (req.user.role !== 'admin') { + return res.status(403).json({ error: 'Admin access required' }); + } + next(); +} + +module.exports = { requireAuth, requireAdmin }; +``` + +## Error Handling + +```javascript +// src/middleware/errorHandler.js +function errorHandler(err, req, res, next) { + console.error(err.stack); + + const status = err.status || 500; + const message = err.message || 'Internal Server Error'; + + res.status(status).json({ + error: message, + ...(process.env.NODE_ENV === 'development' && { stack: err.stack }) + }); +} + +module.exports = errorHandler; +``` + +## Prohibited Actions + +- DO NOT store passwords in plain text +- DO NOT skip input validation +- DO NOT expose stack traces in production +- DO NOT use synchronous operations in request handlers +- DO NOT hardcode secrets or credentials + +## Handoff Protocol + +After implementation: +1. Verify all endpoints work +2. Check security headers +3. Test error handling +4. Create database migration +5. Tag `@CodeSkeptic` for review +## Gitea Commenting (MANDATORY) + +**You MUST post a comment to the Gitea issue after completing your work.** + +Post a comment with: +1. ✅ Success: What was done, files changed, duration +2. ❌ Error: What failed, why, and blocker +3. ❓ Question: Clarification needed with options + +Use the `post_comment` function from `.kilo/skills/gitea-commenting/SKILL.md`. + +**NO EXCEPTIONS** - Always comment to Gitea. \ No newline at end of file diff --git a/.kilo/commands/blog.md b/.kilo/commands/blog.md new file mode 100644 index 0000000..3f56fbb --- /dev/null +++ b/.kilo/commands/blog.md @@ -0,0 +1,1195 @@ +--- +description: Create full-stack blog/CMS with Node.js, Vue, SQLite, admin panel, comments, and Docker deployment +mode: blog +model: qwen/qwen3-coder:free +color: "#10B981" +permission: + read: allow + edit: allow + write: allow + bash: allow + glob: allow + grep: allow + task: + "backend-developer": allow + "frontend-developer": allow + "system-analyst": allow + "lead-developer": allow + "sdet-engineer": allow + "code-skeptic": allow + "the-fixer": allow + "release-manager": allow + "security-auditor": allow + "browser-automation": allow +--- + +# Blog CMS Workflow + +Create a full-stack blog/CMS with posts, categories, tags, comments, author management, SEO optimization, and Docker deployment. Fully tested and production-ready. + +## Parameters + +- `project_name`: Blog name (required) +- `ui_framework`: UI framework - 'vuetify', 'quasar', 'primevue' (default: 'vuetify') +- `features`: Features to include - 'comments,rss,sitemap,analytics' (default: 'all') +- `docker`: Create Docker deployment (default: true) +- `issue`: Gitea issue number for tracking (optional) + +## Overview + +``` +Requirements → Architecture → Posts → Categories → Comments → Admin → SEO → Tests → Docker → Docs +``` + +## Technology Stack + +### Frontend +| Component | Technology | +|-----------|------------| +| Framework | Vue.js 3 (Composition API) | +| UI Library | Vuetify/Quasar/PrimeVue | +| State | Pinia | +| Router | Vue Router | +| Editor | Tiptap/Quill | +| HTTP | Axios | + +### Backend +| Component | Technology | +|-----------|------------| +| Runtime | Node.js 20.x | +| Framework | Express.js | +| Database | SQLite (better-sqlite3) | +| Auth | JWT + bcrypt | +| Markdown | marked + highlight.js | +| RSS | feed library | + +## Step 1: Requirements Analysis + +**Agent**: `@RequirementRefiner` + +### Blog Requirements Checklist + +```markdown +## User Stories + +### Content Management +- [ ] Create/edit/delete posts +- [ ] Rich text editor (markdown/WYSIWYG) +- [ ] Draft/publish/archive states +- [ ] Schedule posts +- [ ] Featured images +- [ ] Media library + +### Organization +- [ ] Categories (hierarchical) +- [ ] Tags (flat) +- [ ] Authors +- [ ] Content series + +### Comments +- [ ] Threaded comments +- [ ] Comment moderation +- [ ] Spam filtering +- [ ] Social login comments + +### SEO +- [ ] Meta tags +- [ ] Open Graph +- [ ] Twitter cards +- [ ] Sitemap +- [ ] RSS feed +- [ ] Structured data + +### User Features +- [ ] Post list with pagination +- [ ] Category filtering +- [ ] Tag filtering +- [ ] Search +- [ ] Related posts +- [ ] Reading time +- [ ] View count + +### Admin +- [ ] Dashboard with stats +- [ ] Post management +- [ ] Category management +- [ ] Tag management +- [ ] Comment moderation +- [ ] Media management +- [ ] User/author management +- [ ] Settings + +### Non-Functional +- [ ] Responsive design +- [ ] Cross-browser support +- [ ] Performance (<2s load) +- [ ] SEO optimized +- [ ] Accessibility +``` + +## Step 2: Architecture Design + +**Agent**: `@SystemAnalyst` + +### Project Structure + +``` +blog/ +├── backend/ +│ ├── src/ +│ │ ├── config/ +│ │ │ ├── database.js +│ │ │ ├── auth.js +│ │ │ └── seo.js +│ │ ├── db/ +│ │ │ ├── migrations/ +│ │ │ └── seeds/ +│ │ ├── models/ +│ │ │ ├── Post.js +│ │ │ ├── Category.js +│ │ │ ├── Tag.js +│ │ │ ├── Comment.js +│ │ │ ├── Author.js +│ │ │ └── User.js +│ │ ├── routes/ +│ │ │ ├── api/ +│ │ │ │ ├── posts.js +│ │ │ │ ├── categories.js +│ │ │ │ ├── tags.js +│ │ │ │ ├── comments.js +│ │ │ │ ├── search.js +│ │ │ │ └── feed.js +│ │ │ └── admin/ +│ │ │ ├── posts.js +│ │ │ ├── categories.js +│ │ │ ├── tags.js +│ │ │ ├── comments.js +│ │ │ ├── media.js +│ │ │ └── users.js +│ │ ├── services/ +│ │ │ ├── markdown.js +│ │ │ ├── seo.js +│ │ │ ├── search.js +│ │ │ └── email.js +│ │ └── middleware/ +│ │ ├── auth.js +│ │ ├── validation.js +│ │ └── pagination.js +│ └── tests/ +├── frontend/ +│ ├── src/ +│ │ ├── views/ +│ │ │ ├── public/ +│ │ │ │ ├── Home.vue +│ │ │ │ ├── Post.vue +│ │ │ │ ├── Category.vue +│ │ │ │ ├── Tag.vue +│ │ │ │ ├── Author.vue +│ │ │ │ ├── Search.vue +│ │ │ │ └── NotFound.vue +│ │ │ └── admin/ +│ │ │ ├── Dashboard.vue +│ │ │ ├── Posts.vue +│ │ │ ├── PostEditor.vue +│ │ │ ├── Categories.vue +│ │ │ ├── Tags.vue +│ │ │ ├── Comments.vue +│ │ │ ├── Media.vue +│ │ │ └── Settings.vue +│ │ ├── components/ +│ │ │ ├── post/ +│ │ │ │ ├── PostCard.vue +│ │ │ │ ├── PostList.vue +│ │ │ │ ├── PostContent.vue +│ │ │ │ └── RelatedPosts.vue +│ │ │ ├── comment/ +│ │ │ │ ├── CommentList.vue +│ │ │ │ ├── CommentForm.vue +│ │ │ │ └── CommentThread.vue +│ │ │ └── admin/ +│ │ │ ├── RichEditor.vue +│ │ │ ├── MediaPicker.vue +│ │ │ ├── CategoryTree.vue +│ │ │ └── TagInput.vue +│ │ ├── stores/ +│ │ │ ├── posts.js +│ │ │ ├── auth.js +│ │ │ └── ui.js +│ │ └── router/ +│ │ └── index.js +│ └── tests/ +├── database/ +│ └── blog.db +├── uploads/ +├── docker/ +│ ├── Dockerfile.backend +│ ├── Dockerfile.frontend +│ └── docker-compose.yml +└── docs/ + ├── API.md + └── DEPLOYMENT.md +``` + +Use the database schema from `.kilo/skills/blog/SKILL.md`. + +## Step 3: Backend Implementation + +**Agent**: `@BackendDeveloper` + +### Post API + +```javascript +// backend/src/routes/api/posts.js +const router = require('express').Router(); +const { query, validationResult } = require('express-validator'); + +// GET /api/posts - List published posts +router.get('/', + [ + query('page').optional().isInt({ min: 1 }), + query('limit').optional().isInt({ min: 1, max: 50 }), + query('category').optional().isString(), + query('tag').optional().isString(), + query('author').optional().isInt(), + query('search').optional().isString() + ], + async (req, res, next) => { + try { + const errors = validationResult(req); + if (!errors.isEmpty()) { + return res.status(400).json({ errors: errors.array() }); + } + + const { page = 1, limit = 10, category, tag, author, search } = req.query; + + const posts = await postService.findAll({ + page: parseInt(page), + limit: parseInt(limit), + status: 'published', + category, + tag, + author: author ? parseInt(author) : undefined, + search + }); + + res.json(posts); + } catch (error) { + next(error); + } + } +); + +// GET /api/posts/:slug - Get post by slug +router.get('/:slug', async (req, res, next) => { + try { + const post = await postService.findBySlug(req.params.slug); + + if (!post || post.status !== 'published') { + return res.status(404).json({ error: 'Post not found' }); + } + + // Increment view count + await postService.incrementViews(post.id); + + // Get related posts + const related = await postService.getRelated(post.id); + + // Get comments + const comments = await commentService.getApproved(post.id); + + res.json({ post, related, comments }); + } catch (error) { + next(error); + } +}); + +// GET /api/posts/slug/:slug/related - Get related posts +router.get('/:slug/related', async (req, res, next) => { + try { + const post = await postService.findBySlug(req.params.slug); + const related = await postService.getRelated(post.id); + res.json(related); + } catch (error) { + next(error); + } +}); + +module.exports = router; +``` + +### Admin Post API + +```javascript +// backend/src/routes/admin/posts.js +const router = require('express').Router(); +const auth = require('../../middleware/auth'); +const { body, validationResult } = require('express-validator'); + +// GET /api/admin/posts - List all posts (all statuses) +router.get('/', auth.requireAuth, async (req, res, next) => { + try { + const { page = 1, limit = 20, status, author } = req.query; + + const posts = await postService.findAll({ + page: parseInt(page), + limit: parseInt(limit), + status, + author: author ? parseInt(author) : req.user.id, + includeUnpublished: true + }); + + res.json(posts); + } catch (error) { + next(error); + } +}); + +// POST /api/admin/posts - Create post +router.post('/', + auth.requireAuth, + [ + body('title').notEmpty().isLength({ max: 255 }), + body('content').notEmpty(), + body('category_id').optional().isInt(), + body('tags').optional().isArray() + ], + async (req, res, next) => { + try { + const errors = validationResult(req); + if (!errors.isEmpty()) { + return res.status(400).json({ errors: errors.array() }); + } + + const postData = { + ...req.body, + author_id: req.user.id, + slug: await generateSlug(req.body.title) + }; + + // Calculate reading time + postData.reading_time = calculateReadingTime(req.body.content); + + // Set published_at if status is published + if (postData.status === 'published' && !postData.published_at) { + postData.published_at = new Date(); + } + + const post = await postService.create(postData); + + // Attach tags + if (req.body.tags) { + await postService.attachTags(post.id, req.body.tags); + } + + res.status(201).json(post); + } catch (error) { + next(error); + } + } +); + +// PUT /api/admin/posts/:id - Update post +router.put('/:id', + auth.requireAuth, + async (req, res, next) => { + try { + const post = await postService.findById(req.params.id); + + if (!post) { + return res.status(404).json({ error: 'Post not found' }); + } + + // Check ownership (unless admin) + if (post.author_id !== req.user.id && req.user.role !== 'admin') { + return res.status(403).json({ error: 'Forbidden' }); + } + + const updates = { + ...req.body, + reading_time: calculateReadingTime(req.body.content || post.content) + }; + + // Handle status changes + if (req.body.status === 'published' && post.status !== 'published') { + updates.published_at = new Date(); + } + + const updated = await postService.update(req.params.id, updates); + + // Update tags + if (req.body.tags) { + await postService.syncTags(updated.id, req.body.tags); + } + + res.json(updated); + } catch (error) { + next(error); + } + } +); + +// DELETE /api/admin/posts/:id - Delete post +router.delete('/:id', + auth.requireAuth, + async (req, res, next) => { + try { + const post = await postService.findById(req.params.id); + + if (!post) { + return res.status(404).json({ error: 'Post not found' }); + } + + // Check ownership (unless admin) + if (post.author_id !== req.user.id && req.user.role !== 'admin') { + return res.status(403).json({ error: 'Forbidden' }); + } + + await postService.delete(req.params.id); + + res.json({ success: true }); + } catch (error) { + next(error); + } + } +); + +// POST /api/admin/posts/:id/publish - Publish post +router.post('/:id/publish', + auth.requireAuth, + async (req, res, next) => { + try { + const post = await postService.update(req.params.id, { + status: 'published', + published_at: new Date() + }); + + res.json(post); + } catch (error) { + next(error); + } + } +); + +module.exports = router; +``` + +### Comment API + +```javascript +// backend/src/routes/api/comments.js +const router = require('express').Router(); + +// GET /api/posts/:postId/comments - Get approved comments +router.get('/posts/:postId/comments', async (req, res, next) => { + try { + const comments = await commentService.getApproved( + parseInt(req.params.postId) + ); + res.json(comments); + } catch (error) { + next(error); + } +}); + +// POST /api/posts/:postId/comments - Submit comment +router.post('/posts/:postId/comments', + [ + body('author_name').notEmpty().isLength({ max: 100 }), + body('author_email').isEmail(), + body('content').notEmpty().isLength({ max: 2000 }), + body('parent_id').optional().isInt() + ], + async (req, res, next) => { + try { + // Spam check + const spamCheck = await commentService.checkSpam({ + ip: req.ip, + email: req.body.author_email, + content: req.body.content + }); + + const status = spamCheck.isSpam ? 'spam' : 'pending'; + + const comment = await commentService.create({ + post_id: parseInt(req.params.postId), + parent_id: req.body.parent_id, + author_name: req.body.author_name, + author_email: req.body.author_email, + author_url: req.body.author_url, + content: req.body.content, + status, + ip_address: req.ip, + user_agent: req.headers['user-agent'] + }); + + res.status(201).json({ + success: true, + message: status === 'pending' + ? 'Comment submitted for moderation' + : 'Comment received', + id: comment.id + }); + } catch (error) { + next(error); + } + } +); + +module.exports = router; +``` + +### RSS Feed + +```javascript +// backend/src/routes/api/feed.js +const router = require('express').Router(); +const { Feed } = require('feed'); + +// GET /api/feed/rss - RSS feed +router.get('/rss', async (req, res, next) => { + try { + const posts = await postService.findAll({ + limit: 20, + status: 'published' + }); + + const feed = new Feed({ + title: config.blog.title, + description: config.blog.description, + link: config.blog.url, + language: 'en', + copyright: `© ${new Date().getFullYear()} ${config.blog.title}` + }); + + posts.forEach(post => { + feed.addItem({ + title: post.title, + id: `${config.blog.url}/posts/${post.slug}`, + link: `${config.blog.url}/posts/${post.slug}`, + description: post.excerpt, + content: post.content, + author: [{ name: post.author.name }], + date: new Date(post.published_at) + }); + }); + + res.set('Content-Type', 'application/rss+xml'); + res.send(feed.rss2()); + } catch (error) { + next(error); + } +}); + +// GET /api/feed/atom - Atom feed +router.get('/atom', async (req, res, next) => { + // Similar to RSS but atom1() +}); + +// GET /api/sitemap.xml - Sitemap +router.get('/sitemap.xml', async (req, res, next) => { + try { + const [posts, categories, tags] = await Promise.all([ + postService.findAll({ status: 'published' }), + categoryService.findAll(), + tagService.findAll() + ]); + + let sitemap = '\n'; + sitemap += '\n'; + + // Homepage + sitemap += ` ${config.blog.url}daily1.0\n`; + + // Posts + posts.data.forEach(post => { + sitemap += ` ${config.blog.url}/posts/${post.slug}${post.updated_at}weekly0.8\n`; + }); + + // Categories + categories.forEach(cat => { + sitemap += ` ${config.blog.url}/categories/${cat.slug}weekly0.6\n`; + }); + + // Tags + tags.forEach(tag => { + sitemap += ` ${config.blog.url}/tags/${tag.slug}weekly0.6\n`; + }); + + sitemap += ''; + + res.set('Content-Type', 'application/xml'); + res.send(sitemap); + } catch (error) { + next(error); + } +}); + +module.exports = router; +``` + +## Step 4: Frontend Implementation + +**Agent**: `@FrontendDeveloper` + +### Public Post View + +```vue + + + + + + +``` + +### Admin Post Editor + +```vue + + + + +``` + +## Step 5: SEO Implementation + +**Agent**: `@BackendDeveloper` + +### Meta Tags Service + +```javascript +// backend/src/services/seo.js +class SEOService { + generateMeta(post) { + return { + title: post.meta_title || `${post.title} | ${config.siteName}`, + description: post.meta_description || post.excerpt, + canonical: `${config.siteUrl}/posts/${post.slug}`, + ogType: 'article', + ogTitle: post.meta_title || post.title, + ogDescription: post.meta_description || post.excerpt, + ogImage: post.featured_image || config.defaultImage, + articlePublishedTime: post.published_at, + articleModifiedTime: post.updated_at, + articleAuthor: post.author.name, + twitterCard: 'summary_large_image', + twitterTitle: post.meta_title || post.title, + twitterDescription: post.meta_description || post.excerpt, + twitterImage: post.featured_image || config.defaultImage + }; + } + + generateSchema(post) { + return { + "@context": "https://schema.org", + "@type": "Article", + "headline": post.title, + "image": post.featured_image, + "author": { + "@type": "Person", + "name": post.author.name, + "url": `${config.siteUrl}/authors/${post.author.slug}` + }, + "publisher": { + "@type": "Organization", + "name": config.siteName, + "logo": { + "@type": "ImageObject", + "url": config.logo + } + }, + "datePublished": post.published_at, + "dateModified": post.updated_at, + "description": post.excerpt, + "mainEntityOfPage": { + "@type": "WebPage", + "@id": `${config.siteUrl}/posts/${post.slug}` + } + }; + } + + generateBreadcrumbSchema(items) { + return { + "@context": "https://schema.org", + "@type": "BreadcrumbList", + "itemListElement": items.map((item, index) => ({ + "@type": "ListItem", + "position": index + 1, + "name": item.name, + "item": item.url + })) + }; + } +} + +module.exports = new SEOService(); +``` + +## Step 6: E2E Testing + +**Agent**: `@SDETEngineer` + +```javascript +// tests/e2e/blog.spec.js +import { test, expect } from '@playwright/test'; + +test.describe('Blog Public', () => { + test('view post', async ({ page }) => { + await page.goto('/'); + + // Click on first post + await page.click('.post-card:first-child'); + + // Verify post loaded + await expect(page.locator('.post-title')).toBeVisible(); + await expect(page.locator('.post-content')).toBeVisible(); + + // Check meta tags + const metaTitle = await page.locator('meta[name="twitter:title"]').getAttribute('content'); + expect(metaTitle).toBeTruthy(); + }); + + test('search posts', async ({ page }) => { + await page.goto('/'); + + await page.fill('input[name="search"]', 'test'); + await page.press('input[name="search"]', 'Enter'); + + await expect(page).toHaveURL(/search\?q=test/); + await expect(page.locator('.post-card')).toHaveCountGreaterThanOrEqual(0); + }); + + test('filter by category', async ({ page }) => { + await page.goto('/'); + + await page.click('.category-link:first-child'); + + await expect(page).toHaveURL(/categories\//); + await expect(page.locator('.category-title')).toBeVisible(); + }); + + test('submit comment', async ({ page }) => { + await page.goto('/posts/test-post'); + + await page.fill('input[name="name"]', 'Test User'); + await page.fill('input[name="email"]', 'test@example.com'); + await page.fill('textarea[name="content"]', 'Great article!'); + + await page.click('button:has-text("Submit")'); + + await expect(page.locator('.comment-success')).toBeVisible(); + }); + + test('RSS feed', async ({ page }) => { + const response = await page.goto('/api/feed/rss'); + + expect(response.status()).toBe(200); + expect(await response.text()).toContain(' { + test.beforeEach(async ({ page }) => { + await page.goto('/admin/login'); + await page.fill('input[name="email"]', 'admin@example.com'); + await page.fill('input[name="password"]', 'password'); + await page.click('button[type="submit"]'); + await expect(page).toHaveURL('/admin/dashboard'); + }); + + test('create post', async ({ page }) => { + await page.goto('/admin/posts/new'); + + await page.fill('input[name="title"]', 'Test Post'); + await page.fill('textarea[name="content"]', 'This is a test post content.'); + await page.fill('input[name="slug"]', 'test-post-' + Date.now()); + + await page.click('button:has-text("Publish")'); + + await expect(page).toHaveURL(/\/admin\/posts\/\d+/); + }); + + test('edit post', async ({ page }) => { + await page.goto('/admin/posts'); + await page.click('.post-row:first-child'); + + await page.fill('input[name="title"]', 'Updated Title'); + await page.click('button:has-text("Save")'); + + await expect(page.locator('.notification')).toContainText('saved'); + }); + + test('moderate comment', async ({ page }) => { + await page.goto('/admin/comments'); + + // Approve comment + await page.click('.comment-row:first-child .approve-btn'); + + await expect(page.locator('.notification')).toContainText('approved'); + }); +}); +``` + +## Step 7: Docker & Deployment + +Same structure as landing-page workflow. + +## Step 8: Documentation + +Same structure as landing-page workflow. + +## Quality Gates + +| Gate | Criteria | +|------|----------| +| Posts | CRUD working, markdown rendered | +| Categories | Hierarchical structure working | +| Tags | Tag-cloud, filtering working | +| Comments | Submit, moderate, approve working | +| SEO | Meta tags, sitemap, RSS working | +| Admin | All management functions working | +| Tests | E2E tests passing | +| Docker | Containers building and running | \ No newline at end of file diff --git a/.kilo/commands/commerce.md b/.kilo/commands/commerce.md new file mode 100644 index 0000000..ef62ada --- /dev/null +++ b/.kilo/commands/commerce.md @@ -0,0 +1,1270 @@ +--- +description: Create full-stack e-commerce site with Node.js, Vue, SQLite, admin panel, payments, and Docker deployment +mode: commerce +model: qwen/qwen3-coder:free +color: "#F59E0B" +permission: + read: allow + edit: allow + write: allow + bash: allow + glob: allow + grep: allow + task: + "backend-developer": allow + "frontend-developer": allow + "system-analyst": allow + "lead-developer": allow + "sdet-engineer": allow + "code-skeptic": allow + "the-fixer": allow + "release-manager": allow + "security-auditor": allow + "browser-automation": allow +--- + +# E-commerce Workflow + +Create a full-stack e-commerce site with product catalog, shopping cart, checkout, payment integration, and admin panel. Fully tested and production-ready. + +## Parameters + +- `project_name`: Store name (required) +- `ui_framework`: UI framework - 'vuetify', 'quasar', 'primevue' (default: 'vuetify') +- `payment_provider`: Payment - 'stripe', 'paypal', 'both' (default: 'stripe') +- `currency`: Default currency - 'USD', 'EUR', etc. (default: 'USD') +- `docker`: Create Docker deployment (default: true) +- `issue`: Gitea issue number for tracking (optional) + +## Overview + +``` +Requirements → Architecture → Products → Cart → Checkout → Payments → Admin → Tests → Docker → Docs +``` + +## Technology Stack + +### Frontend +| Component | Technology | +|-----------|------------| +| Framework | Vue.js 3 (Composition API) | +| UI Library | Vuetify/Quasar/PrimeVue | +| State | Pinia | +| Router | Vue Router | +| HTTP | Axios | + +### Backend +| Component | Technology | +|-----------|------------| +| Runtime | Node.js 20.x | +| Framework | Express.js | +| Database | SQLite (better-sqlite3) | +| Auth | JWT + bcrypt | +| Payment | Stripe/PayPal SDK | + +## Step 1: Requirements Analysis + +**Agent**: `@RequirementRefiner` + +### E-commerce Requirements Checklist + +```markdown +## User Stories + +### Product Catalog +- [ ] View products with pagination +- [ ] Filter by category +- [ ] Search products +- [ ] View product details +- [ ] Product variants (size, color) +- [ ] Product images gallery + +### Shopping Cart +- [ ] Add to cart +- [ ] Update quantity +- [ ] Remove from cart +- [ ] Apply discount code +- [ ] Persistent cart (session/database) +- [ ] Price calculations + +### Checkout +- [ ] Guest checkout +- [ ] User registration +- [ ] Shipping address +- [ ] Billing address +- [ ] Shipping method selection +- [ ] Order summary +- [ ] Order confirmation + +### Payment +- [ ] Credit card payment (Stripe) +- [ ] PayPal payment +- [ ] Payment confirmation +- [ ] Receipt email + +### User Account +- [ ] Registration +- [ ] Login/Logout +- [ ] Order history +- [ ] Saved addresses +- [ ] Wishlist + +### Admin +- [ ] Product management (CRUD) +- [ ] Category management +- [ ] Order management +- [ ] Customer management +- [ ] Discount codes +- [ ] Analytics dashboard + +### Non-Functional +- [ ] Responsive design +- [ ] Cross-browser support +- [ ] Performance (<3s load) +- [ ] Security (HTTPS, CSRF) +- [ ] SEO optimization +``` + +## Step 2: Architecture Design + +**Agent**: `@SystemAnalyst` + +### Project Structure + +``` +{project_name}/ +├── backend/ +│ ├── src/ +│ │ ├── config/ +│ │ │ ├── database.js +│ │ │ ├── auth.js +│ │ │ ├── stripe.js +│ │ │ └── email.js +│ │ ├── db/ +│ │ │ ├── migrations/ +│ │ │ └── seeds/ +│ │ ├── models/ +│ │ │ ├── Product.js +│ │ │ ├── Category.js +│ │ │ ├── Cart.js +│ │ │ ├── Order.js +│ │ │ ├── User.js +│ │ │ └── Payment.js +│ │ ├── routes/ +│ │ │ ├── api/ +│ │ │ │ ├── products.js +│ │ │ │ ├── categories.js +│ │ │ │ ├── cart.js +│ │ │ │ ├── orders.js +│ │ │ │ └── auth.js +│ │ │ └── admin/ +│ │ │ ├── products.js +│ │ │ ├── orders.js +│ │ │ ├── customers.js +│ │ │ └── analytics.js +│ │ ├── services/ +│ │ │ ├── payment/ +│ │ │ │ ├── stripe.js +│ │ │ │ └── paypal.js +│ │ │ ├── email.js +│ │ │ └── inventory.js +│ │ └── middleware/ +│ │ ├── auth.js +│ │ ├── admin.js +│ │ └── validation.js +│ └── tests/ +├── frontend/ +│ ├── src/ +│ │ ├── views/ +│ │ │ ├── public/ +│ │ │ │ ├── Home.vue +│ │ │ │ ├── Products.vue +│ │ │ │ ├── Product.vue +│ │ │ │ ├── Cart.vue +│ │ │ │ ├── Checkout.vue +│ │ │ │ └── Order.vue +│ │ │ ├── account/ +│ │ │ │ ├── Login.vue +│ │ │ │ ├── Register.vue +│ │ │ │ ├── Orders.vue +│ │ │ │ └── Wishlist.vue +│ │ │ └── admin/ +│ │ │ ├── Dashboard.vue +│ │ │ ├── Products.vue +│ │ │ ├── Orders.vue +│ │ │ ├── Customers.vue +│ │ │ └── Settings.vue +│ │ ├── components/ +│ │ │ ├── product/ +│ │ │ │ ├── ProductCard.vue +│ │ │ │ ├── ProductGrid.vue +│ │ │ │ └── ProductFilters.vue +│ │ │ ├── cart/ +│ │ │ │ ├── CartItem.vue +│ │ │ │ ├── CartSummary.vue +│ │ │ │ └── DiscountCode.vue +│ │ │ └── checkout/ +│ │ │ ├── AddressForm.vue +│ │ │ ├── PaymentForm.vue +│ │ │ └── OrderSummary.vue +│ │ ├── stores/ +│ │ │ ├── cart.js +│ │ │ ├── auth.js +│ │ │ └── products.js +│ │ └── router/ +│ │ └── index.js +│ └── tests/ +├── database/ +│ └── shop.db +├── docker/ +│ ├── Dockerfile.backend +│ ├── Dockerfile.frontend +│ └── docker-compose.yml +└── docs/ + ├── API.md + └── DEPLOYMENT.md +``` + +### Database Schema + +Use the schema from `.kilo/skills/ecommerce/SKILL.md` for products, categories, cart, orders, payments. + +## Step 3: Backend Implementation + +**Agent**: `@BackendDeveloper` + +### Product API + +```javascript +// backend/src/routes/api/products.js +const router = require('express').Router(); +const { query, validationResult } = require('express-validator'); + +// GET /api/products - List products with pagination and filters +router.get('/', + [ + query('page').optional().isInt({ min: 1 }), + query('limit').optional().isInt({ min: 1, max: 100 }), + query('category').optional().isInt(), + query('search').optional().isString(), + query('minPrice').optional().isFloat(), + query('maxPrice').optional().isFloat(), + query('sort').optional().isIn(['price', 'name', 'created']) + ], + async (req, res, next) => { + try { + const errors = validationResult(req); + if (!errors.isEmpty()) { + return res.status(400).json({ errors: errors.array() }); + } + + const { page = 1, limit = 20, category, search, minPrice, maxPrice, sort } = req.query; + + const products = await productService.findAll({ + page: parseInt(page), + limit: parseInt(limit), + category: category ? parseInt(category) : undefined, + search, + minPrice: minPrice ? parseFloat(minPrice) : undefined, + maxPrice: maxPrice ? parseFloat(maxPrice) : undefined, + sort + }); + + res.json(products); + } catch (error) { + next(error); + } + } +); + +// GET /api/products/:slug - Get product details +router.get('/:slug', async (req, res, next) => { + try { + const product = await productService.findBySlug(req.params.slug); + + if (!product) { + return res.status(404).json({ error: 'Product not found' }); + } + + // Get related products + const related = await productService.getRelated(product.id); + + res.json({ product, related }); + } catch (error) { + next(error); + } +}); + +module.exports = router; +``` + +### Cart API + +```javascript +// backend/src/routes/api/cart.js +const router = require('express').Router(); +const cartService = require('../../services/cart'); + +// GET /api/cart - Get current cart +router.get('/', async (req, res, next) => { + try { + const cartId = req.session.cartId || req.headers['x-cart-id']; + const cart = await cartService.getOrCreateCart(cartId, req.user?.id); + res.json(cart); + } catch (error) { + next(error); + } +}); + +// POST /api/cart/items - Add item to cart +router.post('/items', + [ + body('productId').isInt(), + body('variantId').optional().isInt(), + body('quantity').isInt({ min: 1 }) + ], + async (req, res, next) => { + try { + const cartId = req.session.cartId || req.headers['x-cart-id']; + const { productId, variantId, quantity } = req.body; + + const cart = await cartService.addItem( + cartId, + parseInt(productId), + variantId ? parseInt(variantId) : null, + parseInt(quantity) + ); + + req.session.cartId = cart.id; + res.json(cart); + } catch (error) { + next(error); + } + } +); + +// PUT /api/cart/items/:id - Update quantity +router.put('/items/:id', + [body('quantity').isInt({ min: 0 })], + async (req, res, next) => { + try { + const { quantity } = req.body; + const cart = await cartService.updateItem( + parseInt(req.params.id), + parseInt(quantity) + ); + res.json(cart); + } catch (error) { + next(error); + } + } +); + +// DELETE /api/cart/items/:id - Remove item +router.delete('/items/:id', async (req, res, next) => { + try { + const cart = await cartService.removeItem(parseInt(req.params.id)); + res.json(cart); + } catch (error) { + next(error); + } +}); + +// POST /api/cart/coupon - Apply discount +router.post('/coupon', + [body('code').isString()], + async (req, res, next) => { + try { + const { code } = req.body; + const cartId = req.session.cartId; + const cart = await cartService.applyCoupon(cartId, code); + res.json(cart); + } catch (error) { + next(error); + } + } +); + +module.exports = router; +``` + +### Checkout API + +```javascript +// backend/src/routes/api/checkout.js +const router = require('express').Router(); +const checkoutService = require('../../services/checkout'); +const stripeService = require('../../services/payment/stripe'); +const { requireAuth, optionalAuth } = require('../../middleware/auth'); + +// POST /api/checkout - Create order from cart +router.post('/', + optionalAuth, + [ + body('email').isEmail(), + body('shippingAddress').isObject(), + body('billingAddress').optional().isObject(), + body('shippingMethod').isString(), + body('paymentMethod').isIn(['stripe', 'paypal']) + ], + async (req, res, next) => { + try { + const errors = validationResult(req); + if (!errors.isEmpty()) { + return res.status(400).json({ errors: errors.array() }); + } + + const cartId = req.session.cartId; + const userId = req.user?.id; + + const order = await checkoutService.createOrder({ + cartId, + userId, + email: req.body.email, + shippingAddress: req.body.shippingAddress, + billingAddress: req.body.billingAddress || req.body.shippingAddress, + shippingMethod: req.body.shippingMethod, + paymentMethod: req.body.paymentMethod + }); + + // Create payment intent + const payment = await stripeService.createPaymentIntent(order); + + res.status(201).json({ + order, + payment, + clientSecret: payment.clientSecret + }); + } catch (error) { + next(error); + } + } +); + +// POST /api/checkout/guest - Guest checkout +router.post('/guest', + [body('email').isEmail()], + async (req, res, next) => { + // Same as above but always creates guest order + } +); + +module.exports = router; +``` + +### Order Status Transitions + +```javascript +// backend/src/services/orders.js +const ORDER_STATUSES = { + pending: { next: ['processing', 'cancelled'] }, + processing: { next: ['on_hold', 'shipped'] }, + on_hold: { next: ['processing', 'cancelled'] }, + shipped: { next: ['delivered'] }, + delivered: { next: ['completed'] }, + completed: { next: [] }, + cancelled: { next: ['refunded'] }, + refunded: { next: [] } +}; + +async function updateStatus(orderId, newStatus) { + const order = await this.findById(orderId); + + if (!ORDER_STATUSES[order.status].next.includes(newStatus)) { + throw new Error(`Cannot transition from ${order.status} to ${newStatus}`); + } + + await this.db.orders.update(orderId, { status: newStatus }); + + // Send notification + await this.notificationService.send(order.userId, { + type: 'order_status', + orderId, + status: newStatus + }); + + return this.findById(orderId); +} +``` + +## Step 4: Frontend Implementation + +**Agent**: `@FrontendDeveloper` + +### Product Catalog + +```vue + + + + +``` + +### Shopping Cart + +```vue + + + + +``` + +### Checkout + +```vue + + + + +``` + +### Admin Dashboard + +```vue + + + + +``` + +## Step 5: Payment Integration + +**Agent**: `@BackendDeveloper` + +### Stripe Integration + +```javascript +// backend/src/services/payment/stripe.js +const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY); + +class StripeService { + async createPaymentIntent(order) { + const paymentIntent = await stripe.paymentIntents.create({ + amount: Math.round(order.total * 100), // Convert to cents + currency: order.currency.toLowerCase(), + metadata: { + orderId: order.id, + orderNumber: order.order_number + }, + receipt_email: order.email + }); + + // Save payment record + await db.payments.create({ + id: paymentIntent.id, + order_id: order.id, + provider: 'stripe', + amount: order.total, + currency: order.currency, + status: 'pending' + }); + + return { + clientSecret: paymentIntent.client_secret, + paymentIntentId: paymentIntent.id + }; + } + + async handleWebhook(signature, payload) { + const event = stripe.webhooks.constructEvent( + payload, + signature, + process.env.STRIPE_WEBHOOK_SECRET + ); + + switch (event.type) { + case 'payment_intent.succeeded': + await this.handlePaymentSuccess(event.data.object); + break; + case 'payment_intent.payment_failed': + await this.handlePaymentFailure(event.data.object); + break; + case 'charge.refunded': + await this.handleRefund(event.data.object); + break; + } + + return { received: true }; + } + + async handlePaymentSuccess(paymentIntent) { + const orderId = paymentIntent.metadata.orderId; + + // Update payment status + await db.payments.update( + { id: paymentIntent.id }, + { status: 'completed' } + ); + + // Update order status + await orderService.updateStatus(orderId, 'processing'); + + // Send confirmation email + await emailService.sendOrderConfirmation(orderId); + + // Deduct inventory + await inventoryService.deductForOrder(orderId); + } + + async refundOrder(orderId, amount = null) { + const payment = await db.payments.findOne({ order_id: orderId }); + + const refund = await stripe.refunds.create({ + payment_intent: payment.id, + amount: amount ? Math.round(amount * 100) : undefined + }); + + // Update payment status + await db.payments.update( + { id: payment.id }, + { status: 'refunded' } + ); + + // Update order status + await orderService.updateStatus(orderId, 'refunded'); + + return refund; + } +} + +module.exports = new StripeService(); +``` + +### Webhook Handler + +```javascript +// backend/src/routes/webhooks/stripe.js +const router = require('express').Router(); +const stripeService = require('../../services/payment/stripe'); + +// Stripe webhook endpoint +router.post('/stripe', + express.raw({ type: 'application/json' }), + async (req, res) => { + const signature = req.headers['stripe-signature']; + + try { + await stripeService.handleWebhook(signature, req.body); + res.json({ received: true }); + } catch (error) { + console.error('Webhook error:', error); + res.status(400).json({ error: error.message }); + } + } +); + +module.exports = router; +``` + +## Step 6: E2E Testing + +**Agent**: `@SDETEngineer` + +```javascript +// tests/e2e/shop.spec.js +import { test, expect } from '@playwright/test'; + +test.describe('E-commerce Flow', () => { + test('complete purchase flow', async ({ page }) => { + // 1. Browse products + await page.goto('/products'); + await expect(page.locator('.product-card')).toHaveCountGreaterThanOrEqual(1); + + // 2. View product details + await page.click('.product-card:first-child'); + await expect(page).toHaveURL(/\/products\/\d+/); + await expect(page.locator('.product-title')).toBeVisible(); + + // 3. Add to cart + await page.click('button:has-text("Add to Cart")'); + await expect(page.locator('.cart-count')).toHaveText('1'); + + // 4. View cart + await page.click('.cart-icon'); + await expect(page).toHaveURL('/cart'); + await expect(page.locator('.cart-item')).toHaveCount(1); + + // 5. Proceed to checkout + await page.click('button:has-text("Checkout")'); + await expect(page).toHaveURL('/checkout'); + + // 6. Fill shipping address + await page.fill('input[name="email"]', 'test@example.com'); + await page.fill('input[name="firstName"]', 'John'); + await page.fill('input[name="lastName"]', 'Doe'); + await page.fill('input[name="address1"]', '123 Main St'); + await page.fill('input[name="city"]', 'New York'); + await page.fill('input[name="postalCode"]', '10001'); + await page.selectOption('select[name="country"]', 'US'); + await page.click('button:has-text("Continue")'); + + // 7. Select shipping + await page.click('input[value="standard"]'); + await page.click('button:has-text("Continue")'); + + // 8. Enter payment (test card) + await page.fill('[name="cardNumber"]', '4242424242424242'); + await page.fill('[name="expiry"]', '12/25'); + await page.fill('[name="cvc"]', '123'); + await page.click('button:has-text("Pay")'); + + // 9. Confirm order + await expect(page.locator('.order-confirmation')).toBeVisible(); + await expect(page.locator('.order-number')).toBeVisible(); + }); + + test('search and filter products', async ({ page }) => { + await page.goto('/products'); + + // Search + await page.fill('input[name="search"]', 'laptop'); + await page.press('input[name="search"]', 'Enter'); + await expect(page.locator('.product-card')).toHaveCountGreaterThanOrEqual(1); + + // Filter by category + await page.click('text=Electronics'); + await expect(page).toHaveURL(/category=electronics/); + + // Filter by price + await page.fill('input[name="minPrice"]', '100'); + await page.fill('input[name="maxPrice"]', '500'); + await page.click('button:has-text("Apply")'); + await expect(page).toHaveURL(/minPrice=100/); + }); + + test('cart persistence', async ({ page }) => { + // Add item to cart + await page.goto('/products/1'); + await page.click('button:has-text("Add to Cart")'); + + // Refresh page + await page.reload(); + await expect(page.locator('.cart-count')).toHaveText('1'); + + // Navigate away and back + await page.goto('/'); + await page.goto('/cart'); + await expect(page.locator('.cart-item')).toHaveCount(1); + }); +}); + +test.describe('Admin Panel', () => { + test.beforeEach(async ({ page }) => { + // Login as admin + await page.goto('/admin/login'); + await page.fill('input[name="email"]', 'admin@example.com'); + await page.fill('input[name="password"]', 'admin123'); + await page.click('button[type="submit"]'); + await expect(page).toHaveURL('/admin/dashboard'); + }); + + test('create product', async ({ page }) => { + await page.goto('/admin/products/new'); + + await page.fill('input[name="name"]', 'Test Product'); + await page.fill('input[name="sku"]', 'TEST-001'); + await page.fill('input[name="price"]', '99.99'); + await page.fill('textarea[name="description"]', 'Test description'); + await page.selectOption('select[name="category"]', '1'); + await page.fill('input[name="stock"]', '10'); + + await page.click('button:has-text("Save")'); + await expect(page).toHaveURL(/\/admin\/products\/\d+/); + }); + + test('process order', async ({ page }) => { + await page.goto('/admin/orders'); + await page.click('tr:first-child td:last-child button'); + + // Update status + await page.selectOption('select[name="status"]', 'processing'); + await page.click('button:has-text("Update")'); + + await expect(page.locator('.status-chip')).toHaveText('processing'); + }); +}); +``` + +## Step 7: Docker & Deployment + +Same as landing-page workflow but with e-commerce specific configurations. + +## Step 8: Documentation + +### API Documentation + +```markdown +# E-commerce API + +## Public Endpoints + +### Products + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | /api/products | List products | +| GET | /api/products/:slug | Get product | +| GET | /api/categories | List categories | +| GET | /api/categories/:slug | Get category | + +### Cart + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | /api/cart | Get cart | +| POST | /api/cart/items | Add item | +| PUT | /api/cart/items/:id | Update quantity | +| DELETE | /api/cart/items/:id | Remove item | +| POST | /api/cart/coupon | Apply discount | + +### Checkout + +| Method | Endpoint | Description | +|--------|----------|-------------| +| POST | /api/checkout | Create order | +| POST | /api/checkout/guest | Guest checkout | +| GET | /api/orders/:id | Get order | + +## Admin Endpoints + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | /api/admin/products | List all products | +| POST | /api/admin/products | Create product | +| PUT | /api/admin/products/:id | Update product | +| DELETE | /api/admin/products/:id | Delete product | +| GET | /api/admin/orders | List orders | +| PUT | /api/admin/orders/:id/status | Update order status | +| GET | /api/admin/customers | List customers | +| GET | /api/admin/analytics | Get analytics | +``` + +## Post to Gitea + +After each step, post progress: + +```python +post_gitea_comment(issue_number, """## ✅ E-commerce Step Complete + +**Step**: {step_name} +**Duration**: {duration} + +### Completed +{completed_items} + +### Next +{next_step} + +**Status**: {status} +""") +``` + +## Quality Gates + +| Gate | Criteria | +|------|----------| +| Products | CRUD working, pagination, search | +| Cart | Add/remove/update, persist across sessions | +| Checkout | Complete flow working | +| Payment | Stripe integration working | +| Admin | All management functions working | +| Tests | E2E tests passing | +| Docker | Containers building and running | \ No newline at end of file diff --git a/.kilo/commands/landing-page.md b/.kilo/commands/landing-page.md index f01f642..47c3f28 100644 --- a/.kilo/commands/landing-page.md +++ b/.kilo/commands/landing-page.md @@ -1,5 +1,5 @@ --- -description: Create fully functional landing page from HTML mockups with Docker deployment +description: Create full-stack landing page CMS with Node.js, Vue, SQLite, admin panel and Docker deployment mode: landing model: ollama-cloud/kimi-k2.5 color: "#8B5CF6" @@ -13,84 +13,124 @@ permission: task: "frontend-developer": allow "system-analyst": allow + "lead-developer": allow "sdet-engineer": allow "code-skeptic": allow "the-fixer": allow "release-manager": allow "visual-tester": allow "browser-automation": allow + "security-auditor": allow --- -# Landing Page Workflow +# Landing Page CMS Workflow -Create a fully functional, tested, and documented landing page from HTML mockups/scetches. Outputs a production-ready Docker container. +Create a full-stack landing page CMS from HTML mockups with Node.js backend, Vue.js frontend, SQLite database, admin panel, and Docker deployment. Fully tested and documented product ready for client delivery. ## Parameters - `mockup_dir`: Directory containing HTML mockups (default: `./mockups/`) - `project_name`: Project name for the landing page (required) -- `style`: CSS framework - 'tailwind', 'bootstrap', 'vanilla' (default: 'tailwind') -- `responsive`: Enable responsive design (default: true) +- `vue_version`: Vue.js version - '3' or '2' (default: '3') +- `ui_framework`: UI framework - 'vuetify', 'quasar', 'primevue', 'none' (default: 'vuetify') +- `admin_theme`: Admin theme - 'modern', 'classic' (default: 'modern') - `docker`: Create Docker deployment (default: true) - `issue`: Gitea issue number for tracking (optional) ## Overview ``` -HTML Mockups → Architecture → Components → Styling → E2E Tests → Docker → Documentation → Product +HTML Mockups → Architecture → Backend API → Vue Frontend → Admin Panel → E2E Tests → Docker → Documentation → Product ``` +## Technology Stack + +### Frontend +| Component | Technology | Version | +|-----------|------------|---------| +| Framework | Vue.js | 3.x (Composition API) | +| UI Library | Vuetify/Quasar/PrimeVue | Latest | +| State Management | Pinia | 2.x | +| Router | Vue Router | 4.x | +| HTTP Client | Axios | 1.x | +| Build | Vite | 5.x | + +### Backend +| Component | Technology | Version | +|-----------|------------|---------| +| Runtime | Node.js | 20.x LTS | +| Framework | Express.js | 4.x | +| Database | SQLite | 3.x (better-sqlite3) | +| ORM | Knex.js | 3.x | +| Auth | JWT + bcrypt | Latest | +| Validation | Joi/Zod | Latest | + +### Cross-Browser Support +| Browser | Min Version | Coverage | +|---------|-------------|----------| +| Chrome | 90+ | Full | +| Firefox | 88+ | Full | +| Safari | 14+ | Full | +| Edge | 90+ | Full | +| Mobile Safari | 14+ | Full | +| Chrome Mobile | 90+ | Full | + ## Step 1: Analyze Mockups **Agent**: `@FrontendDeveloper` ### Input Analysis -1. Scan mockup directory for HTML files: +1. Scan mockup directory: ```bash find {mockup_dir} -name "*.html" -o -name "*.htm" | head -20 ``` -2. Extract structure from each mockup: - - Sections (header, hero, features, pricing, footer) - - Navigation elements - - Forms and CTAs - - Responsive breakpoints - - Assets (images, fonts, icons) +2. Extract content structure: + - Public pages (home, about, contact) + - Content sections (hero, features, pricing, testimonials, footer) + - Editable content areas (text, images, CTAs) + - Forms (contact, newsletter, lead capture) -3. Create component inventory: +3. Create content model: ```markdown - ## Component Inventory + ## Content Model ### Pages - - index.html → Home page with hero, features, pricing - - about.html → About page with team section - - contact.html → Contact form page + - Home: Hero, Features, Pricing, Testimonials, CTA + - About: Team, Mission, History + - Contact: Form, Map, Info - ### Shared Components - - Header: Logo, navigation, CTA button - - Footer: Links, social icons, copyright - - Hero: Headline, subheadline, CTA buttons - - Features: Icon cards grid - - Pricing: Pricing cards table - - Contact Form: Name, email, message fields + ### Editable Content + - Hero: title, subtitle, background_image, cta_text, cta_link + - Features: [{icon, title, description}] + - Pricing: [{name, price, features, highlight}] + - Testimonials: [{avatar, name, role, text}] + - Footer: copyright, social_links, contact_info - ### Assets Detected - - Images: logo.png, hero-bg.jpg, feature-icons/ - - Fonts: Inter, Helvetica - - Icons: Font Awesome / Heroicons + ### Dynamic Content + - Blog/News posts + - FAQ items + - Team members + - Portfolio items + + ### Forms + - Contact: name, email, phone, message + - Newsletter: email + - Lead capture: name, email, phone, interest ``` 4. Post analysis to Gitea: ```python - post_gitea_comment(issue_number, """## 🎨 Landing Page Analysis + post_gitea_comment(issue_number, """## 🎨 Mockup Analysis Complete - **Pages Found**: {page_count} - **Components Identified**: {component_count} - **Estimated Sections**: {sections} + **Pages Identified**: {page_count} + **Content Sections**: {section_count} + **Editable Areas**: {editable_count} + **Forms Detected**: {form_count} - ### Component Tree - {component_tree} + ### Content Model + {content_model_summary} **Next**: Architecture design """) @@ -103,75 +143,329 @@ HTML Mockups → Architecture → Components → Styling → E2E Tests → Docke ### Project Structure ``` -project_name/ -├── src/ -│ ├── index.html # Main landing page -│ ├── pages/ # Additional pages -│ │ ├── about.html -│ │ └── contact.html -│ ├── components/ # Reusable components -│ │ ├── header.html -│ │ ├── footer.html -│ │ └── cta-button.html -│ ├── assets/ -│ │ ├── images/ -│ │ ├── fonts/ -│ │ └── icons/ -│ ├── styles/ -│ │ ├── main.css -│ │ └── components/ -│ ├── scripts/ +{project_name}/ +├── backend/ +│ ├── src/ +│ │ ├── config/ +│ │ │ ├── database.js # SQLite configuration +│ │ │ ├── auth.js # JWT configuration +│ │ │ └── cors.js # CORS configuration +│ │ ├── db/ +│ │ │ ├── migrations/ # Knex migrations +│ │ │ ├── seeds/ # Initial data +│ │ │ └── connection.js # Database connection +│ │ ├── models/ +│ │ │ ├── Page.js # Page model +│ │ │ ├── Section.js # Section model +│ │ │ ├── Content.js # Content model +│ │ │ ├── Media.js # Media model +│ │ │ ├── Form.js # Form submissions +│ │ │ └── User.js # Admin user +│ │ ├── routes/ +│ │ │ ├── api/ +│ │ │ │ ├── pages.js # Public pages API +│ │ │ │ ├── content.js # Public content API +│ │ │ │ ├── forms.js # Form submissions +│ │ │ │ └── health.js # Health check +│ │ │ └── admin/ +│ │ │ ├── auth.js # Admin authentication +│ │ │ ├── pages.js # Page management +│ │ │ ├── content.js # Content management +│ │ │ ├── media.js # Media management +│ │ │ ├── users.js # User management +│ │ │ └── settings.js # Site settings +│ │ ├── middleware/ +│ │ │ ├── auth.js # JWT validation +│ │ │ ├── validation.js # Request validation +│ │ │ ├── upload.js # File upload +│ │ │ └── errorHandler.js # Error handling +│ │ ├── services/ +│ │ │ ├── content.js # Content business logic +│ │ │ ├── media.js # Media processing +│ │ │ └── email.js # Email notifications +│ │ └── app.js # Express app +│ ├── tests/ +│ │ ├── unit/ +│ │ └── integration/ +│ └── package.json +├── frontend/ +│ ├── src/ +│ │ ├── views/ +│ │ │ ├── public/ +│ │ │ │ ├── Home.vue # Landing page +│ │ │ │ ├── About.vue # About page +│ │ │ │ └── Contact.vue # Contact page +│ │ │ └── admin/ +│ │ │ ├── Dashboard.vue +│ │ │ ├── Pages.vue # Page management +│ │ │ ├── Content.vue # Content editor +│ │ │ ├── Media.vue # Media library +│ │ │ ├── Forms.vue # Form submissions +│ │ │ ├── Users.vue # User management +│ │ │ └── Settings.vue # Site settings +│ │ ├── components/ +│ │ │ ├── public/ +│ │ │ │ ├── Hero.vue +│ │ │ │ ├── Features.vue +│ │ │ │ ├── Pricing.vue +│ │ │ │ ├── Testimonials.vue +│ │ │ │ ├── Footer.vue +│ │ │ │ └── Navigation.vue +│ │ │ └── admin/ +│ │ │ ├── Sidebar.vue +│ │ │ ├── Header.vue +│ │ │ ├── ContentEditor.vue +│ │ │ ├── MediaPicker.vue +│ │ │ └── FormBuilder.vue +│ │ ├── stores/ +│ │ │ ├── auth.js # Auth state +│ │ │ ├── content.js # Content state +│ │ │ ├── media.js # Media state +│ │ │ └── ui.js # UI state +│ │ ├── router/ +│ │ │ ├── index.js # Router config +│ │ │ ├── public.js # Public routes +│ │ │ └── admin.js # Admin routes +│ │ ├── api/ +│ │ │ ├── client.js # Axios instance +│ │ │ ├── content.js # Content API +│ │ │ ├── auth.js # Auth API +│ │ │ └── media.js # Media API +│ │ ├── styles/ +│ │ │ ├── main.css +│ │ │ ├── variables.css +│ │ │ └── components/ +│ │ ├── utils/ +│ │ │ ├── validators.js +│ │ │ └── formatters.js │ │ └── main.js -│ └── forms/ -│ └── contact-handler.js -├── public/ -│ └── favicon.ico -├── tests/ -│ ├── e2e/ -│ │ ├── navigation.spec.js -│ │ ├── forms.spec.js -│ │ └── visual.spec.js -│ └── unit/ -├── Dockerfile -├── docker-compose.yml -├── nginx.conf -├── package.json +│ ├── public/ +│ │ └── favicon.ico +│ ├── tests/ +│ │ ├── e2e/ +│ │ └── unit/ +│ └── package.json +├── shared/ +│ ├── types/ # Shared TypeScript types +│ └── validators/ # Shared validators +├── database/ +│ └── landing.db # SQLite database file +├── docker/ +│ ├── Dockerfile.backend +│ ├── Dockerfile.frontend +│ └── docker-compose.yml +├── docs/ +│ ├── API.md # API documentation +│ ├── DEPLOYMENT.md # Deployment guide +│ └── ADMIN.md # Admin guide +├── scripts/ +│ ├── init-db.js # Database initialization +│ └── seed-content.js # Content seeding +├── .env.example +├── package.json # Root workspace └── README.md ``` -### Technology Stack +### Database Schema -| Layer | Technology | Purpose | -|-------|------------|---------| -| Markup | HTML5 | Semantic structure | -| Styling | CSS/Tailwind | Visual design | -| Scripts | Vanilla JS/Alpine.js | Interactivity | -| Build | Vite/esbuild | Optimization | -| Deploy | Docker + Nginx | Production server | -| Testing | Playwright | E2E tests | +```sql +-- Users (Admin) +CREATE TABLE users ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + email TEXT UNIQUE NOT NULL, + password_hash TEXT NOT NULL, + name TEXT NOT NULL, + role TEXT DEFAULT 'admin', + created_at DATETIME DEFAULT CURRENT_TIMESTAMP, + updated_at DATETIME DEFAULT CURRENT_TIMESTAMP +); -### Architecture Decisions +-- Pages +CREATE TABLE pages ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + slug TEXT UNIQUE NOT NULL, + title TEXT NOT NULL, + meta_description TEXT, + meta_keywords TEXT, + is_published BOOLEAN DEFAULT 1, + created_at DATETIME DEFAULT CURRENT_TIMESTAMP, + updated_at DATETIME DEFAULT CURRENT_TIMESTAMP +); + +-- Sections +CREATE TABLE sections ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + page_id INTEGER NOT NULL, + name TEXT NOT NULL, + type TEXT NOT NULL, -- 'hero', 'features', 'pricing', etc. + order_index INTEGER DEFAULT 0, + settings TEXT, -- JSON settings + FOREIGN KEY (page_id) REFERENCES pages(id) +); + +-- Content (Dynamic Content) +CREATE TABLE content ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + section_id INTEGER NOT NULL, + key TEXT NOT NULL, + value TEXT, + type TEXT DEFAULT 'text', -- 'text', 'html', 'image', 'json' + FOREIGN KEY (section_id) REFERENCES sections(id) +); + +-- Media +CREATE TABLE media ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + filename TEXT NOT NULL, + original_name TEXT NOT NULL, + mime_type TEXT NOT NULL, + size INTEGER NOT NULL, + path TEXT NOT NULL, + alt_text TEXT, + created_at DATETIME DEFAULT CURRENT_TIMESTAMP +); + +-- Form Submissions +CREATE TABLE form_submissions ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + form_type TEXT NOT NULL, -- 'contact', 'newsletter', 'lead' + data TEXT NOT NULL, -- JSON + ip_address TEXT, + user_agent TEXT, + created_at DATETIME DEFAULT CURRENT_TIMESTAMP +); + +-- Site Settings +CREATE TABLE settings ( + key TEXT PRIMARY KEY, + value TEXT, + type TEXT DEFAULT 'string' +); + +-- Sessions (for admin) +CREATE TABLE sessions ( + id TEXT PRIMARY KEY, + user_id INTEGER NOT NULL, + expires_at DATETIME NOT NULL, + created_at DATETIME DEFAULT CURRENT_TIMESTAMP, + FOREIGN KEY (user_id) REFERENCES users(id) +); + +-- Indexes +CREATE INDEX idx_pages_slug ON pages(slug); +CREATE INDEX idx_sections_page ON sections(page_id); +CREATE INDEX idx_content_section ON content(section_id); +CREATE INDEX idx_media_filename ON media(filename); +CREATE INDEX idx_forms_created ON form_submissions(created_at); +``` + +### API Endpoints + +```yaml +# Public API +GET /api/pages # List all published pages +GET /api/pages/:slug # Get page with content +GET /api/content/:page/:section # Get section content +POST /api/forms/contact # Submit contact form +POST /api/forms/newsletter # Subscribe to newsletter +POST /api/forms/lead # Submit lead form +GET /api/health # Health check + +# Admin API (requires authentication) +POST /api/admin/auth/login # Admin login +POST /api/admin/auth/logout # Admin logout +GET /api/admin/auth/me # Current user + +# Admin - Pages +GET /api/admin/pages # List all pages +POST /api/admin/pages # Create page +PUT /api/admin/pages/:id # Update page +DELETE /api/admin/pages/:id # Delete page + +# Admin - Content +GET /api/admin/content/:pageId # Get page content +PUT /api/admin/content/:pageId # Update page content + +# Admin - Media +GET /api/admin/media # List media +POST /api/admin/media/upload # Upload media +DELETE /api/admin/media/:id # Delete media + +# Admin - Forms +GET /api/admin/forms # List form submissions +GET /api/admin/forms/:type # Get submissions by type +DELETE /api/admin/forms/:id # Delete submission + +# Admin - Users +GET /api/admin/users # List users +POST /api/admin/users # Create user +PUT /api/admin/users/:id # Update user +DELETE /api/admin/users/:id # Delete user + +# Admin - Settings +GET /api/admin/settings # Get all settings +PUT /api/admin/settings # Update settings +``` + +### Architecture Decision Record ```markdown -## Architecture Decision Record +## ADR-001: Frontend Framework +- **Decision**: Vue.js 3 with Composition API +- **Reason**: + - Reactive data binding for content management + - Composition API for better TypeScript support + - Large ecosystem of UI libraries + - Easy learning curve -### ADR-001: CSS Framework -- **Decision**: Use {style} CSS framework -- **Reason**: Based on mockup complexity and maintenance needs -- **Alternatives**: Tailwind (utility-first), Bootstrap (component-based) +## ADR-002: Backend Framework +- **Decision**: Express.js with SQLite +- **Reason**: + - Lightweight, no external DB server required + - Perfect for low-traffic landing pages + - Easy backup (single file) + - Fast development time -### ADR-002: JavaScript -- **Decision**: Vanilla JS with optional Alpine.js -- **Reason**: Minimal interactivity needs, no heavy framework required -- **Bundle Size**: < 50KB gzipped +## ADR-003: Database +- **Decision**: SQLite with better-sqlite3 +- **Reason**: + - Zero configuration + - Single file deployment + - Full ACID compliance + - Great performance for read-heavy workloads + - Easy backup and migration -### ADR-003: Build Tool -- **Decision**: Vite for development and build -- **Reason**: Fast HMR, simple config, good for static sites +## ADR-004: State Management +- **Decision**: Pinia +- **Reason**: + - Official Vue 3 state management + - TypeScript support out of the box + - Devtools integration + - Simpler than Vuex -### ADR-004: Deployment -- **Decision**: Docker with Nginx -- **Reason**: Production-ready, scalable, easy deployment +## ADR-005: UI Framework +- **Decision**: {ui_framework} +- **Reason**: + - Pre-built admin components + - Accessible by default + - Mobile-responsive + - Active community + +## ADR-006: Authentication +- **Decision**: JWT with bcrypt +- **Reason**: + - Stateless authentication + - Works well with SPA + - Secure password hashing + - Simple implementation + +## ADR-007: Cross-Browser Support +- **Decision**: Support Chrome 90+, Firefox 88+, Safari 14+, Edge 90+ +- **Reason**: + - ES2020+ features supported + - CSS Grid and Flexbox stable + - Native form validation + - Fetch API with streaming ``` ### Post Architecture @@ -179,212 +473,979 @@ project_name/ ```python post_gitea_comment(issue_number, """## 📐 Architecture Complete -**Stack**: HTML5 + {style} + Vanilla JS -**Build**: Vite -**Deploy**: Docker + Nginx +### Stack +**Frontend**: Vue.js 3 + {ui_framework} + Pinia + Vite +**Backend**: Node.js 20 + Express + SQLite +**Auth**: JWT + bcrypt + +### Database Schema +- 7 tables designed +- Indexes optimized +- Foreign keys defined + +### API Endpoints +- 6 public endpoints +- 18 admin endpoints ### Project Structure ``` -{project_tree} +backend/ # Node.js API +frontend/ # Vue.js SPA +shared/ # Shared types +database/ # SQLite file +docker/ # Deployment +docs/ # Documentation ``` -**Next**: Component implementation +**Next**: Backend implementation """) ``` -## Step 3: Component Implementation +## Step 3: Backend Implementation + +**Agent**: `@LeadDeveloper` + +### Database Setup + +```javascript +// backend/src/db/connection.js +const Database = require('better-sqlite3'); +const path = require('path'); + +const dbPath = process.env.DB_PATH || path.join(__dirname, '../../database/landing.db'); +const db = new Database(dbPath); + +// Enable foreign keys +db.pragma('foreign_keys = ON'); + +// Initialize database +function initDatabase() { + const migrate = require('./migrate'); + migrate(db); +} + +module.exports = { db, initDatabase }; +``` + +```javascript +// backend/src/db/migrate.js +function migrate(db) { + // Create tables in order (respecting foreign keys) + const tables = [ + `CREATE TABLE IF NOT EXISTS users ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + email TEXT UNIQUE NOT NULL, + password_hash TEXT NOT NULL, + name TEXT NOT NULL, + role TEXT DEFAULT 'admin', + created_at DATETIME DEFAULT CURRENT_TIMESTAMP, + updated_at DATETIME DEFAULT CURRENT_TIMESTAMP + )`, + `CREATE TABLE IF NOT EXISTS pages ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + slug TEXT UNIQUE NOT NULL, + title TEXT NOT NULL, + meta_description TEXT, + meta_keywords TEXT, + is_published BOOLEAN DEFAULT 1, + created_at DATETIME DEFAULT CURRENT_TIMESTAMP, + updated_at DATETIME DEFAULT CURRENT_TIMESTAMP + )`, + // ... other tables + ]; + + tables.forEach(sql => db.exec(sql)); + + // Create indexes + const indexes = [ + 'CREATE INDEX IF NOT EXISTS idx_pages_slug ON pages(slug)', + 'CREATE INDEX IF NOT EXISTS idx_sections_page ON sections(page_id)', + // ... other indexes + ]; + + indexes.forEach(sql => db.exec(sql)); +} + +module.exports = migrate; +``` + +### Express App + +```javascript +// backend/src/app.js +const express = require('express'); +const cors = require('cors'); +const helmet = require('helmet'); +const rateLimit = require('express-rate-limit'); + +// Routes +const publicRoutes = require('./routes/api'); +const adminRoutes = require('./routes/admin'); + +// Middleware +const errorHandler = require('./middleware/errorHandler'); + +const app = express(); + +// Security middleware +app.use(helmet()); +app.use(cors({ + origin: process.env.FRONTEND_URL || 'http://localhost:5173', + credentials: true +})); + +// Rate limiting +app.use(rateLimit({ + windowMs: 15 * 60 * 1000, // 15 minutes + max: 100 // limit each IP to 100 requests per windowMs +})); + +// Body parsing +app.use(express.json()); +app.use(express.urlencoded({ extended: true })); + +// Static files (uploaded media) +app.use('/media', express.static(path.join(__dirname, '../uploads'))); + +// Routes +app.use('/api', publicRoutes); +app.use('/api/admin', adminRoutes); + +// Health check +app.get('/api/health', (req, res) => { + res.json({ status: 'ok', timestamp: new Date().toISOString() }); +}); + +// Error handling +app.use(errorHandler); + +module.exports = app; +``` + +### Content API + +```javascript +// backend/src/routes/api/content.js +const router = require('express').Router(); +const { db } = require('../../db/connection'); + +// Get page with all content +router.get('/pages/:slug', (req, res) => { + const { slug } = req.params; + + const page = db.prepare(` + SELECT p.*, + json_group_array( + json_object( + 'name', s.name, + 'type', s.type, + 'order', s.order_index, + 'settings', s.settings, + 'content', ( + SELECT json_group_array( + json_object('key', c.key, 'value', c.value, 'type', c.type) + ) + FROM content c WHERE c.section_id = s.id + ) + ) + ) as sections + FROM pages p + LEFT JOIN sections s ON s.page_id = p.id + WHERE p.slug = ? AND p.is_published = 1 + GROUP BY p.id + `).get(slug); + + if (!page) { + return res.status(404).json({ error: 'Page not found' }); + } + + res.json(page); +}); + +// Submit contact form +router.post('/forms/contact', (req, res) => { + const { name, email, phone, message } = req.body; + + // Validation + if (!name || !email || !message) { + return res.status(400).json({ error: 'Missing required fields' }); + } + + // Insert submission + const stmt = db.prepare(` + INSERT INTO form_submissions (form_type, data, ip_address, user_agent) + VALUES ('contact', ?, ?, ?) + `); + + stmt.run( + JSON.stringify({ name, email, phone, message }), + req.ip, + req.headers['user-agent'] + ); + + // TODO: Send email notification + + res.json({ success: true, message: 'Form submitted successfully' }); +}); + +module.exports = router; +``` + +### Admin Authentication + +```javascript +// backend/src/routes/admin/auth.js +const router = require('express').Router(); +const bcrypt = require('bcrypt'); +const jwt = require('jsonwebtoken'); +const { db } = require('../../db/connection'); + +const JWT_SECRET = process.env.JWT_SECRET || 'your-secret-key'; +const JWT_EXPIRES_IN = '24h'; + +// Login +router.post('/login', async (req, res) => { + const { email, password } = req.body; + + // Find user + const user = db.prepare('SELECT * FROM users WHERE email = ?').get(email); + + if (!user) { + return res.status(401).json({ error: 'Invalid credentials' }); + } + + // Verify password + const validPassword = await bcrypt.compare(password, user.password_hash); + + if (!validPassword) { + return res.status(401).json({ error: 'Invalid credentials' }); + } + + // Generate JWT + const token = jwt.sign( + { id: user.id, email: user.email, role: user.role }, + JWT_SECRET, + { expiresIn: JWT_EXPIRES_IN } + ); + + res.json({ + token, + user: { + id: user.id, + email: user.email, + name: user.name, + role: user.role + } + }); +}); + +// Logout +router.post('/logout', (req, res) => { + // JWT is stateless, just return success + res.json({ success: true }); +}); + +// Get current user +router.get('/me', require('../middleware/auth'), (req, res) => { + const user = db.prepare('SELECT id, email, name, role FROM users WHERE id = ?').get(req.user.id); + + if (!user) { + return res.status(404).json({ error: 'User not found' }); + } + + res.json(user); +}); + +module.exports = router; +``` + +### Admin Content Management + +```javascript +// backend/src/routes/admin/content.js +const router = require('express').Router(); +const { db } = require('../../db/connection'); +const auth = require('../../middleware/auth'); + +// Get page content for editing +router.get('/content/:pageId', auth, (req, res) => { + const { pageId } = req.params; + + const content = db.prepare(` + SELECT s.id as section_id, s.name, s.type, s.order_index, s.settings, + json_group_array( + json_object('id', c.id, 'key', c.key, 'value', c.value, 'type', c.type) + ) as items + FROM sections s + LEFT JOIN content c ON c.section_id = s.id + WHERE s.page_id = ? + GROUP BY s.id + ORDER BY s.order_index + `).all(pageId); + + res.json(content); +}); + +// Update content +router.put('/content/:pageId', auth, (req, res) => { + const { pageId } = req.params; + const { sections } = req.body; + + // Use transaction for atomic update + const updateContent = db.transaction(() => { + sections.forEach(section => { + section.items.forEach(item => { + db.prepare(` + UPDATE content SET value = ? WHERE id = ? + `).run(item.value, item.id); + }); + }); + + // Update page timestamp + db.prepare('UPDATE pages SET updated_at = CURRENT_TIMESTAMP WHERE id = ?').run(pageId); + }); + + updateContent(); + + res.json({ success: true, message: 'Content updated' }); +}); + +module.exports = router; +``` + +### Post Backend + +```python +post_gitea_comment(issue_number, """## ✅ Backend Complete + +### Files Created +- `backend/src/app.js` - Express application +- `backend/src/db/connection.js` - SQLite connection +- `backend/src/routes/api/*.js` - Public API (6 endpoints) +- `backend/src/routes/admin/*.js` - Admin API (18 endpoints) +- `backend/src/middleware/*.js` - Auth, validation, error handling + +### Features Implemented +- ✅ SQLite database with migrations +- ✅ JWT authentication +- ✅ Content CRUD API +- ✅ Media upload handling +- ✅ Form submission storage +- ✅ Rate limiting +- ✅ CORS configuration +- ✅ Error handling + +### Database +- 7 tables created +- Indexes optimized +- Foreign keys enabled + +**Next**: Frontend implementation +""") +``` + +## Step 4: Frontend Implementation **Agent**: `@FrontendDeveloper` -### Implementation Order +### Vue 3 Setup -1. **Base Structure** - - HTML5 boilerplate - - Meta tags and SEO - - Viewport and responsive base - - CSS reset/normalize +```javascript +// frontend/src/main.js +import { createApp } from 'vue'; +import { createPinia } from 'pinia'; +import router from './router'; +import App from './App.vue'; -2. **Layout Components** - - Header (logo, nav, CTA) - - Footer (links, social, copyright) - - Sidebar (if applicable) +// UI Framework +import { createVuetify } from 'vuetify'; +import 'vuetify/styles'; -3. **Section Components** - - Hero section - - Features section - - Pricing section - - Testimonials section - - Contact form - - Call-to-action banners +const vuetify = createVuetify({ + theme: { + defaultTheme: 'light', + themes: { + light: { + colors: { + primary: '#1976D2', + secondary: '#424242', + accent: '#82B1FF', + error: '#FF5252', + info: '#2196F3', + success: '#4CAF50', + warning: '#FFC107' + } + } + } + } +}); -4. **Interactive Components** - - Mobile menu toggle - - Form validation - - Scroll animations - - Modal windows +const app = createApp(App); +app.use(createPinia()); +app.use(router); +app.use(vuetify); +app.mount('#app'); +``` -### Component Template +### Public Pages -```html - -
-
-

{title}

-

{subtitle}

-
- {cta_primary} - {cta_secondary} -
+```vue + + - + ``` -### Responsive Implementation +### Content Store + +```javascript +// frontend/src/stores/content.js +import { defineStore } from 'pinia'; +import { contentApi } from '@/api/content'; + +export const useContentStore = defineStore('content', { + state: () => ({ + pages: {}, + loading: false, + error: null + }), + + actions: { + async fetchPage(slug) { + if (this.pages[slug]) { + return this.pages[slug]; + } + + this.loading = true; + try { + const response = await contentApi.getPage(slug); + this.pages[slug] = this.parseContent(response.data); + return this.pages[slug]; + } catch (error) { + this.error = error.message; + throw error; + } finally { + this.loading = false; + } + }, + + parseContent(pageData) { + const content = {}; + pageData.sections?.forEach(section => { + const sectionContent = {}; + section.content?.forEach(item => { + sectionContent[item.key] = item.value; + }); + content[section.name] = { + ...sectionContent, + settings: section.settings + }; + }); + return content; + } + } +}); +``` + +### Admin Panel - Dashboard + +```vue + + + + +``` + +### Admin - Content Editor + +```vue + + + + +``` + +### Responsive Design ```css +/* frontend/src/styles/responsive.css */ + /* Mobile First Approach */ -/* Base: Mobile */ -.hero { - padding: 2rem 1rem; +/* Base: Mobile (< 640px) */ +.container { + padding: 1rem; } .hero-title { font-size: 1.5rem; } -/* Tablet: 768px+ */ -@media (min-width: 768px) { - .hero { - padding: 4rem 2rem; +.grid-cards { + display: grid; + grid-template-columns: 1fr; + gap: 1rem; +} + +/* Small tablets (640px+) */ +@media (min-width: 640px) { + .container { + padding: 1.5rem; } - + + .hero-title { + font-size: 2rem; + } + + .grid-cards { + grid-template-columns: repeat(2, 1fr); + } +} + +/* Tablets (768px+) */ +@media (min-width: 768px) { + .container { + padding: 2rem; + } + .hero-title { font-size: 2.5rem; } + + .grid-cards { + grid-template-columns: repeat(3, 1fr); + } } -/* Desktop: 1024px+ */ +/* Desktops (1024px+) */ @media (min-width: 1024px) { - .hero { - padding: 6rem 4rem; + .container { + padding: 3rem; } - + .hero-title { - font-size: 3.5rem; + font-size: 3rem; + } + + .grid-cards { + grid-template-columns: repeat(4, 1fr); + } +} + +/* Large Desktops (1280px+) */ +@media (min-width: 1280px) { + .container { + max-width: 1280px; + margin: 0 auto; + } +} + +/* Touch Targets (min 44x44px) */ +.btn, .link, .nav-item { + min-width: 44px; + min-height: 44px; +} + +/* Mobile Navigation */ +@media (max-width: 768px) { + .nav-desktop { + display: none; + } + + .nav-mobile { + display: block; } } ``` -### Accessibility Checklist +### Cross-Browser CSS -- [ ] Semantic HTML5 elements -- [ ] ARIA labels for interactive elements -- [ ] Focus states for keyboard navigation -- [ ] Color contrast ≥ 4.5:1 -- [ ] Alt text for all images -- [ ] Skip navigation link -- [ ] Form labels associated with inputs -- [ ] Form validation messages visible -- [ ] Mobile touch targets ≥ 44x44px +```css +/* frontend/src/styles/cross-browser.css */ -### Post Implementation +/* Flexbox Gap (not supported in older browsers) */ +.flex-container { + display: flex; + gap: 1rem; +} + +/* Fallback for browsers without gap support */ +@supports not (gap: 1rem) { + .flex-container > * { + margin: 0.5rem; + } +} + +/* CSS Grid */ +.grid-container { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); +} + +/* Fallback */ +@supports not (grid-template-columns: repeat(auto-fit, minmax(300px, 1fr))) { + .grid-container { + display: flex; + flex-wrap: wrap; + } + .grid-container > * { + width: calc(50% - 1rem); + margin: 0.5rem; + } +} + +/* Aspect Ratio */ +.video-container { + aspect-ratio: 16 / 9; +} + +/* Fallback */ +@supports not (aspect-ratio: 16 / 9) { + .video-container { + position: relative; + padding-bottom: 56.25%; /* 16:9 */ + height: 0; + overflow: hidden; + } + .video-container iframe { + position: absolute; + top: 0; + left: 0; + width: 100%; + height: 100%; + } +} + +/* Object Fit */ +.object-cover { + object-fit: cover; + width: 100%; + height: 100%; +} + +/* Fallback for IE */ +@media all and (-ms-high-contrast: none), (-ms-high-contrast: active) { + .object-cover { + background-size: cover; + background-position: center; + } +} + +/* Smooth scroll */ +html { + scroll-behavior: smooth; +} + +/* Fallback */ +@supports not (scroll-behavior: smooth) { + html { + scroll-behavior: auto; + } +} +``` + +### Post Frontend ```python -post_gitea_comment(issue_number, """## 🎨 Components Implemented +post_gitea_comment(issue_number, """## ✅ Frontend Complete -**Files Created**: {file_count} -**Components**: {components_list} +### Files Created +- `frontend/src/views/public/*.vue` - Public pages (Home, About, Contact) +- `frontend/src/views/admin/*.vue` - Admin panel (Dashboard, Content, Media, Users) +- `frontend/src/components/public/*.vue` - Public components (Hero, Features, Pricing) +- `frontend/src/components/admin/*.vue` - Admin components (Sidebar, ContentEditor, MediaPicker) +- `frontend/src/stores/*.js` - Pinia stores (auth, content, media, ui) +- `frontend/src/router/*.js` - Vue Router config -### Implementation Details -- ✅ Semantic HTML5 -- ✅ {style} CSS framework -- ✅ Responsive breakpoints: mobile, tablet, desktop -- ✅ Accessibility: ARIA labels, focus states +### Features Implemented +- ✅ Vue 3 Composition API +- ✅ {ui_framework} UI components +- ✅ Pinia state management +- ✅ Vue Router with guards +- ✅ JWT authentication +- ✅ Responsive design (mobile-first) +- ✅ Cross-browser support +- ✅ Admin content editor +- ✅ Media library +- ✅ Form submission viewer -### Files -{file_list} +### Responsive Breakpoints +- Mobile: < 640px +- Tablet: 640px - 1023px +- Desktop: ≥ 1024px -**Next**: Testing +**Next**: E2E Testing """) ``` -## Step 4: E2E Testing +## Step 5: E2E Testing **Agent**: `@SDETEngineer` → `@browser-automation` -### Test Strategy - -Create comprehensive tests for: - -| Test Type | Purpose | Priority | -|-----------|---------|----------| -| Smoke | Basic functionality | High | -| Navigation | Menu links work | High | -| Responsive | Breakpoints correct | Medium | -| Forms | Validation and submission | High | -| Visual | Pixel-perfect match | Medium | -| Accessibility | WCAG compliance | High | - -### Test File Structure +### Test Suite ```javascript -// tests/e2e/navigation.spec.js +// tests/e2e/public.spec.js import { test, expect } from '@playwright/test'; -test.describe('Landing Page Navigation', () => { - test.beforeEach(async ({ page }) => { - await page.goto('/'); - }); - - test('header logo visible', async ({ page }) => { - const logo = page.locator('.header-logo'); - await expect(logo).toBeVisible(); - }); - - test('navigation links work', async ({ page }) => { - const navLinks = page.locator('.nav-link'); - const count = await navLinks.count(); - - for (let i = 0; i < count; i++) { - const link = navLinks.nth(i); - const href = await link.getAttribute('href'); - if (href && href.startsWith('#')) { - await link.click(); - await expect(page.locator(href)).toBeInViewport(); - } - } - }); - - test('mobile menu toggle', async ({ page }) => { - await page.setViewportSize({ width: 375, height: 667 }); - const menuButton = page.locator('.mobile-menu-toggle'); - await menuButton.click(); - await expect(page.locator('.mobile-menu')).toBeVisible(); - }); -}); -``` - -### Visual Regression Tests - -```javascript -// tests/e2e/visual.spec.js -import { test, expect } from '@playwright/test'; - -test.describe('Visual Regression', () => { +test.describe('Public Landing Page', () => { const viewports = [ { name: 'mobile', width: 375, height: 667 }, { name: 'tablet', width: 768, height: 1024 }, @@ -392,50 +1453,196 @@ test.describe('Visual Regression', () => { ]; for (const viewport of viewports) { - test(`matches mockup at ${viewport.name}`, async ({ page }) => { - await page.setViewportSize(viewport); - await page.goto('/'); - await page.waitForLoadState('networkidle'); - - await expect(page).toHaveScreenshot( - `homepage-${viewport.name}.png`, - { maxDiffPixels: 100 } - ); + test.describe(`at ${viewport.name}`, () => { + test.use({ viewport: { width: viewport.width, height: viewport.height } }); + + test('hero section displays correctly', async ({ page }) => { + await page.goto('/'); + + // Hero visible + await expect(page.locator('.hero')).toBeVisible(); + + // Title present + const title = page.locator('.hero-title'); + await expect(title).toBeVisible(); + expect(await title.textContent()).toBeTruthy(); + + // CTA button exists and works + const cta = page.locator('.hero-cta-primary'); + await expect(cta).toBeVisible(); + await cta.click(); + }); + + test('navigation works on all viewports', async ({ page }) => { + await page.goto('/'); + + if (viewport.name === 'mobile') { + // Mobile: open hamburger menu + await page.click('.mobile-menu-toggle'); + await expect(page.locator('.mobile-menu')).toBeVisible(); + } else { + // Desktop: check nav links + const navLinks = page.locator('.nav-link'); + const count = await navLinks.count(); + expect(count).toBeGreaterThan(0); + } + }); + + test('contact form submission', async ({ page }) => { + await page.goto('/contact'); + + // Fill form + await page.fill('input[name="name"]', 'Test User'); + await page.fill('input[name="email"]', 'test@example.com'); + await page.fill('textarea[name="message"]', 'Test message'); + + // Submit + await page.click('button[type="submit"]'); + + // Check success + await expect(page.locator('.success-message')).toBeVisible(); + }); }); } + + test('visual regression test', async ({ page }) => { + await page.goto('/'); + await page.waitForLoadState('networkidle'); + + await expect(page).toHaveScreenshot('landing-home.png', { + maxDiffPixels: 100 + }); + }); + + test('accessibility audit', async ({ page }) => { + await page.goto('/'); + + const accessibilityScanResults = await new AxeBuilder({ page }).analyze(); + expect(accessibilityScanResults.violations).toEqual([]); + }); }); ``` -### Form Validation Tests - ```javascript -// tests/e2e/forms.spec.js +// tests/e2e/admin.spec.js import { test, expect } from '@playwright/test'; -test.describe('Contact Form', () => { - test('validates required fields', async ({ page }) => { - await page.goto('/'); +test.describe('Admin Panel', () => { + test.beforeEach(async ({ page }) => { + // Login + await page.goto('/admin/login'); + await page.fill('input[name="email"]', 'admin@example.com'); + await page.fill('input[name="password"]', 'password123'); await page.click('button[type="submit"]'); - await expect(page.locator('.error-message')).toBeVisible(); + // Wait for dashboard + await expect(page).toHaveURL('/admin/dashboard'); }); - test('validates email format', async ({ page }) => { - await page.goto('/'); - await page.fill('input[name="email"]', 'invalid-email'); - await page.click('button[type="submit"]'); - - await expect(page.locator('.email-error')).toBeVisible(); + test('dashboard loads correctly', async ({ page }) => { + await expect(page.locator('h1')).toContainText('Dashboard'); + await expect(page.locator('.stats-card')).toHaveCount(4); }); - test('submits valid form', async ({ page }) => { + test('content editor saves changes', async ({ page }) => { + // Navigate to content editor + await page.click('text=Pages'); + await page.click('text=Home'); + + // Edit hero section + await page.fill('input[name="hero.title"]', 'New Hero Title'); + + // Save + await page.click('text=Save Changes'); + + // Check notification + await expect(page.locator('.notification')).toContainText('saved'); + }); + + test('media upload', async ({ page }) => { + await page.click('text=Media'); + + // Upload file + const fileInput = page.locator('input[type="file"]'); + await fileInput.setInputFiles('./tests/fixtures/test-image.png'); + + // Wait for upload + await expect(page.locator('.media-item')).toBeVisible(); + }); + + test('form submissions list', async ({ page }) => { + await page.click('text=Forms'); + + await expect(page.locator('table')).toBeVisible(); + await expect(page.locator('tr')).toHaveCountGreaterThanOrEqual(1); + }); +}); +``` + +```javascript +// tests/e2e/cross-browser.spec.js +import { test, expect } from '@playwright/test'; + +test.describe('Cross-browser compatibility', () => { + test('CSS Grid works', async ({ page }) => { await page.goto('/'); - await page.fill('input[name="name"]', 'Test User'); - await page.fill('input[name="email"]', 'test@example.com'); - await page.fill('textarea[name="message"]', 'Test message'); + + // Check grid layout + const grid = page.locator('.features-grid'); + const display = await grid.evaluate(el => + window.getComputedStyle(el).display + ); + + expect(['grid', 'flex']).toContain(display); + }); + + test('Flexbox gap support', async ({ page }) => { + await page.goto('/'); + + const flex = page.locator('.hero-cta'); + const hasGap = await flex.evaluate(el => { + const style = window.getComputedStyle(el); + return style.gap !== 'normal' && style.gap !== ''; + }); + + // Either gap works or fallback margins exist + expect(hasGap || true).toBeTruthy(); + }); + + test('Form validation', async ({ page }) => { + await page.goto('/contact'); + + // Submit empty form await page.click('button[type="submit"]'); - await expect(page.locator('.success-message')).toBeVisible(); + // Check validation errors + const errors = page.locator('.error-message'); + await expect(errors.first()).toBeVisible(); + }); + + test('JavaScript functionality', async ({ page }) => { + await page.goto('/'); + + // Mobile menu toggle + await page.setViewportSize({ width: 375, height: 667 }); + await page.click('.mobile-menu-toggle'); + await expect(page.locator('.mobile-menu')).toBeVisible(); + }); + + test('Responsive images', async ({ page }) => { + await page.goto('/'); + + const images = page.locator('img'); + const count = await images.count(); + + for (let i = 0; i < count; i++) { + const img = images.nth(i); + // Check srcset or loading="lazy" + const hasSrcset = await img.getAttribute('srcset'); + const hasLazy = await img.getAttribute('loading'); + + expect(hasSrcset || hasLazy === 'lazy' || true).toBeTruthy(); + } }); }); ``` @@ -449,14 +1656,16 @@ npm install -D @playwright/test # Run all tests npx playwright test -# Run specific test -npx playwright test navigation.spec.js +# Run specific browsers +npx playwright test --project=chromium +npx playwright test --project=firefox +npx playwright test --project=webkit # Run with visible browser npx playwright test --headed -# Generate test report -npx playwright show-report +# Generate coverage report +npx playwright test --reporter=html ``` ### Post Testing @@ -464,44 +1673,91 @@ npx playwright show-report ```python post_gitea_comment(issue_number, """## ✅ Tests Complete -**Test Suite**: Playwright E2E -**Tests Run**: {test_count} -**Tests Passed**: {pass_count} -**Tests Failed**: {fail_count} +### Test Suite +**Framework**: Playwright +**Browsers Tested**: Chrome, Firefox, Safari, Mobile Safari, Mobile Chrome + +### Test Results +| Suite | Tests | Passed | Failed | +|-------|-------|--------|--------| +| Public Pages | 12 | 12 | 0 | +| Admin Panel | 8 | 8 | 0 | +| Cross-browser | 6 | 6 | 0 | +| Visual Regression | 4 | 4 | 0 | +| Accessibility | 4 | 4 | 0 | ### Coverage -- ✅ Navigation: {nav_tests} passed -- ✅ Forms: {form_tests} passed -- ✅ Responsive: {resp_tests} passed -- ✅ Visual: {visual_tests} passed -- ✅ Accessibility: {a11y_tests} passed - -### Visual Regression -- Baseline screenshots created -- Diff threshold: 0.1% +- ✅ Responsive: All viewports tested +- ✅ Forms: Validation and submission +- ✅ Navigation: Desktop and mobile +- ✅ Admin: Content editing, media upload +- ✅ Accessibility: WCAG 2.1 AA +- ✅ Visual: Screenshots match baseline **Next**: Docker deployment """) ``` -## Step 5: Docker Deployment +## Step 6: Docker Deployment **Agent**: `@LeadDeveloper` -### Dockerfile +### Dockerfile - Backend ```dockerfile -# Dockerfile +# docker/Dockerfile.backend FROM node:20-alpine AS builder WORKDIR /app # Copy package files -COPY package*.json ./ +COPY backend/package*.json ./ RUN npm ci --only=production -# Copy source files -COPY . . +# Copy source +COPY backend/src ./src +COPY backend/package.json ./ + +# Production image +FROM node:20-alpine + +WORKDIR /app + +# Copy dependencies and source +COPY --from=builder /app/node_modules ./node_modules +COPY --from=builder /app/src ./src +COPY --from=builder /app/package.json ./ + +# Create directories +RUN mkdir -p /app/uploads /app/database + +# Environment +ENV NODE_ENV=production +ENV PORT=3000 + +# Health check +HEALTHCHECK --interval=30s --timeout=3s --start-period=5s \ + CMD wget --no-verbose --tries=1 --spider http://localhost:3000/api/health || exit 1 + +EXPOSE 3000 + +CMD ["node", "src/index.js"] +``` + +### Dockerfile - Frontend + +```dockerfile +# docker/Dockerfile.frontend +FROM node:20-alpine AS builder + +WORKDIR /app + +# Copy package files +COPY frontend/package*.json ./ +RUN npm ci + +# Copy source +COPY frontend/ ./ # Build RUN npm run build @@ -513,7 +1769,7 @@ FROM nginx:alpine COPY --from=builder /app/dist /usr/share/nginx/html # Copy nginx config -COPY nginx.conf /etc/nginx/nginx.conf +COPY docker/nginx.conf /etc/nginx/nginx.conf # Expose port EXPOSE 80 @@ -522,14 +1778,13 @@ EXPOSE 80 HEALTHCHECK --interval=30s --timeout=3s \ CMD wget --no-verbose --tries=1 --spider http://localhost/ || exit 1 -# Start nginx CMD ["nginx", "-g", "daemon off;"] ``` ### Nginx Configuration ```nginx -# nginx.conf +# docker/nginx.conf worker_processes auto; error_log /var/log/nginx/error.log warn; pid /var/run/nginx.pid; @@ -553,7 +1808,12 @@ http { tcp_nodelay on; keepalive_timeout 65; gzip on; - gzip_types text/plain text/css application/json application/javascript text/xml; + gzip_types text/plain text/css application/json application/javascript text/xml application/xml; + + # Upstream to backend API + upstream backend { + server backend:3000; + } server { listen 80; @@ -563,17 +1823,33 @@ http { add_header X-Frame-Options "SAMEORIGIN" always; add_header X-Content-Type-Options "nosniff" always; add_header X-XSS-Protection "1; mode=block" always; + add_header Referrer-Policy "strict-origin-when-cross-origin" always; root /usr/share/nginx/html; index index.html; - # SPA fallback - location / { - try_files $uri $uri/ /index.html; + # API proxy + location /api { + proxy_pass http://backend; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection 'upgrade'; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_cache_bypass $http_upgrade; } - # Cache static assets - location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ { + # Media files proxy + location /media { + proxy_pass http://backend; + proxy_http_version 1.1; + proxy_set_header Host $host; + } + + # Static files cache + location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ { expires 1y; add_header Cache-Control "public, immutable"; } @@ -583,6 +1859,11 @@ http { expires -1; add_header Cache-Control "no-cache, no-store, must-revalidate"; } + + # SPA fallback + location / { + try_files $uri $uri/ /index.html; + } } } ``` @@ -594,295 +1875,698 @@ http { version: '3.8' services: - landing: + frontend: build: context: . - dockerfile: Dockerfile + dockerfile: docker/Dockerfile.frontend ports: - - "8080:80" - environment: - - NODE_ENV=production - restart: unless-stopped + - "80:80" + depends_on: + - backend + networks: + - landing-network healthcheck: test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost/"] interval: 30s timeout: 3s retries: 3 + + backend: + build: + context: . + dockerfile: docker/Dockerfile.backend + ports: + - "3000:3000" + environment: + - NODE_ENV=production + - JWT_SECRET=${JWT_SECRET:-change-me-in-production} + - FRONTEND_URL=${FRONTEND_URL:-http://localhost} + volumes: + - ./database:/app/database + - ./uploads:/app/uploads + networks: + - landing-network + healthcheck: + test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:3000/api/health"] + interval: 30s + timeout: 3s + retries: 3 + +networks: + landing-network: + driver: bridge + +volumes: + database: + uploads: +``` + +### Environment Configuration + +```bash +# .env.example +# Backend +NODE_ENV=production +PORT=3000 +JWT_SECRET=your-super-secret-jwt-key-change-in-production +JWT_EXPIRES_IN=24h + +# Frontend +FRONTEND_URL=http://localhost +VITE_API_URL=http://localhost/api + +# Database +DB_PATH=./database/landing.db + +# Email (optional) +SMTP_HOST=smtp.example.com +SMTP_PORT=587 +SMTP_USER=user@example.com +SMTP_PASS=password + +# Admin +ADMIN_EMAIL=admin@example.com +ADMIN_PASSWORD=change-me-after-first-login ``` ### Build and Run ```bash -# Build Docker image -docker build -t {project_name}:latest . +# Build all containers +docker-compose build -# Run container -docker run -d -p 8080:80 --name {project_name} {project_name}:latest - -# Or with docker-compose +# Start services docker-compose up -d -# Check logs -docker logs {project_name} +# Check status +docker-compose ps -# Health check -curl http://localhost:8080/ +# View logs +docker-compose logs -f + +# Initialize database +docker-compose exec backend npm run init-db + +# Create admin user +docker-compose exec backend npm run create-admin + +# Stop services +docker-compose down + +# Clean restart +docker-compose down -v +docker-compose up -d --build ``` ### Post Docker ```python -post_gitea_comment(issue_number, """## 🐳 Docker Ready +post_gitea_comment(issue_number, """## 🐳 Docker Complete -**Image**: {project_name}:latest -**Size**: {image_size}MB -**Port**: 8080 +### Containers +- **frontend**: Nginx + Vue.js SPA (port 80) +- **backend**: Node.js API (port 3000) -### Build Commands +### Images +- `{project_name}-frontend:latest` - Vue.js production build +- `{project_name}-backend:latest` - Node.js API server + +### Volumes +- `./database` - SQLite database +- `./uploads` - Uploaded media files + +### Commands ```bash -docker build -t {project_name}:latest . -docker run -d -p 8080:80 {project_name}:latest +# Start +docker-compose up -d + +# Initialize +docker-compose exec backend npm run init-db +docker-compose exec backend npm run create-admin + +# Health check +curl http://localhost/api/health ``` -### Health Check -```bash -curl http://localhost:8080/ -``` +### URLs +- Frontend: http://localhost +- Admin: http://localhost/admin +- API: http://localhost/api **Next**: Documentation """) ``` -## Step 6: Documentation +## Step 7: Documentation **Agent**: `@SystemAnalyst` ### README.md ```markdown -# {Project Name} - Landing Page +# {Project Name} - Landing Page CMS -Fully functional, tested, and Dockerized landing page. +Full-stack landing page CMS with Node.js backend, Vue.js frontend, SQLite database, and admin panel. + +## Features + +- ✅ Vue.js 3 with Composition API +- ✅ {ui_framework} UI components +- ✅ Node.js Express backend +- ✅ SQLite database (zero-config) +- ✅ JWT authentication +- ✅ Admin content management +- ✅ Media library +- ✅ Form submissions +- ✅ Responsive design (mobile-first) +- ✅ Cross-browser support +- ✅ Docker deployment +- ✅ E2E tested ## Quick Start +### Prerequisites + +- Node.js 20.x LTS +- Docker and Docker Compose +- npm or yarn + ### Development ```bash +# Install dependencies npm install -npm run dev -``` -Open http://localhost:5173 +# Start backend +cd backend && npm run dev + +# Start frontend (new terminal) +cd frontend && npm run dev + +# Open http://localhost:5173 +``` ### Production ```bash -npm run build -npm run preview -``` - -### Docker - -```bash +# Build and start docker-compose up -d -``` -Open http://localhost:8080 +# Initialize database +docker-compose exec backend npm run init-db + +# Create admin user +docker-compose exec backend npm run create-admin + +# Open http://localhost +``` ## Project Structure ``` {project_name}/ -├── src/ # Source files -│ ├── index.html # Main page -│ ├── pages/ # Additional pages -│ ├── components/ # Reusable components -│ ├── styles/ # CSS styles -│ └── scripts/ # JavaScript -├── tests/ # E2E tests -├── Dockerfile # Docker build -├── nginx.conf # Nginx config -└── docker-compose.yml +├── backend/ # Node.js API +│ ├── src/ +│ │ ├── routes/ # API routes +│ │ ├── models/ # Data models +│ │ ├── middleware/ # Auth, validation +│ │ └── services/ # Business logic +│ └── tests/ +├── frontend/ # Vue.js SPA +│ ├── src/ +│ │ ├── views/ # Page components +│ │ ├── components/ # Reusable components +│ │ ├── stores/ # Pinia stores +│ │ └── router/ # Vue Router +│ └── tests/ +├── shared/ # Shared types +├── database/ # SQLite files +├── docker/ # Docker configs +└── docs/ # Documentation ``` -## Features +## Admin Panel -- ✅ Semantic HTML5 -- ✅ {style} CSS framework -- ✅ Responsive design (mobile-first) -- ✅ Accessibility (WCAG 2.1 AA) -- ✅ E2E testing with Playwright -- ✅ Docker deployment -- ✅ Nginx configuration optimized +Access the admin panel at `/admin`. + +Default credentials (change after first login): +- Email: `admin@example.com` +- Password: `admin123` + +### Features + +- Dashboard with stats +- Page management +- Content editor +- Media library +- Form submissions +- User management +- Site settings + +## API Documentation + +See [docs/API.md](docs/API.md) for full API documentation. + +### Quick Reference + +| Endpoint | Method | Description | +|----------|--------|-------------| +| `/api/pages/:slug` | GET | Get page content | +| `/api/forms/contact` | POST | Submit contact form | +| `/api/admin/auth/login` | POST | Admin login | +| `/api/admin/content/:pageId` | PUT | Update content | + +## Browser Support + +| Browser | Version | +|---------|---------| +| Chrome | 90+ | +| Firefox | 88+ | +| Safari | 14+ | +| Edge | 90+ | +| Mobile Safari | 14+ | +| Chrome Mobile | 90+ | ## Testing ```bash -npm run test # Run tests -npm run test:ui # UI mode -npm run test:report # View report +# Run all tests +npm run test + +# Run E2E tests +npx playwright test + +# Run with UI +npx playwright test --ui + +# Generate coverage +npm run test:coverage ``` -## Customization - -### Colors -Edit `src/styles/variables.css`: -```css -:root { - --primary: #your-color; - --secondary: #your-color; -} -``` - -### Content -Edit HTML files in `src/` directory. - -### Forms -Configure form handler in `src/scripts/forms.js`. - ## Deployment -### Docker Hub -```bash -docker tag {project_name} your-registry/{project_name} -docker push your-registry/{project_name} -``` - -### Static Hosting -```bash -npm run build -# Upload dist/ to any static host -``` +See [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) for deployment options. ## License MIT License ``` -### Technical Documentation - -Create `docs/TECHNICAL.md`: +### API Documentation ```markdown -# Technical Documentation +# docs/API.md -## Architecture +# API Documentation -### Technology Stack +## Base URL -| Component | Technology | Version | -|-----------|------------|---------| -| Markup | HTML5 | - | -| Styling | {style} | {version} | -| Scripts | Vanilla JS | ES6+ | -| Build | Vite | 5.x | -| Server | Nginx | 1.24 | -| Container | Docker | 24.x | +``` +Development: http://localhost:3000/api +Production: http://your-domain.com/api +``` -### Component Structure +## Authentication -[Component diagram] +Admin endpoints require JWT authentication. -### Data Flow +```http +Authorization: Bearer +``` -[Data flow diagram] +--- -### Responsive Breakpoints +## Public Endpoints -| Breakpoint | Width | Target | -|------------|-------|--------| -| xs | <640px | Mobile | -| sm | ≥640px | Large mobile | -| md | ≥768px | Tablet | -| lg | ≥1024px | Desktop | -| xl | ≥1280px | Large desktop | +### Get Page Content -## Security +```http +GET /api/pages/:slug +``` -### Headers -- X-Frame-Options: SAMEORIGIN -- X-Content-Type-Options: nosniff -- X-XSS-Protection: 1; mode=block +**Response:** +```json +{ + "id": 1, + "slug": "home", + "title": "Home", + "sections": [ + { + "name": "hero", + "type": "section", + "content": [ + { "key": "title", "value": "Welcome", "type": "text" }, + { "key": "subtitle", "value": "Our landing page", "type": "text" } + ] + } + ] +} +``` -### Form Handling -- Client-side validation -- CSRF protection (if backend) -- Input sanitization +### Submit Contact Form -## Performance +```http +POST /api/forms/contact +Content-Type: application/json -### Optimization -- Minified CSS/JS -- Image optimization -- Lazy loading -- Gzip compression +{ + "name": "John Doe", + "email": "john@example.com", + "phone": "+1234567890", + "message": "Hello!" +} +``` -### Metrics Target -- First Contentful Paint < 1.5s -- Largest Contentful Paint < 2.5s -- Cumulative Layout Shift < 0.1 -- Total Blocking Time < 200ms +**Response:** +```json +{ + "success": true, + "message": "Form submitted successfully" +} +``` + +--- + +## Admin Endpoints + +### Login + +```http +POST /api/admin/auth/login +Content-Type: application/json + +{ + "email": "admin@example.com", + "password": "password123" +} +``` + +**Response:** +```json +{ + "token": "eyJhbGciOiJIUzI1NiIs...", + "user": { + "id": 1, + "email": "admin@example.com", + "name": "Admin", + "role": "admin" + } +} +``` + +### Get All Pages + +```http +GET /api/admin/pages +Authorization: Bearer +``` + +**Response:** +```json +[ + { + "id": 1, + "slug": "home", + "title": "Home", + "is_published": true, + "created_at": "2024-01-01T00:00:00Z", + "updated_at": "2024-01-01T00:00:00Z" + } +] +``` + +### Update Content + +```http +PUT /api/admin/content/:pageId +Authorization: Bearer +Content-Type: application/json + +{ + "sections": [ + { + "id": 1, + "items": [ + { "id": 1, "value": "New Title" }, + { "id": 2, "value": "New Subtitle" } + ] + } + ] +} +``` + +**Response:** +```json +{ + "success": true, + "message": "Content updated" +} +``` + +### Upload Media + +```http +POST /api/admin/media/upload +Authorization: Bearer +Content-Type: multipart/form-data + +file: +``` + +**Response:** +```json +{ + "id": 1, + "filename": "abc123.png", + "original_name": "image.png", + "path": "/media/abc123.png", + "size": 102400, + "mime_type": "image/png" +} +``` + +--- + +## Error Responses + +```json +{ + "error": "Error message", + "code": "ERROR_CODE" +} +``` + +### Common Error Codes + +| Code | Description | +|------|-------------| +| `UNAUTHORIZED` | Missing or invalid token | +| `FORBIDDEN` | Insufficient permissions | +| `NOT_FOUND` | Resource not found | +| `VALIDATION_ERROR` | Invalid request data | +| `SERVER_ERROR` | Internal server error | ``` ### Deployment Guide -Create `docs/DEPLOYMENT.md`: - ```markdown +# docs/DEPLOYMENT.md + # Deployment Guide -## Prerequisites +## Option 1: Docker (Recommended) + +### Prerequisites - Docker 24.x -- Docker Compose (optional) +- Docker Compose - 512MB RAM minimum - 1GB disk space -## Option 1: Docker +### Steps ```bash +# 1. Clone repository +git clone +cd + +# 2. Create environment file +cp .env.example .env +nano .env # Edit configuration + +# 3. Build and start docker-compose up -d + +# 4. Initialize database +docker-compose exec backend npm run init-db + +# 5. Create admin user +docker-compose exec backend npm run create-admin + +# 6. Verify +curl http://localhost/api/health ``` -## Option 2: Static Hosting +### SSL Configuration -1. Build: `npm run build` -2. Upload `dist/` folder -3. Configure server for SPA routing +Create `nginx/ssl.conf`: -## Option 3: CDN +```nginx +server { + listen 443 ssl; + server_name your-domain.com; + + ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem; + ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem; + + # ... rest of configuration +} -1. Build: `npm run build` -2. Upload to CDN -3. Configure cache headers +server { + listen 80; + server_name your-domain.com; + return 301 https://$server_name$request_uri; +} +``` + +--- + +## Option 2: VPS/Manual + +### Prerequisites + +- Ubuntu 22.04+ +- Node.js 20.x +- Nginx +- PM2 (process manager) + +### Steps + +```bash +# 1. Install dependencies +curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - +sudo apt-get install -y nodejs nginx + +# 2. Clone and install +git clone +cd +npm install + +# 3. Build frontend +cd frontend && npm run build + +# 4. Configure environment +cp .env.example .env +nano .env + +# 5. Initialize database +npm run init-db + +# 6. Start backend with PM2 +sudo npm install -g pm2 +pm2 start backend/src/index.js --name backend +pm2 save +pm2 startup + +# 7. Configure Nginx +sudo nano /etc/nginx/sites-available/landing +``` + +### Nginx Config for VPS + +```nginx +server { + listen 80; + server_name your-domain.com; + + root /var/www/landing/frontend/dist; + index index.html; + + location /api { + proxy_pass http://localhost:3000; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection 'upgrade'; + proxy_set_header Host $host; + } + + location / { + try_files $uri $uri/ /index.html; + } +} +``` + +--- + +## Option 3: Cloud Platforms + +### Heroku + +```bash +# Create app +heroku create your-app-name + +# Set buildpacks +heroku buildpacks:set heroku/nodejs + +# Deploy +git push heroku main + +# Run migrations +heroku run npm run init-db +``` + +### DigitalOcean App Platform + +1. Connect GitHub repository +2. Configure build: + - Backend: `backend/`, start: `npm start` + - Frontend: `frontend/`, build: `npm run build` +3. Deploy + +--- ## Environment Variables -| Variable | Default | Description | -|----------|---------|-------------| -| NODE_ENV | production | Environment | -| PORT | 80 | Server port | +| Variable | Required | Default | Description | +|----------|----------|---------|-------------| +| `NODE_ENV` | No | development | Environment | +| `PORT` | No | 3000 | Backend port | +| `JWT_SECRET` | Yes | - | JWT secret key | +| `FRONTEND_URL` | No | http://localhost:5173 | Frontend URL | +| `DB_PATH` | No | ./database/landing.db | SQLite path | +| `SMTP_HOST` | No | - | SMTP server | +| `SMTP_PORT` | No | 587 | SMTP port | +| `SMTP_USER` | No | - | SMTP username | +| `SMTP_PASS` | No | - | SMTP password | -## SSL Configuration - -Add to nginx.conf: -```nginx -listen 443 ssl; -ssl_certificate /path/to/cert.pem; -ssl_certificate_key /path/to/key.pem; -``` +--- ## Monitoring ### Health Check + ```bash -curl http://localhost:8080/health +curl http://localhost/api/health ``` ### Logs + ```bash -docker logs {project_name} +# Docker logs +docker-compose logs -f + +# PM2 logs +pm2 logs backend +``` + +### Metrics + +Install PM2 metrics: + +```bash +pm2 install pm2-metrics +pm2 set pm2-metrics:port 9633 ``` ``` @@ -893,96 +2577,157 @@ post_gitea_comment(issue_number, """## 📚 Documentation Complete ### Files Created - ✅ README.md - Quick start guide -- ✅ docs/TECHNICAL.md - Technical docs +- ✅ docs/API.md - API documentation - ✅ docs/DEPLOYMENT.md - Deployment guide +- ✅ docs/ADMIN.md - Admin user guide +- ✅ .env.example - Environment template ### Documentation Coverage - Installation instructions -- Usage examples -- Configuration options -- Troubleshooting guide +- Development setup +- Production deployment +- API reference with examples +- Admin panel guide +- Environment variables +- Monitoring and logs **Next**: Final validation """) ``` -## Step 7: Final Validation +## Step 8: Final Validation **Agent**: `@CodeSkeptic` → `@Evaluator` ### Validation Checklist -- [ ] All HTML valid -- [ ] CSS valid -- [ ] JavaScript no errors -- [ ] All tests passing -- [ ] Docker build succeeds -- [ ] Documentation complete -- [ ] Accessibility audit passed -- [ ] Performance audit passed -- [ ] Mobile responsive verified +- [ ] Backend: Node.js + Express + SQLite working +- [ ] Frontend: Vue.js 3 with all components +- [ ] Admin Panel: CRUD operations working +- [ ] Database: Migrations run successfully +- [ ] Authentication: JWT login working +- [ ] Responsive: All breakpoints tested +- [ ] Cross-browser: Chrome, Firefox, Safari tested +- [ ] E2E Tests: All tests passing +- [ ] Docker: Containers build and run +- [ ] Documentation: Complete -### Run Validations +### Run Validation ```bash -# HTML validation -npx html-validate src/**/*.html +# Backend validation +cd backend +npm run lint +npm test +npm run test:coverage -# CSS validation -npx stylelint "src/**/*.css" +# Frontend validation +cd frontend +npm run lint +npm run build +npm run test -# JS linting -npx eslint src/**/*.js +# E2E tests +npx playwright test -# Accessibility audit -npx pa11y http://localhost:8080 +# Docker validation +docker-compose build +docker-compose up -d +docker-compose exec backend npm run test -# Performance audit -npx lighthouse http://localhost:8080 --output=json +# Accessibility +npx pa11y http://localhost + +# Performance +npx lighthouse http://localhost --output=json ``` ### Final Report ```python -post_gitea_comment(issue_number, """## ✅ Landing Page Complete +post_gitea_comment(issue_number, """## ✅ Landing Page CMS Complete ### Summary **Project**: {project_name} **Status**: Production Ready **Score**: {score}/10 -### Deliverables -- ✅ {pages_count} HTML pages -- ✅ {components_count} components -- ✅ {tests_count} E2E tests (all passing) -- ✅ Docker image ({image_size}MB) -- ✅ Complete documentation - -### Metrics -- Accessibility: WCAG 2.1 AA -- Performance: Lighthouse {lighthouse_score} -- Responsive: Mobile-first -- Bundle size: {bundle_size}KB +### Technology Stack +**Frontend**: Vue.js 3 + {ui_framework} + Pinia + Vite +**Backend**: Node.js 20 + Express + SQLite +**Auth**: JWT + bcrypt +**Deploy**: Docker + Nginx ### Files Created -``` -{file_tree} -``` +- **Backend**: {backend_files} files +- **Frontend**: {frontend_files} files +- **Tests**: {test_files} files +- **Docs**: {doc_files} files + +### Database +- 7 tables created +- Indexes optimized +- Foreign keys enabled + +### API Endpoints +- 6 public endpoints +- 18 admin endpoints + +### Tests +- **Total**: {total_tests} +- **Passed**: {passed_tests} +- **Failed**: {failed_tests} +- **Coverage**: {coverage}% + +### Browser Support +✅ Chrome 90+ +✅ Firefox 88+ +✅ Safari 14+ +✅ Edge 90+ +✅ Mobile Safari 14+ +✅ Chrome Mobile 90+ + +### Responsive +✅ Mobile (< 640px) +✅ Tablet (640px - 1023px) +✅ Desktop (≥ 1024px) + +### Deliverables +1. **Source Code** + - Complete backend API + - Vue.js frontend SPA + - Admin content management + - SQLite database + +2. **Docker** + - Production-ready containers + - Nginx configuration + - Health checks + +3. **Documentation** + - README.md + - API documentation + - Deployment guide + - Admin guide ### Quick Start ```bash docker-compose up -d -# Open http://localhost:8080 +docker-compose exec backend npm run init-db +docker-compose exec backend npm run create-admin +# Open http://localhost +# Admin: http://localhost/admin ``` -### Delivery -This landing page is ready for client delivery: -1. All source code in `/src` -2. Docker image ready for deployment -3. Documentation complete -4. Tests passing +### Client Handoff +- ✅ Fully functional CMS +- ✅ Admin panel for content management +- ✅ Responsive design +- ✅ Cross-browser tested +- ✅ Docker deployment +- ✅ Complete documentation -**Status**: 🟢 COMPLETE +**Status**: 🟢 READY FOR DELIVERY """) ``` @@ -990,42 +2735,45 @@ This landing page is ready for client delivery: | Gate | Criteria | Pass Condition | |------|----------|----------------| -| Analysis | All components identified | 100% mockup coverage | -| Architecture | Tech stack defined | Stack documented | -| Implementation | All components built | No console errors | -| Testing | All tests passing | 100% pass rate | -| Docker | Container builds and runs | Health check passes | -| Documentation | All docs created | README complete | -| Validation | All audits passing | Score ≥ 8/10 | +| Architecture | Full stack defined | Frontend + Backend + DB documented | +| Backend | API working | All endpoints respond | +| Frontend | Vue app working | Pages render correctly | +| Admin | CRUD working | Content can be edited | +| Database | Schema created | Tables and indexes exist | +| Responsive | All breakpoints | Mobile, tablet, desktop tested | +| Cross-browser | 3+ browsers | Chrome, Firefox, Safari pass | +| E2E Tests | All passing | 100% test pass rate | +| Docker | Container builds | Health check passes | +| Documentation | Complete | README, API, Deploy docs exist | ## Error Handling -### Build Errors -``` -If build fails: -1. Check console for errors -2. Verify all dependencies installed -3. Run `npm run lint` for issues -4. Fix reported problems -5. Retry build +### Database Errors + +```bash +# If migration fails +cd backend +rm -f ../database/landing.db +npm run init-db ``` -### Test Failures -``` -If tests fail: -1. Run `npx playwright test --debug` -2. Check screenshots in test-results/ -3. Fix identified issues -4. Re-run tests +### Build Errors + +```bash +# If frontend build fails +cd frontend +rm -rf node_modules package-lock.json +npm install +npm run build ``` ### Docker Issues -``` -If Docker fails: -1. Check Docker daemon running -2. Verify Dockerfile syntax -3. Check disk space -4. Review build logs: `docker build --progress=plain .` + +```bash +# If container fails +docker-compose down -v +docker-compose build --no-cache +docker-compose up -d ``` ## Handoff to Client @@ -1033,65 +2781,71 @@ If Docker fails: After completion, deliver: 1. **Source Code** - - Complete `/src` directory + - Complete repository - All components and pages - - All assets and styles + - Admin panel + - Database migrations -2. **Docker Image** - - Pre-built image - - Or Dockerfile for custom build +2. **Docker Package** + - Pre-built images + - Docker Compose file + - Environment template 3. **Documentation** - - README.md (quick start) - - docs/TECHNICAL.md (technical details) - - docs/DEPLOYMENT.md (deployment guide) + - README.md + - API Reference + - Deployment Guide + - Admin Guide -4. **Tests** - - All test files - - Test report - - Visual regression baselines +4. **Test Evidence** + - E2E test reports + - Screenshot comparisons + - Coverage reports -5. **Instructions** - - How to run locally - - How to deploy - - How to customize +5. **Credentials** + - Admin login + - JWT secret (change in production) + - Database location ## Example Invocation ``` -User: /landing-page --mockup_dir=./mockups --project_name=MyProduct --style=tailwind +User: /landing-page --mockup_dir=./mockups --project_name=MyProduct --ui_framework=vuetify Agent: -1. Analyzes mockups in ./mockups/ -2. Creates project structure -3. Implements components -4. Writes E2E tests -5. Creates Docker setup -6. Generates documentation -7. Validates everything -8. Reports to Gitea -9. Delivers ready-to-deploy package +1. Analyzes mockups +2. Designs architecture (Vue + Node + SQLite) +3. Implements backend API +4. Builds Vue frontend + Admin +5. Creates responsive design +6. Writes E2E tests +7. Creates Docker setup +8. Generates documentation +9. Validates everything +10. Reports to Gitea +11. Delivers ready-to-deploy package ``` ## Gitea Integration Every step posts progress to the linked issue: -1. 🎨 Analysis → Issue comment with component inventory -2. 📐 Architecture → Issue comment with project structure -3. 🛠️ Implementation → Issue comment with file changes -4. ✅ Testing → Issue comment with test results -5. 🐳 Docker → Issue comment with build status -6. 📚 Documentation → Issue comment with deliverables -7. ✅ Complete → Issue comment with final package +1. 🎨 Analysis → Component inventory +2. 📐 Architecture → Tech stack, schema +3. ⚙️ Backend → API endpoints, database +4. 🖼️ Frontend → Components, pages, admin +5. ✅ Testing → E2E results +6. 🐳 Docker → Container status +7. 📚 Documentation → Deliverables +8. ✅ Complete → Final package ## Status Tracking -Update issue labels throughout: +Update issue labels: - `status: new` → Analysis starting - `status: designing` → Architecture in progress -- `status: implementing` → Components being built +- `status: implementing` → Backend + Frontend - `status: testing` → E2E tests running - `status: releasing` → Docker building - `status: completed` → Package delivered \ No newline at end of file diff --git a/.kilo/rules/prompt-engineering.md b/.kilo/rules/prompt-engineering.md new file mode 100644 index 0000000..f542f45 --- /dev/null +++ b/.kilo/rules/prompt-engineering.md @@ -0,0 +1,328 @@ +# Prompt Engineering Rules + +Guidelines for crafting effective prompts for AI agents. + +## General Principles + +### Be Clear and Specific + +- Clearly state what you want the agent to do +- Avoid ambiguity and vague instructions +- Include specific file paths, function names, and line numbers when relevant + +**Bad:** Fix the code. +**Good:** Fix the bug in the `calculateTotal` function that causes it to return incorrect results when cart is empty. + +### Provide Context + +- Use context mentions (`@/path/to/file`) to refer to specific files +- Include relevant code snippets or error messages +- Reference related issues or previous changes + +**Good:** `@/src/utils.ts` Refactor the `calculateTotal` function to use async/await instead of callbacks. + +### Break Down Tasks + +- Divide complex tasks into smaller, well-defined steps +- Use numbered lists for multi-step instructions +- Specify the order of operations + +**Good:** +``` +1. First, analyze the current implementation +2. Identify performance bottlenecks +3. Refactor the main loop to use caching +4. Add unit tests for the new implementation +5. Verify the changes don't break existing tests +``` + +### Give Examples + +- If you have a specific coding style in mind, provide examples +- Show the expected input/output format +- Include code snippets that demonstrate the pattern + +### Specify Output Format + +- If you need output in a particular format, specify it +- Common formats: JSON, Markdown, TypeScript interfaces +- Include example structure when necessary + +## Thinking vs. Doing + +Guide agents through a "think-then-do" process: + +### Analyze Phase +Ask the agent to analyze the current code, identify problems, or plan the approach. + +**Prompt Pattern:** +``` +Analyze the current implementation of [feature]. +Identify: +- Potential issues +- Areas for improvement +- Security vulnerabilities +``` + +### Plan Phase +Have the agent outline the steps it will take to complete the task. + +**Prompt Pattern:** +``` +Before making any changes, provide a plan: +1. What files will be modified +2. What functions will be added/changed +3. What dependencies are needed +4. What tests should be written +``` + +### Execute Phase +Instruct the agent to implement the plan, one step at a time. + +**Prompt Pattern:** +``` +Now implement the plan: +1. Start with [first step] +2. Then [second step] +... +``` + +### Review Phase +Carefully review the results of each step before proceeding. + +**Prompt Pattern:** +``` +Review the changes: +- Do they meet the requirements? +- Are there any side effects? +- Do the tests pass? +``` + +## Custom Instructions + +### Global Custom Instructions + +Apply to all agents and modes. Place in `.kilo/rules/global.md` or `AGENTS.md`. + +**Examples:** +- Enforce coding style guidelines +- Specify preferred libraries +- Define project-specific conventions + +### Mode-Specific Custom Instructions + +Apply only to specific agents. Place in `.kilo/agents/[agent].md`. + +**Examples:** +- Lead Developer: "Always write tests before code (TDD)" +- Code Skeptic: "Check for security vulnerabilities first" +- Frontend Developer: "Use Tailwind CSS for all styling" + +## Handling Ambiguity + +### When Request is Unclear + +The agent should: + +1. **Ask clarifying questions** using the `question` tool +2. **Not make assumptions** without user confirmation +3. **Provide options** for the user to choose from + +**Example:** +``` +I need clarification: +- Option A: Implement as a new module +- Option B: Add to existing service +- Option C: Create a separate microservice +``` + +### Providing Multiple Options + +When presenting choices: +- Use clear, concise labels +- Provide descriptions for each option +- Recommend a default choice +- Allow custom input + +## Providing Feedback + +### Rejecting Actions + +When the agent proposes an incorrect action: + +1. Explain *why* the action is wrong +2. Provide the correct approach +3. Give an example if helpful + +**Example:** +``` +This approach won't work because [reason]. +Instead, use [correct approach]. +Here's an example: [code snippet] +``` + +### Rewording Requests + +If initial prompt doesn't produce desired results: + +1. Be more specific about requirements +2. Add constraints or boundaries +3. Provide examples of expected output +4. Break into smaller sub-tasks + +## Prompt Patterns + +### Feature Request Pattern + +```markdown +## Feature: [Feature Name] + +### Requirements +1. [Requirement 1] +2. [Requirement 2] + +### Acceptance Criteria +- [ ] [Criterion 1] +- [ ] [Criterion 2] + +### Files to Modify +- `path/to/file1.ts` +- `path/to/file2.ts` + +### Constraints +- Use [library/framework] +- Follow [pattern/style] +- Must be backward compatible +``` + +### Bug Fix Pattern + +```markdown +## Bug: [Bug Description] + +### Current Behavior +[What's happening now] + +### Expected Behavior +[What should happen] + +### Steps to Reproduce +1. [Step 1] +2. [Step 2] + +### Files Involved +- `path/to/file.ts` (line X) + +### Error Message +``` +[Stack trace or error message] +``` +``` + +### Refactoring Pattern + +```markdown +## Refactor: [What to Refactor] + +### Current Implementation +[Brief description or code snippet] + +### Target Implementation +[What it should become] + +### Reason +[Why this refactoring is needed] + +### Files to Update +- [File list] + +### Requirements +- Maintain existing functionality +- Keep tests passing +- Update documentation +``` + +## Examples + +### Good Prompts + +**Feature Implementation:** +> `@/src/components/Button.tsx` Refactor the `Button` component to support three variants: primary, secondary, and danger. Use the design tokens from `@/src/styles/tokens.ts`. + +**Bug Fix:** +> `@problems` Fix the TypeError in `calculateTotal` when the cart is empty. The function should return 0 for empty arrays. + +**Architecture:** +> Create a new service for handling user notifications. Follow the pattern in `@/src/services/EmailService.ts`. The service should support email, SMS, and push notifications. + +### Bad Prompts + +**Too Vague:** +> Fix the button. (What's wrong with it?) + +**No Context:** +> Write some Python code. (What should it do?) + +**Too Broad:** +> Fix everything. (What is "everything"?) + +**No Constraints:** +> Create a new feature. (What feature? For what?) + +## Prompt Anti-Patterns + +### Avoid These Patterns + +1. **Kitchen Sink Prompts** + - Asking for too many things at once + - Better: Break into multiple focused prompts + +2. **Missing Constraints** + - Not specifying required libraries or patterns + - Better: Always mention relevant constraints + +3. **Assuming Knowledge** + - Expecting the agent to know project context + - Better: Provide `@file` references + +4. **Ignoring Output** + - Not reviewing agent's changes + - Better: Always review and provide feedback + +5. **No Iteration** + - Accepting first result without refinement + - Better: Iterate on prompts for better results + +## Context Mentions + +Use context mentions to provide specific file references: + +| Mention | Description | +|---------|-------------| +| `@file.js` | Reference a specific file | +| `@/src/utils/` | Reference a directory | +| `@problems` | Reference all errors in the file | +| `@git` | Reference git history | +| `@terminal` | Reference terminal output | + +## Iterative Prompting + +When initial results aren't perfect: + +1. **Identify Issues:** What's wrong with the current output? +2. **Clarify Requirements:** Add more specific instructions +3. **Provide Examples:** Show the expected format or pattern +4. **Break Down:** Split complex tasks into smaller ones +5. **Refine:** Adjust constraints or add context + +## Verification Checklist + +After receiving agent output: + +- [ ] Does it meet all stated requirements? +- [ ] Are there any syntax errors? +- [ ] Does it follow project conventions? +- [ ] Are edge cases handled? +- [ ] Is it backward compatible? +- [ ] Are tests included/updated? +- [ ] Is documentation updated? \ No newline at end of file diff --git a/.kilo/skills/blog/SKILL.md b/.kilo/skills/blog/SKILL.md new file mode 100644 index 0000000..dcc13e9 --- /dev/null +++ b/.kilo/skills/blog/SKILL.md @@ -0,0 +1,489 @@ +--- +name: blog +description: Blog/CMS domain knowledge - posts, categories, tags, comments, authors, SEO +--- + +# Blog Skill + +## Purpose + +Provides domain knowledge for building blog and content management systems: posts, categories, tags, comments, authors, SEO optimization. + +## Capabilities + +### Content Management +- Post CRUD operations +- Draft/Published/Archived states +- Content scheduling +- Rich text editing +- Media embedding + +### Organization +- Categories (hierarchical) +- Tags (flat) +- Author assignment +- Content series + +### Comments +- Comment moderation +- Threaded comments +- Spam filtering +- Social login comments + +### SEO +- Meta tags +- Open Graph +- Structured data (Schema.org) +- Sitemap generation +- RSS feeds + +### Analytics +- View counts +- Reading time estimation +- Popular posts +- Related posts + +## Database Schema + +### Posts + +```sql +CREATE TABLE posts ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + title TEXT NOT NULL, + slug TEXT UNIQUE NOT NULL, + excerpt TEXT, + content TEXT NOT NULL, + featured_image TEXT, + author_id INTEGER NOT NULL, + category_id INTEGER, + status TEXT DEFAULT 'draft', -- 'draft', 'published', 'archived' + published_at DATETIME, + meta_title TEXT, + meta_description TEXT, + canonical_url TEXT, + reading_time INTEGER, -- minutes + view_count INTEGER DEFAULT 0, + allow_comments BOOLEAN DEFAULT 1, + created_at DATETIME DEFAULT CURRENT_TIMESTAMP, + updated_at DATETIME DEFAULT CURRENT_TIMESTAMP, + FOREIGN KEY (author_id) REFERENCES users(id), + FOREIGN KEY (category_id) REFERENCES categories(id) +); + +CREATE INDEX idx_posts_slug ON posts(slug); +CREATE INDEX idx_posts_status ON posts(status); +CREATE INDEX idx_posts_published ON posts(published_at); +CREATE INDEX idx_posts_author ON posts(author_id); +CREATE INDEX idx_posts_category ON posts(category_id); +``` + +### Categories + +```sql +CREATE TABLE categories ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + name TEXT NOT NULL, + slug TEXT UNIQUE NOT NULL, + description TEXT, + parent_id INTEGER, + image_url TEXT, + meta_title TEXT, + meta_description TEXT, + sort_order INTEGER DEFAULT 0, + FOREIGN KEY (parent_id) REFERENCES categories(id) +); + +CREATE INDEX idx_categories_parent ON categories(parent_id); +``` + +### Tags + +```sql +CREATE TABLE tags ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + name TEXT NOT NULL, + slug TEXT UNIQUE NOT NULL, + description TEXT +); + +CREATE TABLE post_tags ( + post_id INTEGER NOT NULL, + tag_id INTEGER NOT NULL, + PRIMARY KEY (post_id, tag_id), + FOREIGN KEY (post_id) REFERENCES posts(id) ON DELETE CASCADE, + FOREIGN KEY (tag_id) REFERENCES tags(id) ON DELETE CASCADE +); + +CREATE INDEX idx_post_tags_post ON post_tags(post_id); +CREATE INDEX idx_post_tags_tag ON post_tags(tag_id); +``` + +### Comments + +```sql +CREATE TABLE comments ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + post_id INTEGER NOT NULL, + parent_id INTEGER, -- for threaded comments + author_name TEXT NOT NULL, + author_email TEXT NOT NULL, + author_url TEXT, + content TEXT NOT NULL, + status TEXT DEFAULT 'pending', -- 'pending', 'approved', 'spam', 'trash' + ip_address TEXT, + user_agent TEXT, + created_at DATETIME DEFAULT CURRENT_TIMESTAMP, + FOREIGN KEY (post_id) REFERENCES posts(id) ON DELETE CASCADE, + FOREIGN KEY (parent_id) REFERENCES comments(id) +); + +CREATE INDEX idx_comments_post ON comments(post_id); +CREATE INDEX idx_comments_status ON comments(status); +``` + +### Authors + +```sql +CREATE TABLE authors ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + user_id INTEGER UNIQUE, + name TEXT NOT NULL, + bio TEXT, + avatar TEXT, + social_links TEXT, -- JSON: {"twitter": "...", "linkedin": "..."} + created_at DATETIME DEFAULT CURRENT_TIMESTAMP, + FOREIGN KEY (user_id) REFERENCES users(id) +); +``` + +## API Endpoints + +### Public API + +```yaml +# Posts +GET /api/posts # List published posts (paginated) +GET /api/posts/:slug # Get post by slug +GET /api/posts/author/:author # Posts by author +GET /api/posts/category/:category # Posts by category +GET /api/posts/tag/:tag # Posts by tag +GET /api/posts/search?q=query # Search posts + +# Categories +GET /api/categories # List categories +GET /api/categories/:slug # Get category with posts + +# Tags +GET /api/tags # List tags +GET /api/tags/:slug # Get tag with posts + +# Comments +GET /api/posts/:slug/comments # Get approved comments +POST /api/posts/:slug/comments # Submit new comment + +# Feeds +GET /api/feed/rss # RSS feed +GET /api/feed/atom # Atom feed +GET /api/sitemap.xml # Sitemap +``` + +### Admin API + +```yaml +# Posts +GET /api/admin/posts # List all posts (all statuses) +POST /api/admin/posts # Create post +PUT /api/admin/posts/:id # Update post +DELETE /api/admin/posts/:id # Delete post +POST /api/admin/posts/:id/publish # Publish post +POST /api/admin/posts/:id/archive # Archive post + +# Categories +GET /api/admin/categories # List all categories +POST /api/admin/categories # Create category +PUT /api/admin/categories/:id # Update category +DELETE /api/admin/categories/:id # Delete category + +# Tags +GET /api/admin/tags # List all tags +POST /api/admin/tags # Create tag +PUT /api/admin/tags/:id # Update tag +DELETE /api/admin/tags/:id # Delete tag + +# Comments +GET /api/admin/comments # List comments (all statuses) +PUT /api/admin/comments/:id/approve # Approve comment +PUT /api/admin/comments/:id/spam # Mark as spam +DELETE /api/admin/comments/:id # Delete comment + +# Media +POST /api/admin/media/upload # Upload media +GET /api/admin/media # List media +DELETE /api/admin/media/:id # Delete media +``` + +## Rich Content Features + +### Markdown Support + +```javascript +// utils/markdown.js +const marked = require('marked'); +const hljs = require('highlight.js'); + +const renderer = { + code(code, language) { + const highlighted = language + ? hljs.highlight(code, { language }).value + : code; + return `
${highlighted}
`; + }, + image(href, title, alt) { + return `
${alt}
${alt}
`; + } +}; + +marked.use({ renderer }); + +function parseMarkdown(content) { + return marked.parse(content); +} + +function calculateReadingTime(content) { + const words = content.split(/\s+/).length; + return Math.ceil(words / 200); // 200 words per minute +} +``` + +### Embed Support + +```javascript +// utils/embeds.js +const embedPatterns = { + youtube: /(?:youtube\.com\/watch\?v=|youtu\.be\/)([a-zA-Z0-9_-]+)/, + twitter: /twitter\.com\/\w+\/status\/(\d+)/, + twitter: /twitter\.com\/(\w+)\/status\/(\d+)/, + vimeo: /vimeo\.com\/(\d+)/, + codepen: /codepen\.io\/(\w+)\/pen\/(\w+)/ +}; + +function parseEmbeds(content) { + let parsed = content; + + for (const [platform, pattern] of Object.entries(embedPatterns)) { + parsed = parsed.replace(pattern, (match) => { + return generateEmbed(platform, match); + }); + } + + return parsed; +} + +function generateEmbed(platform, url) { + switch (platform) { + case 'youtube': + const videoId = url.match(embedPatterns.youtube)[1]; + return ``; + // ... other platforms + } +} +``` + +## SEO Implementation + +### Meta Tags + +```javascript +// utils/seo.js +function generateMeta(post) { + return { + title: post.meta_title || `${post.title} | ${config.siteName}`, + description: post.meta_description || post.excerpt, + canonical: post.canonical_url || `${config.siteUrl}/posts/${post.slug}`, + ogType: 'article', + ogImage: post.featured_image, + articlePublishedTime: post.published_at, + articleAuthor: post.author.name + }; +} +``` + +### Structured Data + +```javascript +// utils/schema.js +function generateArticleSchema(post) { + return { + "@context": "https://schema.org", + "@type": "Article", + "headline": post.title, + "image": post.featured_image, + "author": { + "@type": "Person", + "name": post.author.name + }, + "datePublished": post.published_at, + "dateModified": post.updated_at, + "description": post.excerpt + }; +} +``` + +### Sitemap + +```xml + + + + + https://example.com/ + daily + 1.0 + + {#posts} + + https://example.com/posts/{slug} + {updated_at} + weekly + 0.8 + + {/posts} + +``` + +## Comment Moderation + +### Spam Detection + +```javascript +// services/comments/spam.js +function detectSpam(comment) { + const signals = []; + + // Check for spam patterns + if (containsLinks(comment.content) > 3) signals.push('excessive_links'); + if (isDuplicate(comment)) signals.push('duplicate'); + if (isBlacklisted(comment.ip_address)) signals.push('blacklisted_ip'); + if (containsSpamWords(comment.content)) signals.push('spam_words'); + + // Calculate spam score + const score = signals.length; + + return { + isSpam: score >= 2, + score, + signals + }; +} +``` + +## Content Scheduling + +```javascript +// services/scheduler.js +async function publishScheduledPosts() { + const now = new Date(); + + const posts = await db.posts.findAll({ + where: { + status: 'draft', + published_at: { [Op.lte]: now } + } + }); + + for (const post of posts) { + await post.update({ status: 'published' }); + await notifySubscribers(post); + await updateSitemap(); + } +} + +// Run every minute +setInterval(publishScheduledPosts, 60000); +``` + +## Related Posts + +```javascript +// services/related.js +async function getRelatedPosts(post, limit = 5) { + // Find posts with same category or tags + const related = await db.posts.findAll({ + where: { + id: { [Op.ne]: post.id }, + status: 'published', + [Op.or]: [ + { category_id: post.category_id }, + { '$tags.id$': post.tags.map(t => t.id) } + ] + }, + include: [db.tags], + limit, + order: [['published_at', 'DESC']] + }); + + return related; +} +``` + +## Performance + +### Query Optimization + +```javascript +// Use joins for efficient loading +const post = await db.posts.findOne({ + where: { slug }, + include: [ + { model: db.authors, include: [db.users] }, + { model: db.categories }, + { model: db.tags } + ] +}); + +// Paginate efficiently +const posts = await db.posts.findAll({ + where: { status: 'published' }, + limit: 20, + offset: (page - 1) * 20, + order: [['published_at', 'DESC']] +}); +``` + +### Caching + +```javascript +// Cache popular posts +async function getPopularPosts() { + const cacheKey = 'popular-posts'; + const cached = await cache.get(cacheKey); + + if (cached) return cached; + + const posts = await db.posts.findAll({ + order: [['view_count', 'DESC']], + limit: 10 + }); + + await cache.set(cacheKey, posts, 3600); // 1 hour + + return posts; +} +``` + +## Security + +- Sanitize all user input (HTML, comments) +- Validate author permissions +- Rate limit comments +- Use CSRF protection for forms +- Implement CAPTCHA for guest comments + +## Integration Points + +- Email subscribers: SendGrid, Mailchimp +- CDN for images: Cloudflare, AWS CloudFront +- Analytics: Google Analytics, Plausible +- Comment systems: Disqus, Facebook Comments +- Search: Algolia, Elasticsearch \ No newline at end of file diff --git a/.kilo/skills/ecommerce/SKILL.md b/.kilo/skills/ecommerce/SKILL.md new file mode 100644 index 0000000..ecd52ee --- /dev/null +++ b/.kilo/skills/ecommerce/SKILL.md @@ -0,0 +1,394 @@ +--- +name: ecommerce +description: E-commerce domain knowledge - products, carts, orders, payments, inventory management +--- + +# E-commerce Skill + +## Purpose + +Provides domain knowledge for building e-commerce systems: product catalogs, shopping carts, order processing, payment integration, and inventory management. + +## Capabilities + +### Product Catalog +- Product CRUD operations +- Categories and tags +- Product variants (size, color) +- Pricing and discounts +- Product search and filtering +- Image galleries + +### Shopping Cart +- Add/remove items +- Quantity updates +- Cart persistence (session/database) +- Price calculations +- Discount codes + +### Order Processing +- Order creation from cart +- Order status workflow +- Order history +- Invoice generation +- Email notifications + +### Payment Integration +- Stripe integration +- PayPal integration +- Payment status tracking +- Refund processing +- Webhook handling + +### Inventory Management +- Stock tracking +- Low stock alerts +- Inventory adjustments +- Supplier management + +## Database Schema + +### Products + +```sql +CREATE TABLE products ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + sku TEXT UNIQUE NOT NULL, + name TEXT NOT NULL, + description TEXT, + price DECIMAL(10, 2) NOT NULL, + compare_at_price DECIMAL(10, 2), + cost_price DECIMAL(10, 2), + quantity INTEGER DEFAULT 0, + category_id INTEGER, + is_active BOOLEAN DEFAULT 1, + created_at DATETIME DEFAULT CURRENT_TIMESTAMP, + updated_at DATETIME DEFAULT CURRENT_TIMESTAMP, + FOREIGN KEY (category_id) REFERENCES categories(id) +); + +CREATE TABLE product_variants ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + product_id INTEGER NOT NULL, + sku TEXT UNIQUE NOT NULL, + name TEXT NOT NULL, + price_adjustment DECIMAL(10, 2) DEFAULT 0, + quantity INTEGER DEFAULT 0, + attributes TEXT, -- JSON: {"size": "M", "color": "red"} + FOREIGN KEY (product_id) REFERENCES products(id) +); + +CREATE TABLE categories ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + name TEXT NOT NULL, + slug TEXT UNIQUE NOT NULL, + parent_id INTEGER, + description TEXT, + image_url TEXT, + FOREIGN KEY (parent_id) REFERENCES categories(id) +); +``` + +### Cart and Orders + +```sql +CREATE TABLE carts ( + id TEXT PRIMARY KEY, -- UUID + user_id INTEGER, + session_id TEXT, + created_at DATETIME DEFAULT CURRENT_TIMESTAMP, + updated_at DATETIME DEFAULT CURRENT_TIMESTAMP, + FOREIGN KEY (user_id) REFERENCES users(id) +); + +CREATE TABLE cart_items ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + cart_id TEXT NOT NULL, + product_id INTEGER NOT NULL, + variant_id INTEGER, + quantity INTEGER NOT NULL DEFAULT 1, + price DECIMAL(10, 2) NOT NULL, + FOREIGN KEY (cart_id) REFERENCES carts(id), + FOREIGN KEY (product_id) REFERENCES products(id) +); + +CREATE TABLE orders ( + id TEXT PRIMARY KEY, -- UUID + order_number TEXT UNIQUE NOT NULL, + user_id INTEGER, + email TEXT NOT NULL, + status TEXT DEFAULT 'pending', + subtotal DECIMAL(10, 2) NOT NULL, + tax DECIMAL(10, 2) DEFAULT 0, + shipping DECIMAL(10, 2) DEFAULT 0, + discount DECIMAL(10, 2) DEFAULT 0, + total DECIMAL(10, 2) NOT NULL, + currency TEXT DEFAULT 'USD', + shipping_address TEXT, + billing_address TEXT, + notes TEXT, + created_at DATETIME DEFAULT CURRENT_TIMESTAMP, + updated_at DATETIME DEFAULT CURRENT_TIMESTAMP, + FOREIGN KEY (user_id) REFERENCES users(id) +); + +CREATE TABLE order_items ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + order_id TEXT NOT NULL, + product_id INTEGER NOT NULL, + variant_id INTEGER, + name TEXT NOT NULL, + sku TEXT NOT NULL, + quantity INTEGER NOT NULL, + price DECIMAL(10, 2) NOT NULL, + total DECIMAL(10, 2) NOT NULL, + FOREIGN KEY (order_id) REFERENCES orders(id), + FOREIGN KEY (product_id) REFERENCES products(id) +); + +CREATE TABLE payments ( + id TEXT PRIMARY KEY, -- UUID + order_id TEXT NOT NULL, + provider TEXT NOT NULL, -- 'stripe', 'paypal' + transaction_id TEXT, + amount DECIMAL(10, 2) NOT NULL, + currency TEXT DEFAULT 'USD', + status TEXT DEFAULT 'pending', + metadata TEXT, -- JSON + created_at DATETIME DEFAULT CURRENT_TIMESTAMP, + FOREIGN KEY (order_id) REFERENCES orders(id) +); +``` + +### Inventory + +```sql +CREATE TABLE inventory_transactions ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + product_id INTEGER, + variant_id INTEGER, + quantity INTEGER NOT NULL, + type TEXT NOT NULL, -- 'purchase', 'sale', 'adjustment', 'return' + reference TEXT, -- order ID, PO ID + notes TEXT, + created_at DATETIME DEFAULT CURRENT_TIMESTAMP, + FOREIGN KEY (product_id) REFERENCES products(id) +); +``` + +## API Endpoints + +### Public API + +```yaml +# Products +GET /api/products # List products (with pagination, filters) +GET /api/products/:slug # Get product by slug +GET /api/categories # List categories +GET /api/categories/:slug # Get category with products + +# Cart +GET /api/cart # Get current cart +POST /api/cart/items # Add item to cart +PUT /api/cart/items/:id # Update quantity +DELETE /api/cart/items/:id # Remove item +POST /api/cart/coupon # Apply discount code + +# Checkout +POST /api/checkout # Create order from cart +POST /api/checkout/guest # Guest checkout +GET /api/orders/:id # Get order details +``` + +### Admin API + +```yaml +# Products +GET /api/admin/products # List all products +POST /api/admin/products # Create product +PUT /api/admin/products/:id # Update product +DELETE /api/admin/products/:id # Delete product + +# Categories +GET /api/admin/categories # List all categories +POST /api/admin/categories # Create category +PUT /api/admin/categories/:id # Update category +DELETE /api/admin/categories/:id # Delete category + +# Orders +GET /api/admin/orders # List orders (with filters) +PUT /api/admin/orders/:id # Update order status +POST /api/admin/orders/:id/refund # Process refund + +# Inventory +GET /api/admin/inventory # Inventory status +PUT /api/admin/inventory/:id # Update stock +POST /api/admin/inventory/adjust # Stock adjustment +``` + +## Payment Integration + +### Stripe + +```javascript +// services/payment/stripe.js +const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY); + +async function createPaymentIntent(order) { + const paymentIntent = await stripe.paymentIntents.create({ + amount: Math.round(order.total * 100), // cents + currency: order.currency.toLowerCase(), + metadata: { orderId: order.id }, + receipt_email: order.email + }); + + return { + clientSecret: paymentIntent.client_secret, + paymentIntentId: paymentIntent.id + }; +} + +async function processWebhook(signature, payload) { + const event = stripe.webhooks.constructEvent( + payload, + signature, + process.env.STRIPE_WEBHOOK_SECRET + ); + + switch (event.type) { + case 'payment_intent.succeeded': + await updatePaymentStatus(event.data.object.id, 'completed'); + break; + case 'payment_intent.payment_failed': + await updatePaymentStatus(event.data.object.id, 'failed'); + break; + } +} +``` + +### PayPal + +```javascript +// services/payment/paypal.js +const paypal = require('@paypal/checkout-server-sdk'); + +async function createOrder(order) { + const request = new orders.OrdersCreateRequest(); + request.requestBody({ + intent: 'CAPTURE', + purchase_units: [{ + amount: { + currency_code: order.currency, + value: order.total.toFixed(2) + }, + reference_id: order.id + }] + }); + + const response = await client.execute(request); + return response.result; +} + +async function captureOrder(orderId) { + const request = new orders.OrdersCaptureRequest(orderId); + const response = await client.execute(request); + return response.result; +} +``` + +## Order Statuses + +| Status | Description | Next Statuses | +|--------|-------------|---------------| +| `pending` | Created, awaiting payment | `processing`, `cancelled` | +| `processing` | Payment confirmed, preparing | `shipped`, `on_hold` | +| `shipped` | Shipped to customer | `delivered` | +| `delivered` | Customer received | `completed` | +| `completed` | Order complete | - | +| `on_hold` | Manual review needed | `processing`, `cancelled` | +| `cancelled` | Order cancelled | `refunded` | +| `refunded` | Money returned to customer | - | + +## Email Templates + +### Order Confirmation + +```html +

Thank you for your order!

+

Order #{{order_number}}

+ +

Order Details

+{{#each items}} +

{{name}} x{{quantity}} - ${{total}}

+{{/each}} + +

Total: ${{total}}

+ +

Shipping Address

+

{{shipping_address}}

+ +

We'll send you another email when your order ships.

+``` + +### Shipping Notification + +```html +

Your order has shipped!

+

Order #{{order_number}}

+ +

Tracking: {{tracking_number}}

+

Carrier: {{carrier}}

+ +

Estimated Delivery

+

{{estimated_delivery}}

+``` + +## Security Considerations + +### Payment Security +- Never store credit card numbers +- Use PCI-compliant payment providers +- Implement CSRF protection +- Use HTTPS everywhere + +### Order Fraud Prevention +- Validate shipping address +- Check for suspicious patterns (high value, rush shipping) +- Implement rate limiting on checkout +- Log all order actions + +## Performance Optimizations + +### Product Listings +- Paginate results (20-50 per page) +- Use database indexes on category, price +- Cache category pages +- Lazy load product images + +### Cart Performance +- Store cart in Redis for quick access +- Use database for persistence +- Batch quantity updates + +### Inventory Checks +- Real-time stock validation at checkout +- Lock inventory during payment processing +- Handle concurrent purchases gracefully + +## Integration Points + +- Product Import: CSV, JSON, API +- Shipping Carriers: UPS, FedEx, DHL +- Tax Calculation: TaxJar, Avalara +- Email: SendGrid, Mailgun +- Analytics: Google Analytics, Mixpanel + +## Handoff Protocol + +After implementation: +1. Test checkout flow end-to-end +2. Verify payment processing +3. Check inventory deduction +4. Test email notifications +5. Verify order status transitions +6. Review `@CodeSkeptic` for security audit \ No newline at end of file