GWMS文档中心

中文

English

中文

English

Appearance

GWMS 内容维护指南 ​

1. 文档维护概述 ​

本指南为 GWMS (Generic Warehouse Management System) 文档的内容贡献者和维护者提供了一套标准和流程。遵循本指南将确保文档内容保持高质量、一致性，并且能够有效地支持用户和 AI 智能体的使用。

GWMS 文档采用客户和仓库两层的组织架构，所有功能都在这两层下进行划分。以产品模块为例：产品信息管理、SKU创建等功能归类到客户层；而SKU审核、产品上架等功能归类到仓库层。客户和仓库通过这种明确的职责划分，共同完成产品从创建到上架的全生命周期管理。客户和仓库共用一套系统，通过权限控制区分不同角色的操作范围，确保业务流程的连贯性和数据的一致性。

1.1 目标读者 ​

本指南主要面向以下角色：

  • 内容编写者和编辑者
  • 技术文档维护人员
  • 产品经理和业务分析师
  • 开发者和技术支持人员

1.2 文档维护的重要性 ​

  • 知识传递：确保系统知识准确、完整地传递给用户
  • 用户支持：提供清晰的操作指南，减少用户困惑和支持成本
  • AI 智能体支持：为 AI 智能体提供结构化的知识源，支持智能问答和自动化操作
  • 系统迭代：记录系统变更，确保文档与系统功能同步更新

2. 文档模板使用指南 ​

2.1 模板概述 ​

GWMS 文档项目提供了一套标准化的文档模板，确保所有文档都遵循统一的格式和结构，提高文档的一致性和可维护性。这些模板特别针对 RAG（Retrieval-Augmented Generation）优化，便于 AI 模型理解和检索。

重要规则：所有新文档必须使用相应的模板创建，不得使用自定义格式。

2.2 模板类型 ​

功能文档模板 ​

  • 文件位置：meta/templates/function-document-template.md
  • 适用场景：系统功能操作指南、功能说明文档
  • 主要结构：
    • 功能概述
    • 前置条件
    • 操作步骤
    • 结果说明
    • 常见问题
    • 注意事项
    • 相关功能
    • 版本历史

FAQ 文档模板 ​

  • 文件位置：meta/templates/faq-document-template.md
  • 适用场景：常见问题解答、故障排除指南
  • 主要结构：
    • 问题描述
    • 问题原因
    • 解决方案
    • 预防措施
    • 相关功能
    • 常见误区
    • 版本历史

索引文档模板 ​

  • 文件位置：meta/templates/index-document-template.md
  • 适用场景：功能模块索引、角色导航、流程索引
  • 主要结构：
    • 索引概述
    • 文档分类（按功能、角色、流程）
    • 快速导航
    • 相关资源
    • 版本历史

2.3 Front Matter 填写指南 ​

所有模板都包含标准化的 front matter，必须正确填写以下字段：

必填字段 ​

  • title：文档标题，应简洁明了地反映文档内容
  • description：文档描述，简要说明文档的目的和内容
  • category：文档分类，如"入库管理"、"出库管理"、"常见问题"等
  • role：目标角色，如"客户"、"仓库"、"管理员"等
  • keywords：关键词数组，提供 3-5 个相关关键词，便于检索
  • author：作者姓名
  • created：创建日期，格式为 YYYY-MM-DD
  • updated：更新日期，格式为 YYYY-MM-DD
  • version：文档版本，从 1.0 开始

可选字段 ​

  • related：相关文档数组，列出与此文档相关的其他文档

2.4 模板使用流程 ​

步骤 1：选择合适的模板 ​

根据文档类型选择对应的模板：

  • 功能操作指南 → 功能文档模板
  • 问题解答 → FAQ 文档模板
  • 文档索引 → 索引文档模板

步骤 2：复制模板文件 ​

  1. 复制相应的模板文件到目标目录
  2. 重命名文件，遵循文件命名规范
  3. 删除模板中的示例内容，保留结构

步骤 3：填写 Front Matter ​

  1. 更新所有必填字段
  2. 确保关键词准确反映文档内容
  3. 添加相关文档引用

步骤 4：撰写文档内容 ​

  1. 按照模板结构撰写内容
  2. 保持标题层级的一致性
  3. 使用交叉引用链接相关文档

步骤 5：添加文档标签和交叉引用 ​

  1. 在文档末尾添加相应的标签
  2. 使用 [[文档名称]] 格式添加交叉引用
  3. 确保所有链接有效

2.5 模板使用示例 ​

功能文档示例 ​

markdown
---
title: "新增出库单"
description: "指导用户如何创建新的出库单"
category: "出库管理"
role: "客户"
keywords: ["出库单", "订单处理", "发货"]
related: ["审核出库单", "取消出库单"]
author: "张三"
created: "2025-01-15"
updated: "2025-01-20"
version: "1.1"
---

FAQ 文档示例 ​

markdown
---
title: "出库单审核失败"
description: "解答出库单审核失败的常见原因和解决方法"
category: "常见问题"
role: "客户"
keywords: ["审核失败", "出库单", "错误处理"]
related: ["新增出库单", "审核出库单"]
author: "李四"
created: "2025-01-10"
updated: "2025-01-18"
version: "1.2"
---

2.6 RAG 友好最佳实践 ​

内容结构化 ​

  • 使用清晰的标题层级
  • 每个章节聚焦一个主题
  • 使用列表和表格提高可读性
  • 保持段落简短精炼

元数据优化 ​

  • 提供准确的关键词
  • 确保描述字段包含核心信息
  • 使用标准化的分类和角色标识
  • 维护准确的版本和日期信息

交叉引用 ​

  • 使用统一的引用格式 [[文档名称]]
  • 确保引用文档存在且链接有效
  • 避免循环引用
  • 提供有意义的引用说明

标签系统 ​

  • 使用标准化的标签格式 #标签名
  • 保持标签简洁明了
  • 避免过多标签
  • 使用相关的分类标签

3. 文档编写规范 ​

2.1 格式标准 ​

Markdown 规范 ​

  • 使用标准 Markdown 语法编写文档
  • 标题层级清晰，避免跨级使用（如从 # 直接跳到 ###）
  • 列表使用统一的格式（有序列表使用 1.，无序列表使用 -）
  • 代码块使用语言标识（如 javascript、bash）

文件命名规范 ​

  • 使用小写字母、数字和连字符
  • 避免使用空格和特殊字符
  • 文件名应反映内容主题，例如 新增出库单.md

目录结构 ​

文档根目录/
├── docs/              # GWMS 系统文档
├── meta/              # 文档项目元信息
├── customer/          # 客户端功能文档
│   ├── basic/         # 基础资料（含产品/SKU管理）
│   ├── inbound/       # 入库管理
│   ├── inventory/     # 库存管理
│   ├── outbound/      # 出库管理
│   ├── bizCharge/     # 业务计费
│   └── quote/         # 报价管理
├── warehouse/         # 仓库端功能文档
│   ├── basic/         # 基础资料（含SKU审核）
│   ├── inbound/       # 入库管理
│   ├── inventory/     # 库存管理
│   ├── outbound/      # 出库管理
│   ├── bizCharge/     # 业务计费
│   └── quote/         # 报价管理
├── en/                # 英文文档
└── images/            # 共享图片资源

注：文档结构采用客户和仓库两层的组织方式。以产品模块为例：产品信息管理、SKU创建等功能归类到客户层；而SKU审核、产品上架等功能归类到仓库层。客户和仓库通过这种明确的职责划分，共同完成产品从创建到上架的全生命周期管理。

2.2 内容风格 ​

语言风格 ​

  • 使用简洁、明确的语言
  • 避免使用行话和模糊表达
  • 使用第二人称（"您"）直接与读者交流
  • 关键术语在首次出现时应加粗，例如 出库单

结构化写作 ​

  • 每个文档应有清晰的结构：概述、主要步骤、补充信息
  • 使用标题和子标题组织内容
  • 重要信息和步骤应突出显示
  • 使用列表、表格等形式提高可读性
  • 明确区分客户和仓库角色的操作范围和权限
  • 在涉及相关功能模块时，明确说明客户和仓库的功能职责划分。例如，产品信息管理、SKU创建等功能由客户负责；而SKU审核、产品上架等功能由仓库负责。

2.3 图片处理 ​

图片规范 ​

  • 所有图片应存放在功能点目录下的 images 子目录中
  • 使用相对路径引用图片，并提供有意义的 alt 文本
  • 格式: ![描述性文字](./images/image_name.jpg)

图片要求 ​

  • 图片应清晰、高对比度
  • 重要区域应有标注或高亮
  • 截图应包含完整的上下文，但避免无关信息
  • 图片尺寸应适中，确保在文档中显示清晰

图片优化 ​

  • 使用适当的格式（PNG 适合界面截图，JPG 适合照片）
  • 压缩图片以提高加载速度
  • 对于复杂流程，可考虑使用多张图片或动画

3. 内容更新流程 ​

3.1 新功能文档创建 ​

重要规则：创建任何系统功能文档前，必须先使用 playwright 打开浏览器操作 GWMS 系统收集真实数据和界面信息，不得基于推测或假想创建文档内容。

模板使用要求：所有新文档必须使用相应的标准模板创建，模板位于 meta/templates/ 目录下。

步骤 1: 功能分析和系统操作 ​

  • 确定功能的范围和目标用户
  • 必须使用 playwright 打开浏览器操作 GWMS 系统
  • 通过 browser_navigate 导航到相关功能页面
  • 使用 browser_snapshot 获取页面可访问性快照
  • 使用 browser_take_screenshot 截取界面截图
  • 分析功能的核心流程和关键点
  • 识别可能的用户问题和解决方案

步骤 2: 真实数据收集 ​

  • 强制要求：通过 playwright 打开浏览器实际操作 GWMS 系统
  • 使用 browser_click、browser_type 等工具执行完整操作流程
  • 记录每个操作步骤的界面变化和系统反馈
  • 收集真实的界面元素、按钮文本、提示信息
  • 获取准确的操作路径和导航结构
  • 记录可能出现的错误信息和异常情况

步骤 3: 基于真实数据的内容撰写 ​

  • 基于 playwright 打开浏览器收集的真实数据创建文档框架
  • 使用相应的标准模板创建文档（meta/templates/ 目录下的功能文档模板、FAQ文档模板或索引文档模板）
  • 撰写准确的操作步骤和说明（基于实际操作记录）
  • 添加真实截图和辅助说明（来自系统实际操作）
  • 确保所有界面描述与实际系统一致
  • 检查内容的完整性和准确性
  • 按照模板要求填写 front matter 和添加交叉引用

步骤 4: 质量审核 ​

  • 验证文档内容与实际系统功能完全一致
  • 确认所有截图来自真实系统操作
  • 请同事或相关人员审核
  • 根据反馈进行修改和完善

3.2 现有文档更新 ​

更新触发条件 ​

  • 系统功能变更
  • 用户反馈问题
  • 发现文档错误或不完整
  • 定期审查和优化

更新流程 ​

  1. 识别需要更新的文档
  2. 收集更新信息
  3. 修改文档内容
  4. 更新相关截图
  5. 提交审核和发布

3.3 AI 智能体驱动的内容维护 ​

AI 智能体角色和强制要求 ​

  • 强制规则： AI 智能体（如 Roo）必须通过 playwright 打开浏览器 与 GWMS 系统交互后才能创建或更新文档
  • 禁止推测： 严禁基于推测、假想或经验创建文档内容
  • 必须捕获真实的系统操作流程和界面变化
  • 生成基于实际操作的文档内容

强制性自动化流程 ​

  1. 第一步（强制）： AI 智能体必须通过 playwright 打开浏览器 操作 GWMS 系统
  2. 第二步（强制）： 收集真实的操作数据和界面信息
  3. 第三步： 基于真实数据分析并生成文档内容
  4. 第四步： 提交人工审核和确认

操作验证要求 ​

  • 系统访问验证： 必须成功连接并访问 GWMS 系统
  • 功能操作验证： 必须完成完整的功能操作流程
  • 数据真实性验证： 确保所有文档内容来自真实系统操作
  • 截图真实性验证： 确保所有截图来自实际系统界面

人机协作 ​

  • AI 智能体负责真实数据收集和基于真实数据的初稿生成
  • 人工负责内容审核、优化和最终确认
  • 建立反馈机制，持续改进 AI 智能体的文档生成能力

4. 内容更新流程时序图 ​

以下是GWMS文档内容更新流程的Mermaid时序图，展示了各角色之间的交互和主要流程步骤：

时序图说明 ​

1. 新功能文档创建流程 ​

  • 功能分析阶段：产品经理和业务分析师向内容编写者提供功能需求分析
  • 真实数据收集阶段：AI智能体(Roo)通过playwright操作GWMS系统收集真实数据和界面截图
  • 内容撰写阶段：内容编写者基于真实数据和截图撰写文档内容
  • 质量审核阶段：文档经过审核人员质量审核后，由技术文档维护人员发布

2. 现有文档更新流程 ​

  • 识别更新需求阶段：开发者和技术支持人员、产品经理和业务分析师提供系统变更和功能更新需求
  • 收集更新信息阶段：技术文档维护人员通过AI智能体收集更新后的系统数据和界面
  • 修改内容和更新截图阶段：技术文档维护人员修改文档内容并更新相关截图
  • 审核发布阶段：更新内容经过审核后发布

3. AI智能体驱动的内容维护流程 ​

  • 系统操作阶段：AI智能体(Roo)直接与GWMS系统交互，执行完整的系统操作流程
  • 数据收集阶段：AI智能体收集真实数据并基于数据生成文档内容
  • 内容生成阶段：AI智能体生成文档初稿，由内容编写者进行优化和调整
  • 人工审核阶段：文档经过人工审核后由技术文档维护人员发布

关键步骤强调 ​

  • 真实数据收集：所有文档内容必须基于AI智能体通过playwright操作GWMS系统收集的真实数据和界面信息
  • 系统操作验证：AI智能体必须完成完整的功能操作流程，确保文档内容与实际系统一致
  • 人机协作：AI智能体负责数据收集和初稿生成，人工负责内容优化和最终审核
  • 质量保证：所有文档必须经过严格的质量审核流程，确保准确性和完整性

5. AI 智能体使用指南 ​

4.1 @playwright/mcp 服务器 ​

服务器简介 ​

  • @playwright/mcp 是一个提供浏览器自动化能力的 MCP 服务器
  • AI 智能体通过调用该服务器的工具来操作 GWMS 系统
  • 支持页面导航、元素交互、截图等操作

GWMS 系统访问信息 ​

重要：以下是进行文档创建时必需的GWMS系统访问信息

系统访问地址 ​
测试账号信息 ​

管理员账号：

  • 用户名：[admin]
  • 密码：[jmalltech@2025]
  • 权限：系统管理员，拥有所有功能访问权限

客户账号：

  • 用户名：[wangwu]
  • 密码：[123456]
  • 权限：客户端功能，包括产品管理、入库管理、出库管理等

仓库账号：

  • 用户名：[richard]
  • 密码：[123456]
  • 权限：仓库端功能，包括收货、上架、拣货、出库等

注意事项：

  • 使用测试账号进行文档创建时，请勿在生产环境进行操作
  • 确保测试数据不会影响实际业务运行
  • 定期更新测试账号密码，确保安全性

服务器启动 ​

bash
# 启动服务器
npx @playwright/mcp@latest

# 使用特定参数启动
npx @playwright/mcp@latest --host 0.0.0.0 --viewport-size "1920,1080"

常用工具 ​

  • browser_navigate: 导航到指定 URL
  • browser_snapshot: 获取页面可访问性快照
  • browser_click: 点击页面元素
  • browser_type: 在输入框中输入文本
  • browser_take_screenshot: 截取页面截图

4.2 AI 智能体文档生成流程 ​

自动化文档生成 ​

  1. AI 智能体接收文档生成任务
  2. 使用正确的测试账号登录 GWMS 系统
  3. 使用 playwright 打开浏览器操作 GWMS 系统
  4. 通过 browser_snapshot 获取页面结构
  5. 分析操作流程和界面元素
  6. 捕获真实的界面截图和操作步骤
  7. 使用相应的标准模板生成文档（功能文档模板、FAQ文档模板或索引文档模板）
  8. 生成基于真实数据的结构化 Markdown 文档
  9. 添加真实截图和准确的说明文字
  10. 按照模板要求填写 front matter 和添加交叉引用

内容优化策略 ​

  • 使用清晰的标题和子标题组织内容
  • 确保操作步骤的顺序性和完整性
  • 添加常见问题和解决方案
  • 使用适当的格式和样式提高可读性

4.3 AI 智能体辅助内容审核 ​

自动化检查 ​

  • 检查文档格式是否符合规范
  • 验证链接和图片引用是否有效
  • 识别可能的内容缺失或不一致
  • 检查术语使用的一致性

辅助优化建议 ​

  • 提供内容结构调整建议
  • 识别可能的改进点
  • 建议补充相关内容
  • 推荐优化的表达方式

5. 质量控制标准 ​

5.1 内容质量标准 ​

准确性 ​

  • 确保文档内容与系统功能一致
  • 操作步骤准确无误
  • 术语使用正确且一致
  • 截图与当前系统界面匹配

完整性 ​

  • 覆盖功能的所有主要操作流程
  • 包含必要的背景和上下文信息
  • 提供常见问题和解决方案
  • 链接到相关文档和资源

清晰性 ​

  • 使用简洁、明确的语言
  • 结构清晰，逻辑连贯
  • 重点内容突出显示
  • 复杂概念适当解释

5.2 格式质量标准 ​

文档结构 ​

  • 遵循统一的文档模板
  • 标题层级正确且一致
  • 列表、表格格式规范
  • 代码块语法高亮正确
  • 确保文档结构符合客户和仓库两层的组织方式
  • 相关功能模块应正确区分客户和仓库的功能职责。例如，产品信息管理、SKU创建等功能归类到客户层；而SKU审核、产品上架等功能归类到仓库层。

图片和媒体 ​

  • 图片清晰、裁剪适当
  • 包含必要的标注和说明
  • 图片文件大小合理
  • 替代文本描述准确

链接和引用 ​

  • 内部链接指向正确的位置
  • 外部链接有效且相关
  • 引用格式统一
  • 避免断链和无效引用

5.3 质量检查流程 ​

自查清单 ​

  • [ ] 内容是否准确反映系统功能
  • [ ] 操作步骤是否清晰完整
  • [ ] 术语使用是否一致
  • [ ] 格式是否符合规范
  • [ ] 图片是否清晰且相关
  • [ ] 链接是否有效
  • [ ] 是否包含必要的前置条件
  • [ ] 是否涵盖常见问题和解决方案
  • [ ] 文档结构是否符合客户和仓库两层的组织方式
  • [ ] 相关功能模块是否正确区分客户和仓库的功能职责（如产品信息管理、SKU创建等功能由客户负责；SKU审核、产品上架等功能由仓库负责）
  • [ ] 是否明确区分客户和仓库角色的操作范围和权限

同行评审 ​

  • 由具备相关领域知识的同事进行评审
  • 重点关注内容的准确性和完整性
  • 检查文档是否满足目标用户需求
  • 提供具体的改进建议

用户反馈 ​

  • 收集用户使用文档的反馈
  • 关注用户常见问题和困惑点
  • 根据反馈优化文档内容
  • 建立持续改进机制

6. 版本管理策略 ​

6.1 文档版本控制 ​

Git 工作流 ​

  • 使用 Git 进行文档版本管理
  • 采用分支策略管理不同版本的文档
  • 使用 Pull Request 进行代码审查
  • 使用语义化版本号标记重要更新

分支策略 ​

  • main: 主分支，包含最新稳定的文档版本
  • develop: 开发分支，用于日常文档更新
  • feature/*: 功能分支，用于开发新功能文档
  • release/*: 发布分支，用于准备版本发布

提交规范 ​

  • 提交信息清晰描述变更内容
  • 使用统一的提交信息格式
  • 关联相关的问题或任务编号
  • 避免在一次提交中包含多个不相关的变更

6.2 文档版本与系统版本同步 ​

版本对应关系 ​

  • 明确文档版本与系统版本的对应关系
  • 系统重大更新时，文档应同步更新
  • 维护版本变更日志
  • 为不同系统版本提供相应的文档版本

版本兼容性处理 ​

  • 标注文档适用的系统版本范围
  • 对于不兼容的变更，提供明确的迁移指南
  • 保留旧版本文档，直至不再需要支持
  • 在适当位置提供版本差异说明

6.3 变更管理 ​

变更记录 ​

  • 维护详细的变更日志
  • 记录每次更新的内容、时间和责任人
  • 标记重要变更和新增功能
  • 提供变更摘要，方便用户快速了解更新内容

变更通知 ​

  • 重要文档更新后通知相关方
  • 提供变更摘要和影响范围
  • 指导用户如何适应这些变更
  • 收集用户对变更的反馈

7. 贡献指南 ​

7.1 如何贡献 ​

贡献方式 ​

  • 报告文档问题或错误
  • 提交文档改进建议
  • 撰写新功能文档
  • 翻译现有文档到其他语言
  • 优化文档结构和格式

贡献流程 ​

  1. Fork 项目仓库
  2. 创建新的功能分支
  3. 进行文档修改或添加
  4. 提交变更并创建 Pull Request
  5. 等待审核和反馈
  6. 根据反馈进行必要的修改
  7. 合并到主分支

7.2 贡献者准则 ​

内容准则 ​

  • 确保内容准确、完整且最新
  • 遵循文档编写规范和风格指南
  • 使用简洁、明确的语言
  • 避免个人观点和主观评价

协作准则 ​

  • 尊重其他贡献者的工作
  • 提供建设性的反馈和建议
  • 及时响应审核意见
  • 解决冲突并寻求共识

7.3 社区支持 ​

沟通渠道 ​

  • 使用 Issue 跟踪问题和建议
  • 通过 Pull Request 讨论具体变更
  • 参与定期文档审查会议
  • 加入相关讨论组或论坛

资源和支持 ​

  • 查阅本文档和其他相关指南
  • 寻求资深贡献者的指导
  • 参与文档编写培训和工作坊
  • 使用模板和工具提高贡献效率

8. 附录 ​

8.1 常用工具和资源 ​

GWMS系统访问清单 ​

在创建或更新文档前，请确认以下信息：

  • [ ] 获得GWMS系统访问地址
  • [ ] 获得相应角色的测试账号和密码
  • [ ] 等待用户输入验证码
  • [ ] 确认测试环境可正常访问
  • [ ] 验证账号权限覆盖需要文档化的功能
  • [ ] 准备好@playwright/mcp服务器环境

文档编写工具 ​

  • Markdown 编辑器推荐
  • 截图工具推荐
  • 图表和流程图工具
  • 版本控制工具

参考资料 ​

  • Markdown 语法指南
  • 文档编写最佳实践
  • 技术文档设计原则
  • 可访问性标准

8.2 术语表 ​

系统术语 ​

  • GWMS: Generic Warehouse Management System，通用仓库管理系统
  • RAG: Retrieval-Augmented Generation，检索增强生成
  • MCP: Model Context Protocol，模型上下文协议

文档术语 ​

  • 原子化内容：将知识拆分为最小独立片段
  • 结构化内容：使用标题、列表等元素组织的信息
  • 可访问性快照：描述页面交互元素的结构化数据
  • 客户和仓库两层架构：GWMS文档的组织方式，所有功能都在客户和仓库两层下进行划分
  • 功能职责划分：客户负责产品信息管理、SKU创建等功能；仓库负责SKU审核、产品上架等功能

8.3 常见问题 ​

文档维护相关 ​

  • 如何处理系统频繁更新的文档同步问题？
  • 如何确保多语言文档的一致性？
  • 如何平衡文档的详细程度和易用性？
  • 如何评估文档质量和用户满意度？
  • 如何确保文档结构符合客户和仓库两层的组织方式？
  • 相关功能模块应如何正确区分客户和仓库的功能职责？

技术实现相关 ​

  • 如何配置 @playwright/mcp 服务器以适应不同环境？
  • 如何自定义 AI 智能体的文档生成模板？
  • 如何处理复杂的操作流程和分支逻辑？
  • 如何优化文档的检索和索引效率？