# air-material

**Repository Path**: corner2007/air-material

## Basic Information

- **Project Name**: air-material
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-07
- **Last Updated**: 2026-01-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 航材决策管理系统 - 文档中心

欢迎来到航材决策管理系统的文档中心！这里包含了项目的所有技术文档和说明。

## 📚 文档目录

### 🎯 核心文档

| 文档 | 描述 | 适合读者 | 状态 |
|------|------|----------|------|
| [需求规格说明书 (SRS)](SRS_需求规格文档.md) | 详细的系统功能和非功能需求 | 项目经理、BA、开发、测试 | ✅ 完成 |
| [软件设计文档 (SDD)](SDD_设计文档.md) | 系统架构、模块设计、接口设计 | 架构师、开发人员 | ✅ 完成 |
| [系统架构图](system_architecture.md) | 7个详细的系统架构图 | 所有技术人员 | ✅ 完成 |
| [系统流程图](system_flowchart.md) | 10个详细的业务流程图 | 所有技术人员 | ✅ 完成 |
| [项目总结](project_summary.md) | 项目完成情况和技术亮点 | 项目相关方 | ✅ 完成 |

### 📖 使用指南

| 文档 | 描述 | 适合读者 |
|------|------|----------|
| [用户操作手册](用户操作手册.md) | 业务操作流程、最佳实践 | 所有用户 |
| [前端交互设计](前端交互设计文档.md) | 用户体验设计、界面规范 | 产品经理、设计师、前端开发 |
| [模型评估与验证](模型评估与验证文档.md) | 历史拟合、合理性评估 | 数据科学家、业务分析师 |
| [快速开始示例](../examples/quick_start.py) | 完整的使用示例代码 | 开发人员 |
| [项目README](../README.md) | 项目概述和安装说明 | 所有人员 |
| [Python依赖](../requirements.txt) | 完整的Python包依赖列表 | 开发人员 |

---

## 🗂️ 文档分类

### 1. 需求与设计

#### 需求规格说明书 (SRS)
**内容概览**:
- ✅ 9大功能模块，60+功能需求点
- ✅ 6大类非功能需求（性能、可靠性、安全性等）
- ✅ 5个核心数据实体设计
- ✅ 4类外部系统接口需求
- ✅ 详细的业务规则和约束条件

**主要章节**:
1. 引言 - 编写目的、项目背景、术语定义
2. 总体描述 - 产品功能、用户特征、运行环境
3. 功能需求 - 数据管理、预测分析、优化决策、报告分析、系统管理
4. 非功能需求 - 性能、可靠性、安全性、可维护性、易用性、兼容性
5. 数据需求 - 数据实体、数据量估算、数据质量要求
6. 接口需求 - 用户界面、外部系统接口、数据导入导出
7. 约束条件 - 技术、业务、法律法规约束
8. 质量属性 - 可测试性、可部署性、可观测性
9. 业务规则 - 库存控制、采购审批、预警规则、服务水平

#### 软件设计文档 (SDD)
**内容概览**:
- ✅ 7层系统架构设计
- ✅ 完整的技术栈选型
- ✅ 5大核心模块详细设计
- ✅ RESTful API接口设计
- ✅ 数据库设计和ORM映射
- ✅ 预测和优化算法设计
- ✅ 安全设计（认证、授权、加密、审计）
- ✅ Docker容器化部署方案

**主要章节**:
1. 引言 - 编写目的、系统概述
2. 系统架构设计 - 总体架构、技术架构、部署架构、微服务拆分
3. 模块设计 - 模块依赖关系、核心模块详细设计、API设计
4. 数据库设计 - 数据库选型、数据模型、表结构、索引、分区、ORM
5. 接口设计 - 外部接口、内部服务接口
6. 算法设计 - ARIMA、XGBoost、LSTM预测算法，多周期优化、EOQ、调配优化
7. 安全设计 - JWT认证、RBAC授权、数据加密、审计日志
8. 部署设计 - Docker化、Docker Compose、监控日志

### 2. 用户与体验

#### 用户操作手册 (用户操作手册.md)
**包含内容**:
- ✅ 用户角色与权限定义
- ✅ 详细的业务操作流程（日常、月度）
- ✅ 5大关键业务场景的操作步骤
- ✅ 4大功能模块的详细操作指南
- ✅ 最佳实践和常见问题解答

**主要章节**:
1. 系统概述 - 系统简介和登录
2. 用户角色与权限 - 4种角色和权限矩阵
3. 业务操作流程 - 日常流程、月度流程、关键场景
4. 功能模块操作 - 数据管理、预测分析、优化决策、报告分析
5. 最佳实践 - 数据管理、预测建模、库存优化、采购执行、风险管理
6. 常见问题 - 数据相关、预测相关、优化相关、系统使用

**特色**:
- 步骤化的操作说明
- 预计操作时间
- 截图式界面展示
- 快捷键和技巧

#### 前端交互设计 (前端交互设计文档.md)
**包含内容**:
- ✅ 核心设计原则（简洁直观、高效操作、数据可视化）
- ✅ 用户体验设计（用户旅程、信息架构、任务流程）
- ✅ 界面设计规范（布局、色彩、字体、图标、组件）
- ✅ 核心页面设计（首页、预测分析、库存优化、数据录入）
- ✅ 交互设计细节（加载状态、错误处理、成功反馈）
- ✅ 响应式设计和可访问性

**主要章节**:
1. 设计理念 - 5大核心设计原则
2. 用户体验设计 - 用户旅程、痛点分析、信息架构、任务流程优化
3. 界面设计规范 - 布局系统、色彩系统、字体系统、图标系统、组件规范
4. 核心页面设计 - Dashboard、预测分析、库存优化、数据录入页面的详细设计
5. 交互设计细节 - 加载、错误、成功、空状态的交互设计
6. 响应式设计 - 移动端适配、断点适配策略
7. 可访问性设计 - 键盘导航、屏幕阅读器、颜色对比度

**特色**:
- ASCII艺术风格的界面原型
- 完整的设计系统
- 交互流程图
- 用户旅程地图

### 3. 模型评估与验证

#### 模型评估与验证文档 (模型评估与验证文档.md)
**包含内容**:
- ✅ 三层评估体系（统计指标、可视化验证、业务合理性）
- ✅ 预测模型评估（MAPE、RMSE、R²详解和评分）
- ✅ 优化模型评估（成本对比、服务水平对比、风险评估）
- ✅ 可视化验证方法（拟合图、误差分布、残差分析）
- ✅ 业务合理性评估（趋势一致性、范围检查、可解释性）
- ✅ 持续监控与改进（实时监控、异常检测、A/B测试）

**主要章节**:
1. 评估体系概述 - 三层架构、评估流程
2. 预测模型评估 - 统计指标详解、可视化验证、业务合理性检查
3. 优化模型评估 - 成本对比、服务水平、可行性评估、风险评估
4. 可视化验证 - 交互式图表、历史拟合回测
5. 业务合理性评估 - 逻辑一致性、可解释性、实施可行性
6. 持续监控与改进 - 性能监控、异常告警、定期评估、模型迭代

**特色**:
- 详细的评分标准和评级系统
- 丰富的可视化示例
- 业务可解释性分析
- 持续改进机制

### 4. 架构与流程

#### 系统架构图 (system_architecture.md)
**包含7个架构图**:
1. **总体架构** - 7层架构（数据层→展示层）
2. **技术架构** - 前端、后端、数据科学、基础设施技术栈
3. **数据流架构** - 数据源→数据管道→数据存储→数据服务
4. **模型架构** - 预测模型、优化模型、模型评估
5. **部署架构** - 负载均衡、应用集群、计算集群、数据存储、监控
6. **安全架构** - 认证授权、数据安全、网络安全
7. **扩展性设计** - 水平扩展、垂直扩展、高可用性

#### 系统流程图 (system_flowchart.md)
**包含10个流程图**:
1. **主业务流程** - 数据输入到结果输出的完整流程
2. **数据处理流程** - 采集→清洗→转换→加载
3. **需求预测流程** - 特征工程→模型选择→训练→评估
4. **库存优化流程** - 建模→约束设置→求解→验证
5. **多周期优化流程** - 滚动优化和周期间依赖
6. **订单执行流程** - 推荐→审核→审批→执行→验收
7. **实时监控流程** - 数据监控→异常检测→告警→调整
8. **模型训练与部署流程** - 开发→实验→预生产→生产
9. **数据质量监控流程** - 收集→验证→质量指标→报告
10. **成本优化流程** - 成本收集→建模→优化→仿真
11. **风险管理流程** - 识别→评估→应对→监控

### 3. 代码实现

#### 源代码结构
```
src/
├── data/                          # 数据处理模块
│   └── data_processor.py          # 数据验证、清洗、整合
├── models/                        # 算法模型模块
│   ├── demand_forecast.py         # 需求预测（5种方法）
│   └── inventory_optimization.py  # 库存优化（6种模型）
└── inventory_optimization_system.py  # 主系统类
```

#### 核心功能实现

**需求预测** (`models/demand_forecast.py`):
- ARIMA: 自回归积分滑动平均模型
- Prophet: Facebook时间序列预测
- XGBoost: 梯度提升树回归
- LSTM: 长短期记忆神经网络
- Ensemble: 集成学习模型

**库存优化** (`models/inventory_optimization.py`):
- MultiPeriodInventoryOptimizer: 多周期库存优化
- EOQOptimizer: 经济订货量模型
- NewsvendorOptimizer: 报童模型
- ServiceLevelOptimizer: 服务水平优化
- MultiProductOptimizer: 多产品联合优化
- RobustInventoryOptimizer: 鲁棒优化

**数据处理** (`data/data_processor.py`):
- DataValidator: 5种数据验证方法
- DataCleaner: 4种数据清洗策略
- DataIntegrator: 数据整合和特征工程

### 4. 使用示例

#### 快速开始示例 (`examples/quick_start.py`)
**包含3个完整示例**:
1. **基本使用示例** - 完整的优化流程演示
   - 系统初始化
   - 数据加载和处理
   - 需求预测模型训练
   - 库存优化求解
   - 报告生成和导出

2. **模型比较示例** - 比较不同预测方法
   - ARIMA vs XGBoost vs Ensemble
   - MAPE、R²、总成本对比

3. **敏感性分析示例** - 分析参数影响
   - 不同服务水平的成本对比
   - 安全库存变化分析

---

## 🔍 快速查找

### 按角色查找

#### 项目经理 / 产品经理
- 需求规格说明书 (SRS) - 第1、2章
- 项目总结 - 完成情况和技术亮点
- 系统架构图 - 总体架构图

#### 业务分析师 (BA)
- 需求规格说明书 (SRS) - 全文
- 系统流程图 - 所有业务流程
- 业务规则 (SRS第9章)

#### 架构师 / 技术负责人
- 软件设计文档 (SDD) - 全文
- 系统架构图 - 所有架构图
- 系统流程图 - 技术流程

#### 后端开发人员
- 软件设计文档 (SDD) - 第2、3、4、5、6章
- 系统架构图 - 技术架构、部署架构
- 源代码 - `src/models/`, `src/data/`
- API设计 (SDD第3.3节)

#### 前端开发人员
- 需求规格说明书 (SRS) - 第3章
- API设计 (SDD第3.3节)
- 接口需求 (SRS第6章)

#### 测试工程师
- 需求规格说明书 (SRS) - 功能需求、业务规则
- 软件设计文档 (SDD) - 接口设计
- 性能测试方案 (SDD附录B)

#### 运维工程师
- 软件设计文档 (SDD) - 第8章（部署设计）
- 系统架构图 - 部署架构
- Docker配置 (项目根目录)

### 按主题查找

#### 需求相关
- **功能需求**: SRS第3章
- **非功能需求**: SRS第4章
- **数据需求**: SRS第5章
- **接口需求**: SRS第6章
- **业务规则**: SRS第9章

#### 架构相关
- **总体架构**: SDD第2.1节、system_architecture.md
- **技术架构**: SDD第2.2节、system_architecture.md
- **部署架构**: SDD第2.3节、SDD第8章
- **数据架构**: SDD第4章

#### 设计相关
- **模块设计**: SDD第3章
- **数据库设计**: SDD第4章
- **接口设计**: SDD第5章
- **算法设计**: SDD第6章

#### 实现相关
- **预测算法**: SDD第6.1节、`src/models/demand_forecast.py`
- **优化算法**: SDD第6.2节、`src/models/inventory_optimization.py`
- **数据处理**: SDD第3.2.1节、`src/data/data_processor.py`

#### 部署相关
- **Docker化**: SDD第8.1节
- **监控日志**: SDD第8.3节
- **性能测试**: SDD附录B

---

## 📊 文档统计

| 类别 | 数量 | 详细说明 |
|------|------|----------|
| 核心文档 | 8 | SRS、SDD、架构图、流程图、用户手册、前端设计、模型评估、项目总结 |
| 架构图 | 7 | 涵盖总体、技术、数据流、模型、部署、安全、扩展性 |
| 流程图 | 10+ | 涵盖主业务、数据处理、预测、优化、订单、监控等 |
| 功能需求 | 60+ | 数据管理、预测、优化、报告、系统管理模块 |
| 非功能需求 | 30+ | 性能、可靠性、安全性等 |
| 数据实体 | 5 | 航材、消耗、库存、航线、采购订单 |
| API接口 | 30+ | RESTful API端点 |
| 预测模型 | 5 | ARIMA、Prophet、XGBoost、LSTM、Ensemble |
| 优化模型 | 6 | 多周期、EOQ、报童、服务水平、多产品、鲁棒 |
| 代码模块 | 4 | 数据处理、需求预测、库存优化、主系统 |
| 示例代码 | 3 | 基本使用、模型比较、敏感性分析 |
| 评估指标 | 10+ | MAPE、RMSE、R²、MAE、DW统计量等 |
| 业务场景 | 5+ | 数据录入、预测建模、库存优化、订单创建、调配优化 |

---

## 🎓 学习路径

### 初学者（了解系统）
1. 阅读 [项目README](../README.md) - 了解项目概况
2. 阅读 [用户操作手册](用户操作手册.md) - 了解业务流程和操作
3. 查看 [系统架构图](system_architecture.md) 的"总体架构"部分
4. 运行 [快速开始示例](../examples/quick_start.py) 的"基本使用示例"

### 业务用户（使用系统）
1. 阅读 [用户操作手册](用户操作手册.md) - 学习业务操作流程
2. 阅读 [前端交互设计](前端交互设计文档.md) - 了解界面和交互
3. 阅读 [模型评估与验证](模型评估与验证文档.md) - 理解如何评估预测和优化结果
4. 查看系统帮助和视频教程

### 开发人员（实现功能）
1. 阅读 [需求规格说明书](SRS_需求规格文档.md) 第3章 - 理解功能需求
2. 阅读 [软件设计文档](SDD_设计文档.md) 第3、4、5章 - 理解设计和接口
3. 阅读 [前端交互设计](前端交互设计文档.md) - 了解界面和组件规范
4. 研究源代码 `src/models/` 和 `src/data/`
5. 运行示例代码并修改实验

### 架构师（深入设计）
1. 阅读 [软件设计文档](SDD_设计文档.md) 全文
2. 详细研究 [系统架构图](system_architecture.md) 所有架构图
3. 研究算法设计（SDD第6章）
4. 阅读 [模型评估与验证](模型评估与验证文档.md) - 了解评估体系
5. 查看部署设计（SDD第8章）

### 产品经理/设计师（产品设计）
1. 阅读 [用户操作手册](用户操作手册.md) - 了解业务场景和用户需求
2. 阅读 [前端交互设计](前端交互设计文档.md) - 理解设计原则和规范
3. 阅读 [需求规格说明书](SRS_需求规格文档.md) - 了解功能需求
4. 查看系统流程图和用户旅程地图

### 数据科学家（模型开发）
1. 阅读 [模型评估与验证](模型评估与验证文档.md) - 了解评估方法
2. 阅读 [软件设计文档](SDD_设计文档.md) 第6章 - 算法设计详解
3. 研究源代码 `src/models/` - 查看模型实现
4. 运行模型比较示例

### 测试人员（编写测试）
1. 阅读 [需求规格说明书](SRS_需求规格文档.md) - 功能需求和业务规则
2. 阅读 [软件设计文档](SDD_设计文档.md) 第5章 - 接口设计
3. 阅读 [用户操作手册](用户操作手册.md) - 了解业务流程
4. 查看性能测试方案（SDD附录B）

---

## 🔄 文档维护

### 版本控制
- 所有文档使用Git版本控制
- 主要变更记录在文档的"修订历史"部分
- 重大变更需要更新版本号

### 更新频率
- **核心文档** (SRS、SDD): 每个主要版本更新
- **架构图**: 架构变更时更新
- **流程图**: 流程变更时更新
- **代码示例**: 每个版本验证并更新

### 贡献指南
- 文档改进欢迎提交Pull Request
- 保持文档风格一致
- 添加必要的图表和示例
- 更新相关文档的交叉引用

---

## 📞 联系方式

如有文档相关问题，请联系：
- **项目负责人**: [姓名]
- **架构师**: [姓名]
- **技术支持**: [邮箱]

---

## 📝 许可证

Private - 内部使用

---

**最后更新**: 2024-01-01
**文档版本**: v1.0