crm_project/docs/upgrade-plans/2026-05-11-ui-change-small-version-plan.md

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`。
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: 验收、发布与回归

目标: 形成每次小版本都能复用的检查清单。

必须执行:

cd server
python -m py_compile app/main.py
python -m compileall app
python -m pytest tests/ -v --tb=short

cd frontend
npm ci
npm run build

建议执行:

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. 测试流程建议

后端测试

基础检查:

cd server
python -m py_compile app/main.py
python -m compileall app

单元与接口测试:

cd server
python -m pytest tests/ -v --tb=short

重点补测:

• AI 回调鉴权失败场景。
• AI 回调鉴权成功但 payload 异常场景。
• 客户画像写入。
• 报告草稿写入。
• 导入模板下载。
• 登录与 token 校验。

前端测试

基础检查:

cd frontend
npm ci
npm run build

建议补充:

• 引入 Playwright smoke test，覆盖登录、首页、客户列表、订单列表、AI 聊天入口。
• 对新版 Dashboard 和客户页保留截图，用于后续 UI 回归对比。

集成测试

建议通过 Docker Compose 做一次完整启动:

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 改版强行绑成一个高风险大改。