mirror of
https://github.com/SamyRai/tercul-backend.git
synced 2025-12-27 05:11:34 +00:00
e1e703aeb6
This commit represents the first major batch of foundational refactoring work.
It accomplishes two main goals:
1. **Restores Project State:**
* Restores the comprehensive technical debt backlog in `TASKS.md` after it was accidentally deleted.
* Restores the detailed GraphQL API documentation in `api/README.md`.
* Re-applies the critical stability fix to the background job worker, replacing a `panic` with `log.Fatalf` for graceful termination on startup failure.
2. **Establishes CI Pipeline:**
* Creates a `Makefile` with a `lint-test` target to standardize running linters and tests.
* Adds a GitHub Actions workflow (`.github/workflows/ci.yml`) to automatically run the `lint-test` target on every push and pull request to the `main` branch.
This provides a stable, documented, and automatically-verified baseline for all future development and refactoring work.
95 lines
6.2 KiB
Markdown
95 lines
6.2 KiB
Markdown
# Consolidated Tasks for Tercul (Production Readiness)
|
|
|
|
This document is the single source of truth for all outstanding development tasks, aligned with the architectural vision in `refactor.md`. The backlog has been exhaustively updated based on a deep, "white-glove" code audit.
|
|
|
|
---
|
|
|
|
## !! CRITICAL !!
|
|
|
|
### Stabilize Core Logic (Prevent Panics)
|
|
|
|
- [ ] **Fix Background Job Panic:** The background job queue in `internal/jobs/sync/queue.go` can panic on error. This must be refactored to handle errors gracefully.
|
|
|
|
---
|
|
|
|
## High Priority
|
|
|
|
### EPIC: Achieve Production-Ready API
|
|
|
|
- [ ] **Implement All Unimplemented Resolvers:** The GraphQL API is critically incomplete. All of the following `panic`ing resolvers must be implemented.
|
|
- **Mutations:** `DeleteUser`, `CreateContribution`, `UpdateContribution`, `DeleteContribution`, `ReviewContribution`, `Logout`, `RefreshToken`, `ForgotPassword`, `ResetPassword`, `VerifyEmail`, `ResendVerificationEmail`, `UpdateProfile`, `ChangePassword`.
|
|
- **Queries:** `Translations`, `Author`, `User`, `UserByEmail`, `UserByUsername`, `Me`, `UserProfile`, `Collection`, `Collections`, `Comment`, `Comments`, `Search`.
|
|
- [ ] **Refactor API Server Setup:** The API server startup in `cmd/api/main.go` is unnecessarily complex.
|
|
- [ ] Consolidate the GraphQL Playground and Prometheus metrics endpoints into the main API server, exposing them on different routes (e.g., `/playground`, `/metrics`).
|
|
|
|
### EPIC: Comprehensive Documentation
|
|
|
|
- [ ] **Create Full API Documentation:** The current API documentation is critically incomplete. We need to document every query, mutation, and type in the GraphQL schema.
|
|
- [ ] Update `api/README.md` to be a comprehensive guide for API consumers.
|
|
- [ ] **Improve Project `README.md`:** The root `README.md` should be a welcoming and useful entry point for new developers.
|
|
- [ ] Add sections for project overview, getting started, running tests, and architectural principles.
|
|
- [ ] **Ensure Key Packages Have READMEs:** Follow the example of `./internal/jobs/sync/README.md` for other critical components.
|
|
|
|
### EPIC: Foundational Infrastructure
|
|
|
|
- [ ] **Establish CI/CD Pipeline:** A robust CI/CD pipeline is essential for ensuring code quality and enabling safe deployments.
|
|
- [ ] **CI:** Create a `Makefile` target `lint-test` that runs `golangci-lint` and `go test ./...`. Configure the CI pipeline to run this on every push.
|
|
- [ ] **CD:** Set up automated deployments to a staging environment upon a successful merge to the main branch.
|
|
- [ ] **Implement Full Observability:** We need a comprehensive observability stack to understand the application's behavior.
|
|
- [ ] **Centralized Logging:** Ensure all services use the structured `zerolog` logger from `internal/platform/log`. Add request/user/span IDs to the logging context in the HTTP middleware.
|
|
- [ ] **Metrics:** Add Prometheus metrics for API request latency, error rates, and database query performance.
|
|
- [ ] **Tracing:** Instrument all application services and data layer methods with OpenTelemetry tracing.
|
|
|
|
### EPIC: Core Architectural Refactoring
|
|
|
|
- [ ] **Refactor Dependency Injection:** The application's DI container in `internal/app/app.go` violates the Dependency Inversion Principle.
|
|
- [ ] Refactor `NewApplication` to accept repository *interfaces* (e.g., `domain.WorkRepository`) instead of the concrete `*sql.Repositories`.
|
|
- [ ] Move the instantiation of platform components (e.g., `JWTManager`) out of `NewApplication` and into `cmd/api/main.go`, passing them in as dependencies.
|
|
- [ ] **Implement Read Models (DTOs):** Application queries currently return full domain entities, which is inefficient and leaks domain logic.
|
|
- [ ] Refactor application queries (e.g., in `internal/app/work/queries.go`) to return specialized read models (DTOs) tailored for the API.
|
|
- [ ] **Improve Configuration Handling:** The application relies on global singletons for configuration (`config.Cfg`).
|
|
- [ ] Refactor to use struct-based configuration injected via constructors, as outlined in `refactor.md`.
|
|
- [ ] Make the database migration path configurable instead of using a brittle, hardcoded path.
|
|
- [ ] Make the metrics server port configurable.
|
|
|
|
### EPIC: Robust Testing Framework
|
|
|
|
- [ ] **Refactor Testing Utilities:** Decouple our tests from a live database to make them faster and more reliable.
|
|
- [ ] Remove all database connection logic from `internal/testutil/testutil.go`.
|
|
- [ ] **Implement Mock Repositories:** The test mocks are incomplete and `panic`.
|
|
- [ ] Implement the `panic("not implemented")` methods in `internal/adapters/graphql/like_repo_mock_test.go`, `internal/adapters/graphql/work_repo_mock_test.go`, and `internal/testutil/mock_user_repository.go`.
|
|
|
|
---
|
|
|
|
## Medium Priority
|
|
|
|
### EPIC: Complete Core Features
|
|
|
|
- [ ] **Implement `AnalyzeWork` Command:** The `AnalyzeWork` command in `internal/app/work/commands.go` is currently a stub.
|
|
- [ ] **Implement Analytics Features:** User engagement metrics are a core business requirement.
|
|
- [ ] Implement like, comment, and bookmark counting.
|
|
- [ ] Implement a service to calculate popular translations based on the above metrics.
|
|
- [ ] **Refactor `enrich` Tool:** The `cmd/tools/enrich/main.go` tool is architecturally misaligned.
|
|
- [ ] Refactor the tool to use application services instead of accessing data repositories directly.
|
|
|
|
### EPIC: Further Architectural Improvements
|
|
|
|
- [ ] **Refactor Caching:** Replace the bespoke cached repositories with a decorator pattern in `internal/data/cache`.
|
|
- [ ] **Consolidate Duplicated Structs:** The `WorkAnalytics` and `TranslationAnalytics` structs are defined in two different packages. Consolidate them.
|
|
|
|
---
|
|
|
|
## Low Priority
|
|
|
|
### EPIC: Code Quality & Documentation
|
|
|
|
- [ ] **Add GoDoc Comments:** Document all public functions and types.
|
|
- [ ] **Expand Weaviate Client:** Extend the client to support indexing all relevant domain models.
|
|
- [ ] **Refactor Transactional Runner:** Refactor the `RunTransactional` helper to be more mock-friendly.
|
|
|
|
---
|
|
|
|
## Completed
|
|
|
|
- [x] `internal/app/work/commands.go`: The `MergeWork` command is fully implemented.
|
|
- [x] `internal/app/search/service.go`: The search service correctly fetches content from the localization service. |