快速入门
本演练描述 PiePLM 目标中的首次使用体验。由于项目仍处于设计阶段,下面的数据结构展示的是模型和目标 API,尚不是可以执行的指令。
演练的目标是说明各模块如何配合。一个新团队应当能够创建一个产品、附加文档、定义简单 BOM、提交变更,并通过 API 读取结果。
开始之前
你需要:
- 一个运行中的 PiePLM 实例(见安装)
- 一个管理员账号
- 一个要建模的产品,最好来自你们团队的真实业务
- 一份图纸或规范文件
- 一份 BOM,即使目前还是电子表格
不要一上来就导入整个产品目录。先选一个信息当前最容易造成混乱的产品。
1. 创建组织与用户
第一个账号是初始管理员。它应当创建:
- 组织:拥有数据的法律或运营实体
- 业务单元:负责该产品的团队
- 用户与角色:至少包括工程师、评审人和管理员
角色决定谁可以创建、编辑、评审和批准。初始角色保持精简:admin、engineer、reviewer、viewer。
2. 创建产品
产品是稳定的身份。它有编码、名称、描述、生命周期状态和负责人。它不直接保存版本相关数据,版本负责这些内容。
目标数据结构:
{
"code": "PUMP-100",
"name": "冷却泵",
"description": "用于紧凑型冷水机组的 12V 离心泵",
"lifecycleState": "development",
"owner": "engineering.team"
}产品编码应当沿用组织现有的标识方式。PiePLM 不应强迫企业采用新的编号体系。
3. 创建版本 A
版本是产品定义的一次快照。第一个版本通常是 A 或 1。它记录:
- 版本标识
- 生效日期或生效规则
- 关联的设计文档
- 构成产品的 BOM 行
- 审批状态
创建版本应当是一个显式动作,而不是编辑文档时偷偷产生的副作用。
4. 附加文档
上传图纸、规范和测试报告。每个附件记录:
- 文件名、媒体类型、大小和校验和
- 所属版本
- 上传人和上传时间
- 可选的文档类型(图纸、规范、测试报告、证书)
文件可以放在本地磁盘或对象存储。数据库保存元数据和引用,不保存二进制本身。
5. 定义简单 BOM
BOM 是树形结构。每一行引用一个零件或另一个产品,并带数量、单位和可选的位置号。第一版保持浅层结构即可:
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。一个代表性请求:
GET /api/v1/products/PUMP-100/revisions/A/bom
Authorization: Bearer <token>使用 MCP 的 Agent 会调用等价的工具,例如 bom_get,参数为产品编码和版本。Agent 凭证默认只读。
8. 验证历史
这次演练的重点不是录入数据,而是历史:
- 哪个版本是当前版本?
- 哪个变更产生了它,谁批准的?
- 旧版本包含哪些文档?
- 哪些供应商零件受到变更影响?
如果系统无法在不召开会议的情况下回答这些问题,说明模型或工作流还不完整。
一个现实的首个里程碑
不要在第一周就尝试所有模块。合理的首个里程碑是:
- 一个产品,两个版本
- 三份关联文档
- 一份十行的 BOM
- 一个已批准的变更单
- 一个 API 客户端(哪怕是 shell 脚本)能读取当前版本
这个里程碑验证了数据模型和工作流。其余能力可以逐步增加。