内容规范（CONTRIBUTING）

本仓库是结构化的学习内容：既能直接在 Git 平台上阅读，也能被以后的在线学习平台导入。所有新增、修改的内容都按本规范写，提交前运行校验脚本。

1. 目录结构

zhuangang/
├── README.md                    # 仓库入口
├── CONTRIBUTING.md              # 本文件：内容规范
├── catalog.json                 # 自动生成的内容目录（不要手改）
├── schema/frontmatter.schema.json
├── tools/
│   ├── build_catalog.py         # 校验 + 生成 catalog.json
│   ├── run_examples.py          # 运行示例代码
│   └── check_sensitive.py       # 提交前脱敏检查（第 8 周建立）
├── plan/                        # 16 周学习计划（日程），链接到专题，不重复讲概念
│   ├── README.md                # 总纲
│   └── weekNN-*.md              # type: week
├── topics/                      # 专项学习：按领域 / 技术栈组织
│   ├── index.md
│   └── <domain>/<stack>/
│       ├── index.md             # type: index，技术栈首页：学习路线、课程列表
│       ├── NN-<slug>.md         # type: lesson，课程，NN 是顺序
│       ├── scenarios/<slug>.md  # type: scenario，该技术栈的企业场景
│       ├── interview.md         # type: interview，分级面试题
│       └── examples/            # 可运行的示例代码
├── scenarios/                   # 跨技术栈的企业服务场景（type: scenario，domain: cross）
│   ├── index.md
│   └── <slug>.md
└── research/                    # 岗位调研记录（type: research，domain: plan），只记录实际看到的内容

domain 取值：backend（Go、数据库、缓存、消息队列、微服务）、devops（Docker、Nginx、Linux、CI/CD、Git）、python、ai（RAG、Agent 等）、frontend、cs（计算机基础：算法、网络与操作系统、Web 安全）、cross（跨栈场景）、plan（计划）。
<stack> 是技术栈标识，只用小写字母、数字和 -，例如 redis、grpc-microservices、fe-testing-perf。

2. frontmatter

每个 .md 文件（examples/ 下的除外）第一行开始是 frontmatter。为了让校验脚本不依赖第三方库，只允许两种写法：键: 标量 和 键: [a, b, c]（列表写在一行）。

---
id: backend.redis.cache-patterns
title: 缓存模式：旁路缓存与穿透、击穿、雪崩
type: lesson
domain: backend
stack: [redis]
tags: [缓存, 高并发, 一致性]
level: intermediate
prerequisites: [backend.redis.data-structures]
est_hours: 2
related: [backend.redis.interview, scenario.flash-sale]
week: [3, 14]
order: 2
---

字段	必填	说明
`id`	是	全局唯一、发布后不再修改（平台用它做进度记录和链接）。格式：小写字母数字，用 `.` 分段
`title`	是	标题
`type`	是	`index` / `lesson` / `scenario` / `interview` / `project` / `week` / `research`（岗位调研记录，放在 `research/`）
`domain`	是	见上
`stack`	lesson、scenario、interview 必填	列表；跨栈场景写多个
`level`	lesson、scenario、interview 必填	`basic`（基础）/ `intermediate`（进阶）/ `advanced`（高级）
`tags`	否	关键词，平台用于搜索
`prerequisites`	否	先修内容的 id
`related`	否	相关内容的 id
`est_hours`	否	预计学习小时数
`week`	否	在 16 周计划的哪几周用到（1~16）
`order`	否	同一技术栈内的排序

id 约定：

内容	id 格式	例子
技术栈首页	`<domain>.<stack>.index`	`backend.redis.index`
课程	`<domain>.<stack>.<slug>`	`backend.redis.cache-patterns`
技术栈场景	`<domain>.<stack>.scenario.<slug>`	`backend.redis.scenario.leaderboard`
面试题	`<domain>.<stack>.interview`	`backend.redis.interview`
跨栈场景	`scenario.<slug>`	`scenario.flash-sale`
计划	`plan.index`、`plan.weekNN`	`plan.week03`

3. 各类型的写法

课程（lesson）

必须包含以下二级标题（标题里包含这些词即可，可以加后缀）：

## 解释说明：是什么、为什么，用大白话；和 JS / 前端经验类比更好。
## 案例：在真实业务里用在哪。
## 代码示例：最小、正确、能运行；代码块写语言标记。较长的完整示例放进 examples/，在正文里链接。
## 易错点：常见错误和原因。
可选：## 面试常问（链接到本技术栈的 interview.md）、## 延伸阅读。

场景（scenario）

企业服务场景解决方案，必须包含：

## 业务背景与问题
## 约束：规模、性能、成本、合规、团队等限制条件
## 方案设计：架构图（mermaid）、关键流程、数据模型
## 关键代码
## 取舍：为什么选这个方案、放弃了什么
## 易错点
## 面试怎么讲：一段 1~2 分钟的讲法 + 可能的追问

面试题（interview）

每道题一个三级标题，必须以级别开头：### 【基础】…、### 【进阶】…、### 【场景题】…。校验脚本按这个格式统计题数。
题目下面写 **参考答案**，再写 **追问**（常见的追问和要点）。
能结合项目的写上“在本计划的哪个项目里体现”。

计划（week）

日程安排：每天的任务、要建的文件、运行方式、完成标准。
概念讲解放在专题里，计划文件用链接引用，不重复写。项目的分步实现代码保留在计划文件里（type 仍为 week）。

4. 写作规则

中文写作，术语第一次出现时附英文。
代码必须正确：能运行的示例放进 examples/ 并能被 tools/run_examples.py 跑通；需要外部服务的在文件开头写 不自动运行，并说明怎么手动运行。
更新快的框架（LangChain、LangGraph、MCP、Vite、Next.js、Nuxt 等）标注“以官方文档为准”并附链接，写明验证时的版本。
脱敏：不出现公司内部项目名、代码、接口路径、表名、内网地址、密钥、客户数据。场景都用通用的业务描述。
不编造数据：性能数字、统计数字必须注明来源，或写成“以实测为准”。
链接一律用相对路径，校验脚本会检查链接是否存在。

5. 提交前

python3 tools/build_catalog.py          # 校验并更新 catalog.json
python3 tools/run_examples.py           # 运行示例（可加关键词只跑部分，例如 redis）
python3 tools/check_sensitive.py        # 脱敏检查（如果已经按第 8 周装好钩子，会自动执行）

6. 给学习平台的导入说明

以 catalog.json 为入口：stacks 是技术栈列表（含课程数、场景数、各级面试题数、示例路径），items 是全部内容（frontmatter + 文件路径 + 二级标题列表 + 面试题统计）。
内容正文就是 Markdown 文件本身（去掉 frontmatter）；mermaid 图需要前端渲染。
学习进度按 id 记录；prerequisites 可以生成学习路线图，week 可以生成日程视图。
面试题可以按 ### 【级别】 标题切分成单题，**参考答案** 和 **追问** 是固定的小标题。

7.4 KiB Raw Blame History Unescape Escape