Initial commit: Werkzeuge-Sammlung
Enthält: - rdp_client.py: RDP Client mit GUI und Monitor-Auswahl - rdp.sh: Bash-basierter RDP Client - teamleader_test/: Network Scanner Fullstack-App - teamleader_test2/: Network Mapper CLI Subdirectories mit eigenem Repo wurden ausgeschlossen. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
root
427
teamleader_test/CONTRIBUTING.md
Normal file
427
teamleader_test/CONTRIBUTING.md
Normal file
@@ -0,0 +1,427 @@
|
||||
# Contributing to Network Scanner Tool
|
||||
|
||||
Thank you for contributing! This guide will help you understand our development workflow, coding standards, and documentation requirements.
|
||||
|
||||
---
|
||||
|
||||
## Before You Start
|
||||
|
||||
### 1. Read the Documentation
|
||||
|
||||
**Required reading before contributing:**
|
||||
|
||||
- [docs/index.md](docs/index.md) - Documentation index
|
||||
- [.github/copilot-instructions.md](.github/copilot-instructions.md) - Critical patterns and gotchas
|
||||
- [docs/guides/troubleshooting.md](docs/guides/troubleshooting.md) - Common issues
|
||||
- [docs/project-status.md](docs/project-status.md) - Current feature status
|
||||
|
||||
### 2. Check Existing Issues
|
||||
|
||||
- Search [docs/guides/troubleshooting.md](docs/guides/troubleshooting.md) for known issues
|
||||
- Review [archive/review-2025-12-04/](archive/review-2025-12-04/) for resolved issues
|
||||
- Check if your feature/fix is already documented
|
||||
|
||||
### 3. Understand the Architecture
|
||||
|
||||
- Backend: Python 3.11 + FastAPI + SQLAlchemy + SQLite
|
||||
- Frontend: React 18 + TypeScript + TailwindCSS + React Flow
|
||||
- Deployment: Docker + Docker Compose + nginx
|
||||
|
||||
---
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Setting Up Development Environment
|
||||
|
||||
```bash
|
||||
# Clone and navigate to project
|
||||
cd /home/rwiegand/Nextcloud/entwicklung/Werkzeuge/teamleader_test
|
||||
|
||||
# Start with Docker Compose (recommended)
|
||||
docker compose up -d --build
|
||||
|
||||
# Or setup locally (advanced)
|
||||
# Backend
|
||||
python3 -m venv venv
|
||||
source venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
python main.py
|
||||
|
||||
# Frontend
|
||||
cd frontend
|
||||
npm install
|
||||
npm run dev
|
||||
```
|
||||
|
||||
### Making Changes
|
||||
|
||||
1. **Create a branch** (if using git)
|
||||
```bash
|
||||
git checkout -b feature/your-feature-name
|
||||
```
|
||||
|
||||
2. **Make your changes**
|
||||
- Follow coding conventions (see below)
|
||||
- Write clear commit messages
|
||||
- Test your changes locally
|
||||
|
||||
3. **Update documentation**
|
||||
- **CRITICAL**: Update relevant docs in `docs/`
|
||||
- Add entry to CHANGELOG.md (TODO - create this)
|
||||
- Update [docs/project-status.md](docs/project-status.md) if feature completeness changes
|
||||
|
||||
4. **Test thoroughly**
|
||||
```bash
|
||||
# Backend
|
||||
docker compose logs backend --tail=50
|
||||
curl http://localhost:8000/health
|
||||
|
||||
# Frontend
|
||||
# Open http://localhost and test UI
|
||||
# Check browser console (F12) for errors
|
||||
```
|
||||
|
||||
5. **Submit pull request** (if using git workflow)
|
||||
- Clear description of changes
|
||||
- Reference any related issues
|
||||
- Include documentation updates
|
||||
|
||||
---
|
||||
|
||||
## Coding Standards
|
||||
|
||||
### Backend (Python)
|
||||
|
||||
**Style Guide**: PEP 8
|
||||
|
||||
```python
|
||||
# Good: Type hints, docstrings, descriptive names
|
||||
def create_scan(self, config: ScanConfigRequest) -> Scan:
|
||||
"""
|
||||
Create a new scan record.
|
||||
|
||||
Args:
|
||||
config: Scan configuration
|
||||
|
||||
Returns:
|
||||
Created scan object
|
||||
"""
|
||||
scan = Scan(
|
||||
scan_type=config.scan_type.value,
|
||||
network_range=config.network_range,
|
||||
status=ScanStatusEnum.PENDING.value
|
||||
)
|
||||
self.db.add(scan)
|
||||
self.db.commit()
|
||||
self.db.refresh(scan)
|
||||
return scan
|
||||
|
||||
# Bad: No types, no docs, unclear names
|
||||
def cs(c):
|
||||
s = Scan(scan_type=c.scan_type.value, network_range=c.network_range)
|
||||
self.db.add(s)
|
||||
self.db.commit()
|
||||
return s
|
||||
```
|
||||
|
||||
**Critical Patterns**:
|
||||
|
||||
1. **Database Sessions in Background Tasks**:
|
||||
```python
|
||||
# ✅ DO: Create new session
|
||||
def scan_wrapper(scan_id: int):
|
||||
db = SessionLocal()
|
||||
try:
|
||||
scan_service.execute_scan(scan_id, db)
|
||||
finally:
|
||||
db.close()
|
||||
|
||||
background_tasks.add_task(scan_wrapper, scan_id)
|
||||
|
||||
# ❌ DON'T: Use request session
|
||||
background_tasks.add_task(scan_service.execute_scan, scan_id, db)
|
||||
```
|
||||
|
||||
2. **Database Constraints**:
|
||||
```python
|
||||
# ✅ DO: Commit before adding dependents
|
||||
host = self._get_or_create_host(ip)
|
||||
self.db.commit()
|
||||
self.db.refresh(host) # Ensure host.id is set
|
||||
|
||||
service = Service(host_id=host.id, port=80)
|
||||
self.db.add(service)
|
||||
|
||||
# ❌ DON'T: Add dependents before commit
|
||||
host = self._get_or_create_host(ip)
|
||||
service = Service(host_id=host.id, port=80) # host.id may be None!
|
||||
```
|
||||
|
||||
3. **Logging**:
|
||||
```python
|
||||
import logging
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
logger.info("Starting scan for 192.168.1.0/24")
|
||||
logger.error(f"Scan failed: {error}")
|
||||
logger.debug(f"Processing host: {ip}")
|
||||
```
|
||||
|
||||
### Frontend (TypeScript/React)
|
||||
|
||||
**Style Guide**: TypeScript strict mode, React best practices
|
||||
|
||||
```typescript
|
||||
// Good: Type-safe, clear component structure
|
||||
interface HostDetailsPanelProps {
|
||||
hostId: string;
|
||||
onClose: () => void;
|
||||
}
|
||||
|
||||
export default function HostDetailsPanel({ hostId, onClose }: HostDetailsPanelProps) {
|
||||
const [host, setHost] = useState<HostWithServices | null>(null);
|
||||
const [loading, setLoading] = useState(true);
|
||||
|
||||
useEffect(() => {
|
||||
const fetchHost = async () => {
|
||||
try {
|
||||
setLoading(true);
|
||||
const data = await hostApi.getHost(parseInt(hostId));
|
||||
setHost(data);
|
||||
} catch (err) {
|
||||
console.error('Failed to fetch host:', err);
|
||||
} finally {
|
||||
setLoading(false);
|
||||
}
|
||||
};
|
||||
|
||||
fetchHost();
|
||||
}, [hostId]);
|
||||
|
||||
return (
|
||||
<div className="panel">
|
||||
{/* Component JSX */}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
// Bad: No types, unclear structure, no error handling
|
||||
function Panel(props) {
|
||||
const [data, setData] = useState(null);
|
||||
|
||||
useEffect(() => {
|
||||
fetch('/api/hosts/' + props.id).then(r => r.json()).then(setData);
|
||||
}, []);
|
||||
|
||||
return <div>{data?.name}</div>;
|
||||
}
|
||||
```
|
||||
|
||||
**Critical Rules**:
|
||||
|
||||
1. **Schema Alignment**: Frontend types MUST match backend schemas exactly
|
||||
```typescript
|
||||
// frontend/src/types/api.ts
|
||||
export interface Scan {
|
||||
network_range: string; // ← Must match app/schemas.py
|
||||
}
|
||||
|
||||
// app/schemas.py
|
||||
class ScanConfigRequest(BaseModel):
|
||||
network_range: str # ← Must match frontend
|
||||
```
|
||||
|
||||
2. **API Error Handling**:
|
||||
```typescript
|
||||
try {
|
||||
const data = await scanApi.startScan(config);
|
||||
// Handle success
|
||||
} catch (error) {
|
||||
if (axios.isAxiosError(error)) {
|
||||
console.error('API Error:', error.response?.data);
|
||||
}
|
||||
// Handle error
|
||||
}
|
||||
```
|
||||
|
||||
3. **React Hooks**:
|
||||
- Custom hooks in `hooks/` for reusable logic
|
||||
- Use `useEffect` dependencies correctly
|
||||
- Clean up subscriptions/timers
|
||||
|
||||
### Database Changes
|
||||
|
||||
**When modifying `app/models.py`:**
|
||||
|
||||
1. Update SQLAlchemy model
|
||||
2. Update Pydantic schema in `app/schemas.py`
|
||||
3. Update TypeScript types in `frontend/src/types/api.ts`
|
||||
4. Delete `data/network_scanner.db` (dev) or create migration (prod)
|
||||
5. Update [docs/development/database-schema.md](docs/development/database-schema.md) (TODO)
|
||||
6. Restart backend: `docker compose restart backend`
|
||||
|
||||
**Reserved Column Names** (avoid these in SQLAlchemy):
|
||||
- `metadata` - Use `extra_data` instead
|
||||
- `type` - Use `device_type` or prefix with table name
|
||||
- Other SQLAlchemy/SQL reserved words
|
||||
|
||||
---
|
||||
|
||||
## Documentation Requirements
|
||||
|
||||
### Mandatory Documentation Updates
|
||||
|
||||
**All pull requests MUST include:**
|
||||
|
||||
1. **Updated documentation** if API or behavior changes
|
||||
2. **Entry in CHANGELOG.md** (TODO - create this)
|
||||
3. **Update to [docs/project-status.md](docs/project-status.md)** if feature status changes
|
||||
4. **Troubleshooting entry** if fixing a bug
|
||||
|
||||
### When to Update Specific Docs
|
||||
|
||||
| Change Type | Documentation to Update |
|
||||
|-------------|-------------------------|
|
||||
| New API endpoint | `docs/api/endpoints.md` (TODO), add to OpenAPI docs |
|
||||
| Database schema change | `docs/development/database-schema.md` (TODO) |
|
||||
| New feature | `docs/project-status.md`, `README.md` |
|
||||
| Bug fix | `docs/guides/troubleshooting.md` |
|
||||
| Configuration change | `docs/setup/` files, `.env.example` |
|
||||
| Architecture decision | `docs/architecture/overview.md` |
|
||||
|
||||
### Documentation Style
|
||||
|
||||
```markdown
|
||||
# Good: Clear, actionable, with examples
|
||||
|
||||
## Adding a New API Endpoint
|
||||
|
||||
1. Create handler in `app/api/endpoints/new_feature.py`:
|
||||
```python
|
||||
@router.get("/feature")
|
||||
async def get_feature(db: Session = Depends(get_db)):
|
||||
return {"data": "value"}
|
||||
```
|
||||
|
||||
2. Add to router in `app/api/__init__.py`
|
||||
3. Update `frontend/src/types/api.ts`
|
||||
|
||||
# Bad: Vague, no examples
|
||||
|
||||
Add endpoint and update types.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Testing Guidelines
|
||||
|
||||
### Manual Testing Checklist
|
||||
|
||||
Before submitting changes, test:
|
||||
|
||||
- [ ] Backend health check: `curl http://localhost/health`
|
||||
- [ ] Relevant API endpoints work
|
||||
- [ ] Frontend loads without errors (check F12 console)
|
||||
- [ ] No TypeScript build errors
|
||||
- [ ] Docker build succeeds: `docker compose up -d --build`
|
||||
- [ ] Database operations complete successfully
|
||||
- [ ] WebSocket updates work (if applicable)
|
||||
- [ ] No errors in `docker compose logs`
|
||||
|
||||
### Automated Testing (TODO)
|
||||
|
||||
```python
|
||||
# Backend tests (when implemented)
|
||||
pytest tests/
|
||||
|
||||
# Frontend tests (when implemented)
|
||||
cd frontend && npm test
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Commit Message Guidelines
|
||||
|
||||
**Format**: `<type>: <description>`
|
||||
|
||||
**Types**:
|
||||
- `feat:` New feature
|
||||
- `fix:` Bug fix
|
||||
- `docs:` Documentation changes
|
||||
- `refactor:` Code restructuring
|
||||
- `test:` Adding tests
|
||||
- `chore:` Maintenance tasks
|
||||
|
||||
**Examples**:
|
||||
```
|
||||
feat: add host details panel with service information
|
||||
fix: resolve session management in background tasks
|
||||
docs: update troubleshooting guide with schema mismatch solution
|
||||
refactor: simplify topology service to remove layout calculation
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Code Review Checklist
|
||||
|
||||
### For Reviewers
|
||||
|
||||
- [ ] Code follows style guidelines
|
||||
- [ ] Documentation is updated
|
||||
- [ ] No obvious bugs or security issues
|
||||
- [ ] TypeScript types match backend schemas
|
||||
- [ ] Database operations follow critical patterns
|
||||
- [ ] Logging is appropriate
|
||||
- [ ] Error handling is present
|
||||
- [ ] Changes are tested
|
||||
|
||||
### For Contributors
|
||||
|
||||
Before requesting review:
|
||||
- [ ] Run through manual testing checklist
|
||||
- [ ] All documentation requirements met
|
||||
- [ ] Code is self-documented (clear names, docstrings)
|
||||
- [ ] Commit messages are clear
|
||||
- [ ] No debug code or commented-out blocks
|
||||
- [ ] No hardcoded credentials or secrets
|
||||
|
||||
---
|
||||
|
||||
## Architecture Decisions
|
||||
|
||||
### When to Document an ADR
|
||||
|
||||
If you're making a significant architectural decision:
|
||||
1. Create ADR in `docs/architecture/decisions/` (TODO)
|
||||
2. Document: Context, Decision, Consequences, Alternatives considered
|
||||
|
||||
Examples of ADR-worthy decisions:
|
||||
- Switching from SQLite to PostgreSQL
|
||||
- Changing visualization library
|
||||
- Adding authentication system
|
||||
- Modifying API versioning strategy
|
||||
|
||||
---
|
||||
|
||||
## Getting Help
|
||||
|
||||
**Before asking:**
|
||||
1. Check [docs/guides/troubleshooting.md](docs/guides/troubleshooting.md)
|
||||
2. Review [.github/copilot-instructions.md](.github/copilot-instructions.md)
|
||||
3. Search [docs/index.md](docs/index.md) for relevant documentation
|
||||
|
||||
**For AI agents:**
|
||||
- ALWAYS check `docs/index.md` before suggesting changes
|
||||
- ALWAYS verify against `.github/copilot-instructions.md` for critical patterns
|
||||
- ALWAYS update documentation when making changes
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
(TODO - Add license information)
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: December 4, 2025
|
||||
**Maintainers**: AI Agents (GitHub Copilot, Claude)
|
||||
Reference in New Issue
Block a user