SunYF
f35e9b5b75
- 更新MES和WMS服务端口配置说明 - 详细说明产线工位设备配置（扫码枪+拧紧枪） - 明确AGV配送和接驳台的模拟模式与真实对接方案 - 更新WMS中AGV配送默认模拟模式说明 - 完善厂内物流（AGV/接驳台）的业务架构约束 - 修订临时文档为详细的项目问题和解决方案规划
59 lines
4.3 KiB
Markdown
59 lines
4.3 KiB
Markdown
# 技术约束与编码规范
|
||
|
||
本文件收录本项目（bj_power 装配线统一仓库）必须遵守的技术约束与编码约定。其余历史文档均已清理。
|
||
|
||
## 全局规则
|
||
|
||
- **禁止自动提交 git**：所有 commit/push 必须等用户明确要求后才执行。
|
||
- **单一 Git 仓库**：MES / Dashboard / WMS / WMS客户端 / 工位终端 统一为 `bj_power` 一个仓库；各子项目内部命名（Go module、package.json、import 路径、配置文件名）必须与其文件夹名对齐。
|
||
|
||
## 命名规范
|
||
|
||
- **驼峰命名（camelCase）**：接口参数、默认、字段、前端 JSON 均采用 camelCase；Go 结构体字段为 PascalCase，json tag 用 camelCase。
|
||
- 常量、枚举等大写开头，用户可读中文文案单独维护。
|
||
|
||
## 代码分层
|
||
|
||
- **handler 保持薄层**，业务逻辑写在 logic 层，不在 handler 里写业务。
|
||
- **不手动修改生成代码**：`ent/`、`internal/handler/`、`internal/types/` 为 goctl/ent 自动生成。改 schema 走 `cd schema && go generate`，改 api 走 `cd apis && go generate`。
|
||
- 简单优先：用最少代码解决问题；不为单次使用创建抽象；不写不可能出现的错误处理。
|
||
- 精准改动：只改必须改的部分，不改没坏的东西，风格匹配现有代码。
|
||
|
||
## 安全与配置
|
||
|
||
- **敏感信息一律写入 YAML 配置文件**，不硬编码进代码：JWT Secret、内部 API Token、数据库口令等。
|
||
- **统一内部 API 密钥**：`Hardman_2026`（内部服务间鉴权，请求头 `X-API-TOKEN`）。
|
||
- **鉴权约定**：JWT AccessSecret 统一 `Hardman_2026`，access 短有效（1800s）并支持滑动续签；业务前端接口走 `/api/v1` 用 JWT 鉴权；项目间服务调用一律走 `/api/internal/*`，请求头必须带 `X-API-TOKEN=Hardman_2026`。
|
||
|
||
## 技术栈
|
||
|
||
- **后端**：Go + go-zero（REST 框架）+ Ent ORM + PostgreSQL。
|
||
- **前端（MES / WMS客户端 / 工位终端）**：Vue3（Semi Design / Element Plus）。
|
||
- **看板（Dashboard）**：React + Semi Design + ECharts。
|
||
- **实时通信**：Dashboard 通过 Redis + SSE 从 MES 取数据，1 分钟过期 + 防击穿。
|
||
|
||
## 端口与服务约定
|
||
|
||
| 项目 | 端口 | 说明 |
|
||
|------|------|------|
|
||
| bj_power_mes | 8888 | MES（Go+内嵌 Vue3 前端，go:embed public/） |
|
||
| bj_power_wms | 8890 | WMS（Go+内嵌 Vue3 前端，go:embed web/static/；2026-09-07 吸收原 8891 库房客户端） |
|
||
| bj_power_workstation | 8892 | 工位终端（内嵌 Vue3+SQLite） |
|
||
| bj_power_dashboard | dev 5173 / 生产静态 dist | 看板 React |
|
||
|
||
依赖：PostgreSQL（127.0.0.1:5432）、Redis（127.0.0.1:6379）。前端构建产物内嵌到对应 Go 服务的 public/ 或 web/static/；看板独立部署静态 dist 或 nginx 托管。
|
||
|
||
## 业务架构约束
|
||
|
||
- **产线仅为装配线**：工位设备只有「扫码枪 + 拧紧枪」，其余为人工操作；不存在 CNC、清洗机、检验设备、内窥镜、机器人等加工设备。
|
||
- **厂内物流（AGV / 接驳台）**：接驳台是 AGV 点位（DOCK01~20 产线 / DOCK21 库房，共 21 个），属 **WMS 侧只读主数据**（不可新增/修改，仅查看，与实际接驳台一一对应）；PLC 仅反馈「接驳台上是否有托盘」的到位信号，不控制其动作。AGV 配送由 WMS「AGV 配送」页管理，**当前为模拟模式（mock）、待现场对接真实海康 RCS**（协议见《AGV海康.md》；对接时在 WMS 配置关闭 `Agv.EnableMock` 并填写 `BaseURL/AppKey/AppSecret` 即切换真实调度）。MES 工位页与看板不含 AGV / 接驳台控制。
|
||
- **数据库隔离**：MES 与 WMS 使用各自独立数据库，跨系统通过内部 API 通信。
|
||
- **工位终端**：拧紧数据用 SQLite 本地缓存，完成后上报 MES（两段式：点「完成」才上报，失败本地保留重试/断点续传）。
|
||
- **半成品流转**：工位「暂存/退回库房」时记录已完成工序，MES 调 WMS 半成品入库/出库，重上线从下一工序继续。
|
||
- **日志**：按天存储（如 `bj_power_mes-2026-08-28.log`），保留 30 天。
|
||
- **操作日志可追溯**：`event_log` 必须含 `workOrderNo`、`operator` 字段。
|
||
|
||
## 数据库
|
||
|
||
- MES 库名 `bj_power_mes`、WMS 库名 `bj_power_wms`（两库独立，以各项目 etc/*.yaml 配置为准）。
|
||
- 建表工具（如 migrate.go）的 DSN 从 YAML 读取，不硬编码。 |