370 lines
16 KiB
Markdown
370 lines
16 KiB
Markdown
# SHBL-ERP CRM 小版本升级审查与执行计划
|
||
|
||
生成日期: 2026-05-11
|
||
当前分支: `ui-change`
|
||
适用范围: 下一个小版本迭代，重点是 UI 改进、测试流程补强、安全加固，以及为后续去除 Dify 依赖做架构准备。
|
||
|
||
## 1. 目标与边界
|
||
|
||
本轮小版本不建议直接替换 Dify，也不建议一次性重构所有业务页面。当前系统已经存在可运行的业务骨架，下一步更适合先把基础质量稳住，再做可见的 UI 改进。
|
||
|
||
本轮目标:
|
||
|
||
- 建立更可信的测试与 CI 流程，避免失败被吞掉。
|
||
- 修复 AI 回调和工具接口中明显的鉴权风险。
|
||
- 建立前端设计基座，让后续页面改版有统一标准。
|
||
- 优先重做首页、客户、订单、财务等高频页面的视觉和交互体验。
|
||
- 抽出 AI Provider 适配层，让 Dify 仍可用，同时为后续 OpenAI 标准接口迁移铺路。
|
||
|
||
本轮不做:
|
||
|
||
- 不立即删除 Dify。
|
||
- 不做数据库大迁移。
|
||
- 不大规模改动所有业务逻辑。
|
||
- 不把旧页面全部一次性重写。
|
||
|
||
### UI 参考包审查结论: Aura Finance CRM
|
||
|
||
参考资产: `stitch_aura_finance_crm.zip`。该包包含 `code.html`、`DESIGN.md`、`screen.png` 三个文件，可作为小版本 UI 改进的视觉方向参考。
|
||
|
||
结论: 该方案部分符合本系统改版目标，适合作为“清爽、高端、低噪音、数据表格优先”的视觉标杆，但不能直接作为生产实现照搬。
|
||
|
||
可采纳内容:
|
||
|
||
- 浅色工作台背景、低饱和蓝色主色、深色文字和弱边框的整体基调。
|
||
- 左侧导航、顶部搜索、页面标题、主操作按钮、表格卡片的页面组织方式。
|
||
- 状态标签、金额右对齐、客户名称加辅助信息的表格扫描体验。
|
||
- `DESIGN.md` 中的色彩、间距、字号、阴影、表格密度等 token 思路。
|
||
- `screen.png` 中客户列表页的干净层级，可作为客户、订单、财务列表页的首批改版参考。
|
||
|
||
必须调整内容:
|
||
|
||
- 当前项目是 Vue 3、Vite、Element Plus 技术栈，不能引入 Tailwind CDN 作为生产依赖，也不要直接复制 `code.html`。
|
||
- 不能依赖 Google Fonts、Material Symbols、`lh3.googleusercontent.com` 等远程字体和图片资源；图标优先使用 `@element-plus/icons-vue`，字体使用本地系统字体或经批准的本地字体方案。
|
||
- 参考包是英文静态样张，实际页面必须使用 SHBL CRM 的中文业务文案、现有路由和真实字段。
|
||
- 样张大量使用 `h-screen`、固定侧边栏、固定顶部栏和 12 列表格，必须补充窄屏笔记本和低分辨率下的响应式策略。
|
||
- `DESIGN.md` 建议 16px 到 20px 容器圆角，和本项目业务系统的紧凑风格略有冲突；小版本默认收敛为 8px 主圆角，少量重点容器最高 12px。
|
||
- Glassmorphism 和大阴影只能轻量使用，避免影响性能、可读性和长时间办公体验。
|
||
- 表格必须补齐真实系统需要的加载态、空态、错误态、分页、批量选择、权限控制和操作列，而不是只保留静态展示。
|
||
|
||
## 2. 当前主要问题
|
||
|
||
| 优先级 | 模块 | 现象与证据 | 风险 | 建议 |
|
||
| --- | --- | --- | --- | --- |
|
||
| P0 | AI 回调安全 | `server/app/api/dify_tools.py` 中 Authorization 目前可选，且注释仍提示生产需要补 Dify secret；`ai_coaching.py`、`reports.py`、`customers.py` 中多个 Dify 回调可以写入业务数据。 | 外部请求可能伪造回调，写入客户画像、AI 辅导、报告草稿等数据。 | 所有写入型回调必须增加共享密钥、签名校验或内部网关校验，并记录调用来源。 |
|
||
| P0 | CI 可信度 | `.gitea/workflows/test.yml` 中后端测试命令使用 `pytest ... || echo ...`，测试失败仍可能继续通过；workflow 触发分支未覆盖当前 `ui-change`。 | 真实测试失败不会阻断合并，后续 UI 或接口调整风险放大。 | 去掉吞错逻辑，明确测试失败即失败；补充分支触发规则。 |
|
||
| P1 | Dify 耦合 | `chat.py` 直接调用 Dify chat/workflow 接口，`intent_service.py` 中路由目标硬编码为 `dify_agent`，同时前端 action card、persona、report 等流程依赖 Dify 回调。 | 后续替换 OpenAI 时会牵动前后端多个入口，迁移成本高。 | 先抽 `AIProvider`、`WorkflowRunner`、`ToolAdapter`，保持 Dify 为默认实现。 |
|
||
| P1 | 前端视觉与体验 | `frontend/src/views` 中大量页面使用内联样式，表格高度多处使用固定 `calc(100vh - ...)`，首页和业务页缺少统一布局、间距、色彩和响应式策略。 | 页面观感不统一，窄屏体验差，后续每个页面都要重复修样式。 | 先建立设计变量、页面壳、工具栏、数据表格容器、KPI 卡片等基础组件。 |
|
||
| P1 | 构建环境不一致 | CI 使用 Node 20，`Dockerfile.frontend` 使用 Node 18；Docker 使用 `npm install`，CI 使用 `npm ci`。 | 本地、CI、Docker 构建结果可能不一致。 | 统一 Node 版本和依赖安装方式，优先使用锁文件驱动的 `npm ci`。 |
|
||
| P2 | 配置默认值偏生产风险 | `server/app/core/config.py` 默认 JWT secret、默认 DEBUG 为 true，并写有内部 Ollama 地址；`server/app/main.py` 中 CORS 地址固定。 | 新环境部署时容易沿用不安全默认配置。 | 敏感配置必须由环境变量提供，生产缺失时启动失败。 |
|
||
| P2 | 项目入口历史包袱 | 根目录存在 `app.py`，同时有 `backend/` 和 `server/`，当前 Docker 与 CI 主要使用 `server/`。 | 新开发者容易误判真实后端入口，维护成本上升。 | 文档明确活跃入口；后续小步清理或归档旧入口。 |
|
||
|
||
## 3. 小版本迭代范围建议
|
||
|
||
建议把下一个小版本命名为 `v0.3.0-ui-foundation` 或 `v0.2.1-quality-ui`。如果希望强调 UI 改进，使用 `v0.3.0-ui-foundation` 更清晰。
|
||
|
||
推荐包含 5 条工作线:
|
||
|
||
1. 安全与 CI 加固
|
||
2. 前端设计基座
|
||
3. 高频页面 UI 改进
|
||
4. AI 调用适配层准备
|
||
5. 测试、验收和发布流程
|
||
|
||
## 4. 分阶段执行计划
|
||
|
||
### 阶段 0: 基线确认
|
||
|
||
目标: 确认当前分支、依赖、构建、测试和页面现状，形成可比较基线。
|
||
|
||
任务:
|
||
|
||
- 确认 `ui-change` 分支可正常拉取、提交和推送。
|
||
- 分别执行后端基础检查、前端构建检查。
|
||
- 记录当前首页、客户、订单、财务页面截图，作为 UI 改版对比材料。
|
||
- 将 `stitch_aura_finance_crm.zip` 中的 `screen.png` 作为客户列表视觉参考，但以本项目业务字段和组件体系重新实现。
|
||
- 明确当前部署入口以 `server/`、`frontend/`、`docker-compose.yml` 为准。
|
||
|
||
交付物:
|
||
|
||
- 一组基线截图。
|
||
- 一份当前测试结果记录。
|
||
- 确认可复现的本地启动步骤。
|
||
|
||
### 阶段 1: 安全与 CI 加固
|
||
|
||
目标: 让明显风险先收敛，让自动化测试结果可信。
|
||
|
||
任务:
|
||
|
||
- 修改 `.gitea/workflows/test.yml`，去掉后端测试失败后的吞错逻辑。
|
||
- workflow 触发规则覆盖 `ui-change` 或后续约定的 feature 分支。
|
||
- 统一前端 Node 版本，建议 Docker 与 CI 使用同一大版本。
|
||
- Docker 前端构建改为基于锁文件的 `npm ci`。
|
||
- 为 Dify 回调类接口增加鉴权策略:
|
||
- 请求头共享密钥。
|
||
- 时间戳与签名。
|
||
- 失败请求记录审计日志。
|
||
- 生产环境中强制要求 `SECRET_KEY`、Dify secret、数据库连接等关键配置显式提供。
|
||
|
||
验收标准:
|
||
|
||
- 后端测试失败时 CI 必须失败。
|
||
- 前端构建失败时 CI 必须失败。
|
||
- 未携带合法凭证的写入型 AI 回调返回 401 或 403。
|
||
- 生产模式缺少关键 secret 时服务拒绝启动。
|
||
|
||
### 阶段 2: 前端设计基座
|
||
|
||
目标: 先统一 UI 语言，再改具体页面。
|
||
|
||
建议新增或梳理:
|
||
|
||
- `frontend/src/styles/tokens.css`: 色彩、字号、间距、阴影、圆角、边框、状态色。
|
||
- `frontend/src/styles/layout.css`: 页面宽度、内容区、响应式网格、表格区高度策略。
|
||
- `frontend/src/components/PageShell.vue`: 页面标题、操作区、筛选区、主体区。
|
||
- `frontend/src/components/DataTableShell.vue`: 表格外壳、加载态、空态、分页布局。
|
||
- `frontend/src/components/KpiCard.vue`: 首页和统计页使用的统一指标卡。
|
||
- `frontend/src/components/SectionHeader.vue`: 业务分区标题和辅助操作。
|
||
- Element Plus 主题覆盖文件: 将 Aura 参考包的蓝色、浅色背景、状态色和输入框 focus 效果转译为 Element Plus 变量。
|
||
|
||
设计方向:
|
||
|
||
- 以 Aura Finance CRM 样张为视觉参考，但保留 SHBL CRM 的中文业务系统属性。
|
||
- 保持业务系统的安静、清晰、可扫描，不做营销页风格。
|
||
- 降低深色大面积侧边栏的压迫感，调整为更现代的浅色或低饱和导航。
|
||
- 表格、筛选、操作按钮保持密集但有秩序。
|
||
- 页面内少用嵌套卡片，避免视觉碎片化。
|
||
- 支持至少两档宽度: 桌面端和窄屏笔记本。
|
||
- 主色优先参考 `#0066CC` 和 `#004E9F`，背景参考 `#F5F5F7`、`#F9F9FF`，文字参考深 slate；避免整站变成单一蓝色主题。
|
||
- 主容器圆角以 8px 为默认，重点弹窗或浮层可放宽到 12px；不要使用大面积 16px 到 20px 圆角卡片堆叠。
|
||
|
||
验收标准:
|
||
|
||
- 新页面不再依赖大量内联样式。
|
||
- 高频页面共享同一组布局组件。
|
||
- 主要按钮、表格、筛选区、状态标签风格一致。
|
||
- 1366px、1440px、1920px 宽度下无明显遮挡和错位。
|
||
- 不引入 Tailwind CDN、外部 Google 字体、远程样张图片或与当前 Vue/Element Plus 栈冲突的 UI 依赖。
|
||
|
||
### 阶段 3: 高频页面 UI 改进
|
||
|
||
建议顺序:
|
||
|
||
1. 首页 Dashboard
|
||
2. 客户列表与客户详情
|
||
3. 订单列表与订单详情
|
||
4. 财务相关页面
|
||
5. 产品与设置页面
|
||
|
||
Dashboard 改进方向:
|
||
|
||
- 使用统一 KPI 卡片展示关键指标。
|
||
- 将当前固定 4 列布局改为响应式网格。
|
||
- 把趋势、提醒、待办和最近活动拆成清晰分区。
|
||
- 减少装饰性元素，突出经营信息。
|
||
|
||
客户页面改进方向:
|
||
|
||
- 客户列表优先参考 Aura 样张的结构: 左侧导航、顶部搜索、页面标题、筛选按钮、主操作按钮、表格卡片和底部分页。
|
||
- 强化搜索、筛选、状态、负责人、最近跟进等字段的扫描效率。
|
||
- 客户详情页采用信息区、联系人、跟进记录、AI 画像等分区。
|
||
- AI 画像内容要有更新时间和来源提示。
|
||
- 样张中的 `Customer Index`、`Leads`、`Total Spend` 等英文与金融字段必须映射为本项目真实中文字段，例如客户名称、客户类型、联系人、负责人、订单金额、最近跟进、状态和操作。
|
||
|
||
订单与财务页面改进方向:
|
||
|
||
- 表格操作列更紧凑，金额、状态、日期字段更易读。
|
||
- 固定高度表格改为更稳定的内容区布局。
|
||
- 批量操作和导出入口统一放入工具栏。
|
||
|
||
验收标准:
|
||
|
||
- 至少完成 Dashboard 和一个核心业务列表页的新版 UI。
|
||
- 新旧页面交互流程保持兼容。
|
||
- 表格分页、筛选、查看详情、创建或编辑入口可用。
|
||
- 通过桌面和窄屏截图检查。
|
||
- 客户列表新版截图需要与 Aura 参考图做并排验收: 允许业务字段不同，但层级、留白、表格扫描效率和按钮状态必须达到同一质量级别。
|
||
|
||
### 阶段 4: AI 适配层准备
|
||
|
||
目标: 不移除 Dify，但把未来替换成本降下来。
|
||
|
||
建议后端增加抽象:
|
||
|
||
- `AIProvider`: 统一 chat、stream、structured output 的入口。
|
||
- `WorkflowRunner`: 统一报告生成、客户画像、销售辅导等流程调用。
|
||
- `ToolAdapter`: 统一 CRM 内部工具调用和 action card 生成。
|
||
- `ConversationStore`: 保存会话 ID、provider、外部 conversation ID 的映射关系。
|
||
|
||
第一步实现:
|
||
|
||
- `DifyProvider` 作为默认实现，保持现有行为。
|
||
- `OpenAIProvider` 先提供最小可运行骨架，可通过环境变量关闭。
|
||
- 前端 `FloatingChat` 的响应结构保持稳定，例如 `text`、`conversation_id`、`action_card`。
|
||
|
||
未来大版本迁移方向:
|
||
|
||
- 使用 OpenAI Responses API 作为 chat 和工具编排入口。
|
||
- 使用 OpenAI function calling 映射 CRM 工具能力。
|
||
- 把 Dify workflow 的报告、画像、辅导流程迁移为内部 job 或后端 orchestrator。
|
||
- RAG 或知识库能力可以评估 OpenAI file search、向量库或自建检索方案。
|
||
- 保留 provider 切换能力，避免再次绑定到单一平台。
|
||
|
||
验收标准:
|
||
|
||
- Dify 仍为默认 provider，现有聊天流程不回退。
|
||
- 新增 provider 接口后，业务代码不再直接散落调用 Dify URL。
|
||
- OpenAI provider 可以在测试环境完成最小 chat smoke test。
|
||
|
||
### 阶段 5: 验收、发布与回归
|
||
|
||
目标: 形成每次小版本都能复用的检查清单。
|
||
|
||
必须执行:
|
||
|
||
```powershell
|
||
cd server
|
||
python -m py_compile app/main.py
|
||
python -m compileall app
|
||
python -m pytest tests/ -v --tb=short
|
||
```
|
||
|
||
```powershell
|
||
cd frontend
|
||
npm ci
|
||
npm run build
|
||
```
|
||
|
||
建议执行:
|
||
|
||
```powershell
|
||
docker compose build
|
||
docker compose up -d
|
||
```
|
||
|
||
浏览器回归范围:
|
||
|
||
- 登录页。
|
||
- 首页 Dashboard。
|
||
- 客户列表和详情。
|
||
- 订单列表和详情。
|
||
- 财务列表。
|
||
- 悬浮 AI 聊天入口。
|
||
- 文件导入模板下载。
|
||
- 客户列表 Aura 风格改版页。
|
||
|
||
截图检查尺寸:
|
||
|
||
- 1366 x 768
|
||
- 1440 x 900
|
||
- 1920 x 1080
|
||
- 390 x 844，仅用于确认不会严重溢出，不作为完整移动端目标。
|
||
|
||
UI 参考对比:
|
||
|
||
- 使用 `stitch_aura_finance_crm.zip` 中的 `screen.png` 作为目标风格参考。
|
||
- 新版客户列表需要输出同尺寸或近似比例截图，检查导航、搜索、标题、表格、分页、状态标签和主按钮是否达到参考图的秩序感。
|
||
- 若参考图与业务可用性冲突，优先满足业务效率和真实数据完整性。
|
||
|
||
## 5. 测试流程建议
|
||
|
||
### 后端测试
|
||
|
||
基础检查:
|
||
|
||
```powershell
|
||
cd server
|
||
python -m py_compile app/main.py
|
||
python -m compileall app
|
||
```
|
||
|
||
单元与接口测试:
|
||
|
||
```powershell
|
||
cd server
|
||
python -m pytest tests/ -v --tb=short
|
||
```
|
||
|
||
重点补测:
|
||
|
||
- AI 回调鉴权失败场景。
|
||
- AI 回调鉴权成功但 payload 异常场景。
|
||
- 客户画像写入。
|
||
- 报告草稿写入。
|
||
- 导入模板下载。
|
||
- 登录与 token 校验。
|
||
|
||
### 前端测试
|
||
|
||
基础检查:
|
||
|
||
```powershell
|
||
cd frontend
|
||
npm ci
|
||
npm run build
|
||
```
|
||
|
||
建议补充:
|
||
|
||
- 引入 Playwright smoke test，覆盖登录、首页、客户列表、订单列表、AI 聊天入口。
|
||
- 对新版 Dashboard 和客户页保留截图，用于后续 UI 回归对比。
|
||
|
||
### 集成测试
|
||
|
||
建议通过 Docker Compose 做一次完整启动:
|
||
|
||
```powershell
|
||
docker compose build
|
||
docker compose up -d
|
||
```
|
||
|
||
检查项:
|
||
|
||
- 前端能访问后端 API。
|
||
- CORS 配置符合当前环境。
|
||
- 数据库连接正常。
|
||
- AI provider 配置缺失时有明确错误提示。
|
||
- 生产环境 secret 缺失时服务拒绝启动。
|
||
|
||
## 6. 建议拆分 PR
|
||
|
||
建议按风险从小到大拆分:
|
||
|
||
| PR | 名称 | 内容 |
|
||
| --- | --- | --- |
|
||
| 1 | `ci-test-hardening` | 修正 CI 吞错、统一 Node 版本、补充分支触发。 |
|
||
| 2 | `security-ai-callback-auth` | 为 Dify 回调和工具接口增加鉴权、审计日志和测试。 |
|
||
| 3 | `ui-foundation` | 增加设计变量、页面壳、通用表格容器和 KPI 卡片。 |
|
||
| 4 | `dashboard-refresh` | 重做首页 Dashboard，建立 UI 改版标杆。 |
|
||
| 5 | `customer-page-refresh` | 重做客户列表和详情的关键布局。 |
|
||
| 6 | `ai-provider-interface` | 抽出 AI provider 接口，Dify 作为默认实现，OpenAI provider 保留最小骨架。 |
|
||
|
||
## 7. 完成定义
|
||
|
||
本小版本达到以下条件后可以进入发布候选:
|
||
|
||
- CI 能真实反映后端测试和前端构建结果。
|
||
- 所有写入型 AI 回调都有鉴权。
|
||
- Docker 和 CI 的前端 Node 版本一致。
|
||
- 至少 Dashboard 和一个核心业务页面完成新版 UI。
|
||
- 新 UI 使用统一组件和样式变量。
|
||
- Dify 仍可正常工作，同时后端已有 provider 抽象入口。
|
||
- 后端测试、前端构建、Docker 构建通过。
|
||
- 关键页面完成截图验收。
|
||
|
||
## 8. 推荐先做的第一批任务
|
||
|
||
第一周建议只做基础质量和 UI 基座，不急着改所有页面:
|
||
|
||
1. 修 CI，让失败能失败。
|
||
2. 修 AI 回调鉴权，先堵住 P0 风险。
|
||
3. 统一 Node 和依赖安装流程。
|
||
4. 建立 `tokens.css`、`PageShell.vue`、`DataTableShell.vue`、`KpiCard.vue`。
|
||
5. 将 Aura Finance CRM 的视觉 token 转译为本项目 Element Plus 主题和基础 CSS 变量。
|
||
6. 先重做客户列表页，验证 Aura 风格能否适配真实业务字段。
|
||
7. 重做 Dashboard，形成后续页面参考样式。
|
||
8. 写 3 到 5 个最小 Playwright smoke test。
|
||
|
||
这样做的收益是: 小版本能立刻提升安全性、可维护性和视觉一致性，同时不会把后续 OpenAI 迁移和当前 UI 改版强行绑成一个高风险大改。
|