From bed86ac4546bf5998cb56c1ecd2b779e223b0b26 Mon Sep 17 00:00:00 2001 From: Codex Date: Tue, 16 Jun 2026 19:55:49 +0800 Subject: [PATCH] docs: add architecture showcase html design --- ...oject-architecture-showcase-html-design.md | 158 ++++++++++++++++++ 1 file changed, 158 insertions(+) create mode 100644 docs/superpowers/specs/2026-06-16-project-architecture-showcase-html-design.md diff --git a/docs/superpowers/specs/2026-06-16-project-architecture-showcase-html-design.md b/docs/superpowers/specs/2026-06-16-project-architecture-showcase-html-design.md new file mode 100644 index 0000000..8d83ed7 --- /dev/null +++ b/docs/superpowers/specs/2026-06-16-project-architecture-showcase-html-design.md @@ -0,0 +1,158 @@ +# Project Architecture Showcase HTML Design + +## Goal + +Create a directly viewable static HTML page that introduces the current GEO Agent Article Optimizer project architecture, advantages, and customer-facing highlights. + +The page is for customer demonstrations. It should first explain business value in plain language, then prove technical credibility through the actual architecture and workflow already present in the repository. + +## Audience + +Primary audience: + +- Customer decision makers who need to understand value quickly. +- Customer-side technical evaluators who want to see whether the project is structured and extensible. + +Tone: + +- Mixed business and technical. +- Confident, concise, and presentation-ready. +- Chinese copy, because the current product UI and customer-facing workflow are Chinese-oriented. + +## Output + +Create one standalone HTML file: + +```text +docs/project-architecture-showcase.html +``` + +The file must be usable by opening it directly in a browser. It must not require a Next.js dev server, external assets, CDN CSS, or network access. + +## Content Structure + +### 1. Hero + +Present the project as: + +```text +GEO 智能文章优化器 +一个以事实卡为约束、以质量门禁为闭环的 AI 内容优化工作流 +``` + +The hero should include compact capability labels: + +- 事实卡约束 +- 多节点 Agent 工作流 +- QA 质量门禁 +- 定向重写 +- Markdown / Word / JSON 导出 + +### 2. Customer Problems And Solution + +Explain the customer problems this project targets: + +- 行业漂移。 +- 公司名称不一致。 +- 图片与正文不匹配。 +- 第三方口吻出现在官方文章中。 +- 平台语气和文章类型不匹配。 +- 标题或正文语义不顺。 +- 虚构资质、年限、案例或能力。 +- 同一篇文章中产品、服务、年限前后冲突。 + +Then summarize the solution: + +- First extract candidate facts. +- Ask the user to confirm or edit the fact card. +- Optimize only under confirmed facts. +- Run executable quality gates. +- Rewrite only failed sections. +- Export only after hard failures are cleared. + +### 3. Architecture Overview + +Show the actual workflow as a visual HTML/CSS flow: + +```text +Article Input +→ InputNormalizer +→ FactExtractor +→ UserConfirmedFactCard +→ ArticleOptimizer +→ QualityInspector +→ TargetedRewriter +→ Exporter +``` + +The page should make clear that `TargetedRewriter` loops back into `QualityInspector` for up to two rewrite rounds. + +### 4. Layered Code Architecture + +Introduce the repository layers: + +- `src/app`: Next.js page and API route handlers. +- `src/components`: focused UI panels for input, fact card, preview, and QA report. +- `src/lib/domain`: shared TypeScript types and Zod validation schemas. +- `src/lib/workflow`: independent workflow nodes for normalization, extraction, optimization, QA, rewriting, exporting, and orchestration. +- `src/lib/llm`: provider abstraction for DeepSeek and OpenAI-compatible models. +- `src/lib/db`: local SQLite connection, schema, and repositories. +- `tests` and `src/**/__tests__`: Vitest and Playwright coverage for domain, database, workflow, API, and MVP behavior. + +### 5. Technical Highlights + +Highlight advantages grounded in the current codebase: + +- Confirmed facts are hard constraints, reducing hallucination risk. +- Workflow nodes are separated, making individual steps testable and replaceable. +- Quality checks are structured as `pass`, `warn`, or `fail`. +- Hard QA failures block export. +- Failed checks trigger targeted rewriting instead of full-document blind regeneration. +- LLM calls are isolated in a provider client, so model vendors can be swapped later. +- Missing credentials fall back to deterministic local behavior for tests and local review. +- Local SQLite storage makes the MVP simple to deploy and suitable for internal demonstration. +- Markdown, Word, and JSON exports support both human review and system integration. + +### 6. MVP Boundary And Expansion + +State current MVP boundaries honestly: + +- Pasted text only. +- Local SQLite only. +- No account permissions. +- No collaboration. +- No publishing platform APIs. +- No batch queue. +- Basic Word export layout. + +Then list natural expansion paths: + +- `.docx` parsing and template export. +- Multi-brand fact-card library. +- Batch optimization queue. +- Team review and approval workflow. +- Publishing platform integration. +- More quality gates and industry-specific rule packs. + +## Visual Direction + +Style the page as a polished customer demo page: + +- Dark professional background. +- Clear white and light gray text. +- One or two restrained accent colors. +- No external fonts or images. +- Use CSS cards only for repeated information units. +- Use responsive layout that works on desktop and mobile. +- Avoid marketing filler. Every section should communicate project value or architecture. + +## Acceptance Criteria + +- `docs/project-architecture-showcase.html` exists. +- The file opens directly in a browser without a build step. +- The page is written in Chinese. +- The architecture and highlights match the existing project structure. +- The page includes business value, workflow architecture, code-layer architecture, technical advantages, MVP limits, and expansion paths. +- The page has responsive CSS in the same file. +- No external network resources are required. +