文档库使用与写作规范
本文件是 sunqy-doc 知识库的唯一权威规范。 「项目怎么用」与「文档怎么写」全部集中在此，其他文件不再重复规定，一律指向这里。
最后更新：2026-09-04 · 配套文件：PLAN.md（计划）· PROGRESS.md（进度）
一、速查：新增一篇文档只需 5 步
赶时间的话只看这一节。详细规则见第二～九节。
| # | 动作 | 位置 |
|---|---|---|
| 1 | 打开 plan/<域>.md，确认目标条目的 ID（如 A06）与状态为 ⬜ | plan/ |
| 2 | 按下面**第五节「文章骨架」**写正文，存为 NN-标题.md（文件名禁空格） | 对应域目录 |
| 3 | 在 .vitepress/config.ts 的 nav 和 sidebar 各加一条（绝对路径，以 / 开头） | config.ts |
| 4 | 在该域 README.md 清单表补一行（只列状态为 ✅ 的） | 域目录 |
| 5 | 回 plan/<域>.md 把该行置 ✅；再到 PROGRESS.md 顶部追加一行 | plan/ · 根目录 |
⚠️ 第 5 步是交付的最后一步，漏了就会导致计划与实际不一致。
二、这个库怎么用（站点运维）
2.1 站点信息
| 项 | 值 |
|---|---|
| 生产地址 | https://sunqy-doc.pages.dev |
| 构建工具 | VitePress |
| 构建产物 | .vitepress/dist（由 wrangler 直传，不走 Git 分支） |
| 源码仓库 | Gitee（dev 开发 / master 稳定） |
main分支（早期 Gitee Pages 的产物分支）已废弃。完整部署说明见 deploy.md。
2.2 常用命令
npm install # 首次安装依赖
npm run docs:dev # 本地预览 http://localhost:5173/
npm run docs:build # 构建到 .vitepress/dist
npm run deploy # 构建 + 上传到 Cloudflare Pages2.3 提交 ≠ 部署（重要）
日常只提交源码。 部署必须本地验证通过后再手动执行，且仅在用户明确要求时才执行 npm run deploy。
2.4 导航注册
所有对读者可见的文档，都必须在 .vitepress/config.ts 的 nav 和 sidebar 里注册，链接用绝对路径（以 / 为基准）。
sidebar 按路径前缀分组，新增顶级区域时需新增一个前缀分组。
三、内容组织：域 与 形态
本库用两个维度定位任何一篇文档，二者正交。
3.1 域（横轴）——决定放在哪个目录
| 码 | 域 | 目录 | 状态 |
|---|---|---|---|
| A | 前端 | frontend/ | 在建 |
| B | Flutter · 移动端 | flutter/ | 在建 |
| C | 后端 | backend/ | 在建 |
| D | 运维 DevOps | 待建 | 候选 |
| E | 通用基本功 | 待建 | 候选 |
| F | 工程方法论 | 待建 | 候选 |
| G | AI | AI/ | 在建 |
| H | 产品与设计 | 待建 | 候选 |
| N | 网络与通信 | network/ | 在建 |
| S | 安全 | security/ | 在建 |
| DB | 数据库与存储 | database/ | 在建 |
域码一经分配永久保留，不复用、不回收（现已分配 A~H、N、S、DB）。 新增域见下面第八节「新增一个域」。完整清单见 PLAN.md。
3.2 形态（纵轴）——决定属于哪种文档类型
采用 Diátaxis 四分法。「形态」不是「域」，任何域都可以有这四种形态。
| 形态 | 用途 | 用户心智 | 本库落点 |
|---|---|---|---|
| 教程 Tutorial | 系统学习 | "教我" | flutter/ 系列、AI/practice/ |
| 操作指南 How-to | 完成任务 | "我要解决 X" | cheatsheets/、troubleshooting/ |
| 参考 Reference | 查信息 | "这个 API 是什么" | 速查区、附录 |
| 解释 Explanation | 理解原理 | "为什么这样" | frontend/、AI/ 正文 |
| 面试题 Interview | 面试复习聚合 | "帮我复习/押题" | interview/（按分类链各域 + 内联） |
速查区、踩坑区、面试题区都是「形态区」，不是「域」：
- 速查与踩坑按域分文件。现有 8 篇速查为 B 域（Flutter/Dart/Riverpod/GoRouter/Freezed）与 E 域（Git/Shell/正则）； 将来写后端，追加的是
cheatsheets/09-xxx.md（C 域速查），而不是新建域。 - 现有 4 篇踩坑全部属于 B 域；将来新增其他域的踩坑，同样在
troubleshooting/下追加文件。 - 面试题区是聚合型形态区：按域分类建页，页内题目优先链到各域已有文章， 只有无归属的题目才在本区写内联解答。详见 plan/interview.md。
3.3 文档 ID 规则
每篇文档有一个稳定 ID，计划表与进度日志一律引用 ID，不引用文件名——这样改名不会断链。
| 类型 | 格式 | 示例 | 说明 |
|---|---|---|---|
| 域内长文 | <域码><两位序号> | A06、B22、G05 | 序号域内递增 |
| 子系列 | <域码><子系列码><序号> | GP01 | G 域 practice 实操第 1 篇 |
| 速查 | S<域码><序号> | SB01、SE01 | S = Sheet |
| 踩坑 | T<域码><序号> | TB01 | T = Troubleshooting |
| 面试题 | I<分类字母> | IF、IM、IG、I00 | I = Interview，按域分类（前端/移动/AI/后端/网络/数据库/安全…）；I00 为总览 |
ID 是逻辑标识，与文件名无关。Flutter 区现有编号
00~31直接映射为B00~B31，文件名无需改动。
四、文件与命名规范
4.1 文件命名
| 规则 | 正确 | 错误 |
|---|---|---|
NN-标题.md，两位序号 + 连字符 + 标题 | 06-CSS布局体系.md | 06 CSS布局.md |
| 禁止空格 | 26-混合开发与Add-to-App.md | 21-Platform Channel 原生桥接.md ⚠️ |
| 中文标题，不用拼音缩写 | 04-浏览器与网络.md | 04-llqywl.md |
⚠️ 现存的
21-Platform Channel 原生桥接.md、25-Flutter Web与桌面端.md含空格，导致链接必须写成%20。 属历史遗留，暂不重命名（避免批量死链），但新文件严禁再出现空格。
4.2 目录结构
doc/
├── docs/ ← 项目自身的文档（规范·计划·进度·部署），不含知识内容
│ ├── GUIDE.md 本文件：唯一权威规范
│ ├── PLAN.md 总计划：域清单 + 候选池 + 指向各类别计划
│ ├── PROGRESS.md 进度日志（倒序流水）
│ ├── deploy.md 部署说明
│ └── plan/ 各类别计划文件
│ └── <域>.md frontend / flutter / ai / backend / network / security / database / interview
├── README.md 项目简介（规范内容一律指向本文件）
├── index.md 站点首页
├── pages/ ← 知识内容（内容文档），与 docs/ 在仓库根同级
│ ├── frontend/ A 域
│ ├── flutter/ B 域（haierenergy-onboarding/）
│ ├── AI/ G 域
│ ├── backend/ C 域（开写时建）
│ ├── network/ N 域（开写时建）
│ ├── security/ S 域（开写时建）
│ ├── database/ DB 域（开写时建）
│ ├── cheatsheets/ 速查区（形态区，按域分文件）
│ ├── troubleshooting/ 踩坑区（形态区，按域分文件）
│ └── interview/ 面试题区（形态区，聚合入口，按分类链各域）
└── .vitepress/ 站点配置与构建产物（dist/cache）为什么分成「项目文档」和「知识内容」两层：
docs/装的是关于这个库本身的文档（怎么维护、写了什么、怎么部署）； 顶层其余目录装的是学到的知识。两者性质不同，混在根目录会难以分辨。
语言类专题（flutter/）内部按固定七类分目录，编号 01~07（不需要的类别不建，保留编号跳跃）：
| 目录 | 放什么 |
|---|---|
01-入门导览 | 总索引、学习路线、快速上手 |
02-语言基础 | 语言本身的语法与特性 |
03-框架基础 | 框架核心概念与通用机制 |
04-项目架构 | 分层、状态管理、数据链路 |
05-项目实战 | 端到端功能实现记录 |
06-平台能力 | 与操作系统 / 第三方服务对接 |
07-工程化 | 构建、测试、调试、规范 |
4.3 frontmatter
新增文章必须带，便于机器化统计状态：
---
title: 文章标题
domain: A # 域码，见 PLAN.md
id: A06 # 文档 ID，见 3.3
status: done # draft | done | outdated | paused
priority: P0 # P0 | P1 | P2 | P3
updated: 2026-09-04
---历史文章（本规范建立之前的 60+ 篇）暂不补齐，待翻新时顺带补上。
五、文章骨架（统一结构）
5.1 标准长文
# NN · 标题
> 一句话定位：这篇解决什么问题、适合谁、读完能干什么
## 开篇速览 ← 一张表或卡片，30 秒判断"跟我有没有关系"
## 一、… ← 正文分章，每章开头先给结论
## N、…
## 自检清单 ← "学完你应该能做到什么"
## 常见误区
## 动手练习
## 相关文档 ← 与本域、跨域、速查/踩坑区互链「相关文档」与「延伸方向」等价：G 域（AI）19 篇统一使用「延伸方向」作为该章节标题， 其余各域使用「相关文档」。二者是同一章节，不视为缺失。新写文章跟随所在域的既有叫法， 不必为了统一而批量改名。
Flutter 区在此基础上，正文每章的结构为：概念对照 → 本项目真实代码 → 动手练习。
5.2 速查条目
- 按问题 / 症状组织，不按知识结构组织
- 单条目 ≤ 10 行，只给可直接复制的代码
- 标题即搜索关键词（用大家真正会搜的词，如"垂直溢出"而非"布局约束违规"）
- 不写原理，需要时链回主教程
5.3 踩坑记录
每条固定四段，缺一不可：
| 段 | 内容 |
|---|---|
| 症状 | 具体报错信息或现象，要能被搜索到 |
| 原因 | 根因分析，不要只写"配置问题" |
| 解法 | 可执行的解决步骤 |
| 预防 | 如何避免再犯 |
标题必须用报错原文关键词；标注环境（版本、平台、是否 Release 包）；一条一坑。
六、写作原则
6.1 以判断框架为核心，不做重复教程
基础教程网上已经足够多。本库只写网上少见、对自己有独特价值的内容：
- 选型判断框架——不只是"是什么"，而是"什么时候选它、为什么不选别的"
- 迁移 / 演进的实战经验——踩过的坑、真实的成本
- 跨技术的理解迁移——用已知解释未知（这类内容只写在学习侧那一区，避免两区重复）
6.2 易变信息隔离
版本号、性能跑分、生态排名、价格这类会过时的信息：
- 不写死在正文，集中放附录或速查表
- 正文只写原理、权衡、判断框架
- 无法避免时明确标注"请以官方为准"
6.3 防止文档腐化（引用规范）
- 引用代码时优先标函数名 / 类名（名字比行号稳定）
- 必须标行号时，在该区 README 注明代码基准版本
- 不粘贴大段代码（只给 10~20 行关键片段）
- 每季度抽查一次引用有效性
6.4 宁缺毋滥
只建会写、会用的主题。一个写满 20 篇的库，远胜 50 篇空壳目录。 未写的内容留在计划文件的候选池里（状态 ⏸），不建空目录。
6.5 面向决策
不只解释"是什么"，重点回答"怎么选""代价是什么""什么情况下别用"。
七、状态与优先级定义
状态（计划文件与 frontmatter 共用）
| 符号 | frontmatter | 含义 |
|---|---|---|
| ⬜ | — | 未开始 |
| 📝 | draft | 草稿（写了但不完整） |
| ✅ | done | 已完成 |
| 🔄 | outdated | 待翻新（内容已过时） |
| ⏸ | paused | 暂缓（评估后决定不写） |
优先级
| 值 | 含义 |
|---|---|
| P0 | 常用，必写 |
| P1 | 该有，一年内补 |
| P2 | 有空写 |
| P3 | 候选池，可能永远不写 |
八、新增一个域
- 先在
PLAN.md的候选池登记一行，写明定位与理由，状态标⏸ 候选 - 真正开始写时，状态改为「在建」，此时才允许建
plan/<域>.md和实际目录 - 分配域码（按 A~Z 顺序取用，已分配 A~H、N、S、DB）
- 在
.vitepress/config.ts注册nav与sidebar前缀分组 - 在
README.md的「现有内容」表补一行
未登记的目录 = 违规目录，视为待清理。
九、给 AI 助手与新工具的指令
换任何工具、任何会话，开始工作前先读本文件和
PLAN.md，然后按下面执行。
你是 sunqy-doc 知识库的协作助手。开始任何工作前：
1. 读 GUIDE.md —— 严格遵守其中的全部规范（命名、骨架、frontmatter、注册流程）
2. 读 PLAN.md —— 定位目标条目所属的域与 ID；未登记的域或主题，先问用户是否加入计划，
不要自作主张新建目录
3. 写一篇文档的完整流程 = GUIDE.md 第一节的 5 步，第 5 步（回写计划与进度）不可省略
4. 改动已有文档前，先确认它是否属于「待翻新（🔄）」清单，避免在新旧两套约定间来回
5. 输出全部使用中文（命令、标识符除外）
6. 只提交源码到 Git；绝不自动执行 npm run deploy，除非用户明确要求