[BF-032] GSC/Analytics dashboard 文档和运营检查表

docs/growth/dashboard-runbook.md

@@ -0,0 +1,134 @@
+# Growth Dashboard Runbook
+
+This runbook defines the operating dashboard for byteflow.tools after SEO, privacy, PWA, and tool-discovery changes ship. It is an internal operations document, not user-facing product copy.
+
+## Goals
+
+- Track whether users can find the right local-first tool and complete useful actions.
+- Monitor indexing, crawl health, metadata quality, and page performance after releases.
+- Keep analytics privacy-safe: aggregate signals only, no tool payloads, no user identifiers, and no undisclosed external requests.
+
+## Required Access
+
+The dashboard owner needs explicit access to these sources before using the checklist:
+
+- Google Search Console property for `https://byteflow.tools/`.
+- Hosting/CDN dashboard for deployment, redirects, 404s, cache, and aggregate traffic.
+- GitHub repository access for issues, PRs, release notes, and CI history.
+- PageSpeed Insights or CrUX for aggregate Core Web Vitals.
+- Privacy-safe analytics provider only if it is enabled by configuration and matches the allowlist in `docs/privacy/analytics-policy.md`.
+
+Do not use data exports from sources that require cookies, user-level tracking IDs, session replay, advertising profiles, fingerprinting, or raw request bodies.
+
+## North Star Metrics
+
+| Metric | Definition | Source | Notes |
+| --- | --- | --- | --- |
+| Monthly tool reach | Monthly aggregate count of tool page loads, measured only if a privacy-safe aggregate provider exists. | Privacy-safe analytics | Must not rely on cookies, user IDs, fingerprints, or session IDs. |
+| Successful tool operations | Count of allowlisted `tool_action`, `copy_output`, and `download_output` events. | Privacy-safe analytics | Event params must stay coarse: tool ID, action type, locale, source page, and size bucket only. |
+| Indexed useful pages | Valid indexed locale home, category, tool, workflow, and article pages. | Google Search Console | Track by route family and locale, not by user. |
+| Search discovery quality | Clicks, impressions, CTR, and average position for tool and workflow query clusters. | Google Search Console | GSC query data is aggregate search demand, not internal search text. |
+
+## SEO Dashboard
+
+Track these weekly by route family: root, locale home, all tools, category hubs, tools, workflows, articles, compare pages, alternatives, fix pages, and static trust pages.
+
+| Metric | What To Watch | Action Threshold |
+| --- | --- | --- |
+| Indexed pages | Valid indexed URLs by route family and locale. | Any unexpected drop after a release. |
+| Crawled currently not indexed | Pages Google crawled but did not index. | Rising count for tools, workflows, or localized pages. |
+| Discovered currently not indexed | Pages found but not crawled. | Increasing count for sitemap-backed pages. |
+| Duplicate without user-selected canonical | Canonical confusion. | Any core route hit. |
+| Alternate page with proper canonical | Expected localized alternates. | Investigate if canonical points to the wrong locale. |
+| 404 / soft 404 | Broken links, stale sitemap entries, or removed tools. | Any sitemap URL returning 404. |
+| Redirect errors | Legacy route map or hosting redirect regressions. | Any redirect loop or wrong target. |
+| Sitemap submitted / indexed | Sitemap acceptance and URL coverage. | Submitted count diverges from expected generated routes. |
+| CTR by query cluster | Snippet/title intent match. | CTR drop greater than 20% week over week with stable position. |
+| Average position | Ranking movement by cluster. | Position drop greater than 3 places for core tool clusters. |
+| Core Web Vitals | LCP, INP, CLS by template. | Any route family leaving good status. |
+
+## Product Dashboard
+
+Use only allowlisted, aggregate events. Do not add raw input, output, query text, file information, or user identifiers.
+
+| Event | Allowed Dimensions | Purpose |
+| --- | --- | --- |
+| `tool_loaded` | tool ID, locale, source page | Understand tool discovery and route health. |
+| `tool_action` | tool ID, action type, locale, input size bucket, source page | Count successful local tool actions without payloads. |
+| `copy_output` | tool ID, action type, locale, source page | Measure completion of copy workflows. |
+| `download_output` | tool ID, action type, locale, size bucket, source page | Measure export workflows without file names or content. |
+| `search_performed` | locale, query length bucket, result count, source page | Track search usefulness without query text. |
+| `related_tool_click` | source tool ID, related tool ID, locale, source page | Measure workflow navigation. |
+| `pwa_installed` | locale, platform bucket, source page | Track successful installs. |
+
+If a desired event is not in the current analytics taxonomy, open a privacy review issue before adding it.
+
+## Weekly Checklist
+
+1. Open Google Search Console coverage and compare indexed, crawled-not-indexed, duplicate, and 404 counts with the previous week.
+2. Confirm the submitted sitemap is accepted and the submitted URL count matches expected generated route families.
+3. Review the top query clusters for each core category: JSON, JWT, Base64, hash, URL encoding, regex, Markdown, image tools, OpenAPI, and security headers.
+4. Find pages with CTR drops greater than 20% while average position is stable; create content or metadata follow-up issues.
+5. Review pages with impression growth but low CTR; check title, description, heading, and snippet intent.
+6. Check legacy redirects and 404s; any sitemap URL returning 404 becomes a P1 routing issue.
+7. Review Core Web Vitals by route family; create performance issues for route templates that leave good status.
+8. Check privacy-safe product events for tool load to action completion by route family.
+9. Confirm internal search metrics still avoid query text and only report length bucket, result count, locale, and source page.
+10. Record findings in the weekly dashboard note with links to new issues.
+
+## Monthly Checklist
+
+1. Group GSC queries into clusters: direct tool names, local/privacy intent, alternatives, fix/how-to intent, and workflow intent.
+2. Compare locale performance for `en`, `zh-CN`, `zh-TW`, `ja`, `ko`, `de`, and `fr`; create i18n content issues where a locale underperforms with real impressions.
+3. Review pages with high impressions and low action completion; check whether the tool surface matches the search intent.
+4. Review content decay: pages losing impressions for three consecutive weeks should get a content refresh issue.
+5. Review competitor and alternative-page queries only from aggregate GSC data; do not scrape or store user-level behavior.
+6. Check release notes and CI failures for recurring SEO, PWA, sitemap, hreflang, or metadata regressions.
+7. Reconfirm the analytics provider, if enabled, remains cookie-free and does not add user identifiers or new external requests.
+
+## Post-Release Monitoring
+
+Run this flow for every release that changes routes, sitemap, metadata, PWA, search, analytics, privacy copy, or tool templates:
+
+1. Confirm CI passed: lint, tests, validate, build, and required smoke tests.
+2. Compare generated sitemap URL counts with the previous release.
+3. Spot-check `/`, `/en`, `/zh-CN`, `/en/all-tools`, `/en/json-formatter`, `/en/jwt-decoder`, `/en/base64-encode-decode`, and `/en/trust-center`.
+4. In GSC, inspect a sample of changed URLs after deployment.
+5. Check hosting/CDN aggregate 404s and redirect errors after 24 hours.
+6. Review privacy-safe event volume for sudden drops in tool load, tool action, copy, download, search click, and PWA install signals.
+7. Create issues for regressions instead of making undocumented dashboard-only fixes.
+
+## Feedback Loop
+
+Every dashboard finding must become one of these outcomes:
+
+- No action: documented as expected behavior with evidence.
+- New GitHub issue: include route family, locale, metric, date range, suspected cause, and acceptance criteria.
+- Existing issue update: add dashboard evidence to the relevant BF or follow-up issue.
+- Content refresh: identify the exact page, intent mismatch, and required localized copy scope.
+- Privacy review: required before adding any event, provider, field, cookie, user identifier, or external request.
+
+## Issue Template For Findings
+
+```markdown
+## Dashboard Finding
+- Date range:
+- Source:
+- Route family:
+- Locale(s):
+- Metric:
+- Current value:
+- Previous value:
+- Suspected cause:
+
+## Privacy Check
+- [ ] Does not include tool input/output
+- [ ] Does not include JWTs, tokens, secrets, log bodies, file names, file contents, image contents, hashes, or full URLs
+- [ ] Does not require cookies, user IDs, session IDs, or fingerprinting
+
+## Proposed Action
+- ...
+
+## Acceptance Criteria
+- ...
+```

docs/growth/seo-monitoring.md

@@ -0,0 +1,68 @@
+# SEO Monitoring Checklist
+
+This checklist turns Google Search Console and build-gate output into repeatable SEO operations. It must be used with the privacy limits in `docs/privacy/analytics-policy.md`.
+
+## Query Clusters
+
+Track aggregate GSC queries in these clusters:
+
+- Direct tool names: JSON formatter, JWT decoder, Base64 decode, URL encode, hash generator, regex tester.
+- Local/privacy intent: local JSON formatter, browser JWT decoder, offline developer tools, privacy-first tools.
+- Fix intent: JSON trailing comma, invalid Base64 length, URL malformed percent sequence.
+- Workflow intent: API payload cleanup, security token review, log scrub before sharing, image social export.
+- Comparison and alternative intent: jwt.io alternative, jsonlint alternative, Byteflow vs CyberChef.
+- International intent: localized variants for the supported locales when GSC has enough aggregate data.
+
+Do not combine GSC query data with user-level analytics, cookies, session IDs, or internal search text.
+
+## URL Families
+
+Review SEO health by family, not by individual ad hoc URLs:
+
+| Family | Examples | Checks |
+| --- | --- | --- |
+| Root and locale home | `/`, `/en`, `/zh-CN` | x-default, localized title, category links, no thin root page. |
+| Tool pages | `/en/json-formatter` | self canonical, all hreflang alternates, JSON-LD, unique metadata. |
+| Category hubs | `/en/data-code-formats` | unique intro, linked tools, sitemap inclusion. |
+| Workflow hubs | `/en/workflows/...` or equivalent route | How-to intent, related tools, localized metadata. |
+| Content pages | how-to, fix, compare, alternatives | fair claims, unique title/description, Trust Center link. |
+| Trust pages | privacy, about, install app, trust center | consistent privacy language and disclosed external requests. |
+
+## Weekly GSC Review
+
+1. Coverage: note valid, indexed, excluded, 404, soft 404, redirect error, duplicate, crawled-not-indexed, and discovered-not-indexed counts.
+2. Sitemap: confirm submitted URL count and last read status.
+3. Pages: sort by clicks lost week over week and flag drops not explained by seasonality or release changes.
+4. Queries: group top queries into the clusters above and record changes in impressions, CTR, and average position.
+5. Locales: compare the same route family across all supported locales where data is available.
+6. Enhancements: check breadcrumbs, FAQ schema, software/app schema, and Core Web Vitals reports.
+7. Actions: create issues for unexpected deltas with acceptance criteria and privacy-safe evidence only.
+
+## Monthly Content Review
+
+1. Prioritize pages with high impressions, low CTR, and stable or improving average position.
+2. Refresh pages with declining impressions for three consecutive weeks.
+3. Merge, redirect, or improve pages that remain crawled-not-indexed after two monthly reviews.
+4. Review localized pages together; do not improve only English body copy while leaving other locales generic.
+5. Check whether route metadata, headings, FAQ, examples, and related tools still match the page intent.
+
+## Technical SEO Regression Checks
+
+Run or verify these before using dashboard results to plan content changes:
+
+```bash
+npm run check:canonical
+npm run check:hreflang
+npm run check:sitemap-lastmod
+npm run check:metadata-localization
+npm run check:jsonld-structured-data
+npm run check:rendered-i18n-copy
+```
+
+If a technical gate fails, fix the technical issue before interpreting traffic changes as content performance.
+
+## Escalation
+
+- P1: sitemap URL returns 404, canonical points to the wrong locale, core route has `noindex`, or privacy/trust copy contradicts current behavior.
+- P2: CTR drop greater than 20% for a stable-position core tool page, crawled-not-indexed increase for generated pages, or Core Web Vitals regression.
+- P3: new query cluster opportunity, low-impression content refresh, or title/description experimentation.

docs/privacy/analytics-policy.md

@@ -0,0 +1,90 @@
+# Privacy-Safe Analytics Policy
+
+This policy defines what operational dashboards may collect and what they must never collect. It applies to product analytics, dashboard exports, GSC review notes, screenshots, and issue evidence.
+
+## Allowed Aggregate Signals
+
+Analytics may use only allowlisted aggregate events and coarse dimensions:
+
+- Event name.
+- Tool ID or route family.
+- Locale.
+- Source page or template family.
+- Action type from a fixed list.
+- Result count.
+- Size bucket, not exact content.
+- Query length bucket, not query text.
+- PWA install state or platform bucket.
+
+Any new field requires a privacy review issue before implementation.
+
+## Prohibited Data
+
+Never collect, store, export, paste into issues, or send to a provider:
+
+- Tool input.
+- Tool output.
+- JWTs, tokens, passwords, API keys, private keys, certificates with private material, or secrets.
+- Payloads, request bodies, response bodies, logs, stack traces, HAR bodies, environment dumps, or configuration files.
+- File names, file paths, file contents, image contents, document contents, or generated output containing original content.
+- Raw internal search query text.
+- Full URLs, URL query strings, fragments, or user-provided URLs.
+- Hash values derived from user content.
+- Email addresses, IP addresses, user IDs, account IDs, session IDs, cookies, device IDs, or fingerprints.
+- Session replay, screen recordings, keystrokes, clipboard contents, or form field values.
+
+## Provider Requirements
+
+An analytics provider may be enabled only when it satisfies all requirements:
+
+- Cookie-free by default.
+- No user-level identifier.
+- No fingerprinting.
+- No session replay.
+- No advertising or retargeting use.
+- No tool input/output capture.
+- Configurable by environment variable or build-time setting.
+- Disclosed in Privacy Policy and Trust Center before launch.
+- Covered by tests or gates that prevent forbidden fields.
+
+If any requirement is uncertain, do not enable the provider. Mark the PR `needs-human-review`.
+
+## Search Data Rules
+
+There are two different search sources:
+
+- Google Search Console queries are aggregate external search demand and may be reviewed in dashboard summaries.
+- Byteflow internal search and command palette queries must not collect query text. Only query length bucket, result count, locale, and source page are allowed.
+
+Never join GSC query data with user-level analytics or internal search behavior.
+
+## File And Tool Data Rules
+
+File and tool workflows may report only safe buckets:
+
+- Size bucket instead of exact size when needed.
+- Tool ID instead of file name.
+- Action type instead of raw command or payload.
+- Success/failure count without error payloads.
+
+Do not log file names, MIME-derived personal names, file hashes, previews, extracted text, image pixels, or generated output.
+
+## Dashboard Export Rules
+
+Dashboard exports may contain aggregate rows only. Before sharing an export in an issue or PR:
+
+1. Remove any raw URL query string.
+2. Remove any free-text query from internal search sources.
+3. Remove user, session, cookie, IP, device, and account columns.
+4. Remove file names and full referrers.
+5. Keep only date range, route family, locale, metric name, aggregate value, and dashboard source.
+
+## Review Checklist
+
+- [ ] The metric is aggregate.
+- [ ] The field is allowlisted.
+- [ ] No raw input or output appears in the event, screenshot, log, or issue.
+- [ ] No identifier can track a person or browser across time.
+- [ ] The provider is disclosed.
+- [ ] Privacy Policy and Trust Center remain consistent.
+- [ ] Tests or gates cover the field before merge.