API 接口文档 ​

本文档描述 xt-pms（小微模具制造与注塑企业生产管理系统）后端 HTTP 接口的整体结构、模块划分与各端点的用途。其目的在于为前端对接、第三方集成与测试提供统一的接口索引。

数据来源与约定

• 接口定义来自 server/internal/router/* 的路由注册，服务基于 Gin 框架，所有业务接口挂载在根路径 /api 之下（另有少量根路径公开端点，见对应章节）。
• 路由中的路径参数使用 Gin 语法（如 :id、orderId），调用时替换为实际值。
• 大部分接口需要 JWT 认证（请求头 Authorization: Bearer <token>）；少数公开接口（登录、验证码、字典版本、系统信息、外发公开报工、健康检查）无需认证，已在各章节标注。
• 接口访问同时受菜单权限控制（middleware.RequirePerm / RequireAnyPerm）；写操作通常同时接受对应 :list 权限，便于"列表页内联提交"。权限码形如 mold:mold:list，详见各章节。

通用约定 ​

• Base URL：http://<host>:<port>/api
• 认证：除特别标注为「公开」的接口外，均需在请求头携带 Authorization: Bearer <token>。
• 路径参数：以 :param 形式出现（如 /mold/:id 中的 :id）。
• 请求体：写操作（POST/PUT）一般接收 application/json 主体。
• 权限：端点说明中的「权限」列给出该接口依赖的权限码（以 system:user:list 这类格式表示，部分写操作以 RequireAnyPerm 同时放行 :list 权限）。

系统 / 认证 (system) ​

系统模块包含登录认证、用户/角色/部门/菜单管理、字典与配置、通知、操作日志、收款账户、系统更新等。路由组前缀 /system。

公开接口（无需 JWT）：

需认证接口：

基础资料 (basic) ​

基础资料模块管理客户、仓库、工序、供应商、加工商等主数据。路由组前缀 /basic。列表/写操作权限统一为对应 :list 权限。

模具管理 (mold) ​

模具模块覆盖模具档案、模具订单、模具工单、工单工序、试模、交付、库存、图片、产品关联、订单款项与工序模板。路由组前缀 /mold，另有独立的 /mold-product-relation、/mold-order、/process-template 子组。

模具档案 / 订单 / 工单 ​

试模 / 交付 / 库存 / 图片 ​

模具产品关联 / 订单款项 / 工序模板 ​

产品管理 (product) ​

产品模块管理产品档案、产品 BOM 与产品库存。路由组前缀 /product；库存相关接口复用 production:stock:list 权限。

生产管理 (production) ​

生产模块覆盖生产订单全生命周期、生产报工、外发加工、模具使用记录、库存出入库、外来模具档案等。路由组前缀 /production。

生产订单 ​

生产报工 / 外发 / 模具使用 / 统计 ​

库存 / 出入库 / 外来模具 ​

综合订单 (master order) ​

综合订单将模具订单与生产订单合并管理，实现"先制模具、后做产品"的一体化流程。路由组前缀 /master-orders，权限统一为 order-management:list。

财务管理 (finance) ​

财务模块管理应收账款、应付账款与费用。路由组前缀 /finance。

应收账款 ​

应付账款 / 费用 ​

数据看板 (dashboard) ​

数据看板提供经营概览与各类统计图表数据。路由组前缀 /dashboard；基础看板需 dashboard:base，财务/明细类需 dashboard:detail。

公共引用数据 (reference) ​

公共引用数据接口用于各页面下拉/选择器数据，仅需 JWT 认证（无额外菜单权限），以避免跨模块 403。路由组前缀 /reference。

文件上传 (upload) ​

文件上传接口不单独设权限，由前端页面权限间接控制。上传组前缀 /upload；文件下载接口挂载在根路径 /files（非 /api）。

公开 / 实时接口 (public) ​

以下接口允许免登录或无需业务菜单权限访问，供外部加工商报工、健康检查、实时通知等场景使用。

其他说明 ​

1. 权限模型：接口通过 middleware.RequirePerm(perm) 或 RequireAnyPerm([]string{...}) 校验菜单权限。写操作大多以 RequireAnyPerm 同时放行 :create/:update/:delete 与 :list，即拥有列表权限的用户通常也能在列表页内联提交写操作。
2. 路径参数：Gin 框架以 : 声明路径参数（如 /mold/:id），实际请求需替换为具体值（如 /mold/12）。
3. 外发公开链路：/api/public/outsourcing/:token/* 供加工商免登录使用，token 由 POST /production/outsourcing/:id/share-token 生成，可经 regenerate-token 重新生成。
4. 响应格式：接口统一返回 JSON；具体响应体结构以代码中 controller/handler 实现为准（本文档聚焦路由与用途，未逐接口罗列请求/响应字段）。
5. 字典与引用数据：前端通常先调用 /reference/* 或 /system/dict-data 拉取下拉选项，再提交业务表单；字典取值与中文标签详见《术语对照表》。