quyun-v2/docs/plan.md

Implementation Plan: full-lint-remediation

Branch: [chore/full-lint-remediation] | Date: 2026-02-05 | Spec: N/A Input: Full repo lint remediation covering backend and frontend lint/build steps.

Summary

Remediate all existing lint failures across the backend and frontend by systematically addressing security warnings, de-duplication, complexity, formatting, naming/style violations, and frontend lint/build issues, while preserving behavior and following project constraints.

Technical Context

Language/Version: Go 1.x
Primary Dependencies: Fiber, GORM-Gen, River, golangci-lint
Storage: PostgreSQL
Testing: make lint in backend/, go test ./..., npm -C frontend/superadmin run lint, npm -C frontend/superadmin run build, npm -C frontend/portal run lint, npm -C frontend/portal run build
Target Platform: Linux server
Project Type: Web application (backend + frontend)
Performance Goals: N/A
Constraints: Follow backend/llm.txt; do not edit generated files; avoid behavior changes while refactoring
Scale/Scope: Backend lint errors plus frontend lint/build issues in portal/superadmin

Constitution Check

• Follow backend/llm.txt (controller thin, services handle DB, Chinese comments for business logic).
• Do not edit generated files (*.gen.go, backend/docs/docs.go).
• Fix lint issues without behavior changes or API surface drift.

Project Structure

Documentation (this feature)

docs/
└── plan.md

Source Code (repository root)

backend/
├── app/services/super.go
├── app/services/creator_report.go
├── app/services/content.go
├── app/services/creator.go
├── app/services/coupon.go
├── app/services/common.go
├── app/commands/seed/seed.go
├── app/commands/storage_migrate/migrate.go
├── app/jobs/media_process_job.go
├── providers/http/swagger/config.go
├── providers/http/swagger/template.go
├── providers/http/engine.go
├── providers/jwt/jwt.go
├── providers/postgres/config.go
└── providers/postgres/postgres.go

frontend/
├── superadmin/
│   ├── src/
│   └── package.json
└── portal/
    ├── src/
    └── package.json

Structure Decision: Web application; full repo lint remediation (backend + frontend).

Plan Phases

1. Security & correctness: Address gosec issues (weak crypto, weak random, unsafe conversions) and errcheck/errorlint/wrapcheck failures.
2. De-duplication & complexity: Reduce dupl/gocognit/gocyclo/funlen by extracting helpers and simplifying large service methods (especially services/super.go).
3. Style & formatting: Resolve revive naming issues, line-length (lll), prealloc, nilerr, and other style violations.
4. Frontend lint/build: Resolve frontend lint/build issues for portal/superadmin.
5. Verification: Run backend and frontend lint/build/test commands until clean.

Tasks

1. Capture baseline lint outputs (save cd backend && make lint output; run npm -C frontend/superadmin run lint / npm -C frontend/portal run lint) and group errors by category/file; establish remediation order (security → complexity → style).
2. Fix gosec issues: choose between (a) keep MD5 for non-security hashing with explicit //nolint:gosec justification, or (b) migrate to SHA-256 with any required backfill; switch weak random to crypto/rand where required; guard integer conversions.
3. Fix errcheck/errorlint/wrapcheck issues in providers and error handling.
4. Remove duplicated blocks (dupl) by extracting shared helper functions in services/super.go and services/creator_report.go.
5. Reduce high cognitive/cyclomatic complexity by helper extraction only; keep inputs/outputs and query semantics unchanged.
6. Address revive naming and lll formatting (split long lines, rename variables/types as needed).
7. Run backend verification (cd backend && make lint, go test ./...).
8. Run frontend lint/build (npm -C frontend/superadmin run lint, npm -C frontend/superadmin run build, npm -C frontend/portal run lint, npm -C frontend/portal run build). Review ESLint --fix diffs carefully.
9. Re-run all lint/build/test commands until clean.

Dependencies

• Security fixes precede refactors to ensure safe baselines.
• De-duplication/complexity refactors should precede style fixes to avoid rework.
• Backend verification depends on remediation tasks; frontend verification depends on frontend lint/build tasks.

Acceptance Criteria

• Backend lint passes with no errors (cd backend && make lint).
• Frontend lint/build passes (npm -C frontend/superadmin run lint, npm -C frontend/superadmin run build, npm -C frontend/portal run lint, npm -C frontend/portal run build).
• go test ./... passes (or failures are documented as pre-existing and approved).
• No generated files modified manually.
• No functional/API behavior changes observed during lint fixes.

Risks

• Large refactors in services/super.go may inadvertently change behavior; must keep refactors minimal and covered by tests.
• Security fixes may require signature changes (e.g., hash algorithm changes); need careful review for backward compatibility.
• Volume of lint violations may require staged remediation; ensure each stage keeps lint green where possible.

Complexity Tracking

Fill ONLY if Constitution Check has violations that must be justified

Violation	Why Needed	Simpler Alternative Rejected Because
N/A	N/A	N/A