docs: add market filename refactor design spec

Capture approved design for issue #26 to standardize market package filenames by data dimension without behavior changes. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-04-27 05:12:35 +07:00
parent 259a630b78
commit 8010a00e4d
1 changed files with 85 additions and 0 deletions
@@ -0,0 +1,85 @@
+# Market filenames data-dimension design
+
+## Context
+
+`internal/data/market` currently has mixed filename semantics (`trading_pairs.go`, `future_price.go`, `spot_price.go`, `alpha_tokens.go`).
+This slows code navigation because filenames do not consistently communicate data dimension.
+
+Goal: refactor market package filenames to consistent data-dimension naming, and align function placement with filename responsibility, without changing runtime behavior.
+
+## Scope
+
+Applies only to files in `internal/data/market`.
+
+In scope:
+- Rename files to consistent names by data dimension.
+- Mechanical updates needed due to file rename/move.
+- Move functions between renamed files when needed so file responsibility is clear.
+
+Out of scope:
+- Any behavior or logic changes.
+- New feature work.
+- Refactors outside `internal/data/market` except mechanical references.
+
+## Requirements
+
+1. File naming in market package is consistent by data dimension.
+2. Target filenames:
+   - `spot_pairs.go`
+   - `futures_pairs.go`
+   - `spot_prices.go`
+   - `futures_prices.go`
+   - keep `alpha_tokens.go`
+3. Function placement matches filename responsibility.
+4. No public/package behavior change.
+5. Resulting PR focuses on refactor readability and low review noise.
+
+## Design
+
+### Naming model
+
+Use pluralized, data-dimension based filenames:
+- `*_pairs.go` for symbol/pair resolution concerns.
+- `*_prices.go` for price retrieval/processing concerns.
+
+### File-level responsibilities
+
+- `spot_pairs.go`: Spot pair/symbol resolution code.
+- `futures_pairs.go`: Futures pair/symbol resolution code.
+- `spot_prices.go`: Spot price read/transform code.
+- `futures_prices.go`: Futures price read/transform code.
+- `alpha_tokens.go`: Alpha-token specific logic (unchanged file name).
+
+### Refactor mechanics
+
+1. Rename existing files to target names using git-aware rename.
+2. Inspect each renamed file for responsibility mismatch.
+3. Move declarations to the matching file when mismatch exists.
+4. Keep function signatures and call behavior unchanged.
+5. Apply only mechanical import/reference updates if any are required.
+
+## Error handling and behavior
+
+No new error handling paths are introduced.
+Existing control flow and error behavior remain unchanged.
+
+## Testing and verification
+
+1. Run package tests for market-related code.
+2. Run project test command used by repository.
+3. Confirm no functional diff beyond file rename/moves.
+4. Final check: each renamed file contains only code matching its data dimension.
+
+## Risks and mitigations
+
+- Risk: accidental behavior change while moving declarations.
+  - Mitigation: keep signatures/body unchanged; validate with tests.
+- Risk: review noise from mixed mechanical and logic edits.
+  - Mitigation: avoid logic edits entirely; keep commit focused on naming/responsibility alignment.
+
+## Success criteria
+
+- Market package filenames follow the target naming scheme.
+- Code in each file matches its filename responsibility.
+- Tests pass with no behavior regression.
+- PR is reviewable as a refactor-only change set.