bj_power/项目现状说明.md

北京电力 WMS 项目 · 现状说明（供重新规划）

生成时间：2026-09-03 用途：作为「重新规划」的输入材料，供其他 AI 直接阅读并制定方案 核实方式：全部内容来自实际代码读取（非记忆/推测），关键结论已标注代码位置

---

一、系统全景

根仓库 D:\hardman\bj_power 下共有 5 个子系统：

子系统	端口	技术	职责	备注
bj_power_wms	8890	Go + go-zero + ent	WMS 后端（全部业务逻辑 + PostgreSQL）	核心系统
bj_power_wms_client	8891	Go（仅 config/proxy）	库房客户端：静态托管 + /api 反向代理	无业务逻辑，转发到 8890
bj_power_mes	—	Go + ent + frontend	MES 系统（工单、BOM、台账来源）	独立服务
bj_power_workstation	—	Go + frontend + SQLite	工位终端	独立 DB
bj_power_dashboard	—	Vue3 + TS + Vite	大屏展示（独立构建产物 dist）	免登录

关键架构事实（已核实）：

• bj_power_wms_client（8891）不是纯前端壳，它是一个 Go 服务，但 internal/ 下只有 config 和 proxy 两个包，无 handler、无 ent。
• 其配置 etc/bj_power_wms_client.yaml 明确：WmsAddr: http://127.0.0.1:8890，请求转发时注入 X-API-TOKEN: Hardman_2026。
• 因此：前端页面（8891）看到的 /api/* 实际全部由 8890 的 WMS 后端处理。
• 前端源码在 bj_power_wms_client/frontend/，构建产物输出到 bj_power_wms_client/web/static。
• bj_power_wms（8890）不含 go:embed，不内嵌前端，前端由 8891 单独提供。

结论：用户口中的「wms 和 wms 客户端」= 8890（业务后端）+ 8891（客户端壳）。所有功能/权限改造实际上都落在 8890。

---

二、技术栈

后端（bj_power_wms）

• Go + go-zero（rest 路由）+ ent ORM
• PostgreSQL（bj_power_wms，账号 postgres/postgres）
• JWT 鉴权，Header：Authorization: Bearer {token}
• 统一响应包裹 {code, message, data}，业务数据一律在 data 层
• ent 代码生成：go run -tags entgenerate ./tools（build tag entgenerate，入口 tools/generate.go）

前端（bj_power_wms_client/frontend）

• Vue3（<script setup>）+ Element Plus + Vite
• Axios 封装 src/utils/request.js：baseURL: '/api'，响应拦截器统一拆 data、统一错误提示、401 跳登录
• 路由：src/router/index.js（history 模式）
• 布局/菜单：src/layouts/MainLayout.vue
• 页面：src/pages/（14 个 .vue）
• 页内帮助：每个页面挂 <PageHelp>，文案集中在 src/help.js

运行约定

• 服务端口 8890（后端）/ 8891（客户端）；登录 admin / 123456
• 前端重建套路（避 Windows EPERM）： mv web/static web/static_bak_<时间戳> → mkdir web/static → npm run build → rm -rf web/static_bak_*
• 注意：8890 与 8891 不能同时被两个实例占用；换调试方式前需先结束旧进程。

---

三、数据模型（ent schema，共 13 张业务表）

bj_power_wms/schema/ 下 14 个文件（mixin.go 仅提供 nowUnix()，非共享 mixin）。 所有表的 created_at 均为 Int64 unix 秒时间戳（不是 time.Time），多数表另有 updated_at。

入库域

• inbound_order（入库单·主表）：inbound_no(唯一) inbound_type(purchase/semi/finished/return) material_code material_name manage_mode(1批次/2SN) batch_no zone_code quantity operator remark created_at
• inbound_detail（入库明细·子表）：inbound_no sn_code batch_no material_code quantity created_at
  • 结构件：一批一条（batch_no）；精密件：每个 SN 一条明细（可能上万条）

出库域

• outbound_order（出库单·统一主表）：outbound_no outbound_type(workorder 备料 / general 通用) order_no material_code material_name manage_mode batch_no zone_code quantity operator reviewer target_dock remark box_no box_sn_list contract_no（装箱信息） created_at
• outbound_detail（出库明细·子表）：outbound_no sn_code batch_no material_code quantity order_no created_at

库存域

• inventory（统一库存表）：manage_mode material_code material_name batch_no sn_code quantity locked_qty quality_status zone_code status production_date supplier inbound_no remark created_at updated_at
  • 结构件：按批次一条记录；精密件：每个 SN 一条记录
• inventory_lock（库存锁定）：target_type target_id material_code locked_qty order_no status expired_at remark created_at updated_at

基础数据

• material（物料档案）：code(唯一) name short_name spec unit description manage_mode is_batch_managed is_serial_managed template_code created_at updated_at
• zone（区域）：zone_code zone_name description status created_at updated_at
• user（用户）：username password(bcrypt) real_name role dept phone is_active last_login_at created_at updated_at

业务扩展

• inspection_record（检验记录）：target_type target_id material_code inspection_type status result_value inspector remark created_at updated_at
• order_material_ledger（工单物料台账）：order_no material_code material_name total_qty out_qty status remark created_at updated_at
• semi_finished（半成品/成品）：sn material_code completed_process quantity zone_code status order_no created_at updated_at
• stocktake（盘点，stocktake.go 内含「盘点单 + 盘点明细」两个 schema）：盘点单 stocktake_no status operator total_targets created_at finished_at；盘点明细 target_type target_id material_code zone_code book_qty scanned_qty diff_qty counted updated_at

---

四、后端 API 全清单（来自 internal/handler/routes.go）

模块	接口
健康/登录	GET /api/health、POST /api/auth/login
用户	POST /user/change-password、GET /user/info、GET /user/list、POST /user/create、POST /user/update、POST /user/delete
物料	POST /material/create、POST /material/update、GET /material/query、GET /material/list、GET /material/detail
入库	POST /inbound/create、GET /inbound/query、GET /inbound/details（明细分页，新增）、GET /inbound/export、POST /inbound/batch-excel
出库	POST /outbound/create（备料）、POST /outbound/general（通用）、GET /outbound/query、GET /outbound/export
库存	GET /stock/query、GET /stock/zone-summary、POST /stock/lock、POST /stock/unlock、POST /stock/deduct、POST /stock/check
检验	POST /inspection/create、POST /inspection/batch-flip、GET /inspection/query
区域	POST /zone/create、POST /zone/update、GET /zone/list、GET /zone/picker
盘点	POST /stocktake/start、POST /stocktake/record、POST /stocktake/finish、GET /stocktake/query
半成品	POST /semi/inbound、POST /semi/outbound、GET /semi/query
台账/工单	GET /api/ledger/query、GET /api/orders
大屏	GET /api/display/overview（免登录）
内部 API	/api/internal/*：ledger/sync、stock/{check,lock,unlock,deduct,query}、semi/{inbound,outbound}（用 X-API-TOKEN 保护，供 MES/工位调用）

接口风格现状：均为「按业务模块自由命名」，没有统一的 RESTful 资源风格、没有统一分页/排序/过滤参数规范、没有 OpenAPI 文档。

---

五、前端页面 / 路由 / 菜单

页面（src/pages/，14 个），路由在 router/index.js：

路由	页面	说明
/login	Login.vue	登录
/display	Display.vue	免登录大屏（全屏无侧栏）
/	Dashboard.vue	工作台
/inbound	Inbound.vue	入库管理（列表页：筛选+分页+导出+「批量入库」按钮）
/inbound-create	InboundCreate.vue	批量入库（新 tab 打开，不进侧栏）
/outbound	Outbound.vue	出库管理（tab：工单备料出库 MES / 通用出库）
/inventory	Inventory.vue	库存查询
/inspection	Inspection.vue	质量检验
/stocktake	Stocktake.vue	库存盘点
/semi	Semi.vue	半成品/成品（3 个 tab：入库 / 查询 / 出库）
/ledger	Ledger.vue	备料台账
/zone	BaseData.vue（mode=zone）	区域维护
/material	BaseData.vue（mode=material）	物料档案
/change-password	ChangePassword.vue	修改密码
/users	UserManage.vue	账号管理

侧栏菜单：硬编码在 MainLayout.vue 的 defaultMenus 数组（11 项），每项带 code（如 inbound:view、user:manage），按后端返回的 permissionCodes 过滤显示。 另：每个页面挂 <PageHelp> 组件，帮助文案统一在 src/help.js。

---

六、核心业务流（现状）

1. 入库：InboundCreate.vue 录单 → POST /inbound/create（事务：入库单 + inventory + 入库明细 原子提交）。结构件按批次；精密件按 SN 逐件（SN 全局查重）。支持 Excel 批量导入（POST /inbound/batch-excel，事务化全成功或全失败，支持 batch/SN 双模板）。
2. 出库：统一主表 outbound_order，用 outbound_type 区分：
   • workorder（工单备料出库）：受 order_material_ledger 台账约束，累计出库 ≤ BOM 需求；MES 不可达时 /api/orders 优雅降级返回空列表。
   • general（通用出库）：退料/样品/报废/发货等不挂工单场景。
   • 装箱信息（box_no/box_sn_list/contract_no）直接落在出库主表，未单独建表。
3. 库存查询：直接查 inventory 表。结构件按批次一条记录、精密件每个 SN 一条记录。
4. 质量检验：/api/inspection/*，记录落在 inspection_record。
5. 盘点：stocktake 发起 → 记录 → 完成（含「差异写回库存」）。
6. 闭环跳转：库存页点「入库单号」→ 跳 /inbound?inboundNo=xxx 自动预填查询。

---

七、权限模型现状（对应问题一）

结论：权限是硬编码的，没有数据化。

已核实的事实：

• internal/handler/rbac.go 第 20-35 行：角色→权限码映射写死在 Go 代码里的 rolePermissions map，仅 admin / operator / inspector 三个角色。
• roleOrDefault() 把未知角色统一回退为 operator。
• user 表只有字符串字段 role，没有角色表、没有菜单表、没有按钮权限表。
• GET /user/info 返回 permissionCodes（由 role 经 map 映射得出）。
• 后端权限校验只有一个 requireAdmin()，硬编码判断 role == "admin"（仅用于账号管理类接口）。
• 前端菜单硬编码在 MainLayout.vue 的 defaultMenus（11 项，各带 code），按 permissionCodes 做显示/隐藏过滤。
• 不存在：角色维护页面、角色增删改接口、菜单配置管理、按钮级权限。

遗留问题：rolePermissions 中仍保留已废弃的 "package:view"（装箱功能已合并进出库主表），属脏数据。

---

八、已确立的设计约定（用户强约束，重新规划时务必遵守）

1. 统一主表原则：同类业务必须用「一张主表 + 类型字段区分」，禁止为新增功能另建独立表。

   • 正例：出库用 outbound_type(workorder/general) 区分；装箱字段直接落主表。
   • 反例：曾因入库拆多表导致无法全量导出，被明确批评。
   • 新增能力优先「主表加字段」+ 配套全量导出。

2. 单一职责 + 分页（用户称"互联网思维"）：每个页面只做一件事。

   • 录入/创建页不得内嵌查询列表；查询/列表必须是独立页面（带查询条件、分页、导出）。
   • 已落地范例：入库管理 Inbound.vue（列表页）+ 批量入库 InboundCreate.vue（新 tab 打开的录入页，不进侧栏）。

3. 数据量意识：任何列表/明细/导出必须先估算数据量，禁止无脑全量加载。

   • 列表接口每行只带 count，禁止在列表里对每行加载全部子明细（精密件单可上万 SN）。
   • 明细必须懒加载 + 分页（如 GET /inbound/details，默认 50/页）。

4. 列表规范（用户最新要求，来自《问题记录.md》）：

   • 搜索条件要合适的方式：该模糊的模糊、该下拉的下拉；去掉笼统的"关键字"搜索。
   • 所有列表增加创建时间字段，展示格式 yyyy-MM-dd HH:mm:ss；搜索条件增加创建时间筛选，默认近 3 个月。
   • 所有列表增加主键 ID。

5. 协作流程：非琐碎改动必须先给详细方案并给出推荐选项，用户确认后再动手。

---

九、当前待办问题（《问题记录.md》8 项 + 代码核实结果）

以下每条均已对照实际代码核实，便于规划时直接定位。

一、WMS 与 WMS 客户端

1. 缺少角色维护 → 核实：权限硬编码在 rbac.go 的 map，无角色表、无维护接口、无页面。
2. 缺少角色菜单按钮权限 → 核实：菜单硬编码在 MainLayout.vue，仅做显示过滤；无按钮级权限。

二、物料档案（/material → BaseData.vue mode=material）

1. 搜索条件不足 → 核实：目前只有一个"关键字"输入框（BaseData.vue 第 181/238 行），未按物料编码/名称/规格/类型拆分。
2. 列表缺创建时间 → 核实：material 表有 created_at（Int64 unix 秒），但前端列表未展示、无时间筛选。
3. 列表缺主键 ID → material 表主键 id 存在，前端未展示。

三、区域维护（/zone → BaseData.vue mode=zone）

同上三点：zone 表有 created_at/updated_at，前端同样只有"关键字"搜索、无创建时间、无 ID 列。

四、备料台账（/ledger）

1. 需要填充假数据以便查看展示效果（表：order_material_ledger）。

五、半成品/成品（/semi → Semi.vue）

1. 内嵌 tab 页叫什么 → 核实：Semi.vue 现有 3 个 tab：「半成品/成品入库」「半成品/成品查询」「半成品出库」（Element Plus 组件为 el-tabs，通称"标签页/选项卡"）。
2. 与菜单「出库管理」的区别与关系 → 需重新规划明确职责边界。

六、库存盘点（/stocktake）

1. 发起盘点是否锁全部库存？能否选择盘点全库 / 某个物料？ → 需设计（当前 stocktake 表结构支持按 target_type/material_code/zone_code 记录明细，但前端流程未暴露选择能力）。
2. 缺少物料分布图：无法查看"哪个物料、在哪个货架、每个多少、一共多少"。

七、质量检验（/inspection）

用户评价"设计胡闹、无法闭环"。核实：

• Inspection.vue 中导出相关代码数量为 0（确实不能导出）。
• 现有字段仅：目标类型、已选清单、检验员、检验结论。
• 缺失：检测说明、不合格说明、检验记录闭环、导出能力。
• 表 inspection_record 现有字段：target_type target_id material_code inspection_type status result_value inspector remark created_at updated_at。

八、库存查询（/inventory）

用户评价"设计乱七八糟"。核实到两处关键：

1. SN 被直接暴露在主列表：Inventory.vue 第 73 行 return row.manageMode === 2 ? row.snCode : row.batchNo，即 inventory 表每条 SN 一行直接展示。用户主张：库存查询应按物料聚合只显示数量，SN 属子表明细，应点击查看。
2. 职责边界未定义：「同批次」与「库存查询」如何分工？用户理解——库存查询 = 查物料数量的地方；出入库管理 = 查自己批次的地方。需重新规划确认。

---

十、已知技术债与风险

项	说明
权限硬编码	角色/菜单/权限码全在代码里，加角色或改权限需改代码重新部署
废弃权限码残留	rolePermissions 中仍有 package:view
created_at 类型	全库为 Int64 unix 秒，前端 fmtTime 需 *1000；统一 yyyy-MM-dd HH:mm:ss 展示需统一处理
前端无 TypeScript	全 JS，无类型约束
无统一列表组件	各页面各自实现筛选/表格/分页/导出，风格与能力不一致（这正是"列表乱"的根因）
无统一 API 层	页面内直接 request.get('/xxx')，路径散落
无接口文档	无 OpenAPI；接口命名无统一 RESTful 规范；无统一错误码
库存查询性能	精密件每 SN 一条 inventory 记录，量大时列表与渲染压力大
前端构建	需手动 mv 备份 web/static 再 build（Windows EPERM），无脚本化
Git 状态	所有改动均未提交 git（用户从未要求 commit）

---

十一、给重新规划者的建议输入

重新规划时建议优先处理（按依赖顺序）：

1. 先定"列表规范"标准件：统一筛选区（模糊/下拉/日期）、统一列（ID + 创建时间 yyyy-MM-dd HH:mm:ss）、统一分页 + 导出、创建时间默认近 3 个月。可抽为通用列表组件/配置，一次性解决物料档案、区域维护、库存查询等多处问题。
2. 权限数据化：建角色表 + 菜单表 + 按钮权限表，取代硬编码 map；前端菜单与按钮权限改为按接口下发。
3. 库存查询重构：明确"库存=按物料聚合查数量；SN/批次=子表按需下钻"，同时解决性能与职责边界（问题八）。
4. 质量检验闭环：补齐检验说明/不合格说明字段、检验记录查询与导出（问题七）。
5. 盘点能力：支持选择盘点范围（全库/区域/物料），并新增物料分布图（问题六）。
6. 职责边界澄清：半成品/成品 与 出库管理 的关系（问题五）。

务必遵守：第八节的 5 条强约束（统一主表、单一职责+分页、数据量意识、列表规范、先方案后改）。