docs: 项目规范文档+需求文档+CHANGELOG
This commit is contained in:
Hermes CI Fix
@@ -1,117 +1,99 @@
|
||||
# 管理会计OS
|
||||
|
||||
管理会计操作系统，基于 FastAPI + MariaDB + Vue 3 + Element Plus。
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 开发环境
|
||||
|
||||
```bash
|
||||
# 一键启动（前后端同时）
|
||||
./start-dev.sh
|
||||
|
||||
# 或分步启动：
|
||||
# 后端
|
||||
cd backend && ./dev.sh
|
||||
|
||||
# 前端（新终端）
|
||||
cd frontend && ./dev.sh
|
||||
```
|
||||
|
||||
### 生产部署
|
||||
|
||||
```bash
|
||||
# 一键构建+部署
|
||||
./deploy.sh
|
||||
```
|
||||
|
||||
### 访问地址
|
||||
|
||||
| 环境 | 地址 |
|
||||
|------|------|
|
||||
| 开发前端 | http://localhost:5173 |
|
||||
| 开发后端API | http://127.0.0.1:8010 |
|
||||
| 开发API文档 | http://127.0.0.1:8010/docs |
|
||||
| 生产环境 | https://cma.sxbh.ltd |
|
||||
企业级管理会计操作系统，基于BSC平衡计分卡框架，提供从战略制定到日常执行的全流程数字化管理。
|
||||
|
||||
## 项目结构
|
||||
|
||||
```
|
||||
cma-management/
|
||||
├── start-dev.sh # 一键启动开发环境
|
||||
├── deploy.sh # 一键部署生产
|
||||
├── .gitignore
|
||||
│
|
||||
├── backend/
|
||||
│ ├── .env / .env.example
|
||||
│ ├── dev.sh # 后端开发启动
|
||||
│ ├── deploy.sh # 后端部署
|
||||
│ ├── requirements.txt
|
||||
│ ├── app/
|
||||
│ │ ├── main.py # 入口 + 全局异常处理
|
||||
│ │ ├── database.py # 数据库连接池
|
||||
│ │ ├── models/ # SQLAlchemy 模型
|
||||
│ │ ├── api/ # 路由
|
||||
│ │ │ ├── auth.py
|
||||
│ │ │ ├── kpis.py
|
||||
│ │ │ ├── maps.py
|
||||
│ │ │ ├── dashboard.py
|
||||
│ │ │ ├── alerts.py
|
||||
│ │ │ ├── data.py
|
||||
│ │ │ ├── users.py
|
||||
│ │ │ ├── ai_analysis.py
|
||||
│ │ │ └── alert_rules.py
|
||||
│ │ └── utils/
|
||||
│ └── tests/
|
||||
│
|
||||
├── frontend/
|
||||
│ ├── .env / .env.example
|
||||
│ ├── dev.sh # 前端开发启动
|
||||
│ ├── deploy.sh # 前端构建部署
|
||||
│ ├── .prettierrc
|
||||
│ ├── vite.config.ts
|
||||
│ ├── index.html
|
||||
├── frontend/ # Vue3 + Vite + TypeScript + Element Plus
|
||||
│ └── src/
|
||||
│ ├── main.ts
|
||||
│ ├── App.vue
|
||||
│ ├── router/index.ts
|
||||
│ ├── layouts/MainLayout.vue
|
||||
│ ├── views/
|
||||
│ │ ├── Login.vue
|
||||
│ │ ├── Dashboard.vue
|
||||
│ │ ├── KPIList.vue
|
||||
│ │ ├── KPIDetail.vue
|
||||
│ │ ├── MapList.vue
|
||||
│ │ ├── MapCanvas.vue
|
||||
│ │ ├── AlertList.vue
|
||||
│ │ ├── DataManage.vue
|
||||
│ │ └── UserManage.vue
|
||||
│ └── api/index.ts
|
||||
│
|
||||
└── deploy/ # 部署配置
|
||||
│ ├── api/ # axios 接口封装
|
||||
│ ├── layouts/ # 布局组件（左侧栏+顶栏）
|
||||
│ ├── views/ # 页面组件
|
||||
│ ├── router/ # 路由配置
|
||||
│ └── permission.ts # 菜单+角色权限配置
|
||||
├── backend/ # FastAPI + SQLAlchemy + MySQL
|
||||
│ └── app/
|
||||
│ ├── api/ # 路由层
|
||||
│ ├── models/ # 数据模型
|
||||
│ └── utils/ # 工具函数
|
||||
├── docs/ # 需求文档和设计文档
|
||||
├── ARCHITECTURE.md # 架构说明
|
||||
└── CHANGELOG.md # 版本变更记录
|
||||
```
|
||||
|
||||
## 系统架构
|
||||
## 分支策略 (Git Flow)
|
||||
|
||||
```
|
||||
用户 → https://cma.sxbh.ltd → Nginx (Brotli+缓存)
|
||||
├── / → 前端 SPA (Vue 3)
|
||||
└── /api/cma/ → FastAPI:8010 → MariaDB
|
||||
main ─── 生产分支，只从 release 合并
|
||||
develop ─── 开发主分支
|
||||
feature/* ─── 新功能分支，从 develop 拉出，合并回 develop
|
||||
release/* ─── 发布分支，从 develop 拉出，合并到 main + develop
|
||||
hotfix/* ─── 紧急修复，从 main 拉出，合并到 main + develop
|
||||
```
|
||||
|
||||
## 运维命令
|
||||
### 分支命名规范
|
||||
|
||||
- 功能分支：`feature/模块名-简要描述` 如 `feature/战略回顾会-聚合API`
|
||||
- 发布分支：`release/v版本号` 如 `release/v1.1.0`
|
||||
- 修复分支：`hotfix/简要描述` 如 `hotfix/登录token过期`
|
||||
|
||||
## 开发流程
|
||||
|
||||
1. 从 develop 拉出 feature 分支
|
||||
2. 在 feature 分支上开发和测试
|
||||
3. 提交 PR/MR 合并到 develop（至少1人review）
|
||||
4. 从 develop 拉出 release 分支做最终测试
|
||||
5. 发布前更新 CHANGELOG.md
|
||||
6. 合并到 main + 打 tag
|
||||
7. 部署后切回 develop
|
||||
|
||||
## 版本号规范
|
||||
|
||||
遵循语义化版本：`主版本.次版本.修订号`
|
||||
|
||||
- 主版本：不兼容的API/架构变更
|
||||
- 次版本：向下兼容的新功能
|
||||
- 修订号：向下兼容的bug修复
|
||||
|
||||
## 技术栈
|
||||
|
||||
| 层 | 技术 | 说明 |
|
||||
|----|------|------|
|
||||
| 前端框架 | Vue 3 + Vite + TypeScript | 组合式API |
|
||||
| UI组件 | Element Plus | 后台管理组件库 |
|
||||
| 后端框架 | FastAPI | Python异步框架 |
|
||||
| ORM | SQLAlchemy 2.0 | 数据库映射 |
|
||||
| 数据库 | MySQL 8.0 | 主数据存储 |
|
||||
| 缓存 | Redis | Token存储+数据缓存 |
|
||||
| 部署 | systemd + Nginx | 反向代理+服务管理 |
|
||||
|
||||
## 启动方式
|
||||
|
||||
### 后端
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
pip install -r requirements.txt
|
||||
uvicorn app.main:app --host 127.0.0.1 --port 8010
|
||||
```
|
||||
|
||||
### 前端
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
npm install
|
||||
npm run dev
|
||||
```
|
||||
|
||||
### 生产部署
|
||||
|
||||
```bash
|
||||
# 后端
|
||||
systemctl status cma-backend # 查看状态
|
||||
journalctl -u cma-backend -f # 查看日志
|
||||
systemctl restart cma-backend # 重启
|
||||
|
||||
# Nginx
|
||||
nginx -t # 检查配置
|
||||
nginx -s reload # 重载配置
|
||||
systemctl restart cma-backend
|
||||
|
||||
# 前端
|
||||
cd frontend && pnpm dev # 开发
|
||||
cd frontend && pnpm build # 构建
|
||||
cd frontend && npm run build
|
||||
cp -r dist/* /var/www/cma/
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user