TONASPACE/PartsInquiry
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
44ac2723a071b8704c157e0a1e24844771c67565
PartsInquiry/doc/admin_requirements.md
Wdp-ab d343a1389a 9.20/3
2025-09-20 18:03:22 +08:00

9.3 KiB
Raw Blame History

管理端需求规格说明书（PartsInquiry）

1. 目标与范围

  • 目标：为“配件查询/进销存”系统提供 PC Web 管理端，支持主数据配置、日常业务监管与数据分析，保障多租户（按店铺）数据隔离与安全可控。
  • 范围：围绕商品、库存、订单（销售/进货/退货）、往来（客户/供应商）、账户与收支、报表统计、配件众包审核、公告、系统参数、用户与店铺管理等模块展开。

2. 角色与权限（分阶段）

  • MVP：基于现有 users.role 与 is_owner 字段实现“店长（owner）/员工（staff）”两级权限开关；菜单与接口做最小化授权控制（店长全量、员工受限）。
  • 方案A（MVP落地）：后端以常量维护权限点 → 通过 users.role 做菜单/接口守卫；无需改库，风险低、上线快。
  • 方案B（标准RBAC，需改库）：新增 roles/permissions/user_roles/role_permissions 等表，菜单-权限点分离；支持细粒度到按钮/字段；成本高、可作为后续版本演进。

3. 多租户与数据隔离

  • 以店铺 shops 为租户单位，所有业务表包含 shop_id；接口通过请求头 X-Shop-Id 或 X-User-Id 解析绑定店铺。
  • 管理端所有查询/导出均默认限定到当前 shop_id，严禁越权访问。

4. 信息架构（菜单与模块）

  1. 首页总览（Dashboard）

    • 今日销售额、本月销售额、本月毛利、库存总量等关键指标卡片
    • 公告栏（置顶/定时生效）
    • 快捷入口（新建商品、销售开单、客户/供应商管理、其他收支）

  2. 商品中心

    • 商品管理：新增/编辑/停用、图片管理、别名管理、多列销售价格（零售/批发/大单报价）、安全库存上下限
    • 商品类别：树形维护、排序
    • 计量单位：主数据维护
    • 商品设置：开关“隐藏零库存”“隐藏进货价”等
    • 批量导入/导出：CSV/Excel 模板下载、校验、结果反馈

  3. 库存与盘点

    • 库存台账：按商品查看现存量、安全库存预警、批量调价/调库存
    • 库存流水：支持按时间/商品/原因筛选，定位库存变动来源
    • 盘点（两种实现路径）：
      • 方案A（MVP）：使用 inventory_movements 记录调整（reason=adjust），形成“快速盘点”单据视图
      • 方案B（标准）：新增 stock_counts/stock_count_items 建模正式盘点单（含草稿/提交/审核/生效流程）

  4. 交易中心

    • 销售：出货单、退货单、收款；列表/详情/导出
    • 进货：入库单、退货单、付款；列表/详情/导出
    • 收付款流水：多维筛选与汇总

  5. 往来管理

    • 客户：档案维护（含价格列偏好）、“只看欠款”筛选、期初应收
    • 供应商：档案维护、“只看欠款”（应付）筛选、期初应付

  6. 账户与财务

    • 账户：现金/银行/微信/支付宝等基础账户维护、余额、启停
    • 账户流水（Ledger）：期间收支、期初/本期/期末，按关键词检索
    • 其他收入/支出：分类维护（经营、办公等），按往来单位与账户记账

  7. 报表中心

    • 资金报表：利润、营业员统计、经营业绩
    • 进销存报表：销售统计、进货统计、库存统计、应收/应付对账单
    • 导出：按筛选条件导出 CSV/Excel

  8. 配件查询与众包审核

    • 数据查询：多条件组合、模糊匹配、分页、导出
    • 提交审核：用户提交新配件（型号必填）、图片上传、管理员审核（通过/驳回/编辑）
    • 图片管理：多图、排序、预览、去重

  9. 公告管理

    • 列表/新建/发布/下线、置顶、定时生效

  10. 系统设置

  • 店铺信息、系统参数（业务逻辑开关）、默认价格列、附件占位图路径配置等
  1. 用户与店铺
  • 用户：员工管理、角色（MVP为枚举）、状态启停
  • 店铺：基本信息、状态启停

5. 数据模型对齐（不改库前提）

  • 商品域：products/product_prices/inventories/product_images/product_aliases/product_categories/product_units/global_skus
  • 交易域：sales_orders/sales_order_items/sales_return_orders/...、purchase_orders/purchase_order_items/purchase_return_orders/...
  • 库存域：inventory_movements
  • 往来域：customers/suppliers
  • 资金域：accounts/payments/other_transactions/finance_categories
  • 系统与运营：system_parameters/notices/users/shops/user_identities/wechat_sessions

说明：管理端各模块的列表、详情、导出、筛选字段需与上述表结构保持一致；统计口径（如毛利）以现有订单金额与进价近似规则为准。

6. 功能与数据口径要点

  • 销售/进货单保存即生效（approved），联动库存；退货单同理
  • 收/付款必须绑定订单（sale/purchase），不可游离单据
  • 客户默认价格列按 customers.price_level，支持在下单时临时改价
  • 安全库存预警依据 products.safe_min/safe_max 与当前库存 inventories.quantity
  • 图片当前为占位图策略，管理端需支持占位图路径的配置项

7. 关键缺口与多方案设计

  1. 权限体系

    • A（MVP）：沿用 users.role（owner/staff/finance...）+ 后端常量权限映射，菜单/接口守卫
    • B（标准RBAC）：新增角色/权限/关联表，支持细粒度到按钮/字段（需改库与前后端联动）

  2. 盘点业务

    • A（MVP）：以 inventory_movements reason=adjust 记录快速盘点；提供导入与差异对账视图
    • B（标准）：stock_counts/stock_count_items 正式票据流转（草稿/提交/审核/生效），支持多盘点范围

  3. 配件提交审核

    • A（轻量）：在 products 增加状态/来源字段区分“待审核/发布”（需改库）
    • B（清晰）：新增 part_submissions 表管理提交、审核、版本留痕（需改库）；发布后写入 products

  4. 附件与图片

    • A（现状/MVP）：维持占位图上传接口，集中配置占位图片路径与 URL
    • B（完善）：引入通用 attachments 表与文件存储（本地/对象存储），商品图片与业务附件统一管理（需改库与上传服务）

  5. 报表性能

    • A（MVP）：在线聚合 + 必要索引保障（结合 idx_* 与 FULLTEXT）
    • B（增强）：引入日/月度快照表或物化视图，提升大数据量下统计性能（需改库与离线作业）

8. MVP 范围（建议首版）

  • 首页总览：指标卡、公告、快捷入口
  • 商品中心：商品/类别/单位/设置，图片占位图；导出（导入次版）
  • 往来管理：客户/供应商，支持“只看欠款”筛选
  • 交易中心：销售/进货单列表与详情、收付款创建与列表
  • 账户与财务：账户管理、账户流水、其他收支与分类
  • 库存：库存台账与库存流水（快速调整）
  • 公告管理：发布/下线/置顶/定时
  • 系统设置：系统参数读取/保存、附件占位图路径配置
  • 配件审核：审核列表 + 审核通过/驳回（先走轻量方案A或作为次版）

不含：标准RBAC、正式盘点票据、通用附件库、复杂经营报表、审计日志、批量导入（除模板下载）

9. 验收标准（MVP）

  • 指标一致：首页指标与 /api/dashboard/overview 返回一致
  • 列表正确：商品/订单/客户/供应商/账户/收支/库存流水支持分页、筛选、导出
  • 金额口径：订单金额与收/付款、其他收支汇总与接口返回一致
  • 安全：所有查询写入均限定 shop_id；非店长用户受限菜单与接口
  • 可靠：核心列表在 10 万级数据下查询 ≤ 2s（有索引）
  • 可配置：系统参数与占位图路径可读写并即时生效（或重启后生效有说明）

10. 接口对接与规范

  • 所有接口在 /doc/openapi.yaml 维护；每个 path 在 summary/description 标注实现状态（❌/✅）
  • 统一响应风格与字段命名（驼峰），分页返回 { list, page, size, total } 或兼容数组
  • 认证与多租户：通过 X-Shop-Id/X-User-Id 解析店铺并进行权限校验
  • 导出：提供 text/csv 或 Excel（application/vnd.ms-excel）响应，支持 UTF-8 BOM

11. 配置项（环境变量/系统参数）

  • 附件占位图：ATTACHMENTS_PLACEHOLDER_IMAGE、ATTACHMENTS_PLACEHOLDER_URL
  • 默认店铺/用户（仅开发环境）：ENABLE_DEFAULT_USER、DEFAULT_USER_ID
  • 商品设置（系统参数 product.settings）：hideZeroStock、hidePurchasePrice
  • 报表与导出：最大导出行数上限、异步导出开关

12. 非功能性要求

  • 安全：多租户隔离、权限校验、输入校验与审计日志（次版）
  • 性能：核心列表与统计具备必要索引；长耗时任务支持异步导出
  • 可观测：请求链路日志、接口耗时、错误聚合；慢查询监控
  • 兼容：PC Web 适配 1366×768 及以上分辨率

13. UI/UX 原则

  • 结构克制、信息分层清晰；强调列表可读性与筛选效率
  • 一键导出、批量操作具备操作确认与结果反馈
  • 重要字段固定列/高亮（金额、数量、状态、时间）

14. 后续演进建议

  • 引入标准 RBAC 与审计日志
  • 正式盘点票据与盘亏盘盈处理
  • 通用附件中心与对象存储接入
  • 复杂报表物化与计划任务

（本文档仅描述当前功能与落地方案，不包含历史变更说明。）