# 文档元数据规范

所有新建正式文档必须使用 Markdown Front Matter。

## 必填字段

```yaml
---
doc_id: PRD-202606-001
feature_id: FEAT-202606-001-unified-entry-client
type: prd
title: 统一入口客户端需求说明
status: draft
owner: 张三
created_at: 2026-06-16
updated_at: 2026-06-16
---
```

## 推荐字段

```yaml
reviewers:
  - 李四
related_docs:
  - DES-202606-001
related_modules:
  - emoon-openplatform
  - emoon-admin
tags:
  - 统一入口
  - 终端客户端
supersedes:
superseded_by:
source:
```

## 字段说明

| 字段 | 必填 | 说明 |
|---|---|---|
| `doc_id` | 是 | 单篇文档唯一编号 |
| `feature_id` | 否 | 所属需求、项目、专题；非专题类文档可为空 |
| `type` | 是 | 文档类型，取值见 `文档分类.md` |
| `title` | 是 | 文档标题 |
| `status` | 是 | 生命周期状态 |
| `owner` | 是 | 当前负责人 |
| `created_at` | 是 | 创建日期，格式 `YYYY-MM-DD` |
| `updated_at` | 是 | 最近实质更新日期，格式 `YYYY-MM-DD` |
| `reviewers` | 否 | 评审人 |
| `related_docs` | 否 | 关联文档 `doc_id` 列表 |
| `related_modules` | 否 | 关联代码模块 |
| `tags` | 否 | 检索标签 |
| `supersedes` | 否 | 当前文档替代的旧文档 |
| `superseded_by` | 否 | 替代当前文档的新文档 |
| `source` | 否 | 来源链接、会议、外部资料 |

## 状态

| status | 含义 |
|---|---|
| `draft` | 草稿 |
| `reviewing` | 评审中 |
| `approved` | 已确认 |
| `implemented` | 已实现或已落地 |
| `deprecated` | 已废弃 |
| `superseded` | 已被其他文档替代 |

以上 `status` 用于单篇文档。专题索引还可以使用以下需求级状态：

| 专题状态 | 含义 |
|---|---|
| `draft` | 需求或方案准备中 |
| `reviewing` | 正在评审 |
| `ready_for_development` | 开发 Gate 已通过 |
| `developing` | 共享 feature 分支正在开发 |
| `ready_for_merge` | 合并 Gate 已通过 |
| `implemented` | 已合入稳定分支并完成收尾 |
| `paused` | 暂停，允许后续恢复 |
| `cancelled` | 已取消，不再合入未完成代码 |

专题索引应使用独立字段记录 Git 状态，避免把分支信息塞入文档 `status`：

```yaml
baseline_branch: master
baseline_commit:
docs_branch:
feature_branch:
merge_commit:
development_gate: pending
merge_gate: pending
```

## 规则

- 标题不承载编号、日期和状态，这些信息放在 Front Matter。
- `doc_id` 一旦发布，不应复用给其他文档。
- 文档发生实质内容变更时必须更新 `updated_at`。
- 废弃文档不删除，改为 `deprecated` 或 `superseded`，并说明替代文档。
- 涉及接口、架构边界、鉴权、脱敏、模块依赖的变更，必须补充关联文档。