# V1 Django Baseline Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Build the smallest runnable Django baseline that satisfies the current Chinese requirements and design documents.

**Architecture:** Use a Django monolith with four apps (`scenarios`, `documents`, `chat`, `audit`) plus an independent `agent_core` package. The first implementation returns deterministic mock Agent results so the UI, audit, documents and module boundaries can be verified before real RAG/LLM integration.

**Tech Stack:** Python 3.13, Django 5.x, PyYAML, pytest, pytest-django, SQLite, Docker Compose.

---

## File Structure

- Create `requirements.txt`: runtime and test dependencies.
- Create `manage.py`, `config/settings.py`, `config/urls.py`, `config/wsgi.py`, `config/asgi.py`: Django project shell.
- Create `apps/scenarios/`: YAML scenario loading, homepage, tests.
- Create `apps/documents/`: upload model, upload/list/index views, text extraction, tests.
- Create `apps/chat/`: message form, chat view, Agent Core call, audit write, tests.
- Create `apps/audit/`: audit model, service, list/detail views, tests.
- Create `agent_core/`: dataclasses, orchestrator, mock RAG ingest/retrieve, tool registry, structured output parser.
- Create `configs/*.yaml`: five required scenarios.
- Create `templates/`: minimal Django Templates for pages.
- Create `Dockerfile`, `docker-compose.yml`, `.env.example`: one-command startup.

## Task 1: Dependencies and Django Project Shell

**Files:**
- Create: `requirements.txt`
- Create: `manage.py`
- Create: `config/__init__.py`
- Create: `config/settings.py`
- Create: `config/urls.py`
- Create: `config/wsgi.py`
- Create: `config/asgi.py`
- Test: `pytest.ini`

- [ ] **Step 1: Write failing configuration test**

Create `tests/test_project_configuration.py`:

```python
from django.conf import settings
from django.urls import reverse


def test_core_settings_expose_documented_paths():
    assert settings.SCENARIO_CONFIG_DIR.name == "configs"
    assert settings.CHROMA_PATH.name == "chroma"
    assert settings.MEDIA_ROOT.name == "uploads"


def test_home_url_is_registered(client):
    response = client.get(reverse("scenarios:index"))
    assert response.status_code == 200
```

- [ ] **Step 2: Run test to verify it fails**

Run: `pytest tests/test_project_configuration.py -q`
Expected: FAIL because Django project and apps do not exist.

- [ ] **Step 3: Implement minimal project shell**

Add dependencies and project files with settings for installed apps, templates, SQLite, media paths, and URL includes.

- [ ] **Step 4: Run test to verify progress**

Run: `pytest tests/test_project_configuration.py -q`
Expected: either PASS or fail only because `apps.scenarios` is not implemented yet.

## Task 2: Scenarios Module and Five YAML Configs

**Files:**
- Create: `apps/scenarios/services.py`
- Create: `apps/scenarios/views.py`
- Create: `apps/scenarios/urls.py`
- Create: `apps/scenarios/apps.py`
- Create: `configs/knowledge_qa.yaml`
- Create: `configs/document_review.yaml`
- Create: `configs/ticket_assistant.yaml`
- Create: `configs/quality_analysis.yaml`
- Create: `configs/risk_audit.yaml`
- Create: `templates/scenarios/index.html`
- Test: `tests/test_scenarios.py`

- [ ] **Step 1: Write failing scenario tests**

```python
from apps.scenarios.services import get_scenario, list_scenarios


def test_list_scenarios_loads_five_configs():
    scenarios = list_scenarios()
    assert [scenario["id"] for scenario in scenarios] == [
        "knowledge_qa",
        "document_review",
        "ticket_assistant",
        "quality_analysis",
        "risk_audit",
    ]


def test_get_scenario_returns_full_agent_config():
    scenario = get_scenario("quality_analysis")
    assert scenario["agent"]["role"]
    assert scenario["rag"]["enabled"] is True
    assert scenario["output"]["type"] == "quality_report"
```

- [ ] **Step 2: Run test to verify it fails**

Run: `pytest tests/test_scenarios.py -q`
Expected: FAIL because services/configs are missing.

- [ ] **Step 3: Implement scenario loader and homepage**

Use `yaml.safe_load()`, validate required fields, and render scenario cards on `/`.

- [ ] **Step 4: Run tests**

Run: `pytest tests/test_scenarios.py tests/test_project_configuration.py -q`
Expected: PASS.

## Task 3: Agent Core Mock Orchestrator

**Files:**
- Create: `agent_core/results.py`
- Create: `agent_core/orchestrator.py`
- Create: `agent_core/structured_output.py`
- Create: `agent_core/tool_registry.py`
- Create: `agent_core/tools/builtin_tools.py`
- Create: `agent_core/rag/ingest.py`
- Create: `agent_core/rag/retriever.py`
- Test: `tests/test_agent_core.py`

- [ ] **Step 1: Write failing Agent Core tests**

```python
from agent_core.orchestrator import run_agent


def test_run_agent_returns_structured_mock_result():
    scenario = {
        "id": "knowledge_qa",
        "name": "知识库问答助手",
        "rag": {"enabled": True, "collection": "knowledge_qa", "top_k": 3},
        "tools": ["generate_action_items"],
        "output": {"type": "general_answer"},
    }
    result = run_agent(scenario, "如何处理异常？")
    assert result.status == "success"
    assert result.answer
    assert result.structured_output["output_type"] == "general_answer"
    assert result.tool_calls[0]["tool_name"] == "generate_action_items"
```

- [ ] **Step 2: Run test to verify it fails**

Run: `pytest tests/test_agent_core.py -q`
Expected: FAIL because `agent_core` is missing.

- [ ] **Step 3: Implement deterministic mock AgentResult**

Return stable answer, references, tool calls, model name `mock-model`, and latency.

- [ ] **Step 4: Run tests**

Run: `pytest tests/test_agent_core.py -q`
Expected: PASS.

## Task 4: Audit Module

**Files:**
- Create: `apps/audit/models.py`
- Create: `apps/audit/services.py`
- Create: `apps/audit/views.py`
- Create: `apps/audit/urls.py`
- Create: `apps/audit/admin.py`
- Create: `templates/audit/log_list.html`
- Create: `templates/audit/log_detail.html`
- Test: `tests/test_audit.py`

- [ ] **Step 1: Write failing audit tests**

```python
from apps.audit.models import AgentAuditLog
from apps.audit.services import create_audit_log
from agent_core.results import AgentResult


def test_create_audit_log_records_success_result(db):
    result = AgentResult(answer="回答", structured_output={"x": 1}, status="success")
    log = create_audit_log("knowledge_qa", "知识库问答助手", "问题", result)
    assert AgentAuditLog.objects.count() == 1
    assert log.final_answer == "回答"
    assert log.structured_output == {"x": 1}
```

- [ ] **Step 2: Run test to verify it fails**

Run: `pytest tests/test_audit.py -q`
Expected: FAIL because audit app is missing.

- [ ] **Step 3: Implement model, service, admin, views**

Use JSONField defaults and avoid storing sensitive environment values.

- [ ] **Step 4: Run migrations and tests**

Run: `python manage.py makemigrations audit && pytest tests/test_audit.py -q`
Expected: PASS.

## Task 5: Documents Module

**Files:**
- Create: `apps/documents/models.py`
- Create: `apps/documents/services.py`
- Create: `apps/documents/forms.py`
- Create: `apps/documents/views.py`
- Create: `apps/documents/urls.py`
- Create: `apps/documents/admin.py`
- Create: `templates/documents/document_list.html`
- Create: `templates/documents/upload.html`
- Test: `tests/test_documents.py`

- [ ] **Step 1: Write failing document tests**

```python
from django.core.files.uploadedfile import SimpleUploadedFile
from django.urls import reverse

from apps.documents.models import UploadedDocument


def test_upload_txt_document_creates_uploaded_record(client, db):
    file = SimpleUploadedFile("rules.txt", "hello".encode("utf-8"), content_type="text/plain")
    response = client.post(reverse("documents:upload"), {"scenario_id": "knowledge_qa", "file": file})
    assert response.status_code == 302
    document = UploadedDocument.objects.get()
    assert document.status == "uploaded"
    assert document.file_type == "txt"
```

- [ ] **Step 2: Run test to verify it fails**

Run: `pytest tests/test_documents.py -q`
Expected: FAIL because documents app is missing.

- [ ] **Step 3: Implement upload/list/index flow**

Support `.txt` and `.md`; index action calls `agent_core.rag.ingest.ingest_document()` and updates status.

- [ ] **Step 4: Run migrations and tests**

Run: `python manage.py makemigrations documents && pytest tests/test_documents.py -q`
Expected: PASS.

## Task 6: Chat Module

**Files:**
- Create: `apps/chat/forms.py`
- Create: `apps/chat/views.py`
- Create: `apps/chat/urls.py`
- Create: `apps/chat/apps.py`
- Create: `templates/chat/index.html`
- Test: `tests/test_chat.py`

- [ ] **Step 1: Write failing chat tests**

```python
from django.urls import reverse

from apps.audit.models import AgentAuditLog


def test_chat_post_returns_agent_result_and_audit_log(client, db):
    response = client.post(reverse("chat:index", args=["knowledge_qa"]), {"message": "如何处理异常？"})
    assert response.status_code == 200
    assert "mock-model" in response.content.decode("utf-8")
    assert AgentAuditLog.objects.count() == 1
```

- [ ] **Step 2: Run test to verify it fails**

Run: `pytest tests/test_chat.py -q`
Expected: FAIL because chat app is missing.

- [ ] **Step 3: Implement chat form and view**

Validate message, call `get_scenario()`, `run_agent()`, then `create_audit_log()`.

- [ ] **Step 4: Run tests**

Run: `pytest tests/test_chat.py tests/test_audit.py tests/test_agent_core.py -q`
Expected: PASS.

## Task 7: Docker and Documentation Alignment

**Files:**
- Create: `.env.example`
- Create: `Dockerfile`
- Create: `docker-compose.yml`
- Modify: `README.md`
- Test: all tests and Django checks.

- [ ] **Step 1: Add deployment files**

Use a single web service, install `requirements.txt`, run migrations, and serve `0.0.0.0:8000`.

- [ ] **Step 2: Verify Django and tests**

Run:

```bash
python manage.py check
pytest -q
```

Expected: all checks pass.

- [ ] **Step 3: Verify docs path references**

Run:

```powershell
$patterns = @('docs/需求分析', 'docs/设计文档', 'V1总需求文档', '智能体总体设计')
Get-ChildItem -Recurse -File |
  Where-Object {
    $_.FullName -notlike '*\.git\*' -and
    $_.FullName -notlike '*\.idea\*' -and
    $_.FullName -notlike '*docs\superpowers\plans\2026-05-29-v1-django-baseline.md'
  } |
  Select-String -Pattern $patterns
```

Expected: no matches.

## Self-Review

- Spec coverage: The plan covers Chinese docs, five scenario configs, Django startup, homepage, chat, audit, documents, Agent Core, and Docker baseline.
- Placeholder scan: No implementation step relies on an undefined placeholder; mock LLM/RAG is intentionally scoped as the first runnable baseline.
- Type consistency: Tests use `AgentResult`, `run_agent`, `list_scenarios`, `get_scenario`, `UploadedDocument`, and `AgentAuditLog` consistently.