67/docs/compose/plans/2026-06-22-backend-stabilization.md

# Backend Stabilization Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use compose:subagent (recommended) or compose:execute to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Turn the current scaffold into a repeatable backend-first almost-production demo: real PostgreSQL persistence, real auth, real gateway-backed API responses, and passing root verification.

**Architecture:** Keep the current three-layer shape (`apps/web` -> `apps/gateway` -> `services/cmd/*`) and replace the shared Go `demoStore` with a PostgreSQL-backed store built on `GORM`. Preserve existing HTTP contracts where possible, add only the minimal new plumbing needed for config, auth, health checks, and smoke verification.

**Tech Stack:** npm workspaces, React 19, Vite, Axios, Zustand, Node.js + Elysia gateway, Go HTTP services, GORM, PostgreSQL 17, SQL migrations, Docker Compose.

---

## File Map

- `package.json`: root verification commands and workspace entrypoints.
- `README.md`: authoritative local run and acceptance instructions.
- `.env.example`: example backend DSN, token secret, token TTL and API base URL.
- `docker-compose.yml`: consistent local runtime for postgres, gateway, web and services.
- `scripts/dev-backend.sh`: local backend boot with PostgreSQL-aware env.
- `scripts/smoke-backend.sh`: curl-based critical-path smoke verification.
- `apps/gateway/src/index.ts`: gateway proxying, auth fallback removal, unified error/health behavior.
- `apps/web/src/shared/api/client.js`: correct default API base URL and error normalization.
- `apps/web/src/shared/api/endpoints.js`: API contract used by the UI.
- `apps/web/src/app/store/session.js`: login payload compatibility, `me`, logout, session reset.
- `apps/web/src/pages/*.jsx`: key pages that currently assume mock-only data shapes.
- `apps/web/src/**/*.test.*`: frontend regression tests for login and key data pages.
- `services/go.mod`: PostgreSQL driver and password-hash dependency declarations.
- `services/internal/service/types.go`: backend DTOs and enum/value mapping.
- `services/internal/service/service.go`: service bootstrap, DB-aware health/readiness.
- `services/internal/service/api.go`: HTTP handlers for auth, content, media, search, comments, subscriptions, notifications, admin and analytics.
- `services/internal/service/store.go`: store interface and bootstrap hook.
- `services/internal/service/db.go`: PostgreSQL connection, GORM bootstrap and migration helpers.
- `services/internal/service/store_gorm.go`: GORM-backed implementation of the store.
- `services/internal/service/auth.go`: password hashing and signed token helpers.
- `services/internal/service/seed.go`: idempotent bootstrap data for roles, demo users and demo content.
- `services/internal/service/*_test.go`: Go unit/integration coverage for critical backend flows.
- `database/migrations/001_init.sql`: schema source of truth; must match current Go enum values and required tables.

### Task 1: Reproduce and lock the runtime baseline

**Covers:** [S1, S2, S7]

**Files:**
- Modify: `README.md`
- Modify: `.env.example`
- Modify: `package.json`
- Modify: `scripts/dev-backend.sh`
- Create: `scripts/smoke-backend.sh`

- [ ] **Step 1: Capture the failing baseline in notes and a smoke script stub**

```bash
npm install
npm run check
```

Expected: failure is reproduced before code changes. Right now the first expected failure is the missing frontend toolchain (`vite: command not found`) or another dependency/runtime error from a clean install.

- [ ] **Step 2: Write the failing smoke script skeleton**

```bash
#!/usr/bin/env bash
set -euo pipefail

API_BASE_URL="${API_BASE_URL:-http://127.0.0.1:3000/api}"

echo "[1/4] login"
echo "[2/4] fetch current user"
echo "[3/4] create draft content"
echo "[4/4] read admin dashboard"

exit 1
```

Save as `scripts/smoke-backend.sh` and mark it executable after the rest of the plan fills the real requests.

- [ ] **Step 3: Make the local runtime explicit and consistent**

Add backend env examples to `.env.example`:

```dotenv
DATABASE_URL=postgres://fable:fable_dev_password@127.0.0.1:5432/fable?sslmode=disable
TOKEN_SECRET=local-dev-secret-change-me
TOKEN_TTL=24h
VITE_API_URL=http://127.0.0.1:3000/api
```

Update `scripts/dev-backend.sh` so every Go service receives `DATABASE_URL`, `TOKEN_SECRET` and `TOKEN_TTL` instead of relying on demo-only state.

- [ ] **Step 4: Update root docs and verification contract**

Document the intended acceptance flow in `README.md`:

```markdown
1. `npm install`
2. `docker compose up -d postgres`
3. `npm run dev:backend`
4. `npm run dev:web`
5. `npm run check`
6. `bash scripts/smoke-backend.sh`
```

- [ ] **Step 5: Re-run the root verification command**

```bash
npm run check
```

Expected: it may still fail, but only on real application gaps rather than missing setup instructions.

### Task 2: Replace the shared demo store with PostgreSQL-backed GORM bootstrap

**Covers:** [S2, S4, S5, S6]

**Files:**
- Modify: `services/go.mod`
- Modify: `services/internal/service/store.go`
- Modify: `services/internal/service/service.go`
- Create: `services/internal/service/db.go`
- Create: `services/internal/service/store_gorm.go`
- Create: `services/internal/service/seed.go`
- Create: `services/internal/service/store_gorm_test.go`
- Modify: `database/migrations/001_init.sql`

- [ ] **Step 1: Write the failing DB bootstrap test**

```go
func TestBootstrapStoreLoadsSeededUsersAndContent(t *testing.T) {
	store := newTestGORMStore(t)

	user, ok := store.UserByLogin(context.Background(), "demo_admin")
	if !ok {
		t.Fatal("expected seeded admin user")
	}

	items, err := store.ListContent(context.Background(), ContentFilter{})
	if err != nil {
		t.Fatalf("list content: %v", err)
	}
	if len(items) == 0 {
		t.Fatal("expected seeded content")
	}
}
```

- [ ] **Step 2: Run the failing Go test**

```bash
cd services && go test ./internal/service -run TestBootstrapStoreLoadsSeededUsersAndContent -v
```

Expected: FAIL because there is no GORM bootstrap/store yet.

- [ ] **Step 3: Introduce DB config, connection and store interface**

In `services/internal/service/store.go`, replace the global concrete store with an interface:

```go
type Store interface {
	UserByLogin(ctx context.Context, login string) (UserProfile, bool, error)
	ListContent(ctx context.Context, filter ContentFilter) ([]ContentItem, error)
	// add the remaining methods currently hanging off demoStore
}
```

In `services/internal/service/db.go`, add a PostgreSQL opener using `DATABASE_URL` and return a shared `*gorm.DB`.

- [ ] **Step 4: Implement GORM store and idempotent seed bootstrap**

Key shape for `services/internal/service/store_gorm.go`:

```go
type gormStore struct {
	db *gorm.DB
}

func (s *gormStore) UserByLogin(ctx context.Context, login string) (UserProfile, bool, error) {
	var user userRecord
	err := s.db.WithContext(ctx).Preload("Roles").Where("login = ?", login).First(&user).Error
	// map record -> API DTO
}
```

In `seed.go`, upsert roles, demo users, speakers, categories, tags, content, notifications and comments.

- [ ] **Step 5: Align the migration with Go values before wiring queries**

Fix the enum mismatch in `database/migrations/001_init.sql` so the stored content type matches Go (`event`, not `event_announcement`) or update Go and frontend in one consistent direction. Pick one representation and use it everywhere.

- [ ] **Step 6: Run the new store test and the existing Go service test**

```bash
cd services && go test ./internal/service -run 'TestBootstrapStoreLoadsSeededUsersAndContent|TestHealthEndpoint' -v
```

Expected: PASS.

### Task 3: Implement real auth, session lookup and readiness behavior

**Covers:** [S2, S3, S5, S6, S7]

**Files:**
- Modify: `services/internal/service/api.go`
- Modify: `services/internal/service/types.go`
- Create: `services/internal/service/auth.go`
- Create: `services/internal/service/auth_test.go`
- Modify: `services/internal/service/service.go`

- [ ] **Step 1: Write failing auth tests for register, login and me**

```go
func TestAuthFlowRegisterLoginAndMe(t *testing.T) {
	h := newTestHandler(t, Config{Name: "auth", Domain: "auth"})

	registerBody := `{"login":"new_user","password":"verysecret","name":"Новый пользователь"}`
	registerRec := performJSONRequest(t, h, http.MethodPost, "/api/auth/register", registerBody, "")
	if registerRec.Code != http.StatusCreated {
		t.Fatalf("register status = %d", registerRec.Code)
	}

	token := readTokenFromResponse(t, registerRec.Body.Bytes())
	meRec := performJSONRequest(t, h, http.MethodGet, "/api/auth/me", "", token)
	if meRec.Code != http.StatusOK {
		t.Fatalf("me status = %d", meRec.Code)
	}
}
```

- [ ] **Step 2: Run the failing auth test**

```bash
cd services && go test ./internal/service -run TestAuthFlowRegisterLoginAndMe -v
```

Expected: FAIL because login currently accepts any password and returns a demo token.

- [ ] **Step 3: Add password hashing and signed tokens**

In `services/internal/service/auth.go` add minimal helpers:

```go
func HashPassword(password string) (string, error) { /* bcrypt */ }
func ComparePassword(hash, password string) error { /* bcrypt */ }
func SignToken(secret string, claims TokenClaims, ttl time.Duration) (string, error) { /* HMAC-signed token */ }
func ParseToken(secret, token string) (TokenClaims, error) { /* validate signature + expiry */ }
```

Keep the token format simple and self-contained; do not preserve `demo-token-*` compatibility.

- [ ] **Step 4: Update auth handlers to use the SQL store**

Replace the login fallback in `api.go` with explicit credential checks:

```go
user, ok, err := backendStore.UserByLogin(ctx, payload.Login)
if err != nil { /* 500 */ }
if !ok || ComparePassword(user.PasswordHash, payload.Password) != nil {
	writeAPIError(w, http.StatusUnauthorized, "INVALID_CREDENTIALS", "Неверный логин или пароль")
	return true
}
```

Also make `/auth/change-password` update the stored hash and make `/ready` fail when DB connectivity is broken.

- [ ] **Step 5: Run focused auth/readiness verification**

```bash
cd services && go test ./internal/service -run 'TestAuthFlowRegisterLoginAndMe|TestHealthEndpoint' -v
```

Expected: PASS.

### Task 4: Persist content, taxonomy, subscriptions, comments, admin and analytics endpoints

**Covers:** [S3, S4, S5, S6, S7]

**Files:**
- Modify: `services/internal/service/api.go`
- Modify: `services/internal/service/types.go`
- Modify: `services/internal/service/store_gorm.go`
- Create: `services/internal/service/content_api_test.go`
- Create: `services/internal/service/admin_api_test.go`

- [ ] **Step 1: Write failing tests for the critical domain path**

```go
func TestContentCommentSubscriptionAndAdminFlow(t *testing.T) {
	h := newTestHandlerAsAdmin(t)

	created := performJSONRequest(t, h, http.MethodPost, "/api/content", `{"title":"Новый материал","type":"article","category":"Статьи"}`, adminToken(t, h))
	if created.Code != http.StatusCreated {
		t.Fatalf("create content status = %d", created.Code)
	}

	contentID := readItemID(t, created.Body.Bytes())
	comment := performJSONRequest(t, h, http.MethodPost, "/api/comments/"+contentID, `{"text":"Полезный материал"}`, userToken(t, h))
	if comment.Code != http.StatusCreated {
		t.Fatalf("create comment status = %d", comment.Code)
	}
}
```

- [ ] **Step 2: Run the failing domain test**

```bash
cd services && go test ./internal/service -run TestContentCommentSubscriptionAndAdminFlow -v
```

Expected: FAIL because handlers still depend on the in-memory methods and non-persistent side effects.

- [ ] **Step 3: Port each handler branch to GORM-backed methods without changing the external contract**

Implement GORM methods for:
- content list/detail/create/update/delete;
- events/media derived listings;
- category/tag reads;
- speaker reads;
- comment list/create;
- subscription list/create;
- notification list/mark-read;
- admin users/roles/audit/dashboard;
- analytics summary;
- search using PostgreSQL text search.

Represent the filter in Go explicitly:

```go
type ContentFilter struct {
	Query    string
	Category string
	Type     string
	Sort     string
	Limit    int
	Exclude  string
}
```

- [ ] **Step 4: Keep API payloads stable for the current frontend**

Return the same envelope keys the UI already expects:

```json
{ "user": { ... } }
{ "items": [ ... ] }
{ "item": { ... } }
{ "ok": true }
```

Do not introduce a second incompatible schema while stabilizing the backend.

- [ ] **Step 5: Run the focused Go verification for the critical path**

```bash
cd services && go test ./internal/service -run 'TestContentCommentSubscriptionAndAdminFlow|TestAuthFlowRegisterLoginAndMe' -v
```

Expected: PASS.

### Task 5: Remove gateway/frontend mock-only assumptions and align contracts

**Covers:** [S2, S3, S5, S7, S8]

**Files:**
- Modify: `apps/gateway/src/index.ts`
- Modify: `apps/web/src/shared/api/client.js`
- Modify: `apps/web/src/shared/api/endpoints.js`
- Modify: `apps/web/src/app/store/session.js`
- Modify: `apps/web/src/pages/LoginPage.test.jsx`
- Modify: `apps/web/src/pages/MaterialsPage.test.jsx`
- Create: `apps/web/src/app/store/session.test.js`

- [ ] **Step 1: Write the failing frontend session test**

```js
it("stores token after login and loads current user from /auth/me", async () => {
  authApi.login = vi.fn().mockResolvedValue({ accessToken: "real-token" });
  authApi.me = vi.fn().mockResolvedValue({ id: "u1", login: "demo_admin", roles: ["администратор"] });

  const user = await useSession.getState().login({ email: "demo_admin", password: "secret123" });

  expect(tokenStorage.get()).toBe("real-token");
  expect(user.login).toBe("demo_admin");
});
```

- [ ] **Step 2: Run the failing frontend tests**

```bash
npm --workspace @fable/web run test -- --runInBand
```

Expected: FAIL because the current store sends `{ email, password }` while the backend expects `login`, and the default API URL points to `:8000/api` instead of the gateway on `:3000/api`.

- [ ] **Step 3: Fix the frontend contract with minimal surface area**

Make these concrete adjustments:
- `client.js`: default `VITE_API_URL` to `http://localhost:3000/api`;
- `client.js`: normalize backend errors from `{ error: { message } }` as well as `{ message }`;
- `session.js`: submit `login` instead of `email`, while still reading the same form field from UI;
- `session.js`: persist the `me` response shape without assuming mock-only fields.

Target login change:

```js
login: async ({ email, password }) => {
  const response = await authApi.login({ login: email, password });
  const token = getToken(response);
  tokenStorage.set(token);
  const user = response.user ?? (await authApi.me());
  set({ user });
  persistUser(user);
  return user;
}
```

- [ ] **Step 4: Remove gateway-local demo fallback behavior**

In `apps/gateway/src/index.ts`, delete or bypass the hardcoded `demoUser`, `tokens` and local content arrays once real service URLs are configured. Gateway behavior should become: proxy or fail explicitly, but never silently serve a shadow backend.

- [ ] **Step 5: Re-run frontend verification**

```bash
npm --workspace @fable/web run test
npm --workspace @fable/web run build
npm --workspace @fable/gateway run check
```

Expected: PASS.

### Task 6: Final smoke verification for local and Docker flows

**Covers:** [S2, S6, S7]

**Files:**
- Modify: `docker-compose.yml`
- Modify: `scripts/smoke-backend.sh`
- Modify: `README.md`

- [ ] **Step 1: Fill the smoke script with real requests**

```bash
TOKEN="$({
  curl -sS -X POST "$API_BASE_URL/auth/login" \
    -H 'Content-Type: application/json' \
    -d '{"login":"demo_admin","password":"demo_password"}'
} | jq -r '.token // .accessToken')"

curl -sS "$API_BASE_URL/auth/me" -H "Authorization: Bearer $TOKEN"
curl -sS -X POST "$API_BASE_URL/content" -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{"title":"Smoke draft","type":"article","category":"Статьи"}'
curl -sS "$API_BASE_URL/admin/users" -H "Authorization: Bearer $TOKEN"
```

- [ ] **Step 2: Verify the non-Docker local path**

Run in separate shells:

```bash
docker compose up -d postgres
npm run dev:backend
npm run dev:web
bash scripts/smoke-backend.sh
```

Expected: PASS.

- [ ] **Step 3: Verify the Docker path**

```bash
docker compose up --build -d
bash scripts/smoke-backend.sh
```

Expected: PASS against the same API base URL.

- [ ] **Step 4: Run the final root verification command**

```bash
npm run check
```

Expected: PASS.

- [ ] **Step 5: Update the README acceptance section with the final proven commands**

```markdown
Проверка готовности:
- `npm run check`
- `bash scripts/smoke-backend.sh`
- `docker compose up --build`
```

## Self-Review

- [x] Every spec section `[S1]`..`[S8]` is covered by at least one task.
- [x] The migration/schema mismatch (`event_announcement` vs `event`) is explicitly addressed.
- [x] No `TODO`/`TBD` placeholders remain in tasks.
- [x] Frontend/gateway/backend contract mismatches are called out explicitly (`VITE_API_URL`, `login` payload, demo fallback removal).