API interface design
EasyEDA Native Data Model
These interfaces preserve EasyEDA-native symbol, footprint, shape, pin, pad, and 3D-model semantics. Each interface section is machine-readable: L99 signoff requires the section, rationale, purpose, test requirements, working definition, Rack stratum, test file, and test target.
EasyEdaSymbol
Rationale: A schematic symbol aggregate is the stable unit callers need after parsing an EasyEDA component response.
Purpose: Hold symbol metadata, pins, and graphical primitives without converting away EasyEDA semantics.
Test Requirements: Rack L0 parses saved API fixtures into symbols and verifies pin and graphic counts.
Working Definition: A symbol works when public fixtures parse without errors and preserve expected metadata, pins, and shape collections.
EeSymbolInfo
Rationale: Symbol metadata needs a typed home separate from geometry so callers can inspect identity without walking graphics.
Purpose: Store symbol name, prefix, LCSC id, package, and source identity parsed from component JSON.
Test Requirements: Rack L0 symbol parse tests verify fixture metadata through the enclosing EasyEdaSymbol object.
Working Definition: Metadata works when parsed symbols expose the expected component name and LCSC id from saved fixtures.
EasyEdaPin
Rationale: Pins carry electrical and placement information that must remain distinct from symbol drawing primitives.
Purpose: Store parsed EasyEDA pin fields such as name, number, location, orientation, length, and electrical type.
Test Requirements: Rack L0 symbol tests verify pin counts and that parsed pins expose name or number fields.
Working Definition: Pins work when fixture symbols produce expected pin counts and non-empty identity fields.
EeRectangle
Rationale: EasyEDA rectangles appear in many symbol bodies and footprint graphics and need a typed primitive.
Purpose: Store rectangle position, size, stroke, fill, and layer-like source fields.
Test Requirements: Rack L0 symbol and footprint fixture tests verify rectangle counts through aggregate parsers.
Working Definition: Rectangles work when fixtures with rectangular graphics parse and count correctly.
EeCircle
Rationale: Circles represent footprint silkscreen, holes, and symbol graphics that should not be flattened to generic dictionaries.
Purpose: Store circle center, radius, stroke, fill, and source style fields.
Test Requirements: Rack L0 footprint tests verify circle counts across saved fixtures.
Working Definition: Circles work when circle-heavy fixtures parse with expected counts and round-trip as part of footprints.
EeEllipse
Rationale: EasyEDA ellipses are distinct from circles and preserve separate radius values.
Purpose: Store ellipse center, radii, stroke, fill, and source style fields.
Test Requirements: Rack L0 symbol tests verify ellipse counts on fixtures that include indicator graphics.
Working Definition: Ellipses work when symbols with ellipse graphics parse with expected counts.
EeArc
Rationale: Arc path data must preserve EasyEDA sweep and endpoint intent for downstream drawing and conversion.
Purpose: Store arc path text and parsed style fields as a native EasyEDA primitive.
Test Requirements: Rack L0 footprint tests verify arc counts on fixtures with curved footprint geometry.
Working Definition: Arcs work when arc-bearing fixtures parse with expected counts and retain their source path data.
EePolyline
Rationale: Polylines are common in symbol art and footprint silkscreen and need point-list preservation.
Purpose: Store EasyEDA polyline point data and style fields.
Test Requirements: Rack L0 symbol and footprint tests verify polyline counts on fixtures with line artwork.
Working Definition: Polylines work when aggregate parsers preserve expected polyline counts across fixtures.
EePolygon
Rationale: Filled polygon graphics need to remain distinct from open polylines.
Purpose: Store EasyEDA polygon point data and fill/stroke style fields.
Test Requirements: Rack L0 symbol tests verify polygon counts on fixtures that use filled graphics.
Working Definition: Polygons work when polygon-bearing fixtures parse with expected counts.
EePath
Rationale: Some EasyEDA graphics are arbitrary SVG-like path strings that cannot be represented as simpler primitives.
Purpose: Preserve path command text and style fields for downstream parsing or rendering.
Test Requirements: Rack L0 symbol tests verify path counts on fixtures with internal graphics.
Working Definition: Paths work when path-bearing fixtures parse with expected counts and path text remains available.
EasyEdaFootprint
Rationale: A footprint aggregate is the stable unit callers need after parsing EasyEDA package data.
Purpose: Hold footprint metadata, pads, graphics, vias, holes, and text while preserving EasyEDA-native fields.
Test Requirements: Rack L0 footprint tests parse saved fixtures, assert geometry counts, and verify JSON round-trip behavior.
Working Definition: A footprint works when public fixtures parse without errors and preserve pads, graphics, holes, and round-trip JSON.
EeFootprintInfo
Rationale: Footprint identity metadata should be inspectable without walking geometry collections.
Purpose: Store footprint name, package, source identifiers, and descriptive EasyEDA metadata.
Test Requirements: Rack L0 footprint parse and round-trip tests exercise metadata through the enclosing footprint.
Working Definition: Footprint metadata works when parsed fixtures produce stable aggregate identity and round-trip output.
EeFootprintPad
Rationale: Pads are the central electrical/mechanical footprint primitive and need complete shape and hole fields.
Purpose: Store pad number, geometry, layer, shape, hole, slot, rotation, and source fields.
Test Requirements: Rack L0 footprint tests verify pad counts, pad numbers, shapes, layers, holes, and slots.
Working Definition: Pads work when SMT, through-hole, slotted, and single-pad fixtures parse with expected fields.
EeFootprintTrack
Rationale: Footprint line artwork and copper-like segments need a typed representation with layer and width.
Purpose: Store track point data, width, layer, net-like fields, and style fields.
Test Requirements: Rack L0 footprint tests verify track counts across multiple package styles.
Working Definition: Tracks work when fixtures with silkscreen or copper-like line data parse with expected counts.
EeFootprintHole
Rationale: Non-pad holes and mechanical holes must be represented separately from through-hole pads.
Purpose: Store standalone hole location, diameter, and source fields.
Test Requirements: Rack L0 footprint tests verify non-pad hole counts and diameters for connector and socket fixtures.
Working Definition: Holes work when fixtures with mechanical holes parse with expected count and diameter data.
EeFootprintVia
Rationale: Vias can appear in EasyEDA footprint data and should not be collapsed into pads or holes.
Purpose: Store via position, diameter, drill, net, and layer/source fields.
Test Requirements: Rack L0 footprint parsing exercises the via collection through aggregate fixture parsing and round-trip behavior.
Working Definition: Vias work when via-bearing package data can be parsed and serialized without losing fields.
EeFootprintText
Rationale: Designators, labels, and package text need typed geometry and style fields.
Purpose: Store text value, location, rotation, layer, size, and style data.
Test Requirements: Rack L0 footprint tests verify text counts on fixtures with footprint annotations.
Working Definition: Text works when annotated footprints parse with expected text collection counts.
EasyEda3DModel
Rationale: 3D model references need stable URL and pose metadata for downstream conversion workflows.
Purpose: Store UUID, title, translation, rotation, and derived EasyEDA model URLs.
Test Requirements: Rack L0 3D-model tests verify URL derivation, empty UUID behavior, JSON round-trip, and fixture extraction.
Working Definition: A 3D model works when URLs derive from UUIDs and all pose fields round-trip through JSON.
EasyEdaApiClient
Rationale: API access needs one boundary for caching, timeout, and rate-limit behavior.
Purpose: Fetch EasyEDA component JSON directly or from a cache directory while keeping network policy out of parser dataclasses.
Test Requirements: Rack L0 CLI tests exercise cached API reads through the fetch-part command path.
Working Definition: The client works when cached fixture responses can drive raw and summary CLI output without network access.
extract_3d_models_from_api_response
Rationale: 3D references are nested in API responses and need a stable extraction helper.
Purpose: Return model references from component JSON without requiring callers to know EasyEDA response nesting.
Test Requirements: Rack L0 3D-model tests run extraction across every saved API fixture.
Working Definition: Extraction works when all public fixtures return a list without crashing and valid models round-trip independently.
parse_svg_path
Rationale: EasyEDA path strings must be parsed consistently for downstream drawing and conversion.
Purpose: Convert SVG-like path commands into simple segment dictionaries while preserving arc flags and coordinates.
Test Requirements: Rack L0 SVG path tests cover move, line, horizontal, vertical, cubic, quadratic, arc, close, relative, compact, and negative-coordinate commands.
Working Definition: Path parsing works when supported commands produce stable segment dictionaries and empty input returns an empty list.
CliCommandSpec
Rationale: CLI metadata needs a typed registry item that docs and signoff can inspect.
Purpose: Store command name, design-doc path, and help text for command registration and documentation checks.
Test Requirements: Rack L99 design-doc tests inspect the command registry and require matching CLI design docs.
Working Definition: Command metadata works when every registered command has matching help, design documentation, and config-contract declaration.