docs: add architecture showcase html design
This commit is contained in:
Codex
@@ -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.
|
||||||
|
|
||||||
Reference in New Issue
Block a user