docs: 项目规范文档+需求文档+CHANGELOG

2026-05-28 17:33:38 +08:00
parent 3dddd36866
commit f79db8ccba
6 changed files with 263 additions and 97 deletions
@@ -0,0 +1,44 @@
+# CHANGELOG
+
+## [v1.0.0] - 2026-05-28
+
+### Added
+- 战略回顾会模块（Phase 1）
+  - 后端聚合API: `GET /maps/{id}/review`
+  - 前端战略回顾会页面（健康度卡片/四维度矩阵/重点关注/改善行动进度）
+  - 左侧栏入口：战略回顾会（分析决策分组）
+  
+- 个人工作台模块（Phase 2）
+  - 后端API: `GET /dashboard/my-dashboard`
+  - 前端个人工作台页面（我的KPI/改善行动/待办提醒）
+  - 角色预设KPI（CEO 5项、财务 4项、业务 3项）
+  - 左侧栏入口：我的工作台（数据基础分组）
+
+- 画布增强（Phase 3）
+  - 目标卡片红黄绿灯状态指示器（圆点+边框颜色）
+  - 维度增删改（行内操作：重命名/换色/换图标/增删列）
+  - KPI标签可点击跳转详情
+  - 目标编辑/删除按钮独立显示
+  - 编辑弹窗新增「管理KPI」跳转按钮
+
+- 帮助支持模块
+  - CMA知识库（术语/公式/实践/FAQ + 全文搜索）
+  - 新手引导（5步遮罩 + 首次登录自动弹出）
+  - 左侧栏入口：帮助支持分组
+
+### Changed
+- 左侧栏菜单重组为5个分组
+  - 数据基础：我的工作台 / KPI字典 / 数据管理
+  - 分析决策：驾驶舱 / 战略地图 / 战略回顾会 / 差异分析 / 成本分析 / 预测模拟 / 预算管理
+  - 行动管理：预警中心 / 改善行动
+  - 系统管理：组织管理 / 用户管理 / 通知配置 / 系统设置
+  - 帮助支持：CMA知识库 / 新手引导
+- 画布维度从硬编码改为动态加载，支持自定义
+
+### Fixed
+- 版本历史加载逻辑（新增 loadVersions 函数）
+
+### Docs
+- 项目 README（技术栈/分支策略/开发流程/部署方式）
+- 需求文档模板
+- 战略回顾会/个人工作台/帮助支持 需求文档
@@ -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/
 ```
@@ -0,0 +1,36 @@
+# 管理会计OS — 需求文档模板
+
+## 模块名称
+
+> 一句话描述该模块解决什么问题
+
+## 用户故事
+
+作为【角色】，我希望【功能】，以便【价值】
+
+## 功能列表
+
+- [ ] 功能点1：描述
+- [ ] 功能点2：描述
+
+## 界面设计
+
+（附原型图或页面布局描述）
+
+## 数据流
+
+（输入→处理→输出的流程说明）
+
+## 验收标准
+
+1. 条件1 → 预期结果
+2. 条件2 → 预期结果
+
+## 关联模块
+
+- 依赖哪些模块
+- 被哪些模块依赖
+
+## 备注
+
+（注意事项、已知限制、后续扩展方向）
@@ -0,0 +1,36 @@
+# 个人工作台
+
+> 为每个用户提供个人维度的KPI看板、改善行动和待办提醒
+
+## 用户故事
+
+作为业务经理/财务人员，我希望登录后第一眼看到我负责的KPI状态、我的改善行动进展，以及需要我处理的待办事项，以便快速开始一天的工作。
+
+## 功能列表
+
+- [x] 我的KPI列表（红黄绿灯+进度条+实际值/目标值）
+- [x] 我的改善行动（状态、进度、逾期标记）
+- [x] 待办提醒（逾期行动+红色预警KPI）
+- [x] 角色预设KPI（CEO/财务/业务各有内置关键指标）
+- [x] 首次登录自动弹出引导遮罩
+
+## 数据流
+
+1. 前端请求 `GET /dashboard/my-dashboard`
+2. 后端匹配 `kpi_definitions.responsible_user` 拿到我的KPI
+3. 补充角色预设KPI（从 `ROLE_PRESET_KPIS` 定义中读取）
+4. 从 `action_plans.assignee` 匹配我的改善行动
+5. 计算逾期和红黄灯生成待办提醒
+
+## 验收标准
+
+- [x] 页面展示用户关联的KPI
+- [x] 页面展示用户关联的改善行动
+- [x] 待办提醒准确（逾期红色、预警黄色）
+- [x] 无关联KPI时显示预设指标
+
+## 后续扩展
+
+- 管理员可配置每个角色的预设KPI列表
+- 增加周报提交功能
+- 增加日历待办视图
@@ -0,0 +1,35 @@
+# 帮助支持模块
+
+> 提供CMA知识库、新手引导和技术支持，帮助用户快速上手
+
+## 用户故事
+
+作为新用户，我希望有知识库可以查阅术语和公式，有引导可以快速上手，以便降低使用门槛。
+
+## 功能列表
+
+### CMA知识库
+- [x] 四个分类：术语解释、计算公式、最佳实践、常见问题
+- [x] 全文搜索（标题+摘要+内容）
+- [x] 点击条目弹出详情（含图文、表格、代码示例）
+- [x] 纯静态内容，无后端依赖
+
+### 新手引导
+- [x] 5步引导遮罩（欢迎→驾驶舱→KPI→战略地图→日常管理）
+- [x] 首次登录自动弹出
+- [x] 快速开始卡片
+- [x] 使用流程概览
+- [x] 视频教程占位（6个视频卡片）
+
+### 技术支持（待实现）
+- [ ] 提交工单（标题、描述、附件）
+- [ ] 工单列表（状态跟踪）
+- [ ] 企微通知管理员
+
+## 验收标准
+
+- [x] 知识库内容完整覆盖管理会计核心概念
+- [x] 搜索功能正常
+- [x] 新手引导首次登录弹出
+- [x] 引导步进前进/后退/跳过正常
+- [x] 所有角色可见（ceo/finance/business/it）
@@ -0,0 +1,33 @@
+# 战略回顾会
+
+> 在战略地图画布基础上，为CEO/财务总监提供周会月会用的复盘视图
+
+## 用户故事
+
+作为CEO/财务总监，我希望进入战略回顾会页面就能看到所有战略目标的红黄绿灯状态、KPI达成情况、改善行动进展，以便在周会月会上快速掌握全局异常并决策。
+
+## 功能列表
+
+- [x] 整体健康度卡片（绿色/黄色/红色目标数量+健康度百分比）
+- [x] 四维度矩阵展示（每个维度下的目标状态、关联KPI实际值/目标值）
+- [x] 需重点关注列表（红色/黄色目标按严重度排序）
+- [x] 改善行动进度表（状态、进度条、逾期标记）
+- [x] KPI详情弹出（实际值、目标值、达成率）
+- [x] 期间切换（本月/本季/本年）
+
+## 数据流
+
+1. 前端请求 `GET /maps/{id}/review`
+2. 后端从 `strategic_maps.dimensions` 读取目标和关联KPI编码
+3. 从 `kpi_definitions` + `kpi_values` 获取KPI定义和最新实际值
+4. 计算每个目标的红黄绿灯状态
+5. 从 `action_plans` 查询关联的改善行动
+6. 返回聚合数据
+
+## 验收标准
+
+- [x] 后端API返回完整的目标状态+KPI值+改善行动
+- [x] 前端页面正常渲染四个维度和目标卡片
+- [x] 红黄绿灯颜色正确
+- [x] 改善行动显示进度和逾期状态
+- [x] 支持从左侧栏直接进入和从画布跳转