# 内容规范（CONTRIBUTING）

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

## 1. 目录结构

```text
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
```

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

## 2. frontmatter

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

```yaml
---
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` |
| `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. 写作规则

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

## 5. 提交前

```bash
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` 可以生成日程视图。
- 面试题可以按 `### 【级别】` 标题切分成单题，`**参考答案**` 和 `**追问**` 是固定的小标题。