# 项目管理文档管理规范

> **版本**: v1.0 | **日期**: 2026-07-04 | **状态**: 正式发布

---

## 1. 目的与适用范围

### 1.1 目的

规范 IT 智能服务台项目的文档管理流程，确保文档的准确性、完整性和可追溯性，提高团队协作效率。

### 1.2 适用范围

本规范适用于 IT 智能服务台项目开发过程中的所有文档，包括但不限于：
- 产品需求文档（PRD）
- 技术架构文档
- 原型设计文档
- 代码评审报告
- 测试文档
- 部署运维文档
- 项目管理文档（任务说明书、风险跟踪表等）

---

## 2. 文档目录结构

### 2.1 顶级目录划分

```
docs/
├── 01-项目总览/          ← 核心文档（必读）
├── 02-产品需求/          ← PRD、功能需求
├── 03-技术架构/          ← 架构设计、ADR、图表
├── 04-原型设计/          ← UI/UX原型
├── 05-用户手册/          ← 用户指南
├── 06-测试质量/          ← 测试文档
├── 07-代码评审/          ← Code Review
├── 08-安全审计/          ← 安全、集成分析
├── 09-部署运维/          ← 部署、运维、故障排查
├── 10-项目管理/          ← SOP、项目管理
└── 11-历史归档/          ← 历史归档
```

### 2.2 子目录命名规范

| 目录类型 | 命名规则 | 示例 |
|----------|----------|------|
| 功能模块 | `XX-功能模块名/` | `02-技术方案/` |
| 文档类型 | `XX-文档类型-类型名/` | `01-ADRs-架构决策/` |
| 归档目录 | `archive/` | `prototypes-原型图/archive/` |

---

## 3. 文档命名规范

### 3.1 核心文档

```
序号-文档名-YYYYMMDD.扩展名
```

**规则**：
- 序号：01、02、03...（两位数字）
- 文档名：中文描述，不超过30字
- 日期：创建或重大更新日期（8位数字）

**示例**：
- `01-项目总览与部署手册-20260704.md`
- `02-产品需求文档PRD-v1.2-20260704.md`

### 3.2 普通文档

```
文档名-YYYYMMDD.扩展名
```

**示例**：
- `v0.7.1-release-notes-20260623.md`

### 3.3 归档文档

```
原文档名-archived-YYYYMMDD.扩展名
```

**示例**：
- `PRD-v53-incremental-archived-20260704.md`

### 3.4 ADR 文档

```
ADR-XXX-标题.扩展名
```

**示例**：
- `ADR-001-Gitea自托管-Funnel暴露.md`

### 3.5 SOP 文档

```
SOP-序号-流程名.扩展名
```

**示例**：
- `SOP-01-Gitea部署.md`

### 3.6 禁止事项

- ❌ 禁止使用特殊字符（`/ \ : * ? " < > |`）
- ❌ 禁止使用空格（用 `-` 或 `_` 代替）
- ❌ 禁止使用 emoji
- ❌ 禁止纯数字命名

---

## 4. 文档版本管理

### 4.1 版本号规则

采用 `主版本.次版本.修订号` 格式：
- **主版本**：重大架构变更或功能迭代
- **次版本**：功能新增或较大调整
- **修订号**：文档修正、错别字修改

**示例**：v1.0 → v1.1 → v2.0

### 4.2 版本记录

每个文档头部必须包含版本信息：

```markdown
> **版本**: v1.0 | **日期**: 2026-07-04 | **作者**: xxx | **状态**: 草稿/评审中/正式发布
```

### 4.3 变更记录

重大文档必须包含变更记录：

```markdown
## 📈 版本历史

| 版本 | 日期 | 变更内容 | 变更人 |
|------|------|----------|--------|
| v1.0 | 2026-07-04 | 初始版本 | xxx |
| v1.1 | 2026-07-05 | 新增xxx功能 | xxx |
```

---

## 5. 任务说明书要求

### 5.1 必含字段

根据任务类型，必须包含以下字段：

| 字段 | 说明 | 必填 |
|------|------|------|
| 任务名称 | 任务简短描述 | ✅ |
| 任务ID | 唯一标识（如 #90） | ✅ |
| 优先级 | P0/P1/P2 | ✅ |
| 状态 | 待开始/进行中/已完成/阻塞/延后 | ✅ |
| 输入项来源 | 产品需求/技术架构/原型设计/项目看板 | ✅ |
| 输出成果要求 | 交付物清单 | ✅ |
| 验证方式 | 测试方法 | ✅ |
| 完成标准 | 验收条件 | ✅ |

### 5.2 输入项来源规范

每项任务必须明确输入来源：

```markdown
### 📥 输入项来源

#### 产品需求
| 来源文档 | 相关章节 | 说明 |
|----------|----------|------|
| `02-产品需求/02-产品需求文档PRD-v1.2-20260704.md` | §4.5 | 登录流程要求 |

#### 技术架构
| 来源文档 | 相关章节 | 说明 |
|----------|----------|------|
| `03-技术架构/02-技术方案/技术方案-消息功能详细设计.md` | - | 技术实现方案 |

#### 原型设计
| 来源文档 | 页面 | 说明 |
|----------|------|------|
| `04-原型设计/prototypes-原型图/admin-dashboard-v1.html` | 登录页 | 登录UI要求 |
```

### 5.3 输出成果要求

明确每项任务的交付物：

```markdown
### 📤 输出成果要求

| # | 交付物 | 类型 | 说明 |
|---|--------|------|------|
| 1 | 后端登录API | 代码 | `/api/auth/login` 接口 |
| 2 | 登录页面 | 代码 | Vue组件 |
| 3 | API文档 | 文档 | 更新OpenAPI |
```

### 5.4 验证方式

```markdown
### 🔧 验证方式

| 验证项 | 验证方法 | 预期结果 |
|--------|----------|-----------|
| 功能正常运行 | 手动测试 | 登录成功 |
| 权限控制 | 越权测试 | 无法访问未授权页面 |
| 响应时间 | 性能测试 | < 500ms |
```

### 5.5 完成标准

```markdown
### ✅ 完成标准

- [ ] 代码合入主干分支
- [ ] 所有测试通过
- [ ] 功能测试通过
- [ ] 安全测试通过
- [ ] 文档已更新
```

---

## 6. 文档审批流程

### 6.1 审批角色

| 文档类型 | 审批人 |
|----------|--------|
| 产品需求（PRD） | 产品经理 + 技术负责人 |
| 技术架构文档 | 技术负责人 |
| 代码评审报告 | 评审参与者 |
| 部署文档 | 运维负责人 |

### 6.2 审批状态

| 状态 | 说明 |
|------|------|
| 草稿 | 初始编写 |
| 评审中 | 等待审批 |
| 修订中 | 评审反馈需修改 |
| 正式发布 | 审批通过 |
| 已废弃 | 被新版本替代 |

---

## 7. 文档归档要求

### 7.1 归档条件

满足以下任一条件应归档：
- 文档被新版本替代
- 对应功能已完成并稳定运行超过3个月
- 文档内容已整合到其他文档

### 7.2 归档命名

归档文档添加 `-archived-YYYYMMDD` 后缀：

```bash
# 归档前
PRD-v53-incremental.md

# 归档后
PRD-v53-incremental-archived-20260704.md
```

### 7.3 归档位置

- 历史归档文档统一放置在 `11-历史归档/` 目录
- 按时间顺序保留，最新版本在主目录

---

## 8. 文档索引维护

### 8.1 主索引文档

`01-项目总览/00-索引-YYYYMMDD.md` 为项目主索引，需保持更新。

### 8.2 更新规则

| 操作 | 同步要求 |
|------|----------|
| 新增文档 | 添加到对应目录 + 更新索引 |
| 删除文档 | 从索引移除 |
| 移动文档 | 更新索引路径 |
| 重大变更 | 同步更新 CHANGELOG |

---

## 9. 文档质量检查清单

### 9.1 基本检查

- [ ] 文档命名符合规范
- [ ] 头部包含版本信息
- [ ] 目录结构清晰
- [ ] 无错别字

### 9.2 内容检查

- [ ] 需求来源明确
- [ ] 技术方案合理
- [ ] 验证方式可行
- [ ] 完成标准可衡量

### 9.3 关联检查

- [ ] 相关文档链接正确
- [ ] 版本历史完整
- [ ] 索引已更新

---

## 10. 附则

### 10.1 生效日期

本规范自 2026-07-04 起正式执行。

### 10.2 解释权

本规范解释权归项目负责人所有。

### 10.3 修订周期

每季度评审一次，根据实际执行情况进行修订。

---

## 📈 变更记录

| 版本 | 日期 | 变更内容 | 变更人 |
|------|------|----------|--------|
| v1.0 | 2026-07-04 | 初始版本 | Claude |