aiotagro/xlxumu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 重构API文档和系统架构文档，统一技术栈规范docs(architecture): 更新系统架构设计文档

Browse Source 
- 重新组织文档结构，优化标题层级
- 添加系统架构图，直观展示系统组成- 补充前端架构、后端架构、数据架构等详细内容
- 更新安全架构、部署架构、性能优化策略等章节
- 增加扩展性设计和高可用设计章节
- 总结系统架构设计特点和优势
This commit is contained in:
ylweng
2025-09-11 01:04:51 +08:00
parent 68c6c23f5a
commit f1273daeac
34 changed files with 1663 additions and 1713 deletions
Download Patch File Download Diff File Expand all files Collapse all files

324
docs/PROJECT_STRUCTURE.md
View File

@@ -1,193 +1,185 @@
# 项目目录结构说明
# 项目结构说明
## 整体结构
## 1. 项目总体结构
```
xlxumu/
├── backend-java/ # 后端服务目录 (Java微服务架构)
├── admin-system/ # 管理后台系统目录
├── website/ # 官网项目目录
├── mini_program/ # 微信小程序矩阵目录
├── docs/ # 项目文档目录
├── test/ # 测试文件目录
├── deployment/ # 部署配置目录
└── scripts/ # 工具脚本目录
├── admin-system/ # 管理后台前端
├── backend-java/ # Java后端服务
├── backend/ # Node.js后端服务
├── docs/ # 项目文档
├── frontend/ # 用户端前端
├── miniprogram/ # 微信小程序
└── README.md # 项目说明
```
## 详细目录说明
## 2. 前端项目结构
### 1. 后端服务目录 (backend-java/)
```
backend-java/
├── api/ # API网关模块
├── gateway/ # Spring Cloud Gateway网关服务
├── registry/ # Eureka服务注册中心
├── config-server/ # Spring Cloud配置中心
├── services/ # 微服务模块
│ ├── farming-service/ # 养殖管理服务
│ ├── finance-service/ # 金融服务
│ ├── government-service/ # 政府监管服务
│ ├── trade-service/ # 交易管理服务
│ ├── mall-service/ # 商城管理服务
│ ├── data-platform-service/ # 数据中台服务
│ ├── ai-service/ # AI能力服务
│ └── user-center-service/ # 用户中心服务
├── common/ # 公共模块
├── docs/ # 后端文档
├── scripts/ # 后端脚本
└── pom.xml # Maven父项目配置文件
```
#### 微服务模块结构
每个微服务模块都遵循标准的Maven项目结构：
```
{service-name}/
├── src/
│ ├── main/
│ │ ├── java/com/xlxumu/{service}/
│ │ └── resources/
│ └── test/
│ └── java/com/xlxumu/{service}/
└── pom.xml
```
### 2. 管理后台系统目录 (admin-system/)
### 2.1 admin-system (管理后台)
```
admin-system/
├── farming-management/ # 养殖管理系统
├── bank-supervision/ # 银行监管系统
├── insurance-supervision/ # 保险监管系统
├── government-platform/ # 政府监管平台
├── cattle-trading/ # 活牛交易系统
├── mall-management/ # 商城管理系统
└── dashboard/ # 大屏可视化系统
├── public/
├── src/
│ ├── api/ # API接口
│ ├── assets/ # 静态资源
│ ├── components/ # 公共组件
│ ├── layout/ # 布局组件
│ ├── router/ # 路由配置
│ ├── store/ # 状态管理
│ ├── styles/ # 样式文件
│ ├── utils/ # 工具函数
│ ├── views/ # 页面组件
│ └── App.vue
├── .env # 环境变量
├── .eslintrc.js # ESLint配置
├── package.json # 依赖配置
└── vue.config.js # Vue配置
```
### 3. 官网项目目录 (website/)
### 2.2 frontend (用户端)
```
website/
├── index.html # 首页
├── about.html # 关于页面
├── data.html # 数据展示页面
├── news.html # 新闻页面
├── css/ # 样式文件
├── js/ # JavaScript文件
└── images/ # 图片资源
frontend/
├── public/
├── src/
│ ├── api/ # API接口
│ ├── assets/ # 静态资源
│ ├── components/ # 公共组件
│ ├── composables/ # 组合式函数
│ ├── layout/ # 布局组件
│ ├── pages/ # 页面组件
│ ├── router/ # 路由配置
│ ├── stores/ # 状态管理
│ ├── styles/ # 样式文件
│ ├── utils/ # 工具函数
│ └── App.vue
├── .env # 环境变量
├── .eslintrc.js # ESLint配置
├── nuxt.config.ts # Nuxt配置
├── package.json # 依赖配置
└── tsconfig.json # TypeScript配置
```
### 4. 微信小程序矩阵目录 (mini_program/)
### 2.3 miniprogram (微信小程序)
```
mini_program/
├── beef-mall/ # 牛肉商城小程序
├── farming-manager/ # 养殖管理小程序
├── bank-supervision/ # 银行监管小程序
├── insurance-supervision/ # 保险监管小程序
├── cattle-trading/ # 活牛交易小程序
├── gov-supervision/ # 政府监管小程序
├── data-platform/ # 数据中台小程序
└── ai-capabilities/ # AI能力小程序
miniprogram/
├── components/ # 自定义组件
├── images/ # 图片资源
├── pages/ # 页面文件
├── utils/ # 工具函数
├── app.js # 小程序逻辑
├── app.json # 小程序公共设置
├── app.wxss # 公共样式
├── package.json # 依赖配置
└── project.config.json # 项目配置
```
### 5. 项目文档目录 (docs/)
## 3. 后端项目结构
### 3.1 Java后端 (backend-java)
```
backend-java/
├── README.md # 项目说明
├── pom.xml # Maven配置
├── common/ # 公共模块
│ ├── pom.xml
│ └── src/
├── config-server/ # 配置中心
│ ├── pom.xml
│ └── src/
├── gateway/ # 网关服务
│ ├── pom.xml
│ └── src/
├── registry/ # 注册中心
│ ├── pom.xml
│ └── src/
├── services/ # 业务服务
│ ├── farming-service/ # 养殖管理服务 (端口: 8081)
│ │ ├── pom.xml
│ │ └── src/
│ ├── user-center-service/ # 用户中心服务 (端口: 8082)
│ │ ├── pom.xml
│ │ └── src/
│ ├── trade-service/ # 交易服务 (端口: 8083)
│ │ ├── pom.xml
│ │ └── src/
│ ├── finance-service/ # 金融服务 (端口: 8084)
│ │ ├── pom.xml
│ │ └── src/
│ ├── data-platform-service/ # 数据平台服务 (端口: 8085)
│ │ ├── pom.xml
│ │ └── src/
│ ├── government-service/ # 政务服务 (端口: 8086)
│ │ ├── pom.xml
│ │ └── src/
│ ├── dashboard-service/ # 大屏服务 (端口: 8087)
│ │ ├── pom.xml
│ │ └── src/
│ └── mall-service/ # 商城服务 (端口: 8088)
│ ├── pom.xml
│ └── src/
└── scripts/ # 部署脚本
```
### 3.2 Node.js后端 (backend)
```
backend/
├── api/ # API接口
├── config/ # 配置文件
├── controllers/ # 控制器
├── middleware/ # 中间件
├── models/ # 数据模型
├── routes/ # 路由配置
├── services/ # 业务逻辑
├── utils/ # 工具函数
├── app.js # 应用入口
├── package.json # 依赖配置
└── server.js # 服务启动
```
## 4. 文档结构
```
docs/
├── design/ # 设计文档
│ ├── ARCHITECTURE.md # 系统架构设计
│ ├── DEVELOPMENT_PLAN.md # 开发计划
│ ├── api/ # API设计文档
│ ├── database/ # 数据库设计文档
│ └── system_architecture.svg # 系统架构图
├── requirements/ # 需求文档
│ ├── SYSTEM_REQUIREMENTS.md # 系统需求
│ ├── FARMING_MANAGEMENT_REQUIREMENTS.md # 养殖管理需求
│ ├── FINANCIAL_SERVICES_REQUIREMENTS.md # 金融服务需求
│ ├── GOVERNMENT_SUPERVISION_REQUIREMENTS.md # 政府监管需求
│ ├── MALL_MANAGEMENT_REQUIREMENTS.md # 商城管理需求
│ ├── MARKET_TRADING_REQUIREMENTS.md # 市场交易需求
│ ├── DATA_PLATFORM_REQUIREMENTS.md # 数据中台需求
│ ├── AI_CAPABILITIES_REQUIREMENTS.md # AI能力需求
│ ├── SYSTEM_INTEGRATION_REQUIREMENTS.md # 系统集成需求
│ └── WEBSITE_REQUIREMENTS.md # 官网需求
├── development_plans/ # 开发计划文档
│ ├── backend_api_development_plan.md # 后端API开发计划
│ ├── farming_management_development_plan.md # 养殖管理开发计划
│ ├── bank_supervision_development_plan.md # 银行监管开发计划
│ ├── insurance_supervision_development_plan.md # 保险监管开发计划
│ ├── government_platform_development_plan.md # 政府平台开发计划
│ ├── cattle_trading_development_plan.md # 活牛交易开发计划
│ ├── mall_management_development_plan.md # 商城管理开发计划
│ ├── dashboard_development_plan.md # 大屏可视化开发计划
│ └── website_development_plan.md # 官网开发计划
├── API_DOCUMENTATION_STANDARD.md # API文档规范标准
├── API_DOCUMENTATION_CHECKLIST.md # API文档检查清单
├── DOCUMENTATION_MAINTENANCE_PROCESS.md # 文档维护流程
└── PROJECT_STRUCTURE.md # 项目结构说明（本文档）
├── README.md # 文档目录说明
├── API_DOCUMENTATION_STANDARD.md # API文档标准
├── API_DOCUMENTATION_MAINTENANCE.md # API文档维护流程
├── PROJECT_STRUCTURE.md # 项目结构说明
├── design/ # 设计文档
│ ├── ARCHITECTURE.md # 系统架构设计
│ ├── DEVELOPMENT_PLAN.md # 开发计划
│ ├── api/ # API设计
│ └── database/ # 数据库设计
├── development_plans/ # 开发计划
└── requirements/ # 需求文档
```
### 6. 测试文件目录 (test/)
```
test/
├── unit/ # 单元测试
├── integration/ # 集成测试
├── e2e/ # 端到端测试
└── performance/ # 性能测试
```
## 5. 部署配置
### 7. 部署配置目录 (deployment/)
```
deployment/
├── docker/ # Docker配置
├── kubernetes/ # Kubernetes配置
├── nginx/ # Nginx配置
├── scripts/ # 部署脚本
└── README.md # 部署说明文档
```
### 5.1 环境配置
- `.env`: 开发环境配置
- `.env.staging`: 测试环境配置
- `.env.production`: 生产环境配置
### 8. 工具脚本目录 (scripts/)
```
scripts/
└── update_api_docs.py # API文档更新脚本
```
### 5.2 Docker配置
- `docker-compose.yml`: Docker编排配置
- `Dockerfile`: Docker镜像配置
## 目录命名规范
## 6. 技术栈说明
1. **后端目录**: 使用英文单数形式，如 `backend-java/`
2. **前端目录**: 使用英文单数形式，如 `admin-system/`
3. **文档目录**: 使用英文复数形式，如 `docs/`
4. **子目录**: 使用英文连字符分隔，如 `farming-management/`
5. **API目录**: 使用英文单数形式，如 `api/farming/`
### 6.1 前端技术栈
- Vue 3 + Element Plus (管理后台)
- Nuxt 3 (用户端)
- 微信小程序原生开发
## 开发规范
### 6.2 后端技术栈
- Java Spring Boot (核心服务)
- Node.js Express (部分服务)
- MySQL (主数据库)
- Redis (缓存)
- RabbitMQ (消息队列)
1. **模块化开发**: 每个功能模块独立开发，便于维护和扩展
2. **前后端分离**: 后端提供RESTful API，前端通过API调用数据
3. **文档驱动**: 所有功能开发前必须先完成需求文档和设计文档
4. **测试覆盖**: 每个模块都需要有相应的测试用例
5. **代码规范**: 遵循统一的代码风格和命名规范
## 部署说明
1. **独立部署**: 每个子系统可以独立部署和运行
2. **微服务架构**: 后端采用微服务架构，支持水平扩展
3. **容器化**: 支持Docker容器化部署
4. **自动化部署**: 提供自动化部署脚本和配置
## 维护说明
1. **文档更新**: 任何代码变更都需要同步更新相关文档
2. **版本控制**: 使用Git进行版本控制，遵循语义化版本规范
3. **代码审查**: 所有代码提交都需要经过代码审查
4. **持续集成**: 配置CI/CD流水线，自动化测试和部署
## 相关文档
- [API文档规范标准](./API_DOCUMENTATION_STANDARD.md)
- [API文档检查清单](./API_DOCUMENTATION_CHECKLIST.md)
- [文档维护流程](./DOCUMENTATION_MAINTENANCE_PROCESS.md)
- [系统架构设计](./design/ARCHITECTURE.md)
- [开发计划](./design/DEVELOPMENT_PLAN.md)
---
**最后更新**: 2024年1月20日
**版本**: v1.0.0
### 6.3 DevOps工具
- Git (版本控制)
- Jenkins (持续集成)
- Docker (容器化)
- Kubernetes (容器编排)