# Requirements Document

## Intent Analysis Summary

- **User Request**: Run the full AI-DLC workflow on the brownfield data-service-infra-ai-configurations repository
- **Request Type**: Enhancement + Documentation + Test Coverage
- **Scope Estimate**: System-wide (all Python components)
- **Complexity Estimate**: Moderate (multiple components, multiple priorities)
- **Depth**: Standard (based on adaptive assessment)

## Background

This repository manages OpenClaw AI agent configurations for the Data Service Infra team at PingCAP. It contains:
- 13 cronjobs across 3 roles (team-admin, team-workflow, team-code-expert)
- 20+ agent skills across 4 teams
- 9+ Docker containers defined in docker-compose.yml
- Python scripts for scheduling, analysis, and automation

## Key Findings from Reverse Engineering

| Area | Finding | Impact |
|------|---------|--------|
| Test Coverage | Zero Python test files exist | Critical |
| Dependency Management | No pyproject.toml or requirements.txt | Medium |
| External Dependencies | Uses `requests` library (not stdlib only) | Medium |
| Code Quality | ruff configured but only for cronjobs/ | Low |
| Hardcoded Values | Feishu IDs, ports, timeouts hardcoded | Low |
| Type Safety | No type annotations in any Python file | Medium |

## Functional Requirements

### FR-1: Test Coverage
- **FR-1.1**: Add pytest-based unit tests for `run_cronjob_every_10mins.py` covering schedule matching, cron parsing, job execution, and Feishu notification logic
- **FR-1.2**: Add tests for existing cronjob main.py scripts (at minimum, smoke tests)
- **FR-1.3**: Configure CI/CD to run tests on pull requests

### FR-2: Dependency Management
- **FR-2.1**: Create `pyproject.toml` with all dependencies and versions
- **FR-2.2**: Ensure all cronjob scripts declare dependencies explicitly
- **FR-2.3**: Add `requirements-dev.txt` for development dependencies (pytest, ruff)

### FR-3: Code Quality Improvements
- **FR-3.1**: Add Python type annotations to `run_cronjob_every_10mins.py`
- **FR-3.2**: Move hardcoded constants (Feishu IDs, timeouts) to a config module
- **FR-3.3**: Add proper docstrings to all public functions
- **FR-3.4**: Fix ruff ignore patterns to cover all Python files (not just cronjobs/)

### FR-4: CI/CD Pipeline
- **FR-4.1**: Add GitHub Actions workflow for Python linting + tests
- **FR-4.2**: Add pre-commit validation for all Python files in repo

## Non-Functional Requirements

### NFR-1: Performance
- Cronjob scheduler must complete within 10 seconds for any single role's job list
- Individual job execution timeout: 600 seconds (configurable)

### NFR-2: Reliability
- Failed jobs must send Feishu notification
- Scheduler must handle missing config files gracefully
- Job execution must capture stdout/stderr for debugging

### NFR-3: Maintainability
- Python code target: 3.11+
- No external dependencies beyond `requests` for HTTP calls
- All credentials via environment variables (no hardcoding)

### NFR-4: Observability
- All cronjob executions logged to `~/CRONJOB_LOGS/cron_{YYYYMMDD}.log`
- Log format: `[timestamp] [agent_role] message`

### NFR-5: Security
- No credentials in code (all from env vars)
- Feishu tokens obtained per-request (no long-lived tokens)
- GitHub App auth for GitHub API access

## User Scenarios

### UC-1: Developer runs cronjob scheduler locally
1. Developer clones repo
2. Developer runs `python3 cronjobs/run_cronjob_every_10mins.py team-admin`
3. Scheduler matches scheduled jobs, executes matching commands
4. Results logged to ~/CRONJOB_LOGS/

### UC-2: Pull request triggers CI pipeline
1. Developer opens PR
2. GitHub Actions runs ruff linting on all Python files
3. GitHub Actions runs pytest on test suite
4. PR blocked if linting or tests fail

### UC-3: Adding a new cronjob
1. Developer adds job entry to `cronjobs/{role}/cronjob.json`
2. Developer creates the script in `cronjobs/{role}/`
3. Developer ensures ruff passes
4. Developer opens PR for review

## Acceptance Criteria

| ID | Criterion | Verification |
|----|-----------|-------------|
| AC-1 | `run_cronjob_every_10mins.py` has >80% test coverage | pytest --cov |
| AC-2 | pyproject.toml exists with requests, pytest deps | `pip install -e .` |
| AC-3 | ruff passes on all Python files | `ruff check .` |
| AC-4 | GitHub Actions CI runs on PRs | CI status on PR |
| AC-5 | No hardcoded Feishu IDs or ports in Python code | Code review |
| AC-6 | All public functions have type hints | ruff --select=ANN |