app/templates/rics_templates.py

"""RICS Level 3 Building Survey — section templates.

Section codes, titles, skeleton text, and expected input fields are based on:
  • The official RICS Home Survey Standard (2019 edition)
  • Real Level 3 Building Survey reports issued by Arnold & Baldwin Chartered
    Surveyors (surveyor: Behrang Dizaji MRICS, RICS number 5044891)

The canonical RICS Level 3 structure is:
  A   Introduction to the report
  B   About the inspection
  C   Overall assessment and summary of condition ratings
  D   About the property
  E1–E9   Outside the property
  F1–F9   Inside the property
  G1–G8   Services
  H1–H3   Grounds (including shared areas for flats)
  I1–I3   Issues for your legal advisers
  J1–J4   Risks
  K1–K5   Energy efficiency
  L   Surveyor's declaration

Condition ratings used in elements E–H:
  1  No repair currently needed. The property must be maintained in the
     normal way.
  2  Defects that need repairing or replacing but are not considered to be
     either serious or urgent.
  3  Defects that are serious and/or need to be repaired, replaced or
     investigated urgently.
  NI Not inspected.

IMPORTANT: These templates are samples for AI-assisted drafting.  All
generated text must be reviewed and verified by a qualified RICS surveyor
before use.  Nothing herein constitutes professional surveying advice.
"""

from pydantic import BaseModel


class SectionTemplate(BaseModel):
    """A single RICS report section template.

    Attributes:
        code: Short section identifier (e.g. ``"E1"``).
        title: Human-readable section title (matches official RICS wording).
        group: Parent section letter (``"E"``, ``"F"`` …) for grouping in UI.
        has_condition_rating: Whether this element carries a 1/2/3/NI rating.
        skeleton: Placeholder prose handed to the LLM as a structural target.
        expected_fields: Bullet-point data fields the surveyor should supply.
    """

    code: str
    title: str
    group: str
    has_condition_rating: bool = False
    skeleton: str
    expected_fields: list[str]


# ── Section definitions (canonical RICS order) ────────────────────────────────

_TEMPLATES: list[SectionTemplate] = [

    # ── A: Introduction to the report ────────────────────────────────────────
    SectionTemplate(
        code="A",
        title="Introduction to the report",
        group="A",
        has_condition_rating=False,
        skeleton=(
            "This Building Survey report has been prepared in accordance with the "
            "signed Terms and Conditions of Engagement. It is pointed out this is a "
            "general building survey report on the property and not a Schedule of "
            "Condition which would list every minor defect. It is a report intended "
            "to give a general opinion as to the condition of the property, and to "
            "enable you to plan for future maintenance.\n\n"
            "Most clients find it useful to read the Surveyor's Overall Opinion "
            "section at the beginning of the report first, to gain a general overview "
            "of the most significant matters; however it is essential the whole report "
            "is read and considered in detail. Prior to legal commitment to purchase, "
            "you should conclude all of the further investigations we have recommended "
            "and have these and all the repairs priced so you are fully aware of the "
            "financial commitment you will be entering into when purchasing the property.\n\n"
            "This report has been prepared solely for the benefit of [client_name]. "
            "No liability is accepted to any third party."
        ),
        expected_fields=[
            "client_name",
            "report_reference",
            "surveyor_name",
            "company_name",
            "inspection_date",
            "related_party_disclosure",
        ],
    ),

    # ── B: About the inspection ───────────────────────────────────────────────
    SectionTemplate(
        code="B",
        title="About the inspection",
        group="B",
        has_condition_rating=False,
        skeleton=(
            "Full address and postcode of the property: [property_address]\n\n"
            "Weather conditions when the inspection took place: [weather_conditions]\n\n"
            "The status of the property when the inspection took place: [property_status] "
            "It must be appreciated that floor coverings, fixed units and unmoved "
            "furniture precluded inspection of hidden areas.\n\n"
            "All references in this report to right and left are to be taken as if the "
            "property is being viewed from the road."
        ),
        expected_fields=[
            "property_address",
            "weather_conditions",
            "property_status",
            "occupation_status",
            "access_limitations",
        ],
    ),

    # ── C: Overall assessment and summary of condition ratings ────────────────
    SectionTemplate(
        code="C",
        title="Overall assessment and summary of condition ratings",
        group="C",
        has_condition_rating=False,
        skeleton=(
            "Overall Opinion\n\n"
            "[overall_opinion]\n\n"
            "The property is [property_description] which has been maintained to "
            "[maintenance_standard] for properties of this age and type.\n\n"
            "We [are/are not] pleased to report that this property is considered to be "
            "a reasonable proposition for purchase if potential buyers are prepared to "
            "accept the cost and inconvenience of dealing with the various repair and "
            "improvement works reported.\n\n"
            "The property was constructed [circa_year] and is therefore approximately "
            "[age] years old. With any property of this age there is going to be an "
            "element of risk involved with the purchase.\n\n"
            "Further investigations recommended prior to legal commitment to purchase:\n"
            "[further_investigations]"
        ),
        expected_fields=[
            "overall_opinion",
            "property_description",
            "maintenance_standard",
            "construction_year",
            "condition_3_elements",
            "condition_2_elements",
            "condition_1_elements",
            "further_investigations",
        ],
    ),

    # ── D: About the property ─────────────────────────────────────────────────
    SectionTemplate(
        code="D",
        title="About the property",
        group="D",
        has_condition_rating=False,
        skeleton=(
            "Type of property: [property_type]. [orientation]\n\n"
            "Approximate year the property was built: [build_year]\n\n"
            "Approximate year the property was extended: [extension_info]\n\n"
            "Approximate year the property was converted: [conversion_info]\n\n"
            "Accommodation: [accommodation_schedule]\n\n"
            "Construction: [construction_description]\n\n"
            "Means of escape: [means_of_escape]\n\n"
            "Security: [security_description]\n\n"
            "Services: Gas — [mains/other]. Electricity — [mains/other]. "
            "Water — [mains/other]. Drainage — [mains/other].\n\n"
            "Central heating: [heating_type]\n\n"
            "Energy: [epc_rating_info]\n\n"
            "Grounds: [grounds_description]\n\n"
            "Location: [location_description]\n\n"
            "Facilities: [facilities_description]\n\n"
            "Local Environment: [local_environment]\n\n"
            "Other Local Factors: [other_local_factors]"
        ),
        expected_fields=[
            "property_type",
            "storey_count",
            "orientation",
            "build_year",
            "extension_year",
            "conversion_info",
            "flat_info",
            "accommodation_schedule",
            "roof_construction",
            "wall_construction",
            "floor_construction",
            "ceiling_construction",
            "means_of_escape",
            "security_description",
            "services_mains",
            "central_heating_type",
            "epc_rating",
            "grounds_description",
            "location_description",
            "facilities",
            "local_environment",
        ],
    ),

    # ── E: Outside the property ───────────────────────────────────────────────

    SectionTemplate(
        code="E1",
        title="Chimney stacks",
        group="E",
        has_condition_rating=True,
        skeleton=(
            "[chimney_present_or_none]. [chimney_construction_description]\n\n"
            "[aerial_description]\n\n"
            "Chimney stacks are particularly exposed to the weather and so regular "
            "maintenance must be carried out to ensure their stability and weather "
            "tightness. Chimney repairs tend to be expensive due to the associated "
            "scaffolding costs.\n\n"
            "[defect_description] Condition Rating [1/2/3/NI]."
        ),
        expected_fields=[
            "chimney_present",
            "chimney_construction",
            "pots_flaunchings",
            "flashings_condition",
            "aerial_fixings",
            "lean_or_movement",
            "condition_rating",
        ],
    ),

    SectionTemplate(
        code="E2",
        title="Roof coverings",
        group="E",
        has_condition_rating=True,
        skeleton=(
            "Main roof: The main roof is [roof_structure] structure, covered with "
            "[roof_covering_material].\n\n"
            "[defect_description]\n\n"
            "[extension_roof_description]\n\n"
            "[dormer_description]\n\n"
            "The observed roof coverings [otherwise appear/are] in a [condition] state "
            "of repair [with/with no] significant defects noted. Condition Rating "
            "[1/2/3/NI]."
        ),
        expected_fields=[
            "main_roof_structure",
            "main_roof_covering",
            "slipped_tiles_or_slates",
            "deflection_sagging",
            "moss_lichen",
            "valley_gutters",
            "roof_lights_dormers",
            "flat_roof_covering",
            "extension_roof",
            "condition_rating",
        ],
    ),

    SectionTemplate(
        code="E3",
        title="Rainwater pipes and gutters",
        group="E",
        has_condition_rating=True,
        skeleton=(
            "Defective rainwater goods are a very common cause of dampness which can "
            "lead to deterioration in building fabric and the development of rot in "
            "timbers. Regular inspection and adequate maintenance are therefore "
            "essential if serious problems such as dry rot are to be avoided.\n\n"
            "Rainwater fittings are formed in [material] and comprise [gutter_type] "
            "gutters supported on brackets fixed to fascia boards and served by "
            "downpipes fixed vertically to wall faces.\n\n"
            "[inspection_note_if_dry]\n\n"
            "[defect_description] Condition Rating [1/2/3].\n\n"
            "Gutters should be cleaned on a regular basis to avoid blockage."
        ),
        expected_fields=[
            "material",
            "gutter_type",
            "staining_evidence",
            "blockage",
            "joint_failure",
            "downpipe_discharge",
            "shared_with_neighbour",
            "condition_rating",
        ],
    ),

    SectionTemplate(
        code="E4",
        title="Main walls",
        group="E",
        has_condition_rating=True,
        skeleton=(
            "The main walls are believed to be built of [wall_construction], with "
            "measurements through openings of approximately [wall_thickness]mm.\n\n"
            "[cavity_or_solid_note]\n\n"
            "A damp proof course (DPC) is a waterproof layer built in or formed within "
            "the walls to prevent ground dampness from rising. [dpc_description]\n\n"
            "[movement_cracking_description]\n\n"
            "[damp_staining_description]\n\n"
            "[parapet_walls]\n\n"
            "External elevations are [otherwise] in generally [condition] condition. "
            "[movement_summary] Condition Rating [1/2/3]."
        ),
        expected_fields=[
            "wall_construction",
            "wall_thickness",
            "cavity_or_solid",
            "dpc_type",
            "dpc_height",
            "cracking_description",
            "movement_signs",
            "damp_penetration",
            "pointing_condition",
            "render_condition",
            "parapet_walls",
            "condition_rating",
        ],
    ),

    SectionTemplate(
        code="E5",
        title="Windows",
        group="E",
        has_condition_rating=True,
        skeleton=(
            "The windows are of [window_type] construction.\n\n"
            "It is recommended that waterproof seals are maintained between window "
            "frames and adjacent walls in order to minimise the risk of damp "
            "penetration.\n\n"
            "[double_glazing_certification_note]\n\n"
            "[condensation_between_panes_note]\n\n"
            "[decay_or_damage_description]\n\n"
            "Their general condition is [condition]. Condition Rating [1/2/3/NI]."
        ),
        expected_fields=[
            "window_type",
            "glazing_type",
            "fensa_certification",
            "condensation_between_panes",
            "frame_decay",
            "seal_condition",
            "safety_glass",
            "condition_rating",
        ],
    ),

    SectionTemplate(
        code="E6",
        title="Outside doors (including patio doors)",
        group="E",
        has_condition_rating=True,
        skeleton=(
            "The entrance door is of [entrance_door_construction] construction. "
            "[patio_door_description]\n\n"
            "It is recommended that waterproof seals are maintained between door "
            "frames and adjacent walls in order to minimise the risk of damp "
            "penetration.\n\n"
            "[glazing_and_safety_glass_note]\n\n"
            "[defect_description]\n\n"
            "Their general condition is [condition]. Condition Rating [1/2/3/NI]."
        ),
        expected_fields=[
            "entrance_door_material",
            "patio_door_type",
            "glazing_type",
            "safety_glass",
            "seal_condition",
            "security_locks",
            "frame_condition",
            "condition_rating",
        ],
    ),

    SectionTemplate(
        code="E7",
        title="Conservatory and porches",
        group="E",
        has_condition_rating=True,
        skeleton=(
            "[conservatory_present_note]\n\n"
            "[construction_type_if_present]\n\n"
            "[mould_condensation_movement_note]\n\n"
            "Condition Rating [1/2/3/NI]."
        ),
        expected_fields=[
            "conservatory_present",
            "porch_present",
            "construction_type",
            "glazing_type",
            "condensation_mould",
            "structural_movement",
            "condition_rating",
        ],
    ),

    SectionTemplate(
        code="E8",
        title="Other joinery and finishes",
        group="E",
        has_condition_rating=True,
        skeleton=(
            "All exterior timber work should be carefully checked for decay when "
            "redecoration is carried out, and repairs undertaken as found to be "
            "necessary. The external paintwork should be maintained to a good "
            "standard to reduce the dangers of timber decay.\n\n"
            "[fascia_soffit_description]\n\n"
            "[asbestos_soffit_note]\n\n"
            "[mock_features_note]\n\n"
            "Condition Rating [1/2/3/NI]."
        ),
        expected_fields=[
            "fascia_material",
            "soffit_material",
            "rot_decay",
            "asbestos_containing_materials",
            "decorative_features",
            "paintwork_condition",
            "condition_rating",
        ],
    ),

    SectionTemplate(
        code="E9",
        title="Other (external elements)",
        group="E",
        has_condition_rating=True,
        skeleton=(
            "[other_external_elements_description]\n\n"
            "[made_ground_contamination_note]\n\n"
            "[loft_conversion_legal_note]\n\n"
            "Condition Rating [1/2/3/NI]."
        ),
        expected_fields=[
            "balconies_terraces",
            "external_stairways",
            "loft_conversion",
            "made_ground_note",
            "contaminated_land_note",
            "condition_rating",
        ],
    ),

    # ── F: Inside the property ────────────────────────────────────────────────

    SectionTemplate(
        code="F1",
        title="Roof structure",
        group="F",
        has_condition_rating=True,
        skeleton=(
            "Where there is safe and reasonable access via hatches not more than "
            "3 metres above floor level, the surveyor entered the roof space using "
            "a ladder.\n\n"
            "The roof structure is of [roof_structure_type] construction. [truss_or_cut]\n\n"
            "[insulation_description]\n\n"
            "[ventilation_description]\n\n"
            "[wood_boring_insects_note]\n\n"
            "[damp_or_rot_description]\n\n"
            "[birds_vermin_note]\n\n"
            "[conversion_note]\n\n"
            "Condition Rating [1/2/3/NI]."
        ),
        expected_fields=[
            "roof_access",
            "roof_structure_type",
            "truss_or_cut_rafter",
            "insulation_type",
            "insulation_depth",
            "ventilation_adequacy",
            "wood_boring_insects",
            "rot_or_damp",
            "birds_bats_vermin",
            "loft_converted",
            "condition_rating",
        ],
    ),

    SectionTemplate(
        code="F2",
        title="Ceilings",
        group="F",
        has_condition_rating=True,
        skeleton=(
            "Ceilings within the property are of [ceiling_type] construction.\n\n"
            "[crack_description]\n\n"
            "[damp_staining]\n\n"
            "[asbestos_note]\n\n"
            "[lath_plaster_note]\n\n"
            "[general_condition] Condition Rating [1/2/3/NI]."
        ),
        expected_fields=[
            "ceiling_type",
            "cracking",
            "damp_staining",
            "asbestos_risk",
            "lath_plaster",
            "decorative_condition",
            "condition_rating",
        ],
    ),

    SectionTemplate(
        code="F3",
        title="Walls and partitions",
        group="F",
        has_condition_rating=True,
        skeleton=(
            "The surveyor will visually inspect walls and partitions from floor "
            "level. Using a damp meter, walls will be tested for dampness where "
            "appropriate and free from obstructions.\n\n"
            "The walls are of [wall_type] construction.\n\n"
            "[damp_meter_readings]\n\n"
            "[cracking_description]\n\n"
            "[structural_alterations_note]\n\n"
            "[dry_lining_note]\n\n"
            "[asbestos_note]\n\n"
            "Condition Rating [1/2/3/NI]."
        ),
        expected_fields=[
            "wall_construction_type",
            "damp_meter_readings",
            "rising_damp",
            "penetrating_damp",
            "cracking",
            "structural_alterations",
            "dry_lining",
            "asbestos_risk",
            "condition_rating",
        ],
    ),

    SectionTemplate(
        code="F4",
        title="Floors",
        group="F",
        has_condition_rating=True,
        skeleton=(
            "Surfaces of exposed floors were visually inspected. No carpets, floor "
            "coverings or floorboards were lifted.\n\n"
            "Ground floor: [ground_floor_type] construction. [ground_floor_condition]\n\n"
            "Upper floors: [upper_floor_type] construction. [upper_floor_condition]\n\n"
            "[sub_floor_ventilation_note]\n\n"
            "[wood_boring_insects_note]\n\n"
            "[damp_note]\n\n"
            "Condition Rating [1/2/3/NI]."
        ),
        expected_fields=[
            "ground_floor_construction",
            "upper_floor_construction",
            "sub_floor_ventilation",
            "wood_boring_insects",
            "damp_below_floor",
            "cracking_solid_floor",
            "springiness",
            "floor_covering_type",
            "condition_rating",
        ],
    ),

    SectionTemplate(
        code="F5",
        title="Fireplaces, chimney breasts and flues",
        group="F",
        has_condition_rating=True,
        skeleton=(
            "[fireplaces_present_note]\n\n"
            "No testing of flues or fittings was carried out.\n\n"
            "[blocked_fireplace_note]\n\n"
            "[chimney_breast_removal_note]\n\n"
            "[solid_fuel_fireplace_advice]\n\n"
            "Condition Rating [1/2/3/NI]."
        ),
        expected_fields=[
            "fireplaces_present",
            "fireplace_type",
            "blocked_fireplaces",
            "chimney_breast_removed",
            "building_regs_approval",
            "flue_liner",
            "condition_rating",
        ],
    ),

    SectionTemplate(
        code="F6",
        title="Built-in fittings",
        group="F",
        has_condition_rating=True,
        skeleton=(
            "The built-in fittings comprise [description_of_fitted_elements].\n\n"
            "[adequacy_and_condition]\n\n"
            "[damp_or_insects_note]\n\n"
            "Condition Rating [1/2/3/NI]."
        ),
        expected_fields=[
            "fitted_wardrobes",
            "fitted_kitchen_units",
            "built_in_storage",
            "damp_wood_boring_insects",
            "general_condition",
            "condition_rating",
        ],
    ),

    SectionTemplate(
        code="F7",
        title="Woodwork (e.g. staircase and joinery)",
        group="F",
        has_condition_rating=True,
        skeleton=(
            "During the inspection of the woodwork, the surveyor assessed the general "
            "condition of the doors, stairs and other joinery.\n\n"
            "The staircase is of [staircase_construction] construction. [staircase_condition]\n\n"
            "[internal_doors_condition]\n\n"
            "[skirtings_architraves_condition]\n\n"
            "[wood_boring_beetle_note]\n\n"
            "[damp_note]\n\n"
            "Condition Rating [1/2/3/NI]."
        ),
        expected_fields=[
            "staircase_construction",
            "staircase_condition",
            "internal_doors",
            "skirtings_architraves",
            "wood_boring_beetle",
            "damp_signs",
            "decoration_standard",
            "condition_rating",
        ],
    ),

    SectionTemplate(
        code="F8",
        title="Bathroom and kitchen fittings",
        group="F",
        has_condition_rating=True,
        skeleton=(
            "During the inspection, built-in cupboards were looked into but no stored "
            "items were moved. Kitchen units were visually inspected excluding "
            "appliances.\n\n"
            "Bathroom: [bathroom_description]\n\n"
            "Kitchen: [kitchen_description]\n\n"
            "[condensation_damp_note]\n\n"
            "[visible_defects_note]\n\n"
            "Condition Rating [1/2/3/NI]."
        ),
        expected_fields=[
            "bathroom_suite_type",
            "bathroom_condition",
            "kitchen_units_condition",
            "condensation_damp",
            "tile_condition",
            "ventilation",
            "visible_defects_breakages",
            "condition_rating",
        ],
    ),

    SectionTemplate(
        code="F9",
        title="Other (e.g. integral garages, cellars, loft conversions)",
        group="F",
        has_condition_rating=True,
        skeleton=(
            "[cellar_basement_description]\n\n"
            "[integral_garage_description]\n\n"
            "[loft_conversion_description]\n\n"
            "[asbestos_note]\n\n"
            "[damp_flooding_note]\n\n"
            "Condition Rating [1/2/3/NI]."
        ),
        expected_fields=[
            "cellar_present",
            "integral_garage",
            "loft_conversion",
            "asbestos_risk",
            "damp_flooding",
            "construction_type",
            "condition_rating",
        ],
    ),

    # ── G: Services ───────────────────────────────────────────────────────────

    SectionTemplate(
        code="G1",
        title="Electricity",
        group="G",
        has_condition_rating=True,
        skeleton=(
            "Safety warning: The Electrical Safety Council recommends that you should "
            "get a registered electrician to check the property and its electrical "
            "fittings at least every ten years, or on change of occupancy.\n\n"
            "Electricity is supplied to the property from [supply_description]. "
            "[consumer_unit_location] The consumer unit is of [consumer_unit_type] type.\n\n"
            "[wiring_description]\n\n"
            "[test_recommendation]\n\n"
            "A test of the electrical installation by an NAPIT or NICEIC affiliated "
            "electrician is recommended prior to legal commitment to purchase. "
            "Condition Rating [1/2/3]."
        ),
        expected_fields=[
            "supply_type",
            "consumer_unit_location",
            "consumer_unit_type",
            "wiring_type",
            "earthing",
            "rcd_protection",
            "test_certificate_date",
            "condition_rating",
        ],
    ),

    SectionTemplate(
        code="G2",
        title="Gas/oil",
        group="G",
        has_condition_rating=True,
        skeleton=(
            "Safety warning: All gas and oil appliances and equipment should regularly "
            "be inspected, tested, maintained and serviced by a registered competent "
            "person in line with the manufacturer's instructions.\n\n"
            "[gas_supply_description]\n\n"
            "[meter_location]\n\n"
            "[visible_pipework_condition]\n\n"
            "A test of the gas installation by a Gas Safe qualified engineer is "
            "recommended prior to legal commitment to purchase. "
            "Condition Rating [1/2/3/NI]."
        ),
        expected_fields=[
            "gas_supply_type",
            "meter_location",
            "pipework_material",
            "pipework_condition",
            "gas_safe_certificate",
            "condition_rating",
        ],
    ),

    SectionTemplate(
        code="G3",
        title="Water",
        group="G",
        has_condition_rating=True,
        skeleton=(
            "Accessible parts of the water system were visually inspected without "
            "removing or undoing fittings. No tests were carried out.\n\n"
            "The water supply is from [supply_source]. The internal stopcock is "
            "located [stopcock_location]. The external stopcock is located "
            "[external_stopcock_location].\n\n"
            "[pipework_description]\n\n"
            "[leakage_evidence]\n\n"
            "[shared_supply_note]\n\n"
            "Condition Rating [1/2/3]."
        ),
        expected_fields=[
            "supply_source",
            "stopcock_location",
            "external_stopcock",
            "pipework_material",
            "leakage_evidence",
            "water_pressure",
            "shared_supply",
            "condition_rating",
        ],
    ),

    SectionTemplate(
        code="G4",
        title="Heating",
        group="G",
        has_condition_rating=True,
        skeleton=(
            "No tests to the system or appliances were carried out.\n\n"
            "The property is heated by [heating_system_type]. The boiler is a "
            "[boiler_make_model] located [boiler_location].\n\n"
            "[controls_description]\n\n"
            "[radiators_condition]\n\n"
            "[service_history]\n\n"
            "A test of the heating installation by a Gas Safe qualified heating "
            "engineer is recommended prior to legal commitment to purchase. "
            "Condition Rating [1/2/3]."
        ),
        expected_fields=[
            "heating_type",
            "boiler_make",
            "boiler_age",
            "boiler_location",
            "last_service_date",
            "controls_type",
            "radiators_condition",
            "condition_rating",
        ],
    ),

    SectionTemplate(
        code="G5",
        title="Water heating",
        group="G",
        has_condition_rating=True,
        skeleton=(
            "Accessible parts of the water heating system were visually inspected. "
            "No tests were carried out to the system or appliances.\n\n"
            "[hot_water_system_description]\n\n"
            "[cylinder_tank_description]\n\n"
            "[solar_panel_note]\n\n"
            "Condition Rating [1/2/3/NI]."
        ),
        expected_fields=[
            "hot_water_system_type",
            "cylinder_condition",
            "immersion_heater",
            "solar_panels",
            "condition_rating",
        ],
    ),

    SectionTemplate(
        code="G6",
        title="Drainage",
        group="G",
        has_condition_rating=True,
        skeleton=(
            "Chambers were visually inspected from ground level where it was safe "
            "and reasonable for the surveyor to lift the cover(s). The drains and "
            "drainage systems were not tested.\n\n"
            "[drain_cover_description]\n\n"
            "[soil_vent_pipe_description]\n\n"
            "[shared_drainage_note]\n\n"
            "[blockage_evidence]\n\n"
            "[septic_tank_note]\n\n"
            "Condition Rating [1/2/3/NI]."
        ),
        expected_fields=[
            "drain_covers_lifted",
            "drain_condition",
            "soil_vent_pipe",
            "shared_drainage",
            "blockage_evidence",
            "septic_tank",
            "condition_rating",
        ],
    ),

    SectionTemplate(
        code="G7",
        title="Common services (flats only)",
        group="G",
        has_condition_rating=True,
        skeleton=(
            "[not_applicable_or_description]\n\n"
            "[cctv_entry_phone_lifts]\n\n"
            "[fire_alarm_emergency_lighting]\n\n"
            "Condition Rating [1/2/3/NI]."
        ),
        expected_fields=[
            "applicable_to_flat",
            "entry_phone",
            "lift",
            "cctv",
            "fire_alarm",
            "emergency_lighting",
            "condition_rating",
        ],
    ),

    SectionTemplate(
        code="G8",
        title="Other services/features",
        group="G",
        has_condition_rating=True,
        skeleton=(
            "[other_services_description]\n\n"
            "[solar_panels_wind_turbine]\n\n"
            "[heat_pump]\n\n"
            "Condition Rating [1/2/3/NI]."
        ),
        expected_fields=[
            "solar_pv_panels",
            "solar_thermal",
            "wind_turbine",
            "heat_pump",
            "feed_in_tariff",
            "condition_rating",
        ],
    ),

    # ── H: Grounds ────────────────────────────────────────────────────────────

    SectionTemplate(
        code="H1",
        title="Garages",
        group="H",
        has_condition_rating=True,
        skeleton=(
            "[garage_present_or_none]\n\n"
            "[garage_type_construction]\n\n"
            "[garage_condition]\n\n"
            "[asbestos_roof_note]\n\n"
            "Condition Rating [1/2/3/NI]."
        ),
        expected_fields=[
            "garage_present",
            "garage_type",
            "construction_material",
            "asbestos_roof",
            "up_over_door_condition",
            "condition_rating",
        ],
    ),

    SectionTemplate(
        code="H2",
        title="Permanent outbuildings and other structures",
        group="H",
        has_condition_rating=True,
        skeleton=(
            "[outbuilding_description]\n\n"
            "[condition_description]\n\n"
            "Condition Rating [1/2/3/NI]."
        ),
        expected_fields=[
            "outbuildings_present",
            "outbuilding_type",
            "construction",
            "condition",
            "condition_rating",
        ],
    ),

    SectionTemplate(
        code="H3",
        title="Other (grounds)",
        group="H",
        has_condition_rating=False,
        skeleton=(
            "[garden_description]\n\n"
            "[boundary_walls_fences]\n\n"
            "[retaining_walls]\n\n"
            "[significant_trees]\n\n"
            "[paths_driveways]\n\n"
            "[shared_areas_for_flats]"
        ),
        expected_fields=[
            "garden_description",
            "boundary_type",
            "retaining_walls",
            "significant_trees",
            "paths_drives",
            "parking",
            "shared_areas",
        ],
    ),

    # ── I: Issues for your legal advisers ─────────────────────────────────────

    SectionTemplate(
        code="I1",
        title="Regulations",
        group="I",
        has_condition_rating=False,
        skeleton=(
            "The following matters should be raised with your legal advisers:\n\n"
            "[planning_permission_issues]\n\n"
            "[building_regulations_compliance]\n\n"
            "[listed_building_conservation_area]\n\n"
            "[rights_of_way_easements]\n\n"
            "[permitted_development]"
        ),
        expected_fields=[
            "planning_permission",
            "building_regulations",
            "extension_approval",
            "loft_conversion_regs",
            "listed_building",
            "conservation_area",
            "rights_of_way",
        ],
    ),

    SectionTemplate(
        code="I2",
        title="Guarantees",
        group="I",
        has_condition_rating=False,
        skeleton=(
            "[guarantees_present_or_none]\n\n"
            "[damp_proofing_guarantee]\n\n"
            "[fensa_guarantee]\n\n"
            "[structural_guarantee]\n\n"
            "[other_guarantees]"
        ),
        expected_fields=[
            "damp_proofing_guarantee",
            "window_fensa_certificate",
            "new_build_nhbc",
            "structural_warranty",
            "other_guarantees",
        ],
    ),

    SectionTemplate(
        code="I3",
        title="Other matters for legal advisers",
        group="I",
        has_condition_rating=False,
        skeleton=(
            "[tenure_freehold_leasehold]\n\n"
            "[lease_term_remaining]\n\n"
            "[service_charge_ground_rent]\n\n"
            "[boundary_disputes]\n\n"
            "[chancel_repair]\n\n"
            "[other_legal_matters]"
        ),
        expected_fields=[
            "tenure",
            "lease_term",
            "service_charge",
            "ground_rent",
            "boundary_ownership",
            "chancel_repair",
            "other_matters",
        ],
    ),

    # ── J: Risks ──────────────────────────────────────────────────────────────

    SectionTemplate(
        code="J1",
        title="Risks to the building",
        group="J",
        has_condition_rating=False,
        skeleton=(
            "Elements awarded a Condition Rating 3 relating to the building are "
            "discussed here.\n\n"
            "[structural_movement_description]\n\n"
            "[dampness_risks]\n\n"
            "[timber_defects]\n\n"
            "[non_traditional_construction]\n\n"
            "[other_building_risks]"
        ),
        expected_fields=[
            "structural_movement",
            "subsidence_heave",
            "dampness_type",
            "timber_decay_beetles",
            "non_traditional_construction",
            "other_risks",
        ],
    ),

    SectionTemplate(
        code="J2",
        title="Risks to the grounds",
        group="J",
        has_condition_rating=False,
        skeleton=(
            "[flooding_risk_assessment]\n\n"
            "[radon_risk]\n\n"
            "[mining_risk]\n\n"
            "[japanese_knotweed]\n\n"
            "[tree_root_risk]\n\n"
            "[other_ground_risks]"
        ),
        expected_fields=[
            "flood_zone",
            "radon_area",
            "mining_area",
            "japanese_knotweed",
            "tree_root_proximity",
            "shrinkable_subsoil",
        ],
    ),

    SectionTemplate(
        code="J3",
        title="Risks to people",
        group="J",
        has_condition_rating=False,
        skeleton=(
            "[asbestos_risk_assessment]\n\n"
            "[safety_glass_absence]\n\n"
            "[lead_pipes_paint]\n\n"
            "[fire_escape_adequacy]\n\n"
            "[unprotected_ponds_drops]\n\n"
            "[other_personal_risks]"
        ),
        expected_fields=[
            "asbestos_risk",
            "safety_glass",
            "lead_water_pipes",
            "lead_paint",
            "means_of_escape",
            "gas_leaks",
            "garden_ponds_drops",
        ],
    ),

    SectionTemplate(
        code="J4",
        title="Other risks or hazards",
        group="J",
        has_condition_rating=False,
        skeleton=(
            "[flight_path_noise]\n\n"
            "[planning_proposals_nearby]\n\n"
            "[intrusive_noise_smells]\n\n"
            "[other_hazards]"
        ),
        expected_fields=[
            "flight_path",
            "nearby_development",
            "noise_sources",
            "odour_sources",
            "other_hazards",
        ],
    ),

    # ── K: Energy efficiency ──────────────────────────────────────────────────

    SectionTemplate(
        code="K1",
        title="Insulation",
        group="K",
        has_condition_rating=False,
        skeleton=(
            "This describes the thermal shell of the building.\n\n"
            "Roof/loft insulation: [loft_insulation_description]\n\n"
            "Wall insulation: [wall_insulation_description]\n\n"
            "Floor insulation: [floor_insulation_description]\n\n"
            "[recommendations]"
        ),
        expected_fields=[
            "loft_insulation_depth",
            "wall_insulation_type",
            "floor_insulation",
            "insulation_recommendations",
        ],
    ),

    SectionTemplate(
        code="K2",
        title="Heating (energy)",
        group="K",
        has_condition_rating=False,
        skeleton=(
            "The property is heated by [heating_system]. [efficiency_rating]\n\n"
            "[thermostat_controls]\n\n"
            "[recommendations]"
        ),
        expected_fields=[
            "heating_system_type",
            "boiler_efficiency",
            "thermostat_controls",
            "zone_controls",
        ],
    ),

    SectionTemplate(
        code="K3",
        title="Lighting",
        group="K",
        has_condition_rating=False,
        skeleton=(
            "The surveyor assessed the adequacy of the property's lighting, both "
            "natural and artificial.\n\n"
            "[natural_lighting]\n\n"
            "[artificial_lighting]\n\n"
            "[recommendations]"
        ),
        expected_fields=[
            "natural_lighting",
            "led_lighting",
            "lighting_recommendations",
        ],
    ),

    SectionTemplate(
        code="K4",
        title="Ventilation",
        group="K",
        has_condition_rating=False,
        skeleton=(
            "The provision and nature of ventilation throughout the building:\n\n"
            "[bathroom_kitchen_ventilation]\n\n"
            "[whole_house_ventilation]\n\n"
            "[trickle_vents]\n\n"
            "[recommendations]"
        ),
        expected_fields=[
            "bathroom_ventilation",
            "kitchen_ventilation",
            "trickle_vents",
            "whole_house_ventilation",
            "recommendations",
        ],
    ),

    SectionTemplate(
        code="K5",
        title="Energy efficiency — general",
        group="K",
        has_condition_rating=False,
        skeleton=(
            "[epc_rating_summary]\n\n"
            "[renewable_energy_sources]\n\n"
            "[general_energy_recommendations]"
        ),
        expected_fields=[
            "epc_current_rating",
            "epc_potential_rating",
            "solar_panels",
            "heat_pump",
            "general_recommendations",
        ],
    ),

    # ── L: Surveyor's declaration ─────────────────────────────────────────────
    SectionTemplate(
        code="L",
        title="Surveyor's declaration",
        group="L",
        has_condition_rating=False,
        skeleton=(
            '"I confirm that I have inspected the property and prepared this report."\n\n'
            "Surveyor's name: [surveyor_name]\n"
            "RICS number: [rics_number]\n"
            "Qualifications: [qualifications]\n"
            "For and on behalf of: [company_name]\n"
            "Address: [company_address]\n"
            "Phone: [phone_number]\n"
            "Date of inspection: [inspection_date]"
        ),
        expected_fields=[
            "surveyor_name",
            "rics_number",
            "qualifications",
            "company_name",
            "company_address",
            "inspection_date",
        ],
    ),
]

# ── Lookup maps ───────────────────────────────────────────────────────────────

_TEMPLATE_MAP: dict[str, SectionTemplate] = {t.code: t for t in _TEMPLATES}

# Canonical section order for assembling a complete report
SECTION_ORDER: list[str] = [t.code for t in _TEMPLATES]

# Group labels shown as headings in the report
GROUP_LABELS: dict[str, str] = {
    "A": "A — Introduction to the report",
    "B": "B — About the inspection",
    "C": "C — Overall assessment and summary of condition ratings",
    "D": "D — About the property",
    "E": "E — Outside the property",
    "F": "F — Inside the property",
    "G": "G — Services",
    "H": "H — Grounds (including shared areas for flats)",
    "I": "I — Issues for your legal advisers",
    "J": "J — Risks",
    "K": "K — Energy efficiency",
    "L": "L — Surveyor's declaration",
}


def list_templates() -> list[SectionTemplate]:
    """Return all registered RICS section templates in canonical report order.

    Returns:
        Ordered list of :class:`SectionTemplate` objects.
    """
    return list(_TEMPLATES)


def list_templates_for_group(group: str) -> list[SectionTemplate]:
    """Return all templates belonging to the given ``group`` letter.

    Args:
        group: Single letter such as ``"E"`` or ``"G"``.

    Returns:
        Ordered list of :class:`SectionTemplate` objects in that group.
    """
    return [t for t in _TEMPLATES if t.group == group]


# ── Level 3 pack metadata (used by ``app.templates.registry``) ───────────────

LEVEL_3_DOCX_TITLE = "RICS Level 3 Building Survey Report"
LEVEL_3_PRODUCT_LABEL = "RICS Home Survey Level 3 (Building Survey)"


def get_level3_templates() -> list[SectionTemplate]:
    """Return the canonical Level 3 (Building Survey) template list."""
    return list(_TEMPLATES)


def get_template_level3(code: str) -> SectionTemplate | None:
    """Return a Level 3 template by code (same as legacy :func:`get_template`)."""
    return _TEMPLATE_MAP.get(code)


def get_template(code: str) -> SectionTemplate | None:
    """Legacy lookup — **Level 3 only**. Prefer :func:`app.templates.registry.get_template`.

    Args:
        code: Section code.

    Returns:
        Template or ``None``.
    """
    return get_template_level3(code)