Skip to content

快速入门 ​

本演练描述 PiePLM 目标中的首次使用体验。由于项目仍处于设计阶段,下面的数据结构展示的是模型和目标 API,尚不是可以执行的指令。

演练的目标是说明各模块如何配合。一个新团队应当能够创建一个产品、附加文档、定义简单 BOM、提交变更,并通过 API 读取结果。

开始之前 ​

你需要:

  • 一个运行中的 PiePLM 实例(见安装)
  • 一个管理员账号
  • 一个要建模的产品,最好来自你们团队的真实业务
  • 一份图纸或规范文件
  • 一份 BOM,即使目前还是电子表格

不要一上来就导入整个产品目录。先选一个信息当前最容易造成混乱的产品。

1. 创建组织与用户 ​

第一个账号是初始管理员。它应当创建:

  • 组织:拥有数据的法律或运营实体
  • 业务单元:负责该产品的团队
  • 用户与角色:至少包括工程师、评审人和管理员

角色决定谁可以创建、编辑、评审和批准。初始角色保持精简:admin、engineer、reviewer、viewer。

2. 创建产品 ​

产品是稳定的身份。它有编码、名称、描述、生命周期状态和负责人。它不直接保存版本相关数据,版本负责这些内容。

目标数据结构:

json
{
  "code": "PUMP-100",
  "name": "冷却泵",
  "description": "用于紧凑型冷水机组的 12V 离心泵",
  "lifecycleState": "development",
  "owner": "engineering.team"
}

产品编码应当沿用组织现有的标识方式。PiePLM 不应强迫企业采用新的编号体系。

3. 创建版本 A ​

版本是产品定义的一次快照。第一个版本通常是 A 或 1。它记录:

  • 版本标识
  • 生效日期或生效规则
  • 关联的设计文档
  • 构成产品的 BOM 行
  • 审批状态

创建版本应当是一个显式动作,而不是编辑文档时偷偷产生的副作用。

4. 附加文档 ​

上传图纸、规范和测试报告。每个附件记录:

  • 文件名、媒体类型、大小和校验和
  • 所属版本
  • 上传人和上传时间
  • 可选的文档类型(图纸、规范、测试报告、证书)

文件可以放在本地磁盘或对象存储。数据库保存元数据和引用,不保存二进制本身。

5. 定义简单 BOM ​

BOM 是树形结构。每一行引用一个零件或另一个产品,并带数量、单位和可选的位置号。第一版保持浅层结构即可:

text
PUMP-100 rev A
├── HOUSING-01        数量 1
├── IMPELLER-02       数量 1
├── SEAL-03           数量 2
└── MOTOR-12V-04      数量 1

关键属性是:每一行都有身份和版本上下文。BOM 行不是电子表格里可以随意编辑、没有历史的单元格。

6. 提交变更 ​

假设密封材料需要更换。团队创建变更单:

  • 改什么:将 SEAL-03 替换为 SEAL-03B
  • 为什么:提高对冷却液添加剂的耐受性
  • 影响:影响版本 A 和维修包
  • 审批:工程负责人和质量经理

变更单经过评审和批准后,生成版本 B。旧版本仍然可读,变更与新版本之间的关系是显式的。

7. 通过 API 读取 ​

目标读模型是有文档的 REST API。一个代表性请求:

http
GET /api/v1/products/PUMP-100/revisions/A/bom
Authorization: Bearer <token>

使用 MCP 的 Agent 会调用等价的工具,例如 bom_get,参数为产品编码和版本。Agent 凭证默认只读。

8. 验证历史 ​

这次演练的重点不是录入数据,而是历史:

  • 哪个版本是当前版本?
  • 哪个变更产生了它,谁批准的?
  • 旧版本包含哪些文档?
  • 哪些供应商零件受到变更影响?

如果系统无法在不召开会议的情况下回答这些问题,说明模型或工作流还不完整。

一个现实的首个里程碑 ​

不要在第一周就尝试所有模块。合理的首个里程碑是:

  1. 一个产品,两个版本
  2. 三份关联文档
  3. 一份十行的 BOM
  4. 一个已批准的变更单
  5. 一个 API 客户端(哪怕是 shell 脚本)能读取当前版本

这个里程碑验证了数据模型和工作流。其余能力可以逐步增加。

下一步 ​

Released under the MIT License. Privacy Policy