Simon
344 lines
7.4 KiB
Markdown
344 lines
7.4 KiB
Markdown
# 项目管理文档管理规范
|
||
|
||
> **版本**: 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 |
|