Initial commit

2025-11-29 18:47:11 +08:00
commit 8d68fa43fc
13 changed files with 4244 additions and 0 deletions
--- a/commands/deploy.md
+++ b/commands/deploy.md
@@ -0,0 +1,208 @@
+# Deploy Command
+
+Deploy the ExFabrica Agentic Factory applications to the specified environment with comprehensive validation and safety checks.
+
+## Usage
+
+```
+/deploy <environment> [--skip-tests] [--skip-build]
+```
+
+## Parameters
+
+- **environment** (required): Target deployment environment
+  - `dev` - Development environment
+  - `staging` - Staging/pre-production environment
+  - `production` - Production environment
+- **--skip-tests** (optional): Skip running tests before deployment (not recommended for production)
+- **--skip-build** (optional): Skip building the application (use existing build artifacts)
+
+## Workflow
+
+When you execute this command, Claude will:
+
+1. **Pre-deployment Validation**
+   - Verify git working directory is clean (no uncommitted changes)
+   - Check current branch matches environment requirements
+   - Ensure all required environment variables are set
+   - Validate the target environment configuration
+
+2. **Quality Checks** (unless --skip-tests is used)
+   - Run backend unit tests (`yarn workspace @bdqt/backend test`)
+   - Run frontend unit tests (`yarn workspace @bdqt/frontend test`)
+   - Run integration tests
+   - Verify test coverage meets minimum thresholds
+
+3. **Build Process** (unless --skip-build is used)
+   - Clean previous build artifacts
+   - Build backend application (`yarn workspace @bdqt/backend build`)
+   - Build frontend application with SSR (`yarn workspace @bdqt/frontend build`)
+   - Generate OpenAPI client if backend changes detected
+
+4. **Deployment Execution**
+   - For **dev**: Direct deployment to development environment
+   - For **staging**: Deploy to staging and run smoke tests
+   - For **production**:
+     - Require explicit confirmation
+     - Create deployment tag in git
+     - Deploy with zero-downtime strategy
+     - Run comprehensive smoke tests
+     - Monitor initial metrics
+
+5. **Post-deployment**
+   - Verify application health endpoints
+   - Run smoke tests against deployed environment
+   - Update deployment logs
+   - Notify team (if configured)
+
+## Examples
+
+### Deploy to Development
+```
+/deploy dev
+```
+Quick deployment to development environment with all validations.
+
+### Deploy to Staging
+```
+/deploy staging
+```
+Deploy to staging environment with full test suite and smoke tests.
+
+### Deploy to Production
+```
+/deploy production
+```
+Deploy to production with maximum safety checks, explicit confirmation, and monitoring.
+
+### Quick Development Deploy (skip tests)
+```
+/deploy dev --skip-tests
+```
+Fast deployment to development when you're confident in your changes.
+
+## Safety Features
+
+### Production Safeguards
+- **Explicit confirmation required** before production deployment
+- **Branch validation**: Must be on main/master branch
+- **Test coverage**: Minimum coverage thresholds must be met
+- **Git tag creation**: Every production deploy creates a version tag
+- **Rollback capability**: Previous version kept for quick rollback
+
+### All Environments
+- **Health checks**: Verify application responds correctly
+- **Database migrations**: Automatically run pending migrations
+- **Environment validation**: Ensure all required secrets are configured
+- **Build verification**: Confirm build artifacts are valid
+
+## Environment-Specific Behavior
+
+### Development (`dev`)
+- Fast deployment cycle
+- Automatic database seeding available
+- Detailed error logging
+- Hot reload capabilities maintained
+
+### Staging (`staging`)
+- Production-like configuration
+- Full test suite execution
+- Performance monitoring enabled
+- Load testing option available
+
+### Production (`production`)
+- Zero-downtime deployment strategy
+- Database backup before migrations
+- Comprehensive monitoring and alerting
+- Automatic rollback on critical errors
+
+## Prerequisites
+
+Before deploying, ensure:
+
+1. **Environment Configuration**
+   - `.env.development`, `.env.staging`, or `.env.production` file exists
+   - All required environment variables are set
+   - Database connection is configured
+
+2. **Infrastructure**
+   - Target environment is provisioned and accessible
+   - Database is running and migrations are ready
+   - Required Azure resources are available
+
+3. **Code Quality**
+   - All tests passing locally
+   - No ESLint or TypeScript errors
+   - Code reviewed and approved (for production)
+
+## Troubleshooting
+
+### Deployment Fails on Tests
+```
+Error: Tests failed - cannot proceed with deployment
+```
+**Solution**: Run `/test-all` to identify and fix failing tests.
+
+### Build Errors
+```
+Error: Build failed with TypeScript errors
+```
+**Solution**: Run `/analyze-code` to identify and fix type errors.
+
+### Environment Configuration Missing
+```
+Error: Required environment variable DATABASE_URL not set
+```
+**Solution**: Check `.env.{environment}` file and ensure all required variables are present.
+
+### Git Working Directory Not Clean
+```
+Error: Uncommitted changes detected
+```
+**Solution**: Commit or stash your changes before deploying.
+
+## Related Commands
+
+- `/test-all` - Run comprehensive test suite
+- `/analyze-code` - Check code quality before deployment
+- `/db-operations migrate` - Run database migrations manually
+- `/generate-api-client` - Update API client before deployment
+
+## Best Practices
+
+1. **Always test before deploying to production**
+   ```
+   /test-all
+   /deploy production
+   ```
+
+2. **Use staging as a production mirror**
+   ```
+   /deploy staging
+   # Verify manually
+   /deploy production
+   ```
+
+3. **Keep deployments small and frequent**
+   - Deploy to dev multiple times per day
+   - Deploy to staging at least daily
+   - Deploy to production weekly or bi-weekly
+
+4. **Monitor after deployment**
+   - Check application logs
+   - Verify key user flows
+   - Monitor performance metrics
+
+## Azure DevOps Integration
+
+This command can trigger Azure DevOps pipelines if configured in your `azure-pipelines.yml`:
+
+- Development deploys trigger the `dev` pipeline
+- Staging deploys trigger the `staging` pipeline
+- Production deploys trigger the `production` pipeline with approvals
+
+The command will wait for pipeline completion and report the results.
+
+---
+
+**Note**: This command respects the lifecycle hooks configured in `config/hooks.json` and will run pre-deployment and post-deployment hooks automatically.