系统设计说明

本文汇总 系统架构与配置、功能设计、前端组件设计、功能使用与 HTTP 接口约定，与仓库内 README.md、backend/MICROSERVICES.md 互补；细节以代码为准。

---

一、系统架构与部署配置

1.1 总体结构

层级	技术	说明
前端	Vue 3、Vite、Pinia、Vue Router、Naive UI	浏览器访问开发服务器，经代理调用网关
网关	NestJS	校验 JWT、转发 Sys/Acc、统一响应体
系统服务 Sys	NestJS	用户、认证、站点、角色、权限、字典等
记账服务 Acc	NestJS + Socket.IO（可选）	进销存、生产、结算、库存流水等
数据	MySQL + ZenStack	schema.zmodel 描述模型与访问策略；zen generate / zen db push

默认端口：网关 3000、Sys 3001、Acc 3002、前端 5173、文档 5174。开发时前端将 /api 代理到网关，见 frontend/.env 中 VITE_API_BASE_URL。

1.2 环境变量要点

后端 backend/.env（见 .env.example）

• DATABASE_URL：MySQL 连接串。
• JWT_SECRET：网关与 Sys 必须一致，用于签发/校验 token。
• REDIS_*：会话与 token 黑名单（Sys 登录）。
• SYS_SERVICE_URL / ACC_SERVICE_URL：网关转发目标（本地多为 http://127.0.0.1:3001 / 3002）。

前端 frontend/.env

• VITE_API_BASE_URL：网关根地址（如 http://localhost:3000）。
• VITE_APP_NAME：产品名；与 vite.config.ts 中 define 及 index.html 占位 %VITE_APP_NAME% 一致；未配置时默认 TaskFlow。

1.3 数据库与 Schema

• 模型与策略：backend/zenstack/schema.zmodel。
• 各表用途与功能说明（与模型同步维护）：仓库内 docs/guide/database-tables.md；文档站侧栏「数据表设计说明」同页。
• 修改后：pnpm run zen:generate（在 backend 或根目录透传脚本），再 pnpm run zen:push 同步库结构（生产请改用受控迁移策略）；若变更涉及表职责或新业务表，请 同步更新 database-tables.md。

1.4 网关与鉴权

• 多数业务接口：POST /api/sys/...、POST /api/acc/...，需 JWT。
• 免 JWT：/api/no-check/sys/...、/api/no-check/acc/...，以及环境变量 GATEWAY_JWT_PUBLIC_PATHS 配置的路径。
• 转发后向下游注入头：x-user-id、x-site-ids、x-user-roles，供 ZenStack $setAuth 与业务站点隔离。

更细的端口与路由表见 backend/MICROSERVICES.md。

---

二、功能设计

2.1 域划分

• 系统域（Sys）：账号注册/登录、用户档案、组织架构、多站点、RBAC（角色—权限—菜单）、系统配置、数据字典、操作审计等。
• 记账域（Acc）：商品（原料/成品）、BOM、供应商/客户/工人、入库、生产、出库、工资结算、库存流水等；数据按 站点 siteId 隔离。

2.2 权限与动态路由

• 菜单型权限在库表 sys_permissions 中维护：type=menu 且 route、component 有值时，会进入用户路由清单接口。
• 前端 POST /sys/me/router-routes 拉取可访问路由，与 route-component-registry.ts 中的 componentKey 对齐后 addRoute。
• titleKey：用于侧栏与浏览器标题 i18n；后端 me-routes.service 中通过 权限 code 与 component 键 双重映射补全，避免历史数据缺键。

2.3 生产业务（两种模式）

1. 一次过账（传统）
   单张生产单同时：扣投料、产出成品/半成品行、写记工。orderStatus 为已关账语义（closed），无 AccWorkOperationReport 子表。

2. 在制（WIP）+ 工序报工

   • 开单 wip/open：扣投料、建立多条产出行（计划量 qtyPlanned，初产量 0），orderStatus=open。投料允许 原料 + 成品类型（作半成品料）。
   • 报工 wip/op/add：必须绑定 productionOutputId；计件增加该 SKU 库存与产出行数量；计时只记工。
   • 关账 wip/close：按原料成本 + 全单记工重算各产出行 单位成本，orderStatus=closed。
   • 删除报工 wip/op/delete：仅 未结算 记工；物理删子表与记工，回退计件库存；需 ADMIN / SUPER_ADMIN / PROD_WIP_LEAD。
   • 冲红 wip/op/reverse：仅 已结算 记工；保留原报工行，新增冲红行与 负金额 记工（待下次结算），计件则冲减库存与产量；关账后会重算单位成本；权限同上。

2.4 其他记账能力（摘要）

• 入库 / 出库：关联批次、成本结转与库存台账 AccStockLedger。
• 结算：勾选未结算 AccLaborRecord 生成结算单；与报工冲红产生的负行可在后续结算中冲抵。

---

三、组件设计（前端）

3.1 布局与壳

• SysAdminLayout：系统管理 + 记账共用壳；顶栏分区（工作台 / 系统 / 记账）、侧栏菜单、站点级联选择；品牌文案使用 getAppDisplayName() 与 VITE_APP_NAME 一致。
• AccShellView：记账子应用内层壳（与动态 AccNest 子路由配合）。

3.2 列表与表格

• PageQueryTable：声明式 ProTableColumn[] 同时驱动搜索区与 NDataTable；分页、v-model:query、工具栏插槽；详见文档 /components/page-query-table。
• injectLeadColumns：在无首列序号/勾选时自动补序号列或批量删除列。

3.3 记账域页面模式

• useAccSiteContext：统一要求当前站点，未选站点时展示 AccSiteRequiredAlert 并跳过列表请求。
• 弹窗表单：如 ProductionPostDialog、ProductionDetailDialog；详情弹窗内嵌 报工表格 + 删除/冲红 与 useDialog 二次确认。

3.4 路由与标题

• 静态路由：登录、注册、根重定向、/sys / /acc 空壳子路由等。
• 动态路由：permission-routes store 在拉取用户后注册；update-document-title 根据 meta.titleKey、menuTitleI18nKeyByPath 及 路由 name 回退表 设置 document.title。

---

四、功能使用

4.1 本地一键开发

在仓库根目录：pnpm install → pnpm dev（网关 + Sys + Acc + 前端）。仅后端：pnpm dev:backend。

4.2 初始化权限与菜单

1. 执行 backend/scripts/seed-sys-admin-permissions.mjs（需配置好 backend/.env 中 DATABASE_URL）：写入系统管理目录、系统菜单及 记账中心 菜单（含 titleKey 对应 code）。
2. 按需执行 backend/scripts/seed-super-admin-role.sql：为 SUPER_ADMIN 绑定全部权限。
3. 为用户分配角色后 重新登录，使 JWT 携带 roles / siteIds。

4.3 生产冲红（界面）

1. 打开 记账 → 生产记录 列表。
2. 点击 详情 打开生产详情（含工序报工表）。
3. 对 已结算 的报工行点击 冲红（需管理员或 PROD_WIP_LEAD）；对 未结算 行可 删除。
4. 无报工子表的一次过账单据仅展示汇总信息，无冲红入口（冲红仅针对 WIP 报工子表）。

4.4 应用显示名

修改 frontend/.env 中 VITE_APP_NAME 后重启前端；侧栏品牌、登录/注册标题、浏览器标签会一并更新。

---

五、接口设计

可交互 API 文档：开发环境使用 Knife4j，见 api-docs-knife4j.md（Sys/Acc 的 /doc.html，网关 /api-doc 跳转）。

5.1 统一响应（经网关）

{ "code": 0, "message": "ok", "data": { } }

业务错误时 code 非 0，message 为可读说明；前端可用 getApiErrorMessage 等工具解析。

5.2 风格约定（Sys / Acc 业务侧）

• 列表分页：POST .../page，body 常含 siteId、current、size、筛选字段。
• 写操作：POST .../save、POST .../delete 等动词路径；body JSON。
• 网关对外路径前缀：/api/sys/...、/api/acc/...。

5.3 生产相关接口（Acc，前缀 /api/acc，经网关）

路径	说明
POST /production/page	生产记录分页
POST /production/detail	单条详情（含 materials、outputs、laborRecords、workOpReports）
POST /production/post	一次过账开单
POST /production/available-batches	某成品可出库批次
POST /production/wip/open	WIP 开单
POST /production/wip/op/add	报工
POST /production/wip/close	关账扎口
POST /production/wip/op/delete	删除报工（未结算）
POST /production/wip/op/reverse	冲红报工（已结算）

请求体均须带当前记账 siteId（与站点隔离一致）。冲红/删除接口在后端校验 ADMIN / SUPER_ADMIN / PROD_WIP_LEAD。

5.4 前端 API 封装

• 路径常量：frontend/src/shared/api/acc/const.ts（ACC_API_PREFIX）。
• 生产：frontend/src/shared/api/acc/work-types-and-production.ts（含 accProductionDetail、accProductionWipOpReverse 等）。
• 统一请求：apiPost 等，见 frontend/src/shared/lib/http/api-invoke。

---

相关文档索引

文档	内容
项目概览	文档站入口说明
本地开发与构建	命令与依赖
架构与后端服务	服务与端口摘要
数据表设计说明	物理表用途、与 schema.zmodel 对照及维护约定
前端目录与约定	src 结构
PageQueryTable	列表组件
根目录 README.md	仓库结构与常用脚本
backend/MICROSERVICES.md	网关与微服务细节