### 管理端需求规格说明书（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) 系统设置
   - 店铺信息、系统参数（业务逻辑开关）、默认价格列、附件占位图路径配置等

11) 用户与店铺
   - 用户：员工管理、角色（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 与审计日志
- 正式盘点票据与盘亏盘盈处理
- 通用附件中心与对象存储接入
- 复杂报表物化与计划任务

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