simon/wecom_it_smart_desk

Fork 0

Files

T

Simon 64ff1bf7d5 chore: 整理项目结构，清理归档文件，更新部署配置

2026-07-04 21:01:39 +08:00

7.4 KiB

Raw Blame History

项目管理文档管理规范

版本: 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 版本记录

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

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

4.3 变更记录

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

## 📈 版本历史

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

5. 任务说明书要求

5.1 必含字段

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

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

5.2 输入项来源规范

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

### 📥 输入项来源

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

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

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

5.3 输出成果要求

明确每项任务的交付物：

### 📤 输出成果要求

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

5.4 验证方式

### 🔧 验证方式

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

5.5 完成标准

### ✅ 完成标准

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

6. 文档审批流程

6.1 审批角色

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

6.2 审批状态

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

7. 文档归档要求

7.1 归档条件

满足以下任一条件应归档：

文档被新版本替代
对应功能已完成并稳定运行超过3个月
文档内容已整合到其他文档

7.2 归档命名

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

# 归档前
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

7.4 KiB Raw Blame History Unescape Escape