131 lines
3.8 KiB
Markdown
131 lines
3.8 KiB
Markdown
|
# 文档管理规范（SOP）
|
|||
|
|
|
|||
|
|
> 本文档定义项目文档的分类、命名、模板和维护规范。所有新增文档必须按此规范执行。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 1. 目录结构
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
docs/
|
|||
|
|
├── project/ # 项目级文档（整体架构、需求、数据库等）
|
|||
|
|
│ ├── 01-requirements.md
|
|||
|
|
│ ├── 02-architecture.md
|
|||
|
|
│ ├── 03-database-design.md
|
|||
|
|
│ ├── 04-feature-design.md
|
|||
|
|
│ ├── 05-development-plan.md
|
|||
|
|
│ ├── 06-glossary.md
|
|||
|
|
│ ├── 07-system-overview.md
|
|||
|
|
│ ├── 08-test-plan.md
|
|||
|
|
│ └── 09-test-results.md
|
|||
|
|
│
|
|||
|
|
├── design/ # 功能设计文档（按端 → 按模块）
|
|||
|
|
│ ├── README.md # 设计文档索引
|
|||
|
|
│ ├── super-admin/ # 超管端
|
|||
|
|
│ │ └── unified-user-management.md
|
|||
|
|
│ ├── org-admin/ # 机构管理端
|
|||
|
|
│ ├── public/ # 公众端
|
|||
|
|
│ └── judge/ # 评委端
|
|||
|
|
│
|
|||
|
|
├── deployment/ # 部署运维文档
|
|||
|
|
│ ├── backend-deployment.md
|
|||
|
|
│ └── frontend-deployment.md
|
|||
|
|
│
|
|||
|
|
├── sop/ # 流程规范
|
|||
|
|
│ └── document-standards.md # 本文档
|
|||
|
|
│
|
|||
|
|
└── legacy/ # 已归档的旧文档（重构前遗留，仅保留参考）
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 2. 文档分类
|
|||
|
|
|
|||
|
|
| 分类 | 目录 | 说明 | 示例 |
|
|||
|
|
|------|------|------|------|
|
|||
|
|
| **项目级** | `docs/project/` | 整个项目的顶层设计，跨模块跨端 | 需求概述、系统架构、数据库设计 |
|
|||
|
|
| **功能设计** | `docs/design/{端}/` | 某个端某个模块的需求分析 + 设计方案 | 超管端统一用户管理 |
|
|||
|
|
| **部署运维** | `docs/deployment/` | 环境搭建、部署流程、运维手册 | 后端部署、前端部署 |
|
|||
|
|
| **流程规范** | `docs/sop/` | 团队协作规范、开发流程 | 本文档 |
|
|||
|
|
| **归档** | `docs/legacy/` | 重构前的旧文档，不再更新 | 旧版比赛模块设计 |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 3. 功能设计文档模板
|
|||
|
|
|
|||
|
|
每个功能设计文档使用以下结构：
|
|||
|
|
|
|||
|
|
```markdown
|
|||
|
|
# {模块名称} — 设计方案
|
|||
|
|
|
|||
|
|
> 所属端：超管端 / 机构管理端 / 公众端 / 评委端
|
|||
|
|
> 状态：设计中 / 开发中 / 已完成
|
|||
|
|
> 创建日期：YYYY-MM-DD
|
|||
|
|
> 最后更新：YYYY-MM-DD
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 1. 背景与问题
|
|||
|
|
|
|||
|
|
为什么要做这个功能/改造？当前存在什么问题？
|
|||
|
|
|
|||
|
|
## 2. 现状分析
|
|||
|
|
|
|||
|
|
当前的实现方式、涉及的页面和接口、数据结构。
|
|||
|
|
|
|||
|
|
## 3. 设计方案
|
|||
|
|
|
|||
|
|
### 3.1 整体思路
|
|||
|
|
|
|||
|
|
一句话概括方案。
|
|||
|
|
|
|||
|
|
### 3.2 页面设计
|
|||
|
|
|
|||
|
|
页面结构、交互逻辑、UI 布局说明。
|
|||
|
|
|
|||
|
|
### 3.3 后端改动
|
|||
|
|
|
|||
|
|
接口变更、新增接口、数据模型变更。
|
|||
|
|
|
|||
|
|
### 3.4 前端改动
|
|||
|
|
|
|||
|
|
涉及的文件、组件结构、状态管理。
|
|||
|
|
|
|||
|
|
## 4. 改动范围
|
|||
|
|
|
|||
|
|
列出所有需要新增/修改/删除的文件。
|
|||
|
|
|
|||
|
|
## 5. 实施记录
|
|||
|
|
|
|||
|
|
开发过程中的关键决策和变更记录。
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 4. 命名规范
|
|||
|
|
|
|||
|
|
### 4.1 文件命名
|
|||
|
|
|
|||
|
|
- 功能设计文档：`{功能名-英文短横线}.md`，如 `unified-user-management.md`
|
|||
|
|
- 项目级文档：`{序号}-{名称}.md`，如 `01-requirements.md`
|
|||
|
|
- 全小写，单词间用短横线 `-` 连接
|
|||
|
|
|
|||
|
|
### 4.2 端目录命名
|
|||
|
|
|
|||
|
|
| 端 | 目录名 |
|
|||
|
|
|----|--------|
|
|||
|
|
| 超管端 | `super-admin/` |
|
|||
|
|
| 机构管理端 | `org-admin/` |
|
|||
|
|
| 公众端 | `public/` |
|
|||
|
|
| 评委端 | `judge/` |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 5. 维护规则
|
|||
|
|
|
|||
|
|
1. **先设计后开发**：功能开发前，必须先在 `docs/design/` 创建设计文档，经确认后再编码
|
|||
|
|
2. **开发中同步更新**：实施过程中如有方案变更，及时更新设计文档的"实施记录"部分
|
|||
|
|
3. **完成后标记状态**：开发完成后将文档状态改为"已完成"
|
|||
|
|
4. **不删只归档**：过时文档移入 `legacy/`，不直接删除
|
|||
|
|
5. **索引及时更新**：新增设计文档后，更新 `docs/design/README.md` 索引
|