chore: 忽略 .zcode 本地目录并更新规则表与开发日志

- .gitignore 新增 .zcode/（ZCode 工具本地配置，不入库） - 更新交通/通信/差旅等财务规则表 - 补充 2026-06-25/26 开发日志（chat UI SaaS 化、主题企业 AI 风格、bug 日志）
2026-06-26 22:42:46 +08:00
parent d5a8f84703
commit 6bdaeed6d4
16 changed files with 415 additions and 0 deletions
--- a/document/development/2026-06-25/feature/chat-ui-saas-styling/CONCEPT.md
+++ b/document/development/2026-06-25/feature/chat-ui-saas-styling/CONCEPT.md
@@ -0,0 +1,31 @@
+# AI 对话 UI 样式重构与 SaaS 化设计方案
+
+为了让 X-Financial AI 助手的对话界面展现更专业的金融与 SaaS 企业化视觉，我们对前端全局的 Markdown 渲染样式进行了重构。
+
+## 设计目标
+- **中性色打底**：对话块背景、边框移除饱和偏色，统一采用 Slate/Neutral 冷灰色调（如 `#f8fafc` 和 `#cbd5e1`）。
+- **降低色彩冗余**：将非必须的高亮蓝色改为中性灰色，各单据卡片仅在状态字样与极淡头部透明底中体现状态点缀，避免彩色杂乱堆积。
+- **界面扁平微阴影**：移除带有斜向彩色发光的阴影与复杂的背景图案，采用 1px 实线描边配合微阴影，契合 Stripe, Jira 等现代 SaaS 产品规范。
+
+## 详细参数定义
+- **引用块 (`blockquote` / `.ai-html-callout`)**：
+  - 边框：`3px solid #cbd5e1`
+  - 背景：`#f8fafc`
+  - 文字：`#334155`
+- **信息网格 (`.ai-html-focus-grid`)**：
+  - 边框：`3px solid #cbd5e1`
+  - 标题颜色：`#475569` (Slate-600)
+- **单据卡片 (`.ai-document-card`)**：
+  - 描边：`1px solid #e2e8f0`
+  - 投影：`0 1px 2px 0 rgba(15, 23, 42, 0.05)`
+  - 头部默认背景：`rgba(241, 245, 249, 0.5)`
+  - 状态点缀色：
+    - `is-success` (Teal-700): `#0f766e`
+    - `is-warning` (Amber-700): `#b45309`
+    - `is-danger` (Red-700): `#b91c1c`
+    - is-pending (Blue-600): `#2563eb`
+
+## 消息排版格式规范
+- **限制 Alert 引用块为单条**：在警示/阻塞状态下，只允许包含一条 `>` 引用块用作 Alert 提示。
+- **列表扁平化**：发起前核对结果等普通多维状态信息，一律不使用 `>` 引用块，合并为标准的无序列表展示，保持界面视觉扁平、整洁。
+- **常规表单数据平铺**：时间、单据编号等字段，均采用扁平加粗文本平铺，不再触发 focus-grid 等具有边框线的额外容器。
--- a/document/development/2026-06-25/feature/chat-ui-saas-styling/TODO.md
+++ b/document/development/2026-06-25/feature/chat-ui-saas-styling/TODO.md
@@ -0,0 +1,9 @@
+# 任务计划 (SaaS 风格视觉优化)
+
+- [x] 优化全局 `blockquote` 与 `.ai-html-callout` 的色彩饱和度，改用 Slate 灰蓝色系打底。
+- [x] 优化 `.ai-html-focus-grid` 信息网格与竖线的亮蓝色调。
+- [x] 移除单据卡片上的 `ai-document-card-bg.png` 渐变背景图。
+- [x] 扁平化单据卡片的描边与中性阴影。
+- [x] 优化卡片语义状态角标与操作链接的 SaaS 蓝及点缀。
+- [x] 优化原生 Markdown 列表 `li::marker` 与表格外包边框的色彩层级。
+- [x] 重构预审与冲突消息的 Markdown 输出格式，消除不必要的 `>` 引用块，攻克“三条大竖杠”的排版痛点。
--- a/document/development/2026-06-25/feature/theme-settings-enterprise-ai-style/CONCEPT.md
+++ b/document/development/2026-06-25/feature/theme-settings-enterprise-ai-style/CONCEPT.md
@@ -0,0 +1,207 @@
+# 主题设置与企业沉稳 AI 模式 概念文档
+
+更新时间：2026-06-25
+
+文档路径：document/development/2026-06-25/feature/theme-settings-enterprise-ai-style/CONCEPT.md
+
+## 功能一句话
+
+将系统设置中的“界面皮肤”升级为“主题设置”，从单纯色板选择扩展为产品体验风格选择，并让 AI 模式在“企业沉稳”主题下呈现更符合企业级 SaaS 的低噪声、结构化、克制风格。
+
+## 背景与问题
+
+当前系统设置里的外观入口仍偏向“界面皮肤”语义，主要表达颜色和视觉皮肤选择。这个命名过窄，无法承载用户希望配置的完整体验风格。
+
+现有 AI 模式默认更接近动感活泼风格，使用较多渐变、明亮色块和活跃视觉标识。它适合演示和助手化体验，但在企业级财务、审批、风控、报销场景中，容易显得色彩过重，不够沉稳。
+
+用户希望在系统设置中明确提供主题类型，至少覆盖：
+
+1. 动感活泼：保留当前这种更有活力、更有 AI 助手感的主题。
+2. 企业沉稳：符合企业 SaaS 风格，尤其 AI 模式下的对话图标、样式和整体风格需要克制、稳定，减少颜色渲染。
+3. 专业智能：作为第三类默认方案，介于前两者之间，保留少量智能化识别感，但整体更收敛。
+
+## 目标与非目标
+
+目标：
+
+- 将“界面皮肤”入口重命名为“主题设置”，让用户理解这里配置的是整体体验风格。
+- 将主题从一组颜色选项收敛成三类可理解的主题类型。
+- 在“企业沉稳”主题下，让 AI 模式呈现企业后台应用的专业感。
+- 保持现有设置保存链路稳定，优先复用当前 appearance 配置和主题变量机制。
+- 为后续进一步扩展租户品牌色、暗色模式、组件密度预留结构边界。
+
+非目标：
+
+- 不重做整个系统设置信息架构。
+- 不一次性重写所有业务页面的视觉风格。
+- 不改变 AI 意图识别、报销流程、审批逻辑和后端业务规则。
+- 不新增复杂的租户级主题发布、审批或版本管理能力。
+- 不引入新的前端主题框架或额外依赖。
+
+## 用户与场景
+
+管理员在系统设置中进入“主题设置”，选择适合当前组织的产品体验风格。
+
+演示、培训、轻量工作台场景可以使用“动感活泼”，保留当前更有活力的 AI 交互表达。
+
+企业正式生产环境可以使用“企业沉稳”，让财务、审批、风控和 AI 对话看起来像成熟的企业应用，而不是营销页或玩具化助手。
+
+希望保留智能化识别但又不希望过度活泼的组织，可以使用“专业智能”。
+
+## 功能能力
+
+主题设置页面需要提供三类主题：
+
+- 动感活泼：当前风格延续，允许渐变、轻动效和更明显的 AI 识别色。
+- 企业沉稳：低饱和色、白灰底、轻描边、少阴影、少渐变，强调信息层级和业务可信度。
+- 专业智能：更克制的智能风格，允许小面积蓝灰、紫灰或品牌色点缀，但避免大面积彩色渲染。
+
+页面文案调整：
+
+- 左侧菜单从“界面皮肤”调整为“主题设置”。
+- 页面标题从“界面皮肤与企业主色”调整为“主题风格与界面体验”。
+- 保存反馈从“界面皮肤已保存”调整为“主题设置已保存”。
+- 说明文案从“皮肤/配色”改为“主题/体验风格”。
+
+AI 模式联动：
+
+- 动感活泼：保留当前 AI 模式视觉语言。
+- 企业沉稳：对 AI 对话区、消息气泡、工具调用状态、思考过程、图标、卡片、提示块做克制化覆写。
+- 专业智能：保留轻量 AI 识别感，但降低渐变、发光、背景装饰和高饱和强调色。
+
+## 方案设计
+
+配置模型优先沿用当前系统设置外观配置，避免为了命名调整引入后端迁移风险。
+
+首期可以继续复用 `appearanceForm.themeSkin` 作为持久化字段，将值从原先色板语义逐步映射为主题语义：
+
+- `vivid`：动感活泼。
+- `enterprise`：企业沉稳。
+- `intelligent`：专业智能。
+
+为了减少现有 CSS 变量和本地存储影响，前端可以在兼容期保留 `themeSkin` 字段，同时在 DOM 上补充更清晰的主题标识：
+
+```text
+document.documentElement.dataset.themeSkin = value
+document.documentElement.dataset.themeMode = value
+```
+
+旧值兼容策略：
+
+- 旧的 `sky`、`blue`、`emerald` 等明亮主题默认映射到“动感活泼”。
+- 旧的 `navy`、`slate` 等偏稳重主题默认映射到“企业沉稳”。
+- 无法识别的值回退到“企业沉稳”，保证生产环境默认更克制。
+
+设置页结构：
+
+- 保留现有表单保存机制。
+- 将原色板卡片改为三张主题选项卡。
+- 每个主题卡展示名称、适用场景、视觉关键词和小型预览。
+- 当前选中主题需要有明确选中态，但避免大面积彩色边框。
+
+企业沉稳 AI 模式样式：
+
+- 通过 `[data-theme-mode="enterprise"]` 或 `[data-theme-skin="enterprise"]` 覆写 `personal-workbench-ai-mode.css` 中的 AI 模式变量。
+- 背景从多层 radial-gradient 收敛为白灰底或极轻线性渐变。
+- 对话气泡使用白底、浅灰描边和稳定文字层级。
+- AI 图标使用低饱和单色或品牌主色的小面积点缀。
+- 思考过程、工具调用、风险提示等区域使用结构化信息块，减少发光、彩色渐变和装饰性元素。
+- 风险、成功、警告等语义色保留，但只在图标、状态条或小面积标签上表达。
+
+专业智能主题样式：
+
+- 保留少量 AI 识别色，例如主色强调、轻量渐变按钮或小面积状态标识。
+- 背景和卡片仍以企业应用的可读性为主。
+- 避免全屏强背景、过多彩色阴影和过密装饰。
+
+## 算法与公式
+
+本功能不涉及复杂算法。
+
+需要定义稳定的主题值映射函数：
+
+```text
+normalizeThemeMode(rawTheme):
+  if rawTheme in ["vivid", "sky", "blue", "emerald", "purple"]:
+    return "vivid"
+  if rawTheme in ["enterprise", "navy", "slate", "gray"]:
+    return "enterprise"
+  if rawTheme in ["intelligent"]:
+    return "intelligent"
+  return "enterprise"
+```
+
+主题应用顺序：
+
+```text
+后端保存值 / 本地缓存值
+  -> normalizeThemeMode
+  -> 写入 appearanceForm.themeSkin
+  -> 写入 root dataset
+  -> 应用 CSS 变量
+  -> AI 模式按 data-theme-mode 覆写组件样式
+```
+
+## 测试方案
+
+前端单元和静态测试：
+
+- 断言系统设置外观入口显示为“主题设置”。
+- 断言页面标题显示为“主题风格与界面体验”。
+- 断言三类主题均可见：动感活泼、企业沉稳、专业智能。
+- 断言企业沉稳主题保存后写入稳定主题值。
+- 断言旧主题值能通过 normalize 逻辑回退到可识别主题。
+- 断言 AI 模式存在企业沉稳主题 CSS 钩子。
+
+构建验证：
+
+- 运行前端构建，确保主题设置改动不破坏现有页面。
+- 运行已有设置相关测试，确保系统设置保存链路不回归。
+
+真实页面验收：
+
+- 打开 `/app/settings?section=appearance`，确认左侧菜单、页面标题、三类主题和保存反馈符合预期。
+- 切换到“企业沉稳”后打开 AI 工作台，确认对话区域、图标、消息、思考过程和提示块明显减少彩色渲染。
+- 切回“动感活泼”，确认现有风格仍可正常展示。
+- 切到“专业智能”，确认介于两者之间，不退化为纯色板换色。
+
+## 指标与验收
+
+功能验收：
+
+- “界面皮肤”在设置入口和页面主标题中完成改名。
+- 用户可以选择三类主题，而不是面对一堆颜色皮肤。
+- 选择主题后刷新页面仍保持选中态。
+- 企业沉稳主题下，AI 模式整体视觉明显更接近企业 SaaS。
+- 动感活泼主题不丢失现有活力风格。
+- 专业智能主题具备独立视觉边界。
+
+设计验收：
+
+- 企业沉稳主题下不出现大面积高饱和渐变背景。
+- AI 对话图标和卡片不依赖强发光、强阴影或多彩背景表达层级。
+- 风险、审批、单据、工具调用等业务信息优先使用结构化排版。
+- 主题卡片文字不溢出，不在移动端产生拥挤或重叠。
+
+工程验收：
+
+- 不新增前端依赖。
+- 不引入后端表结构迁移。
+- 旧主题值有明确兼容策略。
+- 相关测试、构建和真实页面验收通过。
+
+## 风险与开放问题
+
+第三类主题默认命名为“专业智能”。如果后续用户指定更贴合业务的名称，可以只替换展示文案，不影响主题值和实现结构。
+
+仅靠全局 CSS 变量可能无法完全消除 AI 模式的活泼感。企业沉稳主题需要对 AI 模式局部样式做有针对性的覆写。
+
+旧色板值如果直接隐藏，可能让已有用户困惑。首期需要在兼容层处理旧值，并保证保存一次后落到新的三类主题值。
+
+如果后续需要租户品牌色和主题组合，应该把“主题模式”和“品牌主色”拆成两个独立配置，避免再次把体验风格退化成颜色选择。
+
+## 本轮文档记录
+
+本轮已完成主题设置功能的前端实现：系统设置入口改名为“主题设置”，主题选项收敛为“动感活泼 / 企业沉稳 / 专业智能”三类，并通过主题归一化兼容旧色板值。
+
+企业沉稳主题已联动 AI 工作台样式：根节点写入 `data-theme-mode="enterprise"`，AI 模式背景、图标容器、输入框、消息、思考过程和建议动作改为低饱和、轻描边、少渲染的企业 SaaS 风格。
--- a/document/development/2026-06-25/feature/theme-settings-enterprise-ai-style/TODO.md
+++ b/document/development/2026-06-25/feature/theme-settings-enterprise-ai-style/TODO.md
@@ -0,0 +1,69 @@
+# 主题设置与企业沉稳 AI 模式 开发 TODO
+
+更新时间：2026-06-25
+
+文档路径：document/development/2026-06-25/feature/theme-settings-enterprise-ai-style/TODO.md
+
+## 使用规则
+
+- 每个任务都需要关联 `CONCEPT.md` 中的章节，格式为 `[CONCEPT: 章节名]`。
+- 完成实现后再勾选对应任务，不用文档勾选代替代码验证。
+- 涉及真实页面效果的任务，需要在 5173 页面完成验收后再标记完成。
+
+## 1. 调研与边界
+
+- [x] [CONCEPT: 背景与问题] 确认当前设置外观入口仍使用“界面皮肤”语义，后续需要改为“主题设置”。
+- [x] [CONCEPT: 方案设计] 确认当前主题能力主要依赖 `appearanceForm.themeSkin`、主题选项和根节点 dataset。
+- [x] [CONCEPT: 方案设计] 确认企业沉稳 AI 模式主要需要覆写 `personal-workbench-ai-mode.css` 中的背景、对话、图标和提示块样式。
+- [x] [CONCEPT: 风险与开放问题] 梳理旧色板值到三类主题值的完整映射清单。
+- [x] [CONCEPT: 用户与场景] 确认三类主题在设置页中的展示顺序和说明文案。
+
+## 2. 契约与设计
+
+- [x] [CONCEPT: 功能能力] 将主题枚举收敛为 `vivid`、`enterprise`、`intelligent`。
+- [x] [CONCEPT: 功能能力] 明确三类主题的中文名称、适用场景和视觉关键词。
+- [x] [CONCEPT: 方案设计] 设计 `normalizeThemeMode` 兼容函数，保证旧值和未知值都有稳定回退。
+- [x] [CONCEPT: 方案设计] 决定是否新增 `themeMode` 前端概念，并保持与 `themeSkin` 字段兼容。
+- [x] [CONCEPT: 指标与验收] 定义企业沉稳 AI 模式的视觉验收标准。
+
+## 3. 后端实现
+
+- [x] [CONCEPT: 方案设计] 评估后端 settings schema 是否需要补充主题枚举校验。
+- [x] [CONCEPT: 方案设计] 若继续复用 `themeSkin`，确保后端允许新主题值保存。
+- [ ] [CONCEPT: 测试方案] 补充或更新设置持久化测试，覆盖三类主题值。
+- [x] [CONCEPT: 风险与开放问题] 确认不需要数据库结构迁移，并在实现说明中记录。
+
+## 4. 算法/规则实现
+
+- [x] [CONCEPT: 算法与公式] 实现旧主题值到新主题值的 normalize 逻辑。
+- [x] [CONCEPT: 算法与公式] 为未知值设置默认回退策略，优先回退到“企业沉稳”。
+- [x] [CONCEPT: 算法与公式] 确保本地缓存、后端返回值和根节点 dataset 使用同一套归一化结果。
+
+## 5. 前端实现
+
+- [x] [CONCEPT: 功能能力] 将设置左侧菜单“界面皮肤”改为“主题设置”。
+- [x] [CONCEPT: 功能能力] 将页面标题改为“主题风格与界面体验”。
+- [x] [CONCEPT: 功能能力] 将保存反馈和说明文案从“皮肤”语义调整为“主题”语义。
+- [x] [CONCEPT: 功能能力] 将原色板式选项调整为三类主题卡片。
+- [x] [CONCEPT: 功能能力] 为“动感活泼”保留当前视觉风格。
+- [x] [CONCEPT: 方案设计] 为“企业沉稳”新增 AI 模式样式覆写。
+- [x] [CONCEPT: 方案设计] 为“专业智能”新增介于活泼和沉稳之间的样式边界。
+- [x] [CONCEPT: 指标与验收] 检查主题卡片、按钮和说明文字在移动端不溢出、不重叠。
+- [x] [CONCEPT: 方案设计] 保证刷新页面后主题选择和 AI 模式样式仍然一致。
+
+## 6. 测试与验证
+
+- [x] [CONCEPT: 测试方案] 更新设置页相关前端测试，断言“主题设置”和三类主题选项。
+- [x] [CONCEPT: 测试方案] 补充 normalize 逻辑测试，覆盖旧值、未知值和三类新值。
+- [x] [CONCEPT: 测试方案] 补充 AI 模式企业沉稳 CSS 钩子测试或静态断言。
+- [x] [CONCEPT: 测试方案] 运行前端设置相关定向测试。
+- [x] [CONCEPT: 测试方案] 运行 `npm --prefix web run build`。
+- [x] [CONCEPT: 测试方案] 运行 `git diff --check`。
+- [x] [CONCEPT: 测试方案] 在真实 5173 页面验收 `/app/settings?section=appearance`。
+- [ ] [CONCEPT: 测试方案] 在真实 5173 页面验收 AI 工作台三类主题切换效果。
+
+## 7. 文档收尾
+
+- [x] [CONCEPT: 本轮文档记录] 实现完成后更新本文勾选状态。
+- [x] [CONCEPT: 指标与验收] 在最终交付说明中记录测试、构建和真实页面验收结果。
+- [ ] [CONCEPT: 风险与开放问题] 若第三类主题命名发生变化，同步更新概念文档和测试描述。