# doc-manager

**Repository Path**: liudc0810/doc-manager

## Basic Information

- **Project Name**: doc-manager
- **Description**: 通用单证管理系统。
服务器端：go语言实现
前端：最新技术实现
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-02
- **Last Updated**: 2026-06-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 金融保险单证管理系统 (Document Manager)

> 面向金融保险企业的单证全生命周期数字化管理平台。

[![Go](https://img.shields.io/badge/Go-1.21+-00ADD8?logo=go)](https://go.dev)
[![React](https://img.shields.io/badge/React-18-61DAFB?logo=react)](https://react.dev)
[![Ant Design](https://img.shields.io/badge/Ant%20Design-5-1677FF?logo=antdesign)](https://ant.design)
[![License](https://img.shields.io/badge/License-MIT-blue)](#license)

---

## 📋 项目概述

管理有价单证（保单、有价凭证）与无价单证（宣传材料、申请表）的全生命周期，实现从**印刷→入库→领用→核销**的数字化闭环，支持**多级组织架构（总公司→分公司→支公司→营业部）** 的数据隔离与权限管控，满足金融行业合规要求。

### 核心价值

- **全流程闭环** — 从印刷计划到核销报废，打通单证完整生命周期
- **分级管控** — 四级组织架构 + RBAC 角色权限 + 数据隔离
- **实时库存** — 安全库存预警、库存变动流水可追溯
- **合规审计** — 完整操作日志、审批留痕，满足金融监管要求

---

## 🛠️ 技术栈

| 层级 | 技术选型 | 说明 |
|------|---------|------|
| **后端** | Go 1.21 + Gin + GORM | RESTful API，handler/service/repository 三层架构 |
| **数据库** | MySQL 8.0 | 14 张核心表，含 seq 索引 |
| **前端** | React 18 + Ant Design 5 + Vite + TypeScript | ProTable/ProForm 企业级组件 |
| **认证** | JWT + bcrypt | 无状态认证，密码加密存储 |
| **部署** | Docker Compose | API + Web + MySQL 一键编排，Nginx 反向代理 SPA |

---

## ✨ 功能模块

| 模块 | 优先级 | 说明 |
|------|--------|------|
| **单证类型定义** | P0 | 支持有价/无价单证分类，编码/名称/规格/单价/面值/有效期 |
| **计划印刷管理** | P0 | 印刷计划制定→审批→状态跟踪（5态状态机） |
| **入库登记** | P0 | 按印刷批次入库，数量核对→差异预警→入库单自动生成 |
| **领用申请与审批** | P0 | 提交申请→上级审批→自动扣库存→出库单生成 |
| **库存管理** | P0 | 实时库存查询，安全库存预警（红色高亮），变动流水 |
| **公司分级管理** | P0 | 四级树形组织架构，上级可查下级数据隔离 |
| **用户管理 (RBAC)** | P0 | 用户-角色-权限三级模型，按操作级别分配权限 |
| **库存盘点** | P1 | 发起盘点→录入实盘数→差异自动计算→报告生成 |
| **报表统计** | P1 | 入库/领用/库存多维统计报表，支持 Excel 导出 |
| **操作审计日志** | P0 | 记录"谁、何时、做了什么"，满足合规可追溯 |

---

## 🚀 快速开始

### 环境要求

- Go >= 1.21
- Node.js >= 18
- MySQL >= 8.0

### 本地开发

```bash
# 1. 克隆项目
git clone https://gitee.com/liudc0810/doc-manager.git
cd doc-manager

# 2. 启动后端 (8080端口)
cd server
cp config.yaml config.local.yaml  # 按需修改数据库配置
go mod tidy
go run ./cmd/api

# 3. 启动前端 (新开终端, 5173端口)
cd web
npm install --legacy-peer-deps
npm run dev
```

访问 `http://localhost:5173`，默认管理员账号 **admin / admin123**。

### Docker 一键部署

```bash
docker-compose -f deploy/docker-compose.yml up -d
```

> 启动后访问 `http://localhost`，首次启动会自动执行数据库初始化脚本。

---

## 📁 项目结构

```
doc-manager/
├── docs/                          # 设计文档
│   ├── prd.md                     # 产品需求文档
│   ├── architecture.md            # 系统架构设计
│   ├── class-diagram.mermaid      # UML 类图
│   └── sequence-diagram.mermaid   # 时序图
├── server/                        # Go 后端
│   ├── cmd/api/main.go            # 应用入口
│   ├── internal/
│   │   ├── config/                # 配置加载 (viper)
│   │   ├── handler/               # API 控制器层
│   │   ├── service/               # 业务逻辑层
│   │   ├── repository/            # 数据访问层 (GORM)
│   │   ├── model/                 # 数据模型 + GORM 迁移
│   │   ├── middleware/            # JWT/CORS/日志/权限拦截
│   │   └── router/                # 路由注册
│   ├── pkg/                       # 通用工具包
│   ├── migrations/                # SQL 迁移脚本
│   ├── config.yaml                # 应用配置
│   ├── Dockerfile                 # Docker 构建
│   └── Makefile                   # 构建/运行命令
├── web/                           # React 前端
│   ├── src/
│   │   ├── pages/                 # 11 个功能页面
│   │   ├── components/            # 通用组件
│   │   ├── layouts/               # 布局组件
│   │   ├── services/              # API 调用层 (axios)
│   │   └── models/                # TypeScript 类型定义
│   ├── Dockerfile                 # Docker 构建 (Nginx)
│   └── nginx.conf                 # Nginx 配置
└── deploy/                        # 部署配置
    ├── docker-compose.yml         # 一键编排
    ├── Dockerfile                 # API 服务 Dockerfile
    └── .env.example               # 环境变量模板
```

---

## 🗄️ 数据模型

| 实体 | 说明 | 关联 |
|------|------|------|
| Organization | 组织架构（四级树形） | parent_id 自关联 |
| DocType | 单证类型定义 | 有价/无价分类 |
| Inventory | 实时库存（Org+DocType 唯一） | 行级锁防超卖 |
| PrintPlan | 印刷计划（5个状态） | →WarehousingIn |
| WarehousingIn | 入库单 | 关联印刷计划 |
| Requisition | 领用申请（4个状态） | →WarehousingOut |
| WarehousingOut | 出库单 | 审批通过自动生成 |
| User | 系统用户 | 关联组织+角色 |
| Role | 角色（RBAC 权限集） | M:N User |
| AuditLog | 操作审计日志 | 所有关键操作留痕 |
| StockCheck | 库存盘点 | 含明细行 |

---

## 🔌 API 概览

所有 API 以 `/api/v1/` 为前缀，认证方式为 `Authorization: Bearer <token>`。

| 模块 | 方法 | 路径 | 说明 |
|------|------|------|------|
| 认证 | POST | `/auth/login` | 登录获取 JWT |
| 认证 | GET | `/auth/profile` | 获取当前用户信息 |
| 单证类型 | GET/POST/PUT | `/doc-types` | 单证类型 CRUD |
| 印刷计划 | GET/POST | `/print-plans` | 印刷计划管理+审批 |
| 入库 | GET/POST | `/warehousing-ins` | 入库登记 |
| 领用 | GET/POST | `/requisitions` | 领用申请+审批 |
| 库存 | GET | `/inventories` | 库存查询+预警 |
| 组织架构 | GET/POST | `/organizations` | 组织树形管理 |
| 用户 | GET/POST/PUT | `/users` | 用户管理 |
| 角色 | GET/POST/PUT | `/roles` | 角色权限管理 |
| 盘点 | GET/POST | `/stock-checks` | 库存盘点 |
| 报表 | GET | `/reports/*` | 多维统计报表 |
| 审计日志 | GET | `/audit-logs` | 操作日志审计 |

---

## 🧪 技术亮点

- **库存并发控制**：`SELECT ... FOR UPDATE` 行级锁 + 事务，确保不超卖
- **审批状态机**：PrintPlan（5 态）/ Requisition（4 态），状态变更自动写审计日志
- **数据隔离**：Organization.path 树形路径编码，SQL 范围限定实现上级可见下级
- **单据编号**：统一 `pkg/serial` 编号生成器（IN/OUT/RQ/PC 前缀 + 日期 + 流水号）
- **响应格式**：统一的 `{code, message, data}` JSON 结构，分页结果含 `{items, total, current, pageSize}`

---

## 📝 License

MIT License. 本项目为金融保险行业内部管理工具，可根据需要自由修改和分发。

---

> **默认登录信息**：admin / admin123 （首次使用请及时修改密码）