working-examples.md•5.11 kB
# Working Examples - Proven Patterns
**Purpose**: Document proven working patterns to prevent regression
---
## ✅ **Proven Authentication Pattern**
### **JWT Redirect Flow**
```javascript
// WORKING - Do not modify
// 1. Start JWT redirect server
const server = require('./tools/servers/jwt-redirect-server-v1.0.2.js');
// 2. Navigate to localhost:8080 in browser
await page.goto('http://localhost:8080');
// 3. Wait for redirect to composer.euconquisto.com
await page.waitForURL('**/composer.euconquisto.com/**');
// 4. Extract from localStorage
const authData = await page.evaluate(() => {
const activeProject = localStorage.getItem('rdp-composer-active-project');
const userData = localStorage.getItem('rdp-composer-user-data');
return { activeProject, userData };
});
```
---
## ✅ **Proven API Save Pattern**
### **FormData Structure**
```javascript
// WORKING - Do not modify
const formData = new FormData();
const blob = new Blob([JSON.stringify(composerJSON)], { type: 'application/json' });
formData.append('file', blob, 'composition.rdpcomposer');
const headers = {
'Authorization': `Bearer ${accessToken}`,
'Project-Key': 'e3894d14dbb743d78a7efc5819edc52e',
'Api-Env': 'prd'
};
const response = await fetch(apiEndpoint, {
method: 'POST',
headers: headers,
body: formData
});
```
---
## ✅ **Proven JSON Structure**
### **Header Widget (head-1)**
```json
{
"type": "head-1",
"category": "<p>SUBJECT - TOPIC</p>",
"author_name": "<p>Professor Name</p>",
"author_office": "<p>Specialization</p>",
"primary_color": "#4CAF50",
"secondary_color": "#2E7D32",
"show_category": true,
"show_author_name": true,
"show_divider": true
}
```
### **Quiz Widget (quiz-1)**
```json
{
"type": "quiz-1",
"max_attempts": 2,
"questions": [
{
"question": "<p>Question text here</p>",
"choices": [
{
"id": "uuid",
"correct": true,
"text": "<p>Choice text here</p>"
}
]
}
]
}
```
### **Metadata Structure**
```json
{
"metadata": {
"uid": "uuid",
"name": "Topic Name",
"description": "Description",
"category": "SUBJECT - TOPIC",
"duration": 50,
"subject": "Subject",
"segment": "Grade Level",
"keywords": ["keyword1", "keyword2"]
}
}
```
---
## ✅ **Proven Content Generation**
### **Subject-Specific Patterns**
```javascript
// WORKING - Physics example
const physicsContent = {
metadata: {
topic: "Cinemática: Movimento Uniforme",
subject: "Física",
gradeLevel: "1º médio",
duration: 50
},
widgets: [
{ type: "head-1", content: { ... } },
{ type: "text-1", content: { text: "Physics content with equations" } },
{ type: "quiz-1", content: { questions: [...] } }
]
};
```
---
## ✅ **Proven Error Handling**
### **API Error Analysis**
```javascript
// WORKING - Error categorization
if (response.status === 500) {
// Server processing error - check JSON structure
// NOT a payload size issue
}
if (response.status === 401) {
// Authentication expired - refresh JWT
}
if (response.status === 413) {
// Payload too large - optimize content
}
```
---
## ❌ **Common Pitfalls to Avoid**
### **Wrong Assumptions**
- ❌ Assuming 500 errors are payload size issues
- ❌ Rebuilding authentication when it's working
- ❌ Using `answers` field instead of `choices` in quiz
- ❌ Not HTML-wrapping header fields
### **Regression Risks**
- ❌ Modifying working JWT redirect server
- ❌ Changing proven API endpoint patterns
- ❌ Ignoring JSON reference structure
- ❌ Rebuilding content generation logic
---
## 🔍 **Debugging Checklist**
### **Before Starting Any Debug Session**:
1. ✅ Check if similar issue was solved before
2. ✅ Reference `/docs/references/json-example.md`
3. ✅ Verify working components are intact
4. ✅ Test with minimal example first
### **For API Errors**:
1. ✅ Check JSON structure matches reference
2. ✅ Verify authentication state
3. ✅ Test with known working payload
4. ✅ Check HTTP status code meaning
### **For Content Issues**:
1. ✅ Verify HTML wrapping in header fields
2. ✅ Check quiz uses `choices` not `answers`
3. ✅ Ensure metadata has required fields
4. ✅ Test with single widget first
---
## 🎉 **LATEST ACHIEVEMENTS** (January 11, 2025)
### **✅ HTTP 500 Errors RESOLVED**
- **Root Cause**: JSON structure incompatibility with API reference
- **Solution**: Implemented HTML wrapping and correct field names per `/docs/references/json-example.md`
- **Validation**: Complete photosynthesis lesson (12 widgets) saves successfully
- **Performance**: 2.5 seconds for complex lessons, HTTP 200 OK responses
### **✅ Production Validation Complete**
- **Minimal Test**: 3-widget composition - ✅ SUCCESS
- **Complex Test**: 12-widget photosynthesis lesson - ✅ SUCCESS
- **All Widget Types**: header, text, quiz, flashcards, hotspots, images, lists - ✅ SUCCESS
- **System Status**: 100% PRODUCTION READY
---
**Last Updated**: January 11, 2025
**Status**: ✅ **PRODUCTION VALIDATED** - All critical issues resolved