CRMEB 项目文档写作规范

0. 自动调用场景

0.1 触发条件

• 目录浏览时：当浏览文档相关目录时自动调用
  • 打开 dev-docs/ 目录时触发
  • 打开 dev-docs/phpapi/ 目录时触发
  • 打开 dev-docs/admin/ 目录时触发
  • 打开 dev-docs/uniapp/ 目录时触发
  • 打开 dev-docs/nuxt/ 目录时触发
• 文档创建时：当创建新的 Markdown 文档文件时自动调用
• 文档编辑时：当编辑现有文档文件时自动调用
• 关键词触发：当文档内容包含以下关键词时自动调用
  • 文档、说明、指南、手册、规范
  • API、接口、部署、开发、需求

0.2 适用文件类型

• .md (Markdown 文件)
• .txt (文本文件)
• .doc/.docx (Word 文档)
• .pdf (PDF 文档)

0.3 调用优先级

• 当多个技能同时触发时，文档规范技能优先级中等
• 仅在文档相关操作时被触发
• 不影响其他技能的正常使用

1. 文档类型

1.1 技术文档

• API 文档：接口设计、参数说明、返回格式
• 开发文档：架构设计、模块说明、开发流程
• 部署文档：环境要求、安装步骤、配置说明
• 接口文档：接口列表、请求参数、返回示例

1.2 业务文档

• 需求文档：功能描述、业务流程、数据结构
• 测试文档：测试用例、测试结果、缺陷报告
• 用户手册：功能介绍、操作指南、常见问题

2. 格式规范

2.1 文件名规范

• 使用小写下划线分隔
• 清晰描述文档内容
• 示例：api接口文档.md、部署指南.md

2.2 标题层级

• 使用 # 表示标题层级
• 一级标题：文档主题
• 二级标题：主要章节
• 三级标题：细分内容
• 最多使用四级标题

2.3 文本格式

• 正文使用宋体/无衬线字体，14px
• 代码块使用 ``` 包裹，指定语言
• 列表使用 - 或 1. 表示
• 强调内容使用 **加粗** 或 *斜体*

2.4 代码规范

• 代码块必须指定语言
• 缩进一致，格式清晰
• 关键代码添加注释
• 示例：

  // 获取用户信息
  public function getUserInfo($id) {
      return $this->where('id', $id)->find();
  }
  

2.5 文档存放目录

• 文档保存到 dev-docs 目录中
• 后端接口文档存放 dev-docs/phpapi 目录中
• 后端前端 ElementUI（Admin）文档存放 dev-docs/admin 目录中
• 移动端前端 UniApp（移动端）文档存放 dev-docs/uniapp 目录中
• PC 端 Nuxt（PC）文档存放 dev-docs/nuxt 目录中

3. 内容要求

3.1 结构清晰

• 引言：文档目的、适用范围
• 主体：详细内容，逻辑连贯
• 结论：总结、后续计划
• 附录：参考资料、术语表

3.2 语言要求

• 使用简洁、准确的语言
• 避免歧义，术语统一
• 中文文档使用规范汉字
• 英文文档语法正确

3.3 内容完整性

• 包含必要的背景信息
• 步骤清晰，可操作
• 提供示例和截图
• 注明版本和更新日期

3.4 可维护性

• 定期更新，保持时效性
• 使用版本控制管理文档
• 注明作者和联系方式
• 便于搜索和导航

4. 文档工具

4.1 编辑工具

• 推荐使用 Markdown 格式
• 支持工具：VS Code、Typora、语雀
• 图片存储：项目内部或图床

4.2 版本管理

• 与代码一同纳入 Git 管理
• 提交信息清晰，说明文档变更
• 定期备份，防止丢失

5. 审核与发布

5.1 审核流程

1. 编写完成后进行自我检查
2. 提交给相关人员审核
3. 根据反馈修改完善
4. 最终确认发布

5.2 发布规范

• 发布前检查格式和内容
• 明确文档版本号
• 通知相关人员文档更新
• 确保文档可访问

6. Markdown 文档模板

# 文档标题

## 1. 引言

### 1.1 文档目的
- 说明文档的编写目的

### 1.2 适用范围
- 说明文档的适用范围

### 1.3 术语定义
- 解释文档中使用的专业术语

## 2. 主体内容

### 2.1 功能描述
- 详细描述功能特性

### 2.2 实现方案
- 说明技术实现方案

### 2.3 代码示例

```php
// 代码示例
function example() {
    return true;
}

2.4 操作步骤

1. 第一步操作
2. 第二步操作
3. 第三步操作

3. 结论

3.1 总结

• 总结文档的主要内容

3.2 后续计划

• 说明后续的工作计划

4. 附录

4.1 参考资料

• 列出参考的文档和资源

4.2 联系方式

• 提供联系人信息

版本: 1.0 作者: 文档作者 更新日期: YYYY-MM-DD

## 7. Markdown 语法指南

### 7.1 标题

```markdown
# 一级标题
## 二级标题
### 三级标题
#### 四级标题

7.2 列表

• 无序列表项 1
• 无序列表项 2
  • 嵌套列表项

1. 有序列表项 1
2. 有序列表项 2

7.3 链接和图片

• 链接文本
• 

7.4 代码块

// JavaScript 代码
console.log('Hello World');

7.5 表格

7.6 引用

这是一段引用文本

8. 注意事项

• 避免冗长，重点突出
• 保持格式统一
• 定期更新文档
• 确保内容准确无误
• 便于他人理解和使用
• 生成文档最后说明由AI生成

以上规范适用于 CRMEB 项目所有文档写作，确保文档质量和一致性。