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