Учебное пособие по самостоятельно разработанной архитектуре WeDoctor "EasyDoc"

Что такое ИзиДок

• ЧТО: EasyDoc — это易配置的降本提效的项目文档系统
• ЗАЧЕМ:
  • Сокращение сложных проектов上手难度, чтобы улучшить взаимодействие с пользователем
  • Сгладить новый и старый состав проектной команды信息差
  • Перенести носитель бизнес-деталей проекта из开发者Изменять文档工具
• Как: через процесс用户引导,обработать操作手册,страница说明文档,项目说明Документы,关键点注解
• Статус: EasyDoc был инкубирован в группе Wedoctor более года, имеет доступ к более чем в десятке онлайн-приложений и всесторонне продвигается в группе. В то же время открытый источник продвижения в сообщество,希望能给社区带来一点新鲜的血液, с нетерпением ждем вашего использования и доступа, если у вас есть какие-либо вопросы, оставьте комментарий или дайте нам свое мнение о github.
• Типичные сценарии: фон управления, сложная форма, сложная процедура, комплексное взаимодействие
• Неудобные сцены: проекты на большом экране, игровые проекты 🤣🤣

Демонстрация использования видео EasyDoc

Демонстрационное видео EasyDoc Bilibili

Учебник EasyDoc

1. Установите зависимости

npm i we-easydoc --save

2. Параметры инициализации

// 使用默认参数
import EasyDoc from 'we-easydoc'
import 'we-easydoc/lib/index.css'

EasyDoc.init()

// 自定义参数
EasyDoc.init({
  urlPrefix: "/easy-doc",
  easyDocPath: "/public/easy-doc/EasyDoc.json",
  easyManualsPath: "/public/easy-doc/Manuals.json",
  easyProjectsPath: "/public/easy-doc/Projects.json",
});

• Параметры функции easydoc.init

параметр	Типы	Необходимый	По умолчанию	иллюстрировать
easyDocPath	string	нет	'/easy-doc/EasyDoc.json'
easyManualsPath	string	нет	'/easy-doc/Manuals.json'
easyProjectsPath	string	нет	'/easy-doc/Projects.json'
minHeight	number	нет	100	Минимальная высота всплывающего окна узла документа
minWidth	number	нет	200	Минимальная ширина всплывающего окна узла документа
maxWidth	number	нет	450	Максимальная ширина всплывающего окна узла документа
editHeight	number	нет		Фиксированная высота всплывающего окна редактируемого узла
editWidth	number	нет		Фиксированная ширина всплывающего окна редактируемого узла
urlPrefix	string	нет		Статический префикс пути к ресурсу, автоматически добавляемый на фронт запросов EASYDOC.
env	(() => AuthEnum) | string	нет	'DEVELOPMENT'	Текущий документ отображается в диапазоне «РАЗРАБОТКА» > «ТЕСТ» > «ПРОИЗВОДСТВО».
showGuideMask	boolean	нет	false	Когда дисплей узла, следует ли отобразить полупрозрачный уровень маски ниже
mountPanel	boolean	нет	true	Монтировать ли верхнюю правую панель
ignorePaths	string[]	нет	[]	Путь страницы не включает массив easydoc
hasEasyDocJSON	boolean	нет	true	Запрашивать ли файл Easydoc.json
hasManualsJSON	boolean	нет	true	Запрашивать ли файл Manuals.json
hasProjectsJSON	boolean	нет	true	запрашивать ли файл Projects.json
EasyDocDocumentUrl	string | boolean	нет	'Самородки. К / post / 703832 ...'

• • «тест» или «ТЕСТ» означает производственную среду, тестовую среду см. все документы
  • «pro» или «PRODUCTION» означает, что все документы видны в производственной среде.

// 可以指定权限 dev > test > pro
EasyDoc.init({
  env: 'pro', // dev | test | pro
})
// 可以传入函数计算求值
EasyDoc.init({
  env: () => {
    switch (process.env.NODE_ENV) {
      case 'production':
        return 'pro'
      case 'test':
        return 'test'
      case 'development':
        return 'dev'
      default:
        return 'pro'
    }
  },
})
// 可以根据域名后缀判断
EasyDoc.init({
  env: () => {
    if (window.location.href.indexOf('.guahao.cn') > -1) {
      return 'pro'
    }
    if (window.location.href.indexOf('.guahao-test.com') > -1) {
      return 'test'
    }
    return 'dev'
  },
})

3. Написать проектную документацию

Документ проекта представляет собой введение ко всему проекту, примечания по вопросам, требующим внимания, и т. д. Он автоматически появляется при первом открытии проекта и больше не появляется после этого. Очистка кеша браузера сделает его недействительным. ; вы также можете просмотреть его, щелкнув документ проекта в правом верхнем углу.

• public/easy-doc/Projects.json (статическая папка также может быть статической, а не общедоступной)
• имя: имя документа проекта
• описание: содержание проектного документа
• Может писать обычный текст или вставлять html, особенно переходить по ссылке
• auth: область видимости документа проекта
• Можно написать несколько документов проекта, если документа проекта нет, пропустите этот шаг.

[
  {
    "name": "Diting最佳实践",
    "description": "Diting最佳实践的详细介绍Diting最佳实践的详细介绍Diting最佳实践的详细介绍Diting最佳实践的详细介绍Diting最佳实践的详细介绍",
    "auth": "pro"
  },
  {
    "name": "Gtrace-最佳实践",
    "description": "Gtrace-最佳实践的详细介绍Gtrace-最佳实践的详细介绍Gtrace-最佳实践的详细介绍Gtrace-最佳实践的详细介绍Gtrace-最佳实践的详细介绍",
    "auth": "pro"
  },
  {
    "name": "Kano最佳实践",
    "description": "Kano最佳实践的详细介绍Kano最佳实践的详细介绍Kano最佳实践的详细介绍Kano最佳实践的详细介绍Kano最佳实践的详细介绍Kano最佳实践的详细介绍",
    "auth": "pro"
  },
  {
    "name": "MQ最佳实践",
    "description": "MQ最佳实践的详细介绍MQ最佳实践的详细介绍MQ最佳实践的详细介绍MQ最佳实践的详细介绍MQ最佳实践的详细介绍MQ最佳实践的详细介绍",
    "auth": "pro"
  },
  {
    "name": "配置中心gconfig 最佳实践",
    "description": "配置中心gconfig 最佳实践的详细介绍配置中心gconfig 最佳实践的详细介绍配置中心gconfig 最佳实践的详细介绍配置中心gconfig 最佳实践的详细介绍配置中心gconfig 最佳实践的详细介绍",
    "auth": "pro"
  }
]

4. Напишите документацию страницы

Страничный документ — это введение к странице и примечание о мерах предосторожности. Укажите отношение сопоставления между страницей и файлом json с помощью Easydoc.json, а затем запишите его в файл json.

• public/easy-doc/Easydoc.json
• match: регулярное выражение, соответствующее маршруту
• jsonFile: соответствующий путь к файлу json.

[
  {
    "match": "/user/list",
    "jsonFile": "/public/easy-doc/user3.json"
  },
  {
    "match": "/dept/list/[0-9]+",
    "jsonFile": "/public/easy-doc/dept.json"
  },
  {
    "match": "/handle-doc.html",
    "jsonFile": "/public/easy-doc/handle-doc.json"
  },
]

• public/easy-doc/user3.json
• имя: имя описания страницы
• description: содержание описания страницы
• Auth: Страница объясняет видимый диапазон

{
  "pages": [
    {
      "name": "第一个user页面介绍",
      "description": "这是一段内容",
      "auth": "dev"
    },
    {
      "name": "第一个user页面介绍",
      "description": "这是又一段内容",
      "auth": "test"
    }
  ],
}

5. Напишите документацию по узлу страницы

Документ узла страницы представляет собой введение в узел на странице и примечания по мерам предосторожности. Укажите отношение сопоставления между страницей и файлом json с помощью Easydoc.json, затем запишите документ в файл json и добавьте docId в узел dom страницы, чтобы реализовать сопоставление.

• public/easy-doc/Easydoc.json
• match: регулярное выражение, соответствующее маршруту
• jsonFile: соответствующий путь к файлу json.

[
  {
    "match": "/user/list",
    "jsonFile": "/public/easy-doc/user3.json"
  },
  {
    "match": "/dept/list/[0-9]+",
    "jsonFile": "/public/easy-doc/dept.json"
  },
  {
    "match": "/handle-doc.html",
    "jsonFile": "/public/easy-doc/handle-doc.json"
  },
]

• public/easy-doc/user3.json
• имя: имя описания страницы
• description: содержание описания страницы
• auth: видимая область описания страницы
• направление: ориентация всплывающего окна узла, не требуется
• zIndex: укажите zIndex для предотвращения окклюзии, не требуется

{
  "docs": [
    {
      "docId": "dept-list",
      "description": "当切换为运行状态时当切换为运行状态时当切换为运行状态时",
      "auth": "pro",
      "direction": "LT",
      "zIndex": 100
    },
    {
      "docId": "dept-btn",
      "description": "方方速递速速递速速递速递对，个按按钮方速递对，一个按按钮方速递对，",
      "auth": "dev",
      "direction": "BR"
    }
  ],
}

• / Пользователь / файлы списка соответствующие Vue

<div>
  <div docId='dept-list'>
    user list 页面 html
  <div>
    <el-button docId='dept-btn'>
    user list 页面 的 btn
  <div>
</div>

6. Напишите редактируемую документацию по узлу

可编辑节点文档用于前台系统展示，后面系统编辑前台展示内容的场景。在此场景中将前台某块内容和后台对该内容的编辑页面连接起来，点击直接跳转过去进行配置，方便产品运营的使用。 Укажите отношение сопоставления между страницей и файлом json с помощью Easydoc.json, затем запишите документ в файл json и добавьте docId в узел dom страницы, чтобы реализовать сопоставление.

• public/easy-doc/Easydoc.json
• match: регулярное выражение, соответствующее маршруту
• jsonFile: соответствующий путь к файлу json.

[
  {
    "match": "/user/list",
    "jsonFile": "/public/easy-doc/user3.json"
  },
  {
    "match": "/dept/list/[0-9]+",
    "jsonFile": "/public/easy-doc/dept.json"
  },
  {
    "match": "/handle-doc.html",
    "jsonFile": "/public/easy-doc/handle-doc.json"
  },
]

• public/easy-doc/user3.json
• имя: имя описания страницы
• description: содержание описания страницы
• auth: видимая область описания страницы
• направление: ориентация всплывающего окна узла, не требуется
• zIndex: укажите zIndex для предотвращения окклюзии, не требуется

{
  "edits": [
    {
      "docId": "dept-list",
      "editUrl": "https://fanyi.baidu.com/translate?aldtype=16047&keyfrom=baidu&smartresult=dict&lang=auto2zh#ru/zh/EasyDoc",
      "auth": "dev",
      "direction": "TL",
      "zIndex": 200
    },
    {
      "docId": "dept-btn",
      "editUrl": "https://fanyi.baidu.com/translate?aldtype=16047&keyfrom=baidu&smartresult=dict&lang=auto2zh#ru/zh/EasyDoc",
      "auth": "test",
      "direction": "LB"
    }
  ],
}

• / Пользователь / файлы списка соответствующие Vue

<div>
  <div docId='dept-list'>
    user list 页面 html
  <div>
    <el-button docId='dept-btn'>
    user list 页面 的 btn
  <div>
</div>

7. Напишите инструкцию по эксплуатации

Руководство по эксплуатации представляет собой динамическое руководство по эксплуатации, работающее в режиме реального времени. Нажмите, чтобы автоматически перейти на первую страницу, соответствующую руководству по эксплуатации. Следуйте инструкциям, чтобы практиковаться шаг за шагом, чтобы новичок мог лучше изучить использование системы и понять скрытую бизнес-информацию за функцией.

• public/easy-doc/Manuals.json
• Примечание. Указав type=link, linkManualName=имя руководства по эксплуатации, можно перейти от одного руководства по эксплуатации к другому руководству по эксплуатации.
• Вы можете добавить ссылку в описание шага, чтобы добиться перехода по внешней ссылке
• Не забудьте добавить docId в шаге к dom соответствующей страницы.

[
   {
    "name": "操作手册A",
    "description": "这是关于操作手册A的描述<a href='http://wcp.gops.guahao.cn/frontend-refactor/home/page'>去WCP</a>",
    "initUrl": "/dept/list", // 打开操作手册的时候会跳到此初始url
    "steps": [
      {
        "url": "/dept/list",
        "description": "操作手册A第一步有两个按钮高亮",
        "nodes": [
          {
            "docId": "dept-open-btn1",
            "description": "操作手册A第一步节点1",
            "auth": "pro",
            "zIndex": 1000 // 指定zIndex防止遮挡，非必填
          },
          {
            "docId": "dept-open-btn2",
            "description": "操作手册A第一步节点2",
            "auth": "pro"
          }
        ]
      },
      ..steps // 多个步骤此处省略
      
  {
    "name": "操作手册B",
    "description": "这是关于操作手册B的描述",
    "initUrl": "/user/list", // 打开操作手册的时候会跳到此初始url
    "steps": [
      {
        "url": "/user/list",
        "description": "操作手册B第一步有两个按钮高亮",
        "nodes": [
          {
            "docId": "dept-open-btn2",
            "description": "操作手册A第一步节点2",
            "auth": "pro"
          }
        ]
      },
       {
        "description": "点击从操作手册B直接跳到操作手册A",
        "type": "link",
        "linkManualName": "操作手册A"
      }
    ]
]

8. Напишите руководство пользователя

• EasyDoc.initGuide(guide: GuideNode) Инициализировать данные руководства пользователя
• EasyDoc.startGuide() запускает текущее руководство пользователя.
• EasyDoc.jumpGuideStep(stepIdx: число, guideStep?: GuideStep) Перейти к первому шагу текущего руководства пользователя, считая от 0, второй переданный параметр означает замену содержимого текущего шага
• EasyDoc.closeGuide() Активно закрывает текущее руководство по эксплуатации.

  // 初始化用户引导数据
  EasyDoc.initGuide({
    'name': '用户引导A',
    'steps': [
      {
        'url': '/dept/list',
        'node': {
          'docId': 'guide1',
          'description': '用户引导<br />A第一步节点1',
          'auth': 'pro'
        }
      },
      {
        'url': '/dept/list',
        'node': {
          'docId': 'guide2',
          'description': '用户引导A第一步节点2',
          'auth': 'pro'
        }
      },
      {
        'url': '/dept/list',
        'node': {
          'docId': 'guide3',
          'description': '用户引导A第一步节点3',
          'auth': 'pro'
        }
      },
      {
        'url': '/dept/list',
        'node': {
          'docId': 'guide4',
          'description': '用户引导A第一步节点4',
          'auth': 'pro'
        }
      },
      {
        'url': '/dept/list',
        'node': {
          'docId': 'guide5',
          'description': '用户引导A第一步节点5',
          'auth': 'pro'
        }
      },
      {
        'url': '/dept/list',
        'node': {
          'docId': 'guide6',
          'description': '用户引导A第一步节点6',
          'auth': 'pro'
        }
      },
    ]
  })
  // 开始当前用户引导
  EasyDoc.startGuide()
  // 4秒后跳到用户引导第4步，并修改第4步内容，并不显示下一步按钮
  setTimeout(() => {
    EasyDoc.jumpGuideStep(3, {
      'url': '/dept/list',
      'node': {
        'docId': 'guide4',
        'description': '手动修改内容',
        'auth': 'pro'
      },
      next: false,//是否显示下一步按钮
    },)
  }, 4000)
  // 再3秒后关闭当前用户引导
  setTimeout(() => {
    EasyDoc.closeGuide()
  }, 7000)

Использование расширения EasyDoc

1. Несколько совместимых способов написания docId

• docId, doc-id, docid, data-docId, data-doc-id, data-docid могут совпадать
• docId не может начинаться с цифры
• Несколько docId могут быть записаны на узле dom, разделенные пробелами.
• Один docId также может соответствовать нескольким узлам dom текущей страницы. Установите noUnique=true. По умолчанию страница соответствует только одному узлу dom.

<div docId="user-list-query user-list-search"></div>
<div docId="user-btn user-list-query"></div>

{
  "docs": [
    {
      "docId": "user-btn-query",
      "description": "点击查询用户列表",
      "auth": "dev",
      "direction": "BL",
      "noUnique": true //单个docId也可以匹配当前页面的多个dom节点
    }
  ]
}

2. Описание направления всплывающего окна

• Направление является необязательным атрибутом, адаптивным положением по умолчанию, пользователь может указать ориентацию для настройки эффекта отображения.
• ТЛ вверху слева
• TR вверх вправо
• В ТК
• РТ вверху справа
• РБ внизу справа
• RC справа посередине
• БЛ внизу слева
• BR внизу справа
• БК Нижний Средний
• LT вверху слева
• ЛБ внизу слева
• LC слева

3. Префикс пути

• Некоторые системы настроят префикс URL, например сайтwww.baidu.comСоответствующий адрес файла Json:Когда он настроен таким образом, что префиксный путь доступа к рефакторингу внешнего интерфейса в

  EasyDoc.init({
    urlPrefix: "/frontend-refactor",
    easyDocPath: "/public/easy-doc/EasyDoc.json",
    easyManualsPath: "/public/easy-doc/Manuals.json",
    easyProjectsPath: "/public/easy-doc/Projects.json",
  });

let urlPrefix = ``
let easyDocPath = `/public/easy-doc/EasyDoc.json`
let easyManualsPath = `/public/easy-doc/Manuals.json`
let easyProjectsPath = `/public/easy-doc/Projects.json`
// 线上
if (location.origin === 'http://xxxxx') {
  urlPrefix = `/frontend-refactor`
  easyDocPath = `http://xxxxx/frontend-refactor/public/easy-doc/EasyDoc.json`
  easyManualsPath = `http://xxxxx/frontend-refactor/public/easy-doc/Manuals.json`
  easyProjectsPath = `http://xxxxx/frontend-refactor/public/easy-doc/Projects.json`
}
EasyDoc.init({
  urlPrefix,
  easyDocPath,
  easyManualsPath,
  easyProjectsPath
})

• По умолчанию мы будем запрашивать файлы public/easy-doc/EasyDoc.json, Manuals.json, Projects.json, но в проекте пока может быть не настроен документ, поэтому сеть сообщит 404, что файл не может быть быть найденным.
• Эта проблема не влияет на бизнес, но бизнес-сторона всегда подозревает, что существует проблема с Easydoc, когда видит ошибку 404 Easydoc при поиске бизнес-ошибок, поэтому она оптимизируется.

EasyDoc.init({
  hasEasyDocJSON: false, //默认true, 设为false则不请求该json
  hasManualsJSON: false, //默认true, 设为false则不请求该json
  hasProjectsJSON: false, //默认true, 设为false则不请求该json
});

5. CHANGLOG.md

В этом файле вы можете увидеть введение контента и соответствующую версию каждого обновления, а также понять историческое развитие EasyDoc.

другое: другие вопросы

По другим вопросам, пожалуйста, свяжитесь с разработчиком, чтобы ответить онлайн.

• Ли Юнтонг😜😜
• Ян Ичжэнь
• Хунин
• 😉😉
• Цюань Минъян😘😘
• Хуан Дандань🤞🤞

дальнейшее чтение

• Самостоятельно разработанная WeDoctor архитектура «EasyDoc» имеет открытый исходный код!
• Шаблоны проектирования, которые вы должны знать о версии ts
• Вы должны знать методологию анализа больших заводских проблем.
• Лучшие практики рефакторинга кода на больших фабриках. Вы действительно знаете, как рефакторить код?
• Нужно ли разбираться в тонкостях исходного кода фреймворка?
• [Анализ исходного кода Vue3] тщательно опубликовать исходный код начинается

Адрес гитхаба EasyDoc

点赞✨✨Заказать звезду🤞🤞（づ￣3￣）づ╭❤～