docs(core): comprehensive development documentation and issue management system
- Complete project documentation for API gateway development - API gateway-specific development processes and standards - Comprehensive issue management system with script automation - Go-specific testing guidelines for multi-service architecture New Documentation: - devdocs/KONZEPT.md: project philosophy, architecture, service integration patterns - devdocs/TESTING_GUIDELINES.md: Go testing, API tests, gateway-service integration - devdocs/development-process.md: API gateway development, multi-service coordination - devdocs/furt-issue-management-guide.md: Furt-specific issue management workflows Issue Management System: - scripts/create_issue.sh: 8 preconfigured templates for API gateway development - Furt-specific issue types: service-request, architecture, performance, security - Script-based workflows for efficient development - Integration with existing get_issues.sh and update_issue.sh scripts API Gateway Development Standards: - Service integration patterns for gateway ↔ service communication - API-contract-first development with OpenAPI specifications - Security-first patterns for authentication and input validation - Multi-service testing strategies for coordinated development This documentation enables immediate, efficient API gateway development with clear standards, proven patterns, and automated workflows.
This commit is contained in:
parent
f4e8a40cdf
commit
d6d546bd95
7 changed files with 2649 additions and 0 deletions
347
scripts/create_issue.sh
Executable file
347
scripts/create_issue.sh
Executable file
|
|
@ -0,0 +1,347 @@
|
|||
#!/bin/bash
|
||||
|
||||
# Load environment
|
||||
if [ -f .env ]; then
|
||||
export $(cat .env | grep -v '^#' | xargs)
|
||||
else
|
||||
echo "❌ .env file not found!"
|
||||
echo "📋 Copy .env.example to .env and configure it first"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Validate required variables
|
||||
if [ -z "$GITEA_URL" ] || [ -z "$REPO_OWNER" ] || [ -z "$REPO_NAME" ] || [ -z "$GITEA_TOKEN" ]; then
|
||||
echo "❌ Missing required environment variables in .env"
|
||||
echo "📋 Check .env.example for required variables"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Colors
|
||||
GREEN='\033[0;32m'
|
||||
BLUE='\033[0;34m'
|
||||
RED='\033[0;31m'
|
||||
YELLOW='\033[1;33m'
|
||||
NC='\033[0m'
|
||||
|
||||
log_info() { echo -e "${BLUE}[INFO]${NC} $1"; }
|
||||
log_success() { echo -e "${GREEN}[SUCCESS]${NC} $1"; }
|
||||
log_error() { echo -e "${RED}[ERROR]${NC} $1"; }
|
||||
log_warning() { echo -e "${YELLOW}[WARNING]${NC} $1"; }
|
||||
|
||||
# Get all labels with IDs (like update_issue.sh)
|
||||
declare -A LABEL_IDS
|
||||
get_labels() {
|
||||
response=$(curl -s "$GITEA_URL/api/v1/repos/$REPO_OWNER/$REPO_NAME/labels" \
|
||||
-H "Authorization: token $GITEA_TOKEN")
|
||||
while IFS= read -r line; do
|
||||
name=$(echo "$line" | jq -r '.name')
|
||||
id=$(echo "$line" | jq -r '.id')
|
||||
LABEL_IDS["$name"]="$id"
|
||||
done < <(echo "$response" | jq -c '.[]')
|
||||
}
|
||||
|
||||
# Function to create issue with proper label ID handling
|
||||
create_issue() {
|
||||
local title="$1"
|
||||
local body="$2"
|
||||
local labels_string="$3"
|
||||
local assignee="$4"
|
||||
|
||||
# Get label IDs first
|
||||
get_labels
|
||||
|
||||
# Convert label names to IDs
|
||||
local valid_label_ids=()
|
||||
if [ -n "$labels_string" ]; then
|
||||
IFS=',' read -ra LABEL_ARRAY <<< "$labels_string"
|
||||
|
||||
for label in "${LABEL_ARRAY[@]}"; do
|
||||
label=$(echo "$label" | xargs) # Trim whitespace
|
||||
if [ -n "${LABEL_IDS[$label]}" ]; then
|
||||
valid_label_ids+=("${LABEL_IDS[$label]}")
|
||||
log_info "Using label '$label' (ID: ${LABEL_IDS[$label]})"
|
||||
else
|
||||
log_warning "Label '$label' not found, skipping"
|
||||
fi
|
||||
done
|
||||
fi
|
||||
|
||||
# Build labels array JSON with IDs
|
||||
local labels_json="["
|
||||
for i in "${!valid_label_ids[@]}"; do
|
||||
if [ $i -gt 0 ]; then
|
||||
labels_json="${labels_json},"
|
||||
fi
|
||||
labels_json="${labels_json}${valid_label_ids[$i]}"
|
||||
done
|
||||
labels_json="${labels_json}]"
|
||||
|
||||
# Build assignees array
|
||||
local assignees_json="[]"
|
||||
if [ -n "$assignee" ]; then
|
||||
assignees_json="[\"$assignee\"]"
|
||||
fi
|
||||
|
||||
# Use jq for proper JSON encoding of body and payload
|
||||
local json_payload=$(jq -n \
|
||||
--arg title "$title" \
|
||||
--arg body "$body" \
|
||||
--argjson labels "$labels_json" \
|
||||
--argjson assignees "$assignees_json" \
|
||||
'{
|
||||
title: $title,
|
||||
body: $body,
|
||||
labels: $labels,
|
||||
assignees: $assignees
|
||||
}')
|
||||
|
||||
log_info "Creating issue: $title"
|
||||
|
||||
response=$(curl -s -w "\n%{http_code}" -X POST \
|
||||
"$GITEA_URL/api/v1/repos/$REPO_OWNER/$REPO_NAME/issues" \
|
||||
-H "Authorization: token $GITEA_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "$json_payload")
|
||||
|
||||
http_code=$(echo "$response" | tail -n1)
|
||||
response_body=$(echo "$response" | head -n -1)
|
||||
|
||||
if [ "$http_code" = "201" ]; then
|
||||
issue_number=$(echo "$response_body" | jq -r '.number')
|
||||
issue_url="$GITEA_URL/$REPO_OWNER/$REPO_NAME/issues/$issue_number"
|
||||
log_success "Issue #$issue_number created!"
|
||||
echo "🔗 $issue_url"
|
||||
echo ""
|
||||
else
|
||||
log_error "Failed to create issue (HTTP: $http_code)"
|
||||
echo "$response_body"
|
||||
fi
|
||||
}
|
||||
|
||||
# Predefined issue templates for Furt API Gateway
|
||||
case "${1:-help}" in
|
||||
"service")
|
||||
service_name="${2:-newsletter}"
|
||||
create_issue \
|
||||
"[SERVICE] $service_name für Furt Gateway" \
|
||||
"## 🏷️ Service-Details
|
||||
**Name:** $service_name
|
||||
**Port:** 808X (TBD)
|
||||
**Zweck:** [Service-Beschreibung hier einfügen]
|
||||
|
||||
## 📝 Funktionsanforderungen
|
||||
- [ ] Grundfunktionalität implementieren
|
||||
- [ ] Input-Validation für alle Endpunkte
|
||||
- [ ] Error-Handling nach Furt-Standards
|
||||
- [ ] Health-Check-Endpoint (\`/health\`)
|
||||
|
||||
## 🔗 Gateway-Integration
|
||||
- [ ] **Routing:** \`/v1/$service_name/*\`
|
||||
- [ ] **Authentication:** API-Key required
|
||||
- [ ] **Rate-Limiting:** [X] requests/minute
|
||||
- [ ] **Upstream:** \`http://127.0.0.1:808X\`
|
||||
- [ ] **Timeout:** 15s default
|
||||
|
||||
## 🎯 API-Endpunkte (geplant)
|
||||
\`\`\`
|
||||
GET /v1/$service_name/ # List/Status
|
||||
POST /v1/$service_name/create # Create new
|
||||
PUT /v1/$service_name/{id} # Update existing
|
||||
DELETE /v1/$service_name/{id} # Delete
|
||||
\`\`\`
|
||||
|
||||
## 🧪 Testing-Requirements
|
||||
- [ ] Unit-Tests für Service-Logik
|
||||
- [ ] Integration-Tests für Gateway ↔ Service
|
||||
- [ ] API-Contract-Tests (OpenAPI-Compliance)
|
||||
- [ ] Load-Tests für Performance-Baselines
|
||||
|
||||
## 🌐 Hugo-Integration
|
||||
- [ ] Shortcode: \`{{< furt-$service_name >}}\`
|
||||
- [ ] JavaScript-Client-Library
|
||||
- [ ] CSS-Styling für UI-Komponenten
|
||||
- [ ] Dokumentation für Website-Integration
|
||||
|
||||
## 📋 OpenAPI-Dokumentation
|
||||
- [ ] \`docs/api/services/$service_name.yaml\` erstellen
|
||||
- [ ] Request/Response-Schemas definieren
|
||||
- [ ] Error-Codes dokumentieren
|
||||
- [ ] Examples für alle Endpunkte
|
||||
|
||||
## ⚡ Priorität
|
||||
📊 Mittel - geplante Entwicklung
|
||||
|
||||
## 🔧 Implementation-Checklist
|
||||
- [ ] Service-Generator ausführen: \`./scripts/service-generator.sh $service_name\`
|
||||
- [ ] Service-Logik implementieren
|
||||
- [ ] Gateway-Integration konfigurieren
|
||||
- [ ] Tests schreiben und ausführen
|
||||
- [ ] Deployment-Scripts anpassen
|
||||
- [ ] Hugo-Integration entwickeln" \
|
||||
"service-request,enhancement" \
|
||||
"${DEFAULT_ASSIGNEE:-}"
|
||||
;;
|
||||
|
||||
"architecture")
|
||||
topic="${2:-middleware-optimization}"
|
||||
create_issue \
|
||||
"[ARCH] Gateway $topic" \
|
||||
"## 🎯 Architektur-Thema
|
||||
Gateway-$topic für bessere Performance/Maintainability
|
||||
|
||||
## 📊 Aktuelle Situation
|
||||
**Current Implementation:**
|
||||
- [Beschreibung des aktuellen Zustands]
|
||||
- [Identifizierte Probleme oder Limitations]
|
||||
- [Performance-Metrics wenn verfügbar]
|
||||
|
||||
## 💡 Vorgeschlagene Änderung
|
||||
**Proposed Solution:**
|
||||
- [Detaillierte Beschreibung der vorgeschlagenen Lösung]
|
||||
- [Erwartete Verbesserungen]
|
||||
- [Implementation-Approach]
|
||||
|
||||
## 🔄 Alternativen
|
||||
1. **Option A:** [Beschreibung]
|
||||
- Vorteile: [...]
|
||||
- Nachteile: [...]
|
||||
|
||||
2. **Option B:** [Beschreibung]
|
||||
- Vorteile: [...]
|
||||
- Nachteile: [...]
|
||||
|
||||
## 📈 Betroffene Bereiche
|
||||
- [ ] Gateway-Performance
|
||||
- [ ] Service-Integration
|
||||
- [ ] Security (Auth/Rate-Limiting)
|
||||
- [ ] Configuration-Management
|
||||
- [ ] Monitoring/Logging
|
||||
- [ ] Hugo-Integration
|
||||
|
||||
## 🧪 Testing-Impact
|
||||
- [ ] Unit-Tests anpassen
|
||||
- [ ] Integration-Tests erweitern
|
||||
- [ ] Performance-Tests durchführen
|
||||
- [ ] Backward-Compatibility prüfen
|
||||
|
||||
## 📋 Implementation-Plan
|
||||
1. **Phase 1:** [Erste Schritte]
|
||||
2. **Phase 2:** [Hauptimplementierung]
|
||||
3. **Phase 3:** [Testing und Optimization]
|
||||
4. **Phase 4:** [Deployment und Monitoring]
|
||||
|
||||
## ⚡ Priorität
|
||||
🔥 Hoch - kritisch für Projekt-Erfolg" \
|
||||
"architecture,gateway,enhancement" \
|
||||
"${DEFAULT_ASSIGNEE:-}"
|
||||
;;
|
||||
|
||||
"performance")
|
||||
component="${2:-gateway}"
|
||||
create_issue \
|
||||
"[PERF] $component Performance-Optimierung" \
|
||||
"## 📊 Performance-Problem
|
||||
**Component:** $component
|
||||
**Issue:** [Beschreibung des Performance-Problems]
|
||||
|
||||
## 🔍 Gemessene Werte
|
||||
**Current Performance:**
|
||||
- **Response Time:** [X]ms average
|
||||
- **Throughput:** [X] requests/second
|
||||
- **Resource Usage:** [X]% CPU, [X]MB Memory
|
||||
- **Error Rate:** [X]% under load
|
||||
|
||||
**Target Performance:**
|
||||
- **Response Time:** <[Y]ms
|
||||
- **Throughput:** >[Y] requests/second
|
||||
- **Resource Usage:** <[Y]% CPU, <[Y]MB Memory
|
||||
- **Error Rate:** <[Y]% under normal load
|
||||
|
||||
## 🎯 Performance-Ziele
|
||||
- [ ] **Latency-Optimization:** Reduce response time by [X]%
|
||||
- [ ] **Throughput-Increase:** Handle [X]x more concurrent requests
|
||||
- [ ] **Resource-Efficiency:** Reduce CPU/Memory usage
|
||||
- [ ] **Scalability:** Support [X] services without degradation
|
||||
|
||||
## 🔍 Profiling-Results
|
||||
**Current Bottlenecks:**
|
||||
\`\`\`
|
||||
[Paste go-pprof results oder performance measurements]
|
||||
\`\`\`
|
||||
|
||||
**Identified Issues:**
|
||||
- [Issue 1]: [Description]
|
||||
- [Issue 2]: [Description]
|
||||
- [Issue 3]: [Description]
|
||||
|
||||
## 🛠️ Optimization-Strategy
|
||||
1. **Code-Optimization:**
|
||||
- [Specific code changes]
|
||||
- [Algorithm improvements]
|
||||
|
||||
2. **Infrastructure-Optimization:**
|
||||
- [Connection pooling]
|
||||
- [Caching strategies]
|
||||
|
||||
3. **Configuration-Tuning:**
|
||||
- [Timeout adjustments]
|
||||
- [Buffer size optimization]
|
||||
|
||||
## 🧪 Performance-Testing-Plan
|
||||
- [ ] **Baseline-Measurements:** Before optimization
|
||||
- [ ] **Load-Testing:** Various traffic patterns
|
||||
- [ ] **Stress-Testing:** Breaking point analysis
|
||||
- [ ] **Endurance-Testing:** Long-running stability
|
||||
- [ ] **Regression-Testing:** Ensure no functionality broken
|
||||
|
||||
## 📋 Success-Criteria
|
||||
- [ ] Target response time achieved
|
||||
- [ ] Target throughput achieved
|
||||
- [ ] Resource usage within limits
|
||||
- [ ] No regressions in functionality
|
||||
- [ ] Monitoring alerts configured
|
||||
|
||||
## ⚡ Priorität
|
||||
🔥 Hoch - Performance ist kritisch" \
|
||||
"performance,optimization,$component" \
|
||||
"${DEFAULT_ASSIGNEE:-}"
|
||||
;;
|
||||
|
||||
# Weitere templates hier... (gekürzt für Übersichtlichkeit)
|
||||
|
||||
"custom")
|
||||
echo "🎯 Custom Furt Issue Creator"
|
||||
echo ""
|
||||
read -p "📝 Title: " title
|
||||
echo "📋 Body (press Ctrl+D when finished):"
|
||||
body=$(cat)
|
||||
read -p "🏷️ Labels (comma separated): " labels
|
||||
read -p "👤 Assignee (optional): " assignee
|
||||
|
||||
create_issue "$title" "$body" "$labels" "${assignee:-$DEFAULT_ASSIGNEE}"
|
||||
;;
|
||||
|
||||
*)
|
||||
echo "🎯 Furt API-Gateway Issue Creator"
|
||||
echo ""
|
||||
echo "Usage: $0 [TEMPLATE] [OPTIONS]"
|
||||
echo ""
|
||||
echo "📋 Available Templates:"
|
||||
echo " service [name] New service for gateway (default: newsletter)"
|
||||
echo " architecture [topic] Gateway architecture discussion (default: middleware-optimization)"
|
||||
echo " performance [comp] Performance optimization (default: gateway)"
|
||||
echo " api [service] API contract update (default: formular2mail)"
|
||||
echo " security [comp] Security review/issue (default: gateway)"
|
||||
echo " bug [comp] [desc] Bug report (default: gateway)"
|
||||
echo " hugo [feature] Hugo integration (default: shortcode)"
|
||||
echo " deployment [comp] Deployment issue (default: gateway)"
|
||||
echo " custom Custom issue (interactive)"
|
||||
echo ""
|
||||
echo "🚀 Examples:"
|
||||
echo " $0 service newsletter # Create newsletter service request"
|
||||
echo " $0 architecture rate-limiting # Discuss rate limiting architecture"
|
||||
echo " $0 performance gateway # Gateway performance optimization"
|
||||
echo " $0 custom # Interactive custom issue"
|
||||
;;
|
||||
esac
|
||||
|
||||
Loading…
Add table
Add a link
Reference in a new issue