# 00 · 项目总览（晓镜书阁 · 书店进销存管理系统）

> 本文档集是「晓镜书阁 · 书店进销存管理系统」的**分析与设计交付物**，覆盖行业分析、需求分析、UML 建模、数据库设计、技术选型、软件架构与信创适配。
> 全系列文档均为中文 Markdown，UML 一律使用 ```mermaid 代码块绘制，可直接在支持 Mermaid 的编辑器（VS Code、Typora、飞书文档、GitLab/GitHub）中渲染。

---

## 1. 项目概述

**项目名称**：晓镜书阁 · 书店进销存管理系统（Bookstore PSI System）
**项目代号**：SHG-PSI
**项目定位**：面向**实体书店 + 电商 + 直播电商**多渠道经营的**进销存一体化管理系统**，实现「采购进货 — 库存管理 — 销售出货 — 盘点调拨 — 退货 — 查询统计 — 报表分析 — 扫码作业」的全链路数字化，并支持信创环境国产化部署。

**建设目标**：

| 目标 | 说明 |
|---|---|
| 业务一体化 | 进货、出货、库存、盘点、调拨、退货六大业务闭环，库存台账实时准确 |
| 成本精细化 | 基于**移动加权平均成本**的出库成本核算与毛利分析 |
| 数据可视化 | 22 项查询统计 + 15 张统计报表，支撑经营决策 |
| 多端协同 | B/S Web、PC（Electron）、移动 APP（uni-app）、微信小程序四端一致体验 |
| 扫码作业 | 图书/单据二维码体系（`SHG:BOOK:<isbn>`），PC 扫码枪 / APP / 小程序扫码盘点 |
| 信创兼容 | MySQL 8 为主库，达梦 DM8 / openGauss 为信创兼容；麒麟 / 统信 / 鸿蒙适配 |

---

## 2. 文档索引

| 编号 | 文档 | 内容摘要 | 关键指标 |
|---|---|---|---|
| 00 | [00-总览](00-总览.md) | 本文档，项目概述、索引、术语、读者指引 | — |
| 01 | [01-行业分析](01-行业分析.md) | 书店行业现状、渠道变迁、竞争格局、痛点、数字化与信创方向 | 6 大痛点、7 节结论 |
| 02 | [02-需求分析与用例](02-需求分析与用例.md) | 参与者、用例图、用例清单与描述卡、非功能需求 | **36 个用例** |
| 03 | [03-UML图集](03-UML图集.md) | 用例/类/ER/活动/时序/状态/组件/部署/包图 | **类图 + ER + 活动×3 + 时序×4 + 状态×2 + 组件 + 部署 + 包** |
| 04 | [04-查询统计设计](04-查询统计设计.md) | 22 项统计的设计与 SQL | **22 项统计** |
| 05 | [05-报表设计](05-报表设计.md) | 15 张报表的用途、列定义、汇总、导出 | **15 张报表（R01~R15）** |
| 06 | [06-技术选型报告](06-技术选型报告.md) | 各层次选型对比与结论、版本清单 | 9 类选型 |
| 07 | [07-软件架构设计](07-软件架构设计.md) | 分层架构、模块划分、状态机、库存一致性、二维码、安全 | 5 层架构 |
| 08 | [08-数据库设计](08-数据库设计.md) | 30 张表逐表设计说明 | **30 张表** |
| 09 | [09-接口设计](09-接口设计.md) | **REST API 权威契约**（不修改） | 11 章契约 |
| 10 | [10-信创适配方案](10-信创适配方案.md) | OS/数据库/CPU/JDK/前端/移动端信创适配 | 全栈信创 |

**配套数据库脚本**：

| 文件 | 说明 |
|---|---|
| `02-database/schema.sql` | MySQL 8 建表脚本（30 张表，权威结构） |
| `02-database/data.sql` | 初始化数据（40 本图书、6 用户、权限、样例单据等） |
| `02-database/dm/dm-schema.sql` | 达梦 DM8 建表脚本（信创适配） |
| `02-database/dm/dm-adaptation-notes.md` | MySQL → 达梦迁移说明 |
| `02-database/README.md` | 数据库初始化与信创迁移指南 |

---

## 3. 术语表

| 术语 | 英文 / 缩写 | 说明 |
|---|---|---|
| 进销存 | PSI（Purchase-Sale-Inventory） | 采购、销售、库存三大业务的一体化管理 |
| 进货单 | Purchase In Order | 向供应商采购图书的入库单据，单号前缀 `PI` |
| 出货单 | Stock Out Order | 销售/出库单据，含零售 POS，单号前缀 `SO` |
| 盘点单 | Stock Check Order | 库存实物盘点与差异调整单据，单号前缀 `CK` |
| 调拨单 | Stock Transfer Order | 仓库间库存转移单据，单号前缀 `TR` |
| 退货单 | Return Order | 采购退货 / 销售退货单据，单号前缀 `RT` |
| 库存流水 | Stock Flow | 所有出入库动作的统一台账（报表与追溯核心） |
| 移动加权平均成本 | Moving Weighted Average Cost | 每笔入库后重算的单位成本，字段 `psi_stock.avg_cost` |
| 安全库存 | Safety Stock | 触发低库存预警的阈值，字段 `psi_stock.safety_stock` |
| 锁定库存 | Locked Quantity | 已下单未出库占用的数量，字段 `psi_stock.locked_qty` |
| 单号 | Order No | 业务单据唯一编号，规则见 §接口设计 1.通用约定 |
| 二维码内容 | QR Content | 图书 `SHG:BOOK:<isbn>`，单据 `SHG:ORDER:<orderNo>` |
| 信创 | 信息技术应用创新 | 国产化软硬件适配（麒麟/统信/鸿蒙、达梦/openGauss、鲲鹏/飞腾/龙芯） |
| 四端 | 4 Clients | B/S Web、PC(Electron)、APP(uni-app)、小程序 |

---

## 4. 读者指引

- **业务/产品评审人**：先读 [01-行业分析](01-行业分析.md) → [02-需求分析与用例](02-需求分析与用例.md)，快速理解业务价值与范围。
- **架构师 / 技术评审人**：重点读 [07-软件架构设计](07-软件架构设计.md) → [03-UML图集](03-UML图集.md) → [08-数据库设计](08-数据库设计.md)。
- **后端开发**：以 [09-接口设计](09-接口设计.md) 为契约，结合 [03-UML图集](03-UML图集.md) 时序图与 [08-数据库设计](08-数据库设计.md) 实现。
- **数据/报表开发**：[04-查询统计设计](04-查询统计设计.md) 与 [05-报表设计](05-报表设计.md) 提供 SQL 与列定义。
- **信创/交付工程师**：[10-信创适配方案](10-信创适配方案.md) + `02-database/dm/` 迁移脚本与说明。

> **一致性约定**：本文档集所有表名、字段名、单号前缀（`PI/SO/CK/TR/RT`）、二维码内容（`SHG:BOOK:<isbn>`）均以 `02-database/schema.sql`、`02-database/data.sql` 与 `01-docs/09-接口设计.md` 为权威来源。

---

## 5. 需求概览

### 5.1 功能需求（按模块）

| 模块 | 核心能力 | 对应用例 |
|---|---|---|
| 认证与用户 | 登录、登出、当前用户、用户/角色/权限管理 | UC01~UC08 |
| 基础数据 | 图书、分类、出版社、供应商、客户会员、会员等级、仓库 | UC09~UC15 |
| 进货管理 | 开单、修改、提交、审核入库、作废、采购退货 | UC16~UC21 |
| 出货管理 | 开单、POS 收银、提交、出库、作废、销售退货 | UC22~UC27 |
| 库存管理 | 查询、低库存预警、盘点、扫码盘点、调拨、流水 | UC28~UC34 |
| 查询统计 | 22 项统计看板 | UC35 |
| 报表 | 15 张报表生成与导出 | UC36 |
| 二维码 | 图书/单据二维码生成、扫码解析与扫码记账 | UC37~UC40 |
| 移动端 | 在线查询、移动盘点 | UC41~UC42 |
| 系统支撑 | 操作日志、数据字典 | 并入 UC08 |

### 5.2 非功能需求（摘要）

| 类别 | 关键指标 |
|---|---|
| 性能 | 单接口 P95 < 500ms；POS 扫码检索 < 300ms；报表（万级）导出 < 5s |
| 并发 | 支持 ≥ 200 并发在线，POS 收银 ≥ 50 TPS |
| 安全 | JWT 认证 + RBAC 权限 + 操作审计 + BCrypt 密码 + 参数校验 |
| 可用性 | 目标可用性 99.5%，关键单据操作幂等、可回滚 |
| 可维护 | 分层架构、统一响应/异常、MyBatis-Plus 代码生成、前端组件化 |
| 信创 | 兼容麒麟/统信 UOS/鸿蒙；达梦 DM8/openGauss；鲲鹏/飞腾/龙芯 + 国产 JDK |

### 5.3 数据规模约定

- 图书（SKU）：万级；客户/会员：十万级；单据：百万级/年；库存流水：千万级/年。
- 金额 `DECIMAL(14,2)`，数量 `DECIMAL(14,3)`，成本 `DECIMAL(14,4)`（见 [08-数据库设计](08-数据库设计.md) 精度约定）。

---

## 6. 技术栈速览

| 层次 | 选型 |
|---|---|
| 后端 | Java 21 + Spring Boot 3.2 + MyBatis-Plus + JWT + Hutool（二维码）+ POI（Excel 导出） |
| 前端（B/S） | Vue 3 + Vite + Element Plus + Pinia + Vue Router + Axios + ECharts |
| 数据库 | MySQL 8（主）；达梦 DM8 / openGauss（信创兼容） |
| PC 端 | Electron |
| 移动端 | uni-app（Android / iOS / 鸿蒙） |
| 小程序 | 微信原生小程序 |

详见 [06-技术选型报告](06-技术选型报告.md)。