# Findings & Decisions

## Requirements
- Verify the repository against the 9-step implementation plan provided by the user.
- Use `/Users/liangxu/Documents/test/geo-rankly/docs/superpowers/specs/2026-03-31-admin-web-backend-core-design.md` as the source of truth for the next development slice.
- Continue development immediately after identifying the earliest unfinished step.
- For desktop AI monitoring, put scheduling authority on the client, keep scraping silent/background-only, allow stale cross-day tasks to be dropped, and avoid fanning one question to all models at once.

## Research Findings
- Current 2026-05-07 publish-management request targets `apps/admin-web`: the user wants a new content-management page showing publish title, account/platform, status, task info, time, and actions for external link, opening the desktop client workbench, and retrying.
- Desktop client already has `PublishManagementView.vue` with the desired table shape and action semantics, but it calls Electron IPC (`window.desktopBridge`). Admin-web needs tenant-authenticated HTTP endpoints instead.
- Existing backend desktop endpoints are `/api/desktop/publish-tasks` and `/api/desktop/publish-tasks/:id/retry`, but they require desktop client token auth. Tenant API currently exposes publish-job creation only, not publish task list/retry.
- `DesktopTaskService.ListPublishTasks` already has the correct pagination/title-search/status ordering behavior, but accepts a desktop client context. A tenant variant should scope by request actor/current workspace and created-by user.
- `PublishJobService.RetryByDesktopTask` already contains retry reconstruction logic, but accepts desktop client context. A tenant variant can reuse the same core flow with actor workspace/user ownership checks.
- Admin-web content-management nav currently includes media, knowledge, and images under `AppShell.vue`; publish management should join that group as `/publish-management`.
- Web "open workbench" cannot call Electron IPC directly. A desktop deep-link URL can be used as a link-style entry; if the desktop app does not register that scheme yet, the link is still a front-end contract for the desktop client to adopt.
- Current review scope: determine whether the monitoring data detail path and the daily scheduled generation of question collection tasks are working.
- `cmd/scheduler` starts `ScheduleDispatchWorker`, monitoring result recovery, lease recovery, received inspection, and knowledge cleanup; it does not start a worker that generates daily `monitoring_collect_tasks`.
- The only production code path found so far that inserts `monitoring_collect_tasks` is `MonitoringService.CollectNow` via `ensureCollectNowTasks`; this writes `trigger_source = 'manual'`.
- Current local Monitoring PG data confirms recent task creation is manual: on 2026-04-24 there are 3 desktop/manual/plugin_standard tasks; on 2026-04-23 there are 6 desktop/manual/plugin_standard tasks. The latest `automatic` monitoring collect tasks in this local DB are from 2026-04-17, not today.
- Current local business PG has `tenant_monitoring_quotas.collect_frequency = 'daily'` and `task_daily_hard_cap = 36`, but those fields are configuration only in the code paths inspected so far; no scheduler reads them to generate today's monitoring tasks.
- The repository already contains core backend scaffolding under `server/`, including `cmd/tenant-api`, `internal/bootstrap`, `shared`, `tenant`, `migrations`, and SQL query files.
- `server/Makefile` already defines `dev-init`, `dev-api`, `migrate-up`, `sqlc-generate`, `seed`, `lint`, and `test`.
- The bootstrap layer already exposes `/api/health/live` and `/api/health/ready`.
- The design doc defines a sequential 9-step delivery plan and expects `sqlc` generated code under `internal/tenant/repository/generated/`, plus repository wrappers around it.
- The repository has 19 migration `.up.sql` files, matching the plan's schema count, and `cmd/dev-seed` seeds `admin@geo.local` plus plan/quota/template data.
- `internal/tenant/repository/` currently contains only query SQL, `sqlc.yaml`, `tx.go`, and placeholder integration tests; there is no `generated/` directory and no repository wrapper implementations.
- `auth_service.go`, `workspace_service.go`, `template_service.go`, `article_service.go`, and `brand_service.go` still issue SQL directly against `pgxpool.Pool`, which contradicts the design doc's Step 4 target.
- Running `make sqlc-generate` currently fails because `server/internal/tenant/repository/sqlc.yaml` sets `schema: "../../migrations/"`, which resolves to a non-existent path. The correct repository-relative path should point to `server/migrations`.
- After fixing `sqlc.yaml`, `make sqlc-generate` succeeds and produces typed code in `server/internal/tenant/repository/generated/`.
- Repository wrappers now exist for auth, workspace, template, article, quota, and audit queries, and the auth/workspace/template services consume them on the main code path.
- Refresh token rotation is now atomic in Redis via a Lua script in `session_store.go`, with tests covering successful rotation and hash mismatch rejection.
- `make test` and `make lint` both pass locally after cleaning up existing lint violations.
- A GitHub Actions workflow now exists at `.github/workflows/backend-ci.yml`; it runs `sqlc` generation, verifies generated code is committed, executes the tenant SQL scope guard, runs tests, and runs `golangci-lint`.
- The `server/Makefile` now exposes `tenant-scope-guard`, so the tenant filter check is available both locally and in CI.
- The `server/Makefile` no longer depends on a preinstalled `migrate` binary; it now runs `golang-migrate` via `go run -tags postgres`, which allowed `make dev-init` to run successfully on this machine.
- `make dev-init` now completes end-to-end: Docker services start, all 19 migrations apply, and seed data creates tenant/user/plan/template records.
- Runtime verification succeeded for `/api/health/live`, `/api/health/ready`, `POST /api/auth/login`, `GET /api/auth/me`, `POST /api/auth/refresh`, and `POST /api/auth/logout`.
- Negative auth checks also passed at runtime: the old access token returns `40103 token_revoked` after logout, and the old refresh token returns `40121 refresh_session_expired` after rotation.
- Workspace runtime verification passed for all four first-screen endpoints: `overview`, `recent-articles`, `quota-summary`, and `template-cards`.
- Template generation runtime verification passed end-to-end: creating a generation task produced an article, article detail returned `generate_status=completed`, article versions returned one version, and quota balance decreased from 100 to 99.
- Brand runtime verification passed for create keyword/question/competitor flows, question version history returned two versions after update, and soft-deleted brands can be recreated with the same name.
- The repository still has no `apps/` or `packages/` directories, so neither `admin-web` nor `ops-admin-web` has been started.
- The frontend architecture doc recommends `pnpm workspace + Vue 3 + TypeScript + ant-design-vue + Vite`, with shared packages for UI, shared DTOs, HTTP client, and TS config.
- The current backend already exposes enough stable endpoints for a first `admin-web` slice: `POST /api/auth/login`, `GET /api/auth/me`, and the four workspace endpoints under `/api/tenant/workspace/*`.
- Backend responses use a consistent envelope: `code`, `message`, `data`, and `request_id`, which makes a shared frontend API client straightforward.
- Local toolchain support for the frontend is present on this machine: `node v22.20.0`, `npm 10.9.3`, and `pnpm 10.28.2`.
- A new pnpm workspace now exists at the repo root, with `apps/admin-web` plus shared packages under `packages/shared-types`, `packages/http-client`, and `packages/tsconfig`.
- `apps/admin-web` is now a working Vue 3 + TypeScript + Vite 8 app with Ant Design Vue, Pinia, Vue Router, and Vue Query wired in.
- The frontend implements a persistent auth session store, login flow, route guard, auto-refresh-capable API client, and a tenant-facing application shell.
- The workspace page is wired to live backend data through the four dashboard endpoints and renders template cards, stats, quota, and recent articles.
- Placeholder routes now exist for template creation, custom generation, optimization, media, brands, tracking, and knowledge so the navigation shell is ready for incremental page delivery.
- `pnpm build:admin` passes successfully, producing a production build under `apps/admin-web/dist/`.
- Static preview verification passed via `vite preview` and HTTP checks against `http://127.0.0.1:4173/login`, which returned `HTTP/1.1 200 OK` plus the built asset references.
- Gemini CLI was tested but then abandoned for this turn: `gemini-3.1-pro-preview` consistently returned `429 MODEL_CAPACITY_EXHAUSTED`, and the user explicitly requested not to use Gemini afterward.
- After the user indicated Playwright was fixed, browser-level verification succeeded through the Playwright CLI path rather than the broken MCP path.
- Browser testing exposed one real frontend bug: the login CTA rendered correctly but did not submit the form on click until it was explicitly bound to `handleSubmit`.
- After the login-button fix, a Playwright end-to-end flow successfully loaded `/login`, signed in with the seeded account, reached `/workspace`, and verified the presence of the workspace heading plus the template and recent-content sections.
- The production bundle size improved substantially after switching Ant Design Vue registration from full-plugin mode to per-component registration; the main JS chunk dropped from roughly `1.4 MB` to about `747 kB` before gzip.
- The currently exposed tenant-facing backend interfaces fall into four frontend-covered groups: auth, workspace, templates/articles, and brands.
- The reference screenshots were re-read using position-aware OCR extraction, which made the layout intent clear beyond the raw text labels.
- `docs/refer/工作台.png` places the main content in a left-heavy column with template cards above recent articles, while the right side holds the compact stats cluster; the quota/plan card sits in the left sidebar footer rather than the main canvas.
- `docs/refer/模板创作.png` uses a top page hero, a horizontal filter/action strip, an article table below it, and a separate template-selection layer before entering a 3-step generation flow.
- `docs/refer/文擎GEO/模版创作-新建模版-创建topx文章-步骤一.png` and `...步骤二.png` show the generation flow as a wizard: step 1 basic info plus brand/keyword/competitor context, step 2 title and structure selection, step 3 generation.
- `docs/refer/品牌词库.png` uses a top brand card rail, then a split content area with keyword navigation on the left and question management on the right; the competitor library lives under a sibling tab.
- `docs/refer/媒体管理.png` confirms the overall visual system: page hero under the content header, three-step guide card near the top, and white cards on a cool gray background with the same left navigation shell.
- The user explicitly asked for i18n and styling discipline during implementation: text should move behind translation keys, and component styles should live in `<style>` blocks rather than inline attributes.
- `pnpm dev:admin` regressed temporarily after the route graph referenced a missing `BrandsView.vue`; adding the missing view, installing the new frontend dependency set, and rerunning checks restored the Vite startup path.
- `pnpm typecheck:admin` now passes after introducing the i18n scaffold, restoring `AppShell.vue` to the user's preferred version, and removing inline styles from the Vue SFC templates.
- The currently used hard-coded prompts are concentrated in four runtime areas: `cmd/dev-seed` platform template seeds, `template_prompt.go` generation fallback sections, `template_assist.go` analyze/title/outline fallback prompts, and `prompt_generate_service.go` plus `knowledge_service.go` prompt supplements.
- The seed path stores four full article prompt templates plus twelve wizard prompt templates inside large inline JSON blobs, which makes prompt iteration awkward and easy to miss during later tuning.
- Runtime prompt assembly still embeds section titles, writing rules, output requirements, output examples, and knowledge-reference instructions directly inside application functions.
- A dedicated prompt hub now exists under `server/internal/tenant/prompts/`: `template_seeds.go` owns the four platform template seeds and their wizard prompt templates, while `runtime.go` owns generation fallback prompts, assist fallback prompts, prompt-rule supplements, and knowledge prompt instructions.
- `cmd/dev-seed` now reads platform templates from `prompts.PlatformTemplateSeeds()` instead of carrying 400+ lines of inline prompt/card-config text in the command itself.
- `template_prompt.go`, `template_assist.go`, `prompt_generate_service.go`, and `knowledge_service.go` now assemble prompts from the centralized prompt package, so runtime business logic no longer embeds the long prompt text directly.
- The prompt centralization also corrected invalid JSON quoting in the seed card config `custom_placeholder` fields, which previously contained unescaped inner quotes.
- Targeted verification passed with `go test ./internal/tenant/... ./cmd/dev-seed` from `server/`, confirming the refactor compiles cleanly across the affected runtime and seed paths.
- `desktop-client` now includes an AI platform management view with all six target platforms and the existing bind/open/unbind flows wired through the desktop bridge.
- `account-binder.ts` already supports all six AI platforms through generic binding definitions, but identity detection is heuristic and not yet platform-specific.
- The current desktop runtime executes tasks through a simple in-memory FIFO guarded by a single `currentTaskId`, so all desktop tasks are effectively global-serial today.
- Monitor-task dropping by `business_date` is already implemented in the runtime controller; stale tasks are returned as `unknown` with a client-drop reason instead of being retried on the next day.
- There is currently no durable local monitor-task queue/cache in `desktop-client`; if the process exits, queued work only survives on the server side.
- `process-metrics.ts` already samples Electron process CPU and memory, which gives us enough local telemetry to drive a small adaptive-concurrency policy without introducing a new metrics dependency.
- `session-registry.ts` already persists per-account Electron session partitions to `desktop-session-partitions.json`, showing that lightweight file-backed persistence is already accepted in this runtime.
- The only implemented monitor adapter is `doubao`, and it still uses the existing hidden `WebContentsView` path rather than Playwright.
- `playwright-core` is installed in `apps/desktop-client`, but there is no `connectOverCDP()` runtime integration yet.
- Hidden execution primitives already exist in two forms: hidden `BrowserWindow` instances for silent account checks and pooled hidden `WebContentsView` instances for existing adapters.
- Runtime diagnostics already expose scheduler and process-metrics state through the desktop snapshot, so new scheduler/CDP fields can be surfaced without inventing a new renderer path.
- A new local monitor scheduler now persists queued monitor tasks to `app.getPath("userData")/desktop-monitor-scheduler.json`, recovers same-day tasks after restart, and drops stale cross-day tasks during hydration.
- The new scheduler is intentionally conservative when a task has no question-level metadata: unknown-question monitor tasks do not consume the second concurrency slot, which avoids accidental same-question fan-out until server event metadata is available.
- Electron process metrics are sufficient to drive a two-tier adaptive concurrency policy: default to `1`, raise to `2` only when the machine looks healthy enough and multiple live AI accounts exist.
- Desktop task SSE events now carry optional `business_date`, `scheduler_group_key`, `question_text`, and `title` metadata derived from the task payload, allowing the local scheduler to defer same-question fan-out before leasing.
- A new hidden Playwright manager now connects to Electron Chromium through a local CDP endpoint and leases hidden pages bound to the existing account session partition, while leaving the legacy hidden-view path available for current adapters.
- The browser-extension `qwen` adapter does not rely on stable DOM selectors; it drives Tongyi's internal text/chat managers from `__TONGYI_PORTSL_GLOBAL_CONTAINER__` and reads results from `__qianwenChatAPI`, which makes Playwright page evaluation a better desktop port than raw HTTP.
- Qwen binding was previously too strict for desktop because the generic AI bind flow waited for obvious post-login UI signals like avatar/name; in practice Qwen can already have a durable session footprint before those signals render, so the bind window may fail to auto-close.
- Anonymous `curl` inspection of `https://www.qianwen.com/` currently returns an `XSRF-TOKEN` cookie even before login, so CSRF-only cookies should not count as authenticated AI session evidence.
- On this machine's real `pending-qwen-*` partition, a logged-in Qwen session persists cookies including `tongyi_sso_ticket`, `tongyi_sso_ticket_hash`, and `b-user-id`; these are materially stronger auth signals than generic DOM nickname/avatar detection.
- The user clarified that only `yuanbao`, `kimi`, and `deepseek` require login for monitor execution; other AI platforms may still ask questions and collect responses anonymously, so preflight auth gating must not block those monitor tasks.
- The `admin-web` tracking page still used the removed browser-plugin monitoring bridge for `立即采集`, even though the current monitoring architecture is desktop-client driven and runs silently in the background.
- The user clarified that `立即采集` must only be available when the current logged-in user's own desktop client is online; another user's online client in the same workspace must not make the action available.
- `MonitoringService.CollectNow` previously fell back to the most recently online workspace client regardless of `user_id`, so the backend rule did not match the desired UI rule until this turn.
- Media publishing is now treated as the desktop runtime foreground channel, while AI monitoring remains background/best-effort. This is implemented through admission control rather than queue ordering alone.
- A new in-memory `publish-scheduler.ts` owns publish queue selection, per-platform active locks, and 3-6 second post-completion platform cooldowns. It intentionally does not persist state or copy monitor scheduler question/cross-day semantics.
- `runtime-controller.ts` now uses per-kind lease-in-flight tracking, so a monitor lease request no longer blocks a publish lease request at the runtime-controller guard.
- Total runtime concurrency is now derived from hardware class, current Electron process health, and optional `GEO_DESKTOP_MAX_TOTAL_CONCURRENCY`, while monitor capacity is capped to leave a reserved foreground publish slot.
- When publish is queued or publish lease is in flight, monitor admission returns zero; even a same-platform/cooldown-blocked publish backlog prevents monitor from consuming the publish reserve.
- Desktop runtime diagnostics now expose `publishScheduler` alongside `monitorScheduler` in the runtime snapshot.

## Technical Decisions
| Decision | Rationale |
|----------|-----------|
| Verify by code inspection first, then run targeted commands | Faster way to establish step coverage before making changes |
| Use the design doc as the acceptance reference when repository behavior is ambiguous | User explicitly pointed to this document for next-step development |
| Treat Step 4 as the current development target unless command verification disproves it | Earlier steps have visible artifacts, but repository/sqlc acceptance is not yet met |
| Fix `sqlc` generation and introduce repository wrappers before touching later roadmap items | This is the first broken acceptance gate and an architectural dependency for the service layer |
| Close Step 9 by adding repository-scoped CI rather than a repo-wide generic pipeline | The remaining missing acceptance item was backend CI plus the tenant scope guard |
| Resume into `admin-web` instead of `ops-admin-web` | Only tenant-facing APIs exist in the repository today, so this is the only frontend slice that can be meaningfully wired end to end |
| Keep the initial frontend page set broad in navigation but shallow in implementation | This gives the repo a usable admin shell now without inventing missing backend modules for later pages |
| Use templates/articles and brands as the primary implementation targets for this turn | They are the remaining backend-backed pages still missing real frontend coverage |
| Use screenshot-derived spatial structure as an implementation constraint | Needed to satisfy the user's requirement to follow layout and placement, not just labels |
| Introduce a minimal `vue-i18n` foundation now instead of leaving hard-coded strings in new pages | The user explicitly called out the current i18n approach as non-standard |
| Keep `AppShell.vue` on the user-preferred version and avoid structural/style rewrites there | The user said that file is managed elsewhere and only allowed inline-style cleanup |
| Create a dedicated `internal/tenant/prompts` package for prompt text and seed definitions | This keeps prompt tuning in one place while minimizing refactor risk in the current dirty worktree |
| Add the local scheduler before wiring more monitor adapters | This aligns with the user's requirement that the client, not the server, decides actual execution timing |
| Keep publish-task execution behavior intact while evolving monitor-task scheduling | Publish is already working and should not be destabilized by monitor-specific policy changes |
| Build the hidden Playwright layer as reusable infrastructure instead of burying it inside one adapter | Qwen is the immediate motivation, but the same layer will likely be needed by other complex AI platforms |
| Port Qwen by evaluating in-page managers/state instead of reverse-engineering private APIs | The existing extension path already proved this is the stable way to drive Qwen's encrypted web client |
| Exclude CSRF-only cookie names from generic AI auth fingerprinting | Qwen sets `XSRF-TOKEN` on anonymous visits, which would otherwise create false-positive auth evidence |
| Only enforce active auth preflight for monitor tasks on `yuanbao`, `kimi`, and `deepseek` | The user explicitly allowed anonymous execution for the other AI monitoring platforms |
| Gate tracking `collect-now` on the current actor's online desktop client, not any workspace client | The user explicitly wants the action tied to the current logged-in account's client presence |
| Expose current-user desktop-client availability through the monitoring dashboard response | `TrackingView` already loads the dashboard, so returning the runtime bit there avoids a second frontend probe and keeps button gating aligned with backend validation |
| Implement publish priority through runtime admission control, not just queue sort order | Already-running monitor tasks cannot be moved by queue priority; publish needs reserved execution capacity to avoid starvation |
| Keep monitor hard preemption out of the first publish-priority slice | Soft priority with reserved capacity avoids browser half-submit and lease/result inconsistency while still preventing monitor saturation |

## Issues Encountered
| Issue | Resolution |
|-------|------------|
| Repository is fully untracked in git status output | Avoid relying on git history; verify via filesystem and test commands instead |
| `make sqlc-generate` fails before any code is generated | Repair the `sqlc.yaml` schema path and then build repository wrappers around generated queries |
| `go run` migrate initially failed with `unknown driver postgres` | Added `-tags postgres` to the Makefile-managed migrate command |
| Playwright MCP could not open a browser session locally because it tried to create `/.playwright-mcp` | Use `vite preview` plus `curl` verification for this turn instead of spending time on browser tool plumbing |
| `desktop-client` has no existing SQLite/local DB layer despite `better-sqlite3` being installed | Decide between a tiny file-backed queue or adding a new DB-backed task store during implementation |

## Resources
- `/Users/liangxu/Documents/test/geo-rankly/docs/superpowers/specs/2026-03-31-admin-web-backend-core-design.md`
- `/Users/liangxu/Documents/test/geo-rankly/server/Makefile`
- `/Users/liangxu/Documents/test/geo-rankly/server/cmd/tenant-api/main.go`
- `/Users/liangxu/Documents/test/geo-rankly/server/internal/bootstrap/bootstrap.go`
- `/Users/liangxu/Documents/test/geo-rankly/server/internal/shared/auth/session_store.go`
- `/Users/liangxu/Documents/test/geo-rankly/server/internal/tenant/repository/sqlc.yaml`
- `/Users/liangxu/Documents/test/geo-rankly/server/scripts/check_tenant_scope.sh`
- `/Users/liangxu/Documents/test/geo-rankly/.github/workflows/backend-ci.yml`
- `/Users/liangxu/Documents/test/geo-rankly/server/docker-compose.yaml`
- `/Users/liangxu/Documents/test/geo-rankly/apps/admin-web`
- `/Users/liangxu/Documents/test/geo-rankly/packages/shared-types/src/index.ts`
- `/Users/liangxu/Documents/test/geo-rankly/packages/http-client/src/index.ts`

## Dongchedi Desktop Publish Debug - 2026-04-28
- Local `desktop_tasks` evidence for article `95` showed the latest `dongchedi` failures changed from `request_failed_403` to platform response `server exception` after switching the adapter to page-context publish.
- Raw `article_versions.markdown_content` stores diff-match-patch patches by design; repository reconstruction for article `95` produced a normal 8219-byte article body, so raw DB diff text is not the publish payload.
- The reconstructed article contains editor image asset references from `/api/public/assets/...`; Dongchedi `/spice/image?sk=dcd` cannot fetch localhost/relative desktop assets. Leaving those image URLs in final HTML is a likely cause of Dongchedi `server exception`.
- After image URL replacement was fixed, Dongchedi still returned `server exception`; local reconstruction of article `95` showed the submitted HTML contained GFM `<table>` output. The Dongchedi publish API likely rejects or crashes on table markup, so the desktop adapter now downgrades tables to paragraph rows before submit.
- After table downgrading, Dongchedi still returned `server exception`; the adapter now further reduces content to conservative tags (`p`, `strong`, `img`), strips editor image wrapper attributes, converts headings/list items to paragraphs, and runs ImageX-uploaded local body images through `spice/image` before inserting the content URL.
- Latest retry after conservative HTML still returned `server exception` with `content_table_count = 0`, `content_has_local_asset_url = false`, and `content_image_count = 1`, so the remaining suspects are the body image URL shape, table-derived HTML entities, or cover metadata rather than raw local asset/table markup.
- Follow-up hardening removes `&nbsp;` from Dongchedi body HTML and tries Dongchedi `/spice/image?sk=dcd` in both session and page context.
- A retry showed `content_image_upload_strategies = ['imagex_direct_fallback']` and still returned `server exception`, confirming direct ImageX body URLs are not safe for Dongchedi正文. The adapter now removes local body images that cannot be converted to a Dongchedi `spice` URL and submits the article with the uploaded cover only.
- A no-body-image retry still returned `server exception`, leaving `extra.content_word_cnt` as the most suspicious remaining mismatch because it was still hardcoded to the reference extension's `267` while the final submitted content length is much larger. The adapter now computes `content_word_cnt` from the final HTML text and logs both submitted and recomputed counts.

## Visual/Browser Findings
- Reviewed the reference screenshots for `工作台.png` and `模板创作.png` and matched the new UI to the same left-nav plus airy card/table composition.
- Browser automation verification was attempted but blocked by the local Playwright MCP directory error; preview HTTP verification succeeded instead.
- Later browser verification succeeded with Playwright CLI, and the captured login/workspace screenshots matched the intended layout and data density.
- Position-aware OCR of the reference images confirmed the sidebar navigation occupies roughly the left 10-12% of the frame, with content titles aligned at the upper-left of the main canvas and most action buttons aligned to the right edge of page headers.
- The workspace screenshot places stats on the upper-right and the recent-articles table directly beneath the template card block, so the existing all-grid treatment should be tightened into a more asymmetric two-column composition.

## Monitoring Daily Collection Review
- Data-detail/dashboard reads are working for existing monitoring data: the detail API returned 2026-04-24 question samples, and the dashboard composite showed manual collection progress for brand 3.
- The daily automatic path was not working before this repair: `cmd/scheduler` started article scheduled generation plus monitoring recovery/inspection workers, but no worker generated `monitoring_collect_tasks` from `tenant_monitoring_quotas.collect_frequency = daily`.
- Local monitoring DB evidence matched the code gap: 2026-04-24 and 2026-04-23 tasks were manual/plugin-standard; the latest automatic tasks were older 2026-04-17 and 2026-04-10 rows.
- `MonitoringService.CollectNow` was the only production path found that inserted monitoring collect tasks before this repair, and it writes `trigger_source = manual`.
- The repair adds `MonitoringDailyTaskWorker` under `internal/tenant/app` and starts it from `cmd/scheduler`.
- Daily task generation now materializes durable `monitoring_collect_tasks` after midnight using stable jitter, per-run/per-plan/per-brand caps, daily hard-cap enforcement, tenant/brand advisory locks, and the existing idempotent unique key.
- Desktop offline is now a normal deferred state: automatic daily tasks stay `pending` with `execution_owner = desktop_tasks`; missing live desktop account/client no longer falls back to legacy backend execution.
- Due desktop dispatch is claimed with `FOR UPDATE SKIP LOCKED`, `last_dispatched_at`, and `dispatch_attempts`, so multiple scheduler instances do not repeatedly fan out the same pending tasks.
- P0 follow-up: when `desktop_tasks` rollout is disabled or the tenant has no `primary_client_id`, the daily worker now skips the plan instead of inserting `automatic/legacy` rows. This prevents orphan daily tasks that no intended worker will dispatch.
- Follow-up simplification: Go runtime and dev seed code no longer depend on `tenant_monitoring_quotas`. Daily plans are derived from registered `desktop_clients`; platform coverage uses the canonical default monitoring platform set; dashboard/projection no longer read quota rows; and heartbeat/collect-now no longer write a primary client pointer into that table.
- P0 follow-up: daily worker RabbitMQ publish no longer uses `context.Background()`. It now derives a 5-second child context from the worker tick context, so RabbitMQ publish is bounded by both the per-publish timeout and the worker's 45-second deadline.
- P0 follow-up: one tenant/brand failure no longer aborts the whole tick. Plan/brand load and generation failures increment summary failure counts, log scoped fields, and continue unless the worker context is canceled or reaches its deadline.
- Observability follow-up: the daily worker now records real counters/gauges for completed/failed/partial runs, plan/brand failures, skipped plans, planned/due/created/desktop/deferred task counts, last timestamps, duration, scope counts, business date, and last fatal error code.
- `cmd/scheduler` now starts a lightweight HTTP server on `scheduler.http_port` default `8081`; `/metrics` returns Prometheus text for scraping and `/api/internal/metrics/monitoring/daily-tasks` returns the JSON snapshot from the scheduler process.
- Fairness follow-up: daily hard-cap accounting now starts from the durable count of already materialized automatic desktop tasks for that tenant/date, keeps the full hard-cap candidate horizon for existing-key filtering, and only decrements in-memory remaining capacity by rows actually inserted in the current tick. Existing candidates no longer consume later brands' new-task capacity.
- Product-policy follow-up: the daily worker no longer treats any registered desktop client as eligible. Daily plans now require an active tenant subscription, use subscription/config brand limits, use only live desktop `platform_accounts` as authorized AI platforms, and compute per-brand task capacity from `min(active configured questions, brand_library.max_keywords * max_questions_per_keyword) * authorized_platform_count`.
- Dashboard/projection follow-up: platform lists no longer backfill the full six-platform catalog. Tenant UI quota resolution is based on the current user's registered desktop client and bound platform accounts; projection platform rows are derived from actual task platforms for that brand/date.
- Verification passed with targeted Go tests and a live Postgres `EXPLAIN` of the new SQL claim statement.
- Heartbeat primary follow-up: selecting the primary desktop client by `ORDER BY last_seen_at DESC` is unsafe because the current heartbeat has not touched `last_seen_at` yet and multiple desktop clients can alternate primary. The fix uses a per-tenant/per-workspace `desktop_client_primary_leases` row with a TTL: the incumbent renews its lease, non-primary clients cannot steal a live lease, and failover only happens after lease expiry or primary client revocation.
- Daily-plan follow-up: daily automatic task generation now prefers the sticky primary lease when choosing `primary_client_id`; if no lease exists or the leased client has no bound platform accounts, it falls back to a deterministic eligible desktop client.
- UI quota follow-up: current-user registered client lookup no longer sorts by `last_seen_at`; it now uses registration order so heartbeat cadence cannot make platform authorization display flip between the same user's desktop clients.
- Index follow-up: `desktop_clients` did not have a tenant/workspace/last_seen covering index. A migration now adds tenant/workspace and tenant/workspace/user partial indexes for active desktop-client lookup paths.
- Scheduler metrics hardening: `/metrics` and `/api/internal/metrics/monitoring/daily-tasks` now require a configured internal metrics token and accept either `Authorization: Bearer <token>` or `X-Internal-Metrics-Token`. If the token is missing, the HTTP metrics server does not start.
- Scheduler bind hardening: `scheduler.http_host` defaults to `127.0.0.1` instead of `0.0.0.0`; deployments that need pod/network scraping must explicitly set `SCHEDULER_HTTP_HOST=0.0.0.0` or config equivalent and provide `SCHEDULER_INTERNAL_METRICS_TOKEN`.
- Scheduler shutdown hardening: the metrics server now uses `http.Server` with `Shutdown`, and `ListenAndServe` errors are logged without `Fatalf`, so a port bind failure does not kill all scheduler workers or bypass deferred cleanup.
- Scheduler disablement: `scheduler.http_port: -1` is preserved as an explicit disable sentinel, while omitted/zero ports still normalize to `8081`.
- Scheduler worker shutdown follow-up: the scheduler process now starts every long-running worker through a `sync.WaitGroup` and waits on shutdown before returning from `main`, so deferred DB/MQ cleanup does not race active worker goroutines.
- Worker lifecycle follow-up: scheduler workers expose blocking `Run(ctx)` entrypoints. Their loops still stop when the process context is canceled, but active `runOnce` work uses its own timeout context and is not interrupted immediately by the signal.
- Authorization-contract follow-up: dashboard runtime and question-detail responses now expose `platform_authorization_status` with `authorized`, `no_desktop_client`, and `no_authorized_platforms`. Dashboard runtime also exposes `authorized_monitoring_platform_count`.
- Frontend no-auth follow-up: `TrackingView` does not render a dashboard no-authorized/no-desktop alert; it keeps the platform matrix stable and disables collect-now for no authorized platforms and for a selected platform outside the authorized set. `TrackingQuestionDetailView` still renders an explicit unavailable state when detail data has no executable platforms.
- Browser regression: admin-web was exercised with a no-authorized-platform response. Dashboard rendered all six platform rows, blocked collection, and did not show the removed no-authorized alert; question detail showed the unavailable state and did not render the answer/detail grid.
- Product display follow-up: the dashboard/projection display contract is now fixed at the canonical six AI platforms (`yuanbao`, `kimi`, `wenxin`, `deepseek`, `doubao`, `qwen`). This is separate from executable platform authorization, so a revoked/offline/unbound platform remains visible with zero samples/pending status instead of disappearing.
- Authorization execution follow-up: dashboard runtime now returns `authorized_monitoring_platform_ids`; frontend collect-now uses this explicit list to decide whether a selected platform is executable, not the six display rows.
- Workspace-scope follow-up: monitoring quota/runtime/access-state and collect-now client resolution now use `auth.CurrentWorkspaceID(ctx)` instead of `actor.PrimaryWorkspaceID`, so a future multi-workspace switch can scope desktop clients and platform accounts correctly.
- Workspace request scope is set by `WorkspaceScope`: absent `X-Workspace-ID` falls back to the actor's primary workspace; a non-primary workspace id must be present in `workspace_memberships` for the current tenant/user.
- Daily-plan config follow-up: malformed `enabled_platforms` JSON now returns a decode error, logs a scoped Warn with tenant/workspace/business date, increments the plan failure counter through `FailedPlanCount`, and skips only that plan.
- Heartbeat primary lease follow-up: the primary decision path no longer runs a write transaction or `FOR UPDATE` on every heartbeat. Normal primary/non-primary heartbeats are read-only; writes happen only for missing lease insert, throttled primary renew, expired/unavailable primary claim, or CAS race handling.
- Heartbeat lease observability now records resolution outcomes, DB write operations, CAS contention, errors, and duration; tenant-api exposes JSON and Prometheus-format internal endpoints under `/api/internal/metrics/monitoring/heartbeat-primary-lease` when `scheduler.internal_metrics_token` is configured.
- Monitoring heartbeat snapshot follow-up: access snapshots are now handled as semantic state instead of a per-heartbeat liveness write. The heartbeat path batch-loads current platform states, skips fresh unchanged rows, refreshes unchanged rows at most every 10 minutes, and only opens a monitoring DB transaction if a snapshot insert/update/refresh or pending-task reconciliation is actually needed.
- Inaccessible-platform reconciliation now does a read-only pending-task platform check first. Stable `not_logged_in` / `unavailable` reports with no pending tasks do not open a transaction; if pending rows exist, the primary client updates only those rows to `skipped`.
- Monitoring heartbeat snapshot observability now tracks reported platforms, opened transactions, snapshot inserts/updates/refreshes/skips, reconciled skipped tasks, projection rebuilds, errors, and duration. Tenant-api exposes token-protected JSON and Prometheus endpoints under `/api/internal/metrics/monitoring/heartbeat-snapshots`.
- Added a monitoring DB partial index for the reconciliation check: `idx_collect_tasks_pending_platform_reconcile` on `(tenant_id, business_date, ai_platform_id)` where `collector_type = 'desktop'` and `status = 'pending'`.
- Prometheus exposition follow-up: daily-task, heartbeat-primary-lease, and heartbeat-snapshot Prometheus text output now uses `prometheus/client_golang` collectors plus `promhttp` instead of hand-written `Fprintf` formatting.
- Scheduler `/metrics` now uses a dedicated Prometheus registry with the custom daily-task collector plus `collectors.NewGoCollector()` and `collectors.NewProcessCollector()`. Process metrics are emitted on supported production OSes such as Linux; local Darwin tests assert runtime metrics and keep process assertion OS-gated.
- `client_golang` v1.20.5 still does not escape raw carriage returns in label values before exposition on this local toolchain, so the custom collector path normalizes `\r` to a literal `\\r` sequence before passing label values into `ConstMetric`.
- Daily task materialization follow-up: `ensureDailyMonitoringCollectTasks` no longer loops with one `tx.Exec` per candidate. It now builds arrays of question IDs, question hashes, platform IDs, and dispatch times, then performs one `INSERT ... SELECT FROM unnest(...) ON CONFLICT DO NOTHING` per batch. This preserves idempotency and created-row counting while keeping transaction round trips fixed.
- Daily plan loading follow-up: `loadDailyMonitoringPlans` no longer uses one SQL statement for lease-aware client election and platform JSON aggregation. It first selects the primary client candidate per `(tenant_id, workspace_id)` with subscription policy and lease preference, then batch-loads authorized platform JSON for the selected `(tenant_id, workspace_id, client_id)` tuples. If authorization disappears between reads, the candidate is skipped rather than producing an empty executable plan.
- Authorization bug fix: monitoring authorization now means a bound, non-deleted platform account for a supported AI platform. `platform_accounts.health` is treated as execution state, not authorization state, so non-live accounts no longer suppress daily scheduled task generation, dashboard authorization, desktop task targeting, or question-detail history display.
- Immediate collection remains stricter than daily scheduled collection: it still requires the target desktop client to be online, and the target client is now the same client that owns the authorized platform accounts. Daily scheduled collection still materializes backend tasks while the desktop client is offline and dispatches when the client becomes available.

## k3s Deployment Foundation - 2026-04-30
- The existing deploy topology is a good base for k3s: app services are `tenant-api`, `worker-generate`, `scheduler`, `ops-api`, and `frontend`; repo runtime also contains `kol-assist-worker` and `ops-web`, so the k3s stack includes them too.
- The stateful dependencies needed for a self-contained k3s install are `postgres`, `monitoring-postgres`, `rabbitmq`, `redis`, `qdrant`, and `minio`.
- `deploy/k3s` now uses kustomize and renders a namespace, config map, placeholder secret, infra StatefulSets, one-shot `migrate` and `minio-init` Jobs, app Deployments/Services, and Traefik Ingress rules for `geo-rankly.local` and `ops.geo-rankly.local`.
- Kustomize cannot reference files above `deploy/k3s` under its default load restrictions, so the k3s overlay now carries its own `config/config.yaml`, `config/prompts.yml`, and `config/ops-config.yaml`.
- Tenant services mount `/app/configs/config.yaml`, `/app/configs/prompts.yml`, and secret-backed `/app/configs/config.local.yaml`, allowing sensitive overrides without rebuilding images.
- `ops-api` currently reads a single ops config file and does not merge an `ops-config.local.yaml`, so k3s documentation calls out that database password changes must also be reflected in `deploy/k3s/config/ops-config.yaml`.
- The existing offline package script did not build `ops-api`, `kol-assist-worker`, or `ops-web`; it now builds and saves those images so k3s can run the full service set.
- `Dockerfile.ops-web` now builds the operations frontend and serves it through its existing nginx proxy to `ops-api`.
- Verification succeeded with `kubectl kustomize deploy/k3s`, local YAML parsing of 30 rendered Kubernetes objects, `bash -n` for deploy scripts, `git diff --check`, `pnpm --filter ops-web build`, and `pnpm --filter admin-web typecheck`.
- Live `kubectl apply --dry-run=client` validation could not complete locally because the configured kube-apiserver at `127.0.0.1:26443` is not running; run that validation on the target k3s node.

## Gitea Registry CI/CD Boundary - 2026-05-01
- Deployable business images are owned by two CI workflows: `frontend-ci.yml` publishes `frontend` and `ops-web`; `backend-ci.yml` publishes `migrate`, `tenant-api`, `ops-api`, `worker-generate`, `kol-assist-worker`, and `scheduler`.
- `deploy-config-ci.yml` is intentionally validation-only. It checks compose, shell scripts, and a smoke Docker build, but does not push images because deployment config is not a component image boundary.
- The canonical deploy tag is the pushed commit hash first 8 chars. CI uses `git rev-parse --short=8 HEAD`; CD and offline packaging default to the same value.
- Gitea Registry secret name is `REGISTRY_PASSWORD`; Gitea rejects secret names beginning with `GITEA_`.
- CD workflows verify required commit8 image tags in Gitea Registry before pulling or deploying. Missing images are treated as a failed prerequisite, not as a signal to build during CD.
- Offline packaging pulls previously published Gitea Registry images into the package; it does not rebuild business images when `SOURCE_IMAGE_REGISTRY` is set by the workflow.

## Stable PgBouncer Deployment - 2026-05-03
- Before this change the deployment had no PgBouncer/pooler service. Runtime services used `pgxpool` and connected directly to `postgres` / `monitoring-postgres`.
- Stable-first decision: add PgBouncer in `session` pooling mode, not transaction pooling, so current `pgx` behavior and any session-level assumptions remain compatible.
- Runtime services now target `pgbouncer` and `monitoring-pgbouncer`; migration and seed jobs continue to connect directly to the underlying Postgres services.
- Application-side pools are intentionally smaller: tenant runtime config uses 12 main DB connections and 8 monitoring DB connections per process; ops runtime uses 5 for each DB.
- Offline packages must include `edoburu/pgbouncer:v1.24.1-p1` alongside the existing infra images.
- Postgres passwords are passed through environment placeholders instead of hard-coded in deploy configs. The Go DSN builder now URL-escapes credentials so strong passwords containing `@`, `:`, `/`, or `?` remain valid.
- Local smoke validation used the existing `server/docker-compose.yaml` Postgres containers on `server_default`; PgBouncer successfully returned `SELECT 1` through the pooler and the temporary test container was removed.

## Compliance Detection Implementation - 2026-05-05
- Source of truth is `docs/superpowers/specs/2026-04-28-compliance-detection-design.md`, Revision 8 dated 2026-05-05.
- The current repo has no `server/internal/tenant/compliance` or `server/internal/ops/compliance` packages, no compliance routes, no compliance config, and no compliance migrations yet.
- Current `PublishJobService.Create()` validates desktop account liveness and creates desktop publish jobs/tasks directly; it does not resolve `article_version_id`, does not pass target platform sets through a compliance gate, and `CreatePublishJobRequest` lacks `article_version_id` / `ack_record_id`.
- `ArticleDetailResponse` internally reads `articles.current_version_id` but does not expose it to the frontend; shared TS `ArticleDetail` also lacks `current_version_id`.
- Article version storage is diff-based; `repository.LoadArticleVersionContent` reconstructs history. The compliance design requires `article_versions.plaintext_snapshot` for O(1) gate reads, so new writes must populate that snapshot and old rows need fallback/backfill support.
- Ops API currently has account/admin/KOL/audit/site-domain modules only; content safety pages and APIs need to be added without disrupting existing auth middleware.
- Existing frontend publish flow is centralized through `apps/admin-web/src/components/PublishArticleModal.vue`, which is the right integration point for runtime status, check, ack, and manual-review states.
- Tenant compliance is now implemented with runtime status, article/plain checks, latest records, ack creation/consumption, manual review submit/latest/cancel, tenant whitelist/blacklist terms, publish-gate integration, scheduler-time recheck, RabbitMQ review jobs, and LLM review AI-point billing.
- Ops compliance is now implemented with dictionary/term CRUD, batch import, publish/rollback, singleton global policy, master switch, manual reviews, records, and stats under `/api/ops/compliance`.
- Ops-web now has content-safety navigation and pages for global policy, dictionaries/editing, records, stats, manual-review list, and manual-review detail.
- Per-tenant compliance policy customization was removed before launch: ops-web now only exposes global policy pages/APIs, and `ops.compliance_policies` is an `id=1` global singleton without per-tenant columns.

## Article Generation Reliability Hardening - 2026-05-05
- Incident source: article title and outline generation can succeed while article body generation fails because the queued article worker path persists task/article/version/quota state through separate transitions.
- The production root cause was a Postgres type inference failure in `UpdateGenerationTaskStatus`; the earlier hotfix cast `status` and migrated `generation_tasks.status` to `TEXT`.
- Remaining reliability gap: body-generation services still ignore the initial `UpdateGenerationTaskStatus(... running ...)` error, and several failure-cleanup paths ignore quota ledger / reservation refund errors. That means a DB error can be present but not promoted with task/article context.
- Recovery already avoids retrying a running task when the article is already `failed`, but it logs only a narrow message. The worker needs stable structured fields and alert-ready counters around retries/finalization so frontend “失败后不再重试” semantics can be verified from logs and metrics.
- State consistency checks should flag article-generation anomalies such as completed task without article version/current version, failed article with queued/running task, completed article with non-completed task, and expired running leases.
- Scheduler DB scanning should stay a bounded safety net, not the primary control loop: defaults are 5-minute interval, 10-second timeout, batch size 100, 24-hour lookback, and partial indexes on active/recent completed generation task candidates.
- Alerting should be metric-driven: Prometheus rules now cover cleanup failures, task/article/version state anomalies, state-check failures, queue failures, failure spikes, and recovery finalization.
- Admin-web now has compliance API helpers, an editor-side compliance check drawer with locate/highlight and whitelist actions, and a publish modal that handles pass / needs_ack / block / manual-review flows before creating publish jobs.
- Desktop publish management now surfaces scheduled-publish compliance recheck blocks through publish job metadata: `publish_job_status`, `compliance_blocked_record_id`, `compliance_blocked_at`, and summarized `compliance_blocked_reason`.
- Verification passed on 2026-05-05: targeted compliance Go tests, full `go test ./...`, admin-web typecheck/build, ops-web typecheck/build, desktop-client typecheck/build, and `git diff --check`.
- Residual risk: build output still reports large Ant Design / Milkdown chunks, but this is an existing bundle-size warning rather than a functional failure.

## Desktop Client Account Isolation - 2026-05-06
- Root cause: `/api/desktop/accounts` was calling `ListByUser`, so it returned all active platform accounts for `workspace_id + user_id`. The same user logging in on Mac and Windows therefore saw the same bound media accounts.
- Second root cause: desktop account upsert used `ON CONFLICT (workspace_id, platform_id, platform_uid)`, so the same third-party UID on another machine could update the existing row and move its `client_id`.
- Fix: desktop account listing, identity lookup, upsert, patch, delete, and async health sink paths are now scoped by the current desktop token's `client_id`.
- Migration `20260506120000_scope_platform_accounts_to_desktop_client` replaces the active platform-account uniqueness index with `(workspace_id, client_id, platform_id, platform_uid)`.
- Desktop client IDs are still stable hardware-derived UUIDs, but the seed intentionally includes tenant/workspace/user scope so two users on the same physical computer do not share one client record/token.
- Device fingerprinting now prefers OS-level machine IDs and uses a filtered MAC-address fingerprint only when OS machine IDs are unavailable; raw hardware identifiers are hashed locally and are not sent to the server.

## Desktop Publisher Playwright Packaging - 2026-05-09
- Bilibili and dongchedi publish failures with `page.evaluate: ReferenceError: wO is not defined` are caused by the packaged `build:obf` path, not by the target sites themselves.
- The Electron main bundle owns Playwright adapters. Playwright serializes `page.evaluate` callbacks with `Function.prototype.toString()` and runs them in the target web page. When `javascript-obfuscator` rewrites main-process evaluate callbacks, string-array helper identifiers remain in the function body but are not defined in the browser page context.
- `electron.vite.config.ts` already disables Vite minification for main for the same reason; the remaining failure path was `scripts/obfuscate.cjs` obfuscating `out/main/*.cjs` after build.
- Fix: keep the main process bundle unobfuscated and only obfuscate renderer assets. `pnpm --filter @geo/desktop-client build:obf` now rebuilds main cleanly and obfuscates renderer only.