full-stack-doc

Product Documentation Standard (full-stack-doc v3.0)

Enforces a fixed directory-and-naming convention for product documentation, aligned with the PartMe / Octo series. Ready-to-copy Markdown templates live under templates/. Detailed file mappings and conventions in references/structure.md.

1. When to Use

Creating or initializing a product documentation repository
Scaffolding doc trees for Octo* or PartMe projects
Auditing or aligning existing repos against the PartMe doc standard
Generating / renaming docs to match the naming convention
Aligning partme-docs/ content with the template structure
Writing or expanding any of the 10 root-level planning documents

2. Placeholders

Placeholder	Meaning	Example
`{Name}`	Product / brand name	`OctoEcom`, `OpenMem`
`{Name-Open}`	Open-source variant name (if dual-track)	`OpenEcom`, `OpenMem`
`{V}`	Version directory name	`V1`, `V2`
`{模块简称}`	Module short name	`登录页`, `设备中心`
`{YYYY-MM-DD}`	Date placeholder	`2026-03-27`
`{姓名}`	Author / reviewer name	`张三`
`{组织}`	Organization name	`PartMe`

Replace placeholders in both filenames and content. Root keeps one 6、 file. The old 6、详细功能清单 has been merged into 10、功能菜单与版本规划.

3. Document Architecture

3.1 Four-Layer Structure

{产品名}/
├── 1、{Name}-命名与品牌说明.md          ─┐
├── 2、{Name}-术语表与词汇表.md          │
├── 3、{Name}-市场与商业分析.md          │
├── 4、{Name}-技术与可行性分析.md        │ Root (10) — 产品级，与版本无关
├── 5、{Name}-技术方案与路线.md          │
├── 6、{Name}-产品与版本规划.md          │
├── 7、{Name}-领域模型设计.md            │
├── 8、{Name}-系统架构设计.md            │
├── 9、{Name}-视觉与交互DNA规范.md       │
├── 10、{Name}-功能菜单与版本规划.md      ─┘
│
├── V1/                                   ─┐
│   ├── 1、{Name}-需求调研文档-V1.md      │
│   ├── 2、{Name}-需求分析文档-V1.md      │
│   ├── 3、{Name}-系统架构设计-V1.md      │ Version (7) — 版本级实施文档
│   ├── 4、{Name}-功能与界面规划-V1.md    │
│   ├── 5、{Name}-PRD文档-V1.md           │
│   ├── 6、{Name}-功能菜单与版本规划-V1.md│
│   ├── 7、{Name}-UI设计说明-V1.md        │
│   │                                     ─┘
│   ├── 1、{模块A}/                       ─┐
│   │   ├── {Name}-{模块A}-PRD-V1.md      │ Module (3) — 可选，按模块
│   │   ├── {Name}-{模块A}-Stitch设计提示词.md │
│   │   └── {Name}-{模块A}-UI设计说明-V1.md    ─┘
│   └── ...
│
├── 其他/                                 ─┐
│   ├── 1、技术细分模板.md                │
│   ├── 2、功能提测模板.md                │ Delivery (5) — 可选，研发交付
│   ├── 3、测试结果模板.md                │
│   ├── 4、上线通知模板.md                │
│   └── 5、项目运维模板.md                ─┘
│
├── 技术调研/                             ── 技术调研、协议分析（版本无关）
└── assets/                               ── 图片、附件等

3.2 Scope Summary

Scope	Count	Templates	Naming Pattern
Root	10	`templates/root/`	`{序号}、{Name}-{文档名}.md`
Version (`{V}/`)	7	`templates/version/`	`{序号}、{Name}-{文档名}-{V}.md`
Module (optional)	3 per module	`templates/module/`	`{Name}-{模块简称}-{类型}-{V}.md`
Delivery (optional)	5	`templates/delivery/`	Context-dependent

3.3 Root 10 Documents — Authoring Chain

There are strict upstream and downstream dependencies between documents, so they should be written in progressive order:

flowchart LR
    D1["1、命名与品牌"] --> D2["2、术语表"]
    D2 --> D3["3、市场分析"]
    D3 --> D4["4、可行性分析"]
    D4 --> D5["5、技术方案"]
    D5 --> D6["6、版本规划"]
    D6 --> D7["7、领域模型"]
    D7 --> D8["8、系统架构"]
    D8 --> D9["9、视觉DNA"]
    D6 --> D10["10、功能菜单"]
    D9 --> D10

No.	Document	Key Input	Key Output	Benchmark Mermaid Type
1	Naming and Brand Description	Product Vision	Brand Positioning, Boundaries	`graph LR` (Brand Relationship)
2	Terminology and Glossary	Doc 1 Brand Positioning	Unified Language	None (Pure Table)
3	Market and Business Analysis	Doc 1 Positioning + External Data	TAM/SAM/SOM, Competitors, Pricing	`quadrantChart` / `funnel`
4	Technical and Feasibility Analysis	Doc 3 Opportunity + Doc 5 Preliminary Selection	Feasibility Conclusion, Risks	`flowchart` / `sequenceDiagram`
5	Technical Solution and Roadmap	Doc 4 Conclusion	Tech Stack, ADR, Milestones	`flowchart` / `gantt`
6	Product and Version Planning	Doc 3 Business + Doc 5 Roadmap	Version Matrix, Pricing, Release Strategy	`graph` / `timeline`
7	Domain Model Design	Doc 2 Terminology + Doc 6 Functional Boundaries	Bounded Contexts, Aggregates, Events	`classDiagram` / `graph TB`
8	System Architecture Design	Doc 5 Tech Stack + Doc 7 Domain	Layering, Data Flow, Deployment	`flowchart` / `sequenceDiagram`
9	Visual and Interaction DNA Specification	Doc 1 Brand Character	Color, Typography, Components, Motion	`flowchart` (Page Skeleton)
10	Feature Menu and Version Planning	Doc 6 + Doc 8 + Doc 9	Navigation, Routing, Feature List, Priority	`mindmap` / `pie` / `flowchart`

4. Scaffolding Workflow

Step 1 — Root Docs

Copy all 10 files from templates/root/ into the project root. Rename each replacing {Name}:

# Example: OctoEcom
for f in templates/root/*.md; do
  name=$(basename "$f" | sed 's/{Name}/OctoEcom/g')
  cp "$f" "partme-docs/18、OctoEcom/$name"
done

Step 2 — Version Docs

Create {V}/ (e.g., V1/). Copy 7 files from templates/version/. Replace both {Name} and {V} in filenames and content.

Step 3 — Module Docs (optional)

For each functional module, create {V}/{序号}、{模块名}/. Copy 3 files from templates/module/. Replace {Name}, {模块简称}, and {V}.

Example (OctoEcom V1 Product Collection):

V1/1、商品采集/
├── OctoEcom-商品采集-PRD-V1.md
├── OctoEcom-商品采集-Stitch设计提示词.md
└── OctoEcom-商品采集-UI设计说明-V1.md

Step 4 — Delivery Docs (optional)

Copy templates/delivery/ into 其他/ or a dedicated delivery folder. Replace {Name} and dates.

Step 5 — Special Directories

Create 技术调研/ for tech research and 其他/ for non-standard docs. Directories like demo/, assets/, .stitch/ stay untouched.

Step 6 — Validate

Run the validation checklist (Section 7).

5. Quality Standards

5.1 Content Depth Benchmarks

Based on OctoEcom and OpenEcom production documents:

Document	Target Line Count	Minimum Mermaid	Minimum Tables	Key Quality Markers
1. Naming and Brand	100–120	1	2	Brand Relationship Diagram, Open/Commercial Comparison Table
2. Terminology	100–160	0	8+	Classified by Layer/Domain, Chinese-English Comparison, Abbreviations
3. Market Analysis	160–220	1–3	10+	TAM Data Source Notes, SWOT Table, Competitor Matrix
4. Feasibility Analysis	180–230	2–3	10+	Feasibility Rating Legend, Layered Assessment, Risk Summary Table
5. Technical Solution	260–400	3–4	9+	Code Examples, Gantt Roadmap, Deployment Topology
6. Version Planning	200–340	2–3	5+	Version Feature Matrix, Pricing Table, Release Strategy
7. Domain Model	300–410	7–9	7+	classDiagram per Aggregate, Event Table, Repository Interfaces
8. System Architecture	400–510	7–14	9+	Layered subgraph, Sequence Diagram, State Machine
9. Visual DNA	250–300	0–1	12+	ASCII Wireframe, CSS Variables, Color Value Table
10. Feature Menu	400–560	3–5	20+	mindmap Panorama, Feature Enumeration, Priority Statistics

5.2 Universal Document Structure

Each root document must contain the following standard structure:

Document Header:

# {Name} 文档标题

> **文档说明**：一句话说明文档用途与范围。
>
> **版本**：V1.0.0
> **最后更新**：{YYYY-MM-DD}

Document Footer:

---

**文档版本**：V1.0.0
**创建日期**：{YYYY-MM-DD}
**最后更新**：{YYYY-MM-DD}
**文档状态**：✅ 待评审

5.3 Formatting Conventions

Element	Specification
Section Numbering	`## N.` top level,`### N.M` sub-level, hierarchy no more than 3 levels
Table alignment	Use `:---` left-aligned
Feasibility rating	✅ High feasibility / ⚠️ Medium feasibility / 🔴 Low feasibility
Priority	P0 (Must) / P1 (Important) / P2 (Desired) / P3 (Optional)
Version tag	🆓 Free / 👤 Personal / 👥 Professional / 🏢 Enterprise
Status marker	✅ Implemented / 🔧 In development / ⏳ Planned / ❌ Not implemented
Mermaid	Blank line before and after each diagram; the diagram type should match the content (see the benchmarking column in 3.3)
Code block	Specify the language (`typescript`/`go`/`bash`/`yaml`/`sql`）
Mixed Chinese and English	Add a space between Chinese and English/numbers:`OpenAI 模型`

5.4 Cross-Reference Rules

Doc 3 related documents must link to Doc 1 (brand boundaries) and Doc 5 (technical feasibility)
Doc 5 Gantt dates must be consistent with Doc 6 version milestones and Doc 10 release cadence
Doc 7 aggregate names must be defined in the Doc 2 glossary
Doc 8 layer names must correspond to the Doc 5 technology selections
The version annotations in the Doc 10 feature list must be consistent with the Doc 6 version matrix

6. Gotchas

Sequence numbers 1–7 in version folders are reserved for the 7 standard docs. Non-standard docs must use 8+ or go into 其他/.
Root has one file numbered 6、 (Product and Version Planning). Detailed feature lists are embedded in 10、功能菜单与版本规划.
Don't reorganize special directories (demo/, assets/, .stitch/, stitch_*, 实施指南/) unless the user explicitly requests it.
Delivery templates are optional and do not occupy root-level standard sequence numbers.
When a product has open-source + commercial dual-track (e.g., OpenEcom/OctoEcom), each track gets its own full 10-doc set with cross-references.

7. Validation Checklist

Doc Validation:
- [ ] Root contains exactly 10 standard files (1–10)
- [ ] Each file starts with H1 + blockquote doc description
- [ ] Each file ends with version/date/status footer
- [ ] ## section numbering is sequential (no gaps, no duplicates)
- [ ] ### sub-sections use parent number prefix (e.g., ## 3 → ### 3.1)
- [ ] Mermaid diagrams render without syntax errors
- [ ] Cross-document references resolve to existing files
- [ ] Timeline dates are consistent across Doc 3, 5, 6, 10
- [ ] Terminology matches Doc 2 definitions
- [ ] Version folder contains exactly 7 standard files with {V} suffix
- [ ] Module folders have PRD / Stitch / UI triplet (if applicable)
- [ ] 技术调研/ and 其他/ do not contain root-level standard docs
- [ ] No sequence numbers 1–7 used for non-standard docs in version folders

8. Template Inventory

Template	Location	Lines	Mermaid	Key Sections
Naming and Brand Description	`templates/root/1、命名与品牌说明.md`	~120	1	Brand positioning, origin of the name, product boundaries, core formula, brand family
Glossary and Vocabulary	`templates/root/2、术语表与词汇表.md`	~150	0	Document information, product/architecture/business/platform/governance terms, abbreviations
Market and Business Analysis	`templates/root/3、市场与商业分析.md`	~220	3	Market opportunity, TAM/SAM/SOM, competitor matrix, SWOT, business model, pricing
Technical and Feasibility Analysis	`templates/root/4、技术与可行性分析.md`	~230	3	Layered assessment, security compliance, performance scaling, risk summary table, conclusion
Technical Solution and Roadmap	`templates/root/5、技术方案与路线.md`	~300	4	Technology selection, layered solution, ADR, phased roadmap, deployment, monitoring
Product and Version Planning	`templates/root/6、产品与版本规划.md`	~240	3	Product positioning, version matrix, roadmap, pricing, release strategy, success metrics
Domain Model Design	`templates/root/7、领域模型设计.md`	~350	9	Strategic design, ubiquitous language, aggregate design, domain events, repository interfaces
System Architecture Design	`templates/root/8、系统架构设计.md`	~400	8	Layered architecture, DDD/COLA, data flow, security, deployment, extension mechanisms
Visual and Interaction DNA	`templates/root/9、视觉与交互DNA规范.md`	~280	1	Design principles, color, typography, layout, components, motion, dark mode, accessibility
Feature Menu and Version Planning	`templates/root/10、功能菜单与版本规划.md`	~450	5	Overview, menu structure, feature details, version distribution, user journeys, feature list

9. Related Skills

documentation-builder: General doc writing and formatting conventions
api-doc-generator: OpenAPI and API documentation generation