Builder6 Docs Module

Builder6 Docs 模块是一个完整的文档管理和在线编辑系统，集成了 OnlyOffice 编辑器、实时协作、文档版本管理和权限控制等功能。该模块为 Builder6 平台提供企业级的文档管理解决方案。

功能特性

• 文档管理: 完整的文档生命周期管理（创建、编辑、删除、归档）
• OnlyOffice 集成: 支持 Word、Excel、PowerPoint 在线编辑
• 实时协作: 多用户同时编辑同一文档，实时同步变更
• 版本控制: 自动保存文档版本，支持版本比较和恢复
• 权限管理: 细粒度的文档访问和编辑权限控制
• 水印保护: 可配置的文档水印，保护文档安全
• 文档预览: 支持多种格式的文档在线预览
• 全文搜索: 快速搜索文档内容
• 审批流程: 支持文档审批工作流
• 评论和标注: 文档评论、批注和审阅功能

安装

npm install @builder6/docs

或

yarn add @builder6/docs

环境变量

OnlyOffice 配置

# 启用 OnlyOffice 插件
B6_ONLYOFFICE_ENABLED=true

# OnlyOffice JWT 密钥
B6_ONLYOFFICE_JWT_SECRET=your-secret-key

# 启用默认编辑水印
B6_ONLYOFFICE_WATERMARK_ENABLED=true

# 水印文本
B6_ONLYOFFICE_WATERMARK_TEXT=Confidential

# OnlyOffice Document Server URL
B6_ONLYOFFICE_URL=https://onlyoffice.steedos.cn

文档存储配置

# 文档存储路径
B6_DOCS_STORAGE_PATH=/app/storage/docs

# 最大文件大小（MB）
B6_DOCS_MAX_FILE_SIZE=100

# 启用文档版本控制
B6_DOCS_VERSION_ENABLED=true

# 保留版本数量
B6_DOCS_VERSION_KEEP_COUNT=10

数据库配置

# MongoDB 连接字符串
B6_MONGO_URL=mongodb://127.0.0.1:27017/steedos

# Redis 连接（用于会话和缓存）
B6_REDIS_URL=redis://127.0.0.1:6379

服务配置

# 服务端口
B6_PORT=5100

# 服务地址
B6_HOST=http://127.0.0.1:5100

# Session 密钥
B6_SESSION_SECRET=your-session-secret

使用示例

在 NestJS 应用中集成

import { Module } from '@nestjs/common';
import { DocsModule } from '@builder6/docs';

@Module({
  imports: [DocsModule],
})
export class AppModule {}

创建文档

import { DocsService } from '@builder6/docs';

constructor(private docsService: DocsService) {}

async createDocument(userId: string, data: any) {
  const doc = await this.docsService.create({
    title: 'New Document',
    type: 'docx',
    owner: userId,
    content: '',
    metadata: {
      project: 'Project A',
      department: 'Engineering'
    }
  });
  return doc;
}

打开文档编辑器

async openEditor(docId: string, userId: string) {
  const editorConfig = await this.docsService.getEditorConfig(docId, userId, {
    mode: 'edit',
    permissions: {
      edit: true,
      download: true,
      print: true,
      review: true,
      comment: true
    }
  });
  return editorConfig;
}

保存文档版本

async saveVersion(docId: string, userId: string, comment: string) {
  const version = await this.docsService.createVersion(docId, {
    savedBy: userId,
    comment,
    timestamp: new Date()
  });
  return version;
}

获取文档历史

async getHistory(docId: string) {
  const versions = await this.docsService.getVersions(docId);
  return versions;
}

恢复文档版本

async restoreVersion(docId: string, versionId: string) {
  await this.docsService.restoreVersion(docId, versionId);
}

API 端点

文档管理

• POST /api/v6/docs: 创建新文档
• GET /api/v6/docs: 列出文档
• GET /api/v6/docs/:id: 获取文档详情
• PUT /api/v6/docs/:id: 更新文档信息
• DELETE /api/v6/docs/:id: 删除文档

文档编辑

• GET /api/v6/docs/:id/editor: 获取编辑器配置
• POST /api/v6/docs/:id/callback: OnlyOffice 回调处理
• GET /api/v6/docs/:id/download: 下载文档

版本管理

• GET /api/v6/docs/:id/versions: 获取版本列表
• POST /api/v6/docs/:id/versions: 创建新版本
• GET /api/v6/docs/:id/versions/:versionId: 获取特定版本
• POST /api/v6/docs/:id/versions/:versionId/restore: 恢复版本

权限管理

• GET /api/v6/docs/:id/permissions: 获取文档权限
• PUT /api/v6/docs/:id/permissions: 更新文档权限
• POST /api/v6/docs/:id/share: 分享文档

文档权限

权限级别

• Owner: 文档所有者，拥有全部权限
• Editor: 编辑者，可以编辑和评论
• Reviewer: 审阅者，可以查看和评论
• Viewer: 查看者，只能查看

权限配置

const permissions = {
  owner: userId,
  editors: ['user1', 'user2'],
  reviewers: ['user3', 'user4'],
  viewers: ['user5', 'user6'],
  public: false, // 是否公开
  allowDownload: true,
  allowPrint: true,
  allowCopy: true
};

await this.docsService.setPermissions(docId, permissions);

文档协作

实时协作编辑

多用户可以同时编辑同一文档，所有更改实时同步：

const config = {
  coEditing: {
    mode: 'fast', // 快速模式或严格模式
    change: true
  },
  user: {
    id: userId,
    name: userName,
    group: teamId
  }
};

文档评论

// 添加评论
await this.docsService.addComment(docId, {
  userId,
  text: '这段需要修改',
  position: { line: 10, column: 5 },
  timestamp: new Date()
});

// 获取评论
const comments = await this.docsService.getComments(docId);

文档水印

启用水印保护文档：

B6_ONLYOFFICE_WATERMARK_ENABLED=true
B6_ONLYOFFICE_WATERMARK_TEXT=Confidential

水印配置选项：

const watermark = {
  enabled: true,
  text: 'Confidential - Internal Use Only',
  diagonal: true,
  opacity: 0.3,
  color: '#D3D3D3',
  fontSize: 24
};

文档模板

创建模板

await this.docsService.createTemplate({
  title: 'Meeting Minutes Template',
  type: 'docx',
  content: templateContent,
  category: 'meetings'
});

从模板创建文档

const doc = await this.docsService.createFromTemplate(templateId, {
  title: 'Q1 Meeting Minutes',
  metadata: {
    date: '2024-01-15',
    attendees: ['user1', 'user2']
  }
});

前端集成

React 组件示例

import React, { useEffect } from 'react';

const DocumentEditor = ({ docId, userId }) => {
  useEffect(() => {
    fetch(`/api/v6/docs/${docId}/editor?userId=${userId}`)
      .then(res => res.json())
      .then(config => {
        new DocsAPI.DocEditor("editor-container", config);
      });
  }, [docId, userId]);

  return <div id="editor-container" style={{ height: '100vh' }} />;
};

使用场景

• 企业文档管理: 集中管理企业文档，支持权限控制
• 团队协作: 多人实时协作编辑文档
• 文档审批: 支持文档审批工作流程
• 知识库: 构建企业知识库和文档中心
• 合同管理: 管理合同文档，支持版本追踪
• 项目文档: 项目相关文档的集中管理

依赖项

主要依赖

• @builder6/docs-client: ^3.0.4-beta.8 - 文档管理客户端
• aws-sdk: ^2.1692.0 - AWS S3 存储支持
• cookie-parser: ^1.4.7 - Cookie 解析
• dataloader: ^2.2.3 - 数据加载优化
• ejs: ^3.1.10 - 模板引擎
• express-session: ^1.18.2 - 会话管理
• ioredis: ^5.8.2 - Redis 客户端
• moment: ^2.30.1 - 日期处理

Peer Dependencies

• @builder6/core: ^3.0.10 - 核心功能模块
• @builder6/files: ^3.0.10 - 文件管理模块
• @builder6/moleculer: ^3.0.10 - 微服务框架
• @builder6/oidc: ^3.0.10 - OIDC 认证
• @builder6/onlyoffice: ^3.0.10 - OnlyOffice 集成
• @nestjs/common: ^11.0.0 - NestJS 核心
• @nestjs/config: ^4.0.1 - 配置管理
• @nestjs/core: ^11.0.0 - NestJS 核心
• @nestjs/jwt: ^11.0.0 - JWT 认证
• @nestjs/platform-express: ^11.0.0 - Express 平台
• @nestjs/serve-static: ^5.0.3 - 静态文件服务
• @nestjs/swagger: ^11.0.7 - API 文档

开发

构建

npm run build

开发模式

npm run start:dev

生产模式

npm run start:prod

测试

npm run test

格式化代码

npm run format

代码检查

npm run lint

参考资源

• OnlyOffice API 文档
• OnlyOffice Document Server
• Builder6 文档

License

MIT