文档规范 (Documentation Spec)

本文件定义 xueda-docs 的写作与组织标准。所有新文档、修改现有文档时遵循此规范。

---

目录结构

docs/
├── product/       产品 PRD — 每个模块一个完整文档
├── design/        设计规范 — 仅跨模块共享的通用规范
├── operations/    运营指南 — 面向运营团队
├── agent/         Agent — AI Skills、能力矩阵
└── archive/       归档 — 历史验收报告等（不进侧边栏）

放置规则

内容类型	放在哪	说明
业务逻辑 + UI 设计 + 原型 + 验收标准	product/	一个模块 = 一个文件，不拆
B 端管理功能	product/ 同一文件	作为模块 PRD 的一个章节
跨模块通用组件/样式	design/	唯一需要独立维护的设计文档
运营 SOP / 作战手册 / 体验报告	operations/	面向运营，非产品 spec
Agent Skill / 能力矩阵	agent/	AI 相关
已过期的验收报告	archive/	srcExclude，不构建

核心原则

设计、原型、验收标准是 PRD 的一部分，不单独拆文件。

唯一例外：

• design/通用组件规范.md — 跨模块共享的页面骨架、插槽、组件
• 原型设计如果作为独立视觉参考有价值（如打卡型原型设计），可保留为子文档

---

文档结构模板

PRD 文档（product/）

# 模块名称

> **文档版本**: VX.X
> **更新日期**: YYYY-MM-DD
> **状态**: 草稿 | 评审中 | 定稿
> **依赖**: [通用组件规范](../design/通用组件规范.md)

---

## 一、背景与目标
### 问题陈述
### 成功指标

## 二、核心逻辑与业务规则

## 三、C 端详情页
### 3.1 页面结构
### 3.2 差异化插槽
### 3.3 交互流程

## 四、发布端 / B 端管理
### 4.1 创建/编辑流程
### 4.2 管理功能

## 五、验收标准
### 5.1 通用
### 5.2 模块专属

## 六、文档修订记录
| 版本 | 日期 | 变更内容 |

必须包含：背景目标、业务规则、C 端设计、验收标准、修订记录 按需包含：B 端管理、原型图、数据字段定义

运营文档（operations/）

无固定模板，但必须包含：

• 文档目的和适用场景
• 操作步骤（编号）
• 注意事项/风险提示

Agent 文档（agent/）

遵循 Skill 标准格式（name/version/trigger/steps）。

---

命名规范

类型	格式	示例
模块 PRD	{模块名}.md	里程挑战.md
子模块 PRD	{父模块}-{子模块}.md	票务-库存与订单.md
子文档	{模块名}-{子文档}.md	里程挑战-打卡型原型设计.md
运营文档	自然语言命名	运营作战手册.md
原型图	{功能}-{描述}.png	c-end-detail-compare.png

---

图片与资产

优先：R2 图床

图片优先上传到 R2 图床（img.mudui.me），文档中用 URL 引用：

![描述](https://img.mudui.me/xueda-docs/filename.png)

优点：不占仓库体积、CDN 加速、跨文档复用无路径问题。

备选：本地存放

没有 R2 权限的协作者可以将图片放在仓库内：

图片类型	存放位置
产品原型图	product/assets/
运营截图	operations/验收资产/
归档截图	archive/

本地引用格式：![描述](./assets/filename.png)

通用规则

• 命名用英文小写+连字符：c-end-detail-compare.png
• 禁止在文档目录外散落图片
• 已上传 R2 的图片，本地副本可删除以减小仓库体积

---

交叉引用规则

SSoT（Single Source of Truth）

每个知识点只在一个地方写完整版，其他地方引用：

> 完整定义见 [里程挑战 §3.2](./里程挑战#32-检查点机制)

引用格式

• 同目录：[文档名](./文档名)
• 跨目录：[文档名](../design/通用组件规范)
• 章节锚点：[§标题](./文档名#锚点)

引用 vs 复制

情况	做法
通用组件（报名抽屉、底部栏）	引用 design/通用组件规范.md，本地只写差异
算法/字段定义	只在 PRD 写一次，其他文档引用
原型图	可在多处引用同一张图，不复制文件

---

版本管理

• 文档头部 frontmatter 标注版本号和日期
• 重大变更在文末「修订记录」表格追加一行
• commit message 格式：docs({模块}): {变更描述}

---

侧边栏维护

文件：docs/.vitepress/config.ts

规则：

• 新增文档必须同步加入 sidebar
• 子文档缩进表示（用 └ 前缀或嵌套 items）
• archive/ 下的文档不进侧边栏（已在 srcExclude）
• 空壳页面（无实质内容）不放侧边栏

---

检查清单（新建/修改文档时）

• [ ] 放在正确的目录
• [ ] 文档头部有版本号、日期、状态
• [ ] 设计+原型+验收在同一文件内（不拆）
• [ ] 图片放在 product/assets/ 或对应目录
• [ ] 交叉引用用链接，不复制内容
• [ ] 侧边栏已更新
• [ ] VitePress 构建通过