Skip to content

Latest commit

 

History

History
131 lines (96 loc) · 5.5 KB

REQUIREMENTS_STAGE_2.md

File metadata and controls

131 lines (96 loc) · 5.5 KB

Software Requirements Specification (SRS)

Civil War General - Stage 2: AI-Driven Tactical Analysis

Document Information

  • Project Name: Civil War General
  • Document Version: 1.0
  • Date: January 17, 2026
  • Author: Development Team
  • Document Type: Software Requirements Specification
  • Stage: Stage 2 - AI-Driven Tactical Analysis

1. Introduction

1.1 Purpose

This document specifies the functional and non-functional requirements for Stage 2 of the Civil War General application. Stage 2 transitions the application from a simple random command generator to an intelligent tactical advisor that considers battlefield context.

1.2 Scope

Stage 2 introduces an AI-driven selection engine that evaluates situational data—specifically battlefield conditions and troop states—to recommend the most appropriate tactical orders. This stage involves extending the data models, enhancing the UI to capture context, and implementing logic-based selection algorithms.

1.3 Definitions and Acronyms

  • AI Selection: The process of choosing an order based on weighted logic and environmental variables.
  • Battlefield Condition: Environmental factors (weather, terrain, visibility) affecting combat.
  • Troop State: The condition of a military unit (morale, fatigue, supply level).
  • Weighting: The importance assigned to a specific condition when calculating the suitability of an order.

2. Overall Description

2.1 Product Perspective

Stage 2 builds directly upon the MVP architecture established in Stage 1. It replaces the SecureRandom selection logic with a context-aware TacticalAISelector while maintaining the core UI and order management foundations.

2.2 Product Functions

  • Capture and manage battlefield conditions (e.g., Rain, Fog, Heat).
  • Capture and manage troop states (e.g., High Morale, Low Supplies, Exhausted).
  • Perform weighted tactical analysis to select orders.
  • Provide reasoning for the AI's selection.
  • Persist environmental settings across selections within a session.

3. System Features

3.1 Contextual Data Management

3.1.1 Functional Requirements

  • REQ-034: The system shall support a set of Battlefield Conditions:
    • Weather (Clear, Rain, Snow, Fog)
    • Terrain (Open, Forest, Hill, Swamp)
    • Time of Day (Day, Night)
  • REQ-035: The system shall support a set of Troop States:
    • Morale (High, Average, Low)
    • Fatigue (Fresh, Weary, Exhausted)
    • Supply Level (Plentiful, Limited, Critical)
  • REQ-036: The system shall allow the user to toggle these conditions via the UI.

3.2 AI Tactical Selection Engine

3.2.1 Description

The CommandSelector interface shall be extended or implemented to provide logic-based selection instead of pure randomization.

3.2.2 Functional Requirements

  • REQ-037: The AI shall assign "Suitability Weights" to orders based on current conditions.
    • Example: "Attack Forward" weight decreases in "Swamp" or "Exhausted" state.
    • Example: "Defend Forward" weight increases in "Forest" or "Low Supply".
  • REQ-038: The AI shall select the order with the highest suitability score.
  • REQ-039: If multiple orders have equal highest scores, the system shall randomly pick between them using the Stage 1 secure random logic.
  • REQ-040: The system shall handle "Impossible" scenarios (where no order is suitable) by returning a "Hold Position" or default fallback.

3.3 Enhanced User Interface

3.3.1 Functional Requirements

  • REQ-041: The UI shall include a "Tactical Context" panel.
  • REQ-042: The context panel shall use ComboBoxes or RadioButtons for selecting conditions and states.
  • REQ-043: The UI shall display the "Reasoning" behind an AI selection (e.g., "Selected 'Retreat' due to Critical Supplies and Exhausted troops").
  • REQ-044: The history list shall record the conditions present at the time the command was generated.

4. Non-Functional Requirements

4.1 Performance

  • REQ-045: AI selection logic shall compute within 200 milliseconds.
  • REQ-046: UI updates for condition toggles shall be instantaneous (< 50ms).

4.2 Maintainability

  • REQ-047: AI logic shall be externalized in a strategy pattern to allow for future "Personalities" (e.g., Aggressive vs. Defensive General).
  • REQ-048: Condition-Order mappings shall be configurable via JSON.

5. System Architecture (Stage 2)

5.1 Pattern Updates

The system continues using MVP but introduces:

  • Strategy Pattern: For different AI selection behaviors.
  • Observer Pattern: To notify the Presenter when UI conditions change.

5.2 Updated Data Model

  • Order is extended with Map<String, Integer> weights.
  • TacticalContext class introduced to encapsulate battlefield and troop data.

6. Acceptance Criteria

6.1 Functional Acceptance

  • Users can change battlefield conditions in the UI.
  • AI selects different orders when conditions significantly change.
  • The history log shows the context (e.g., Weather, Morale) for each entry.
  • Selection reasoning is displayed to the user.

6.2 Quality Acceptance

  • Unit tests cover 100% of the new AI scoring logic.
  • Integration tests verify that UI condition changes correctly affect the selection output.
  • Javadoc is applied to all new Stage 2 classes and methods.

Document Approval

Role Name Signature Date
Product Owner
Lead Developer
QA Lead
Project Manager