HaiLin/ai-ticket-platform

Fork 0

Files

hailin f46369883e docs: consolidate project blueprint

2026-07-14 13:38:52 +08:00

20 KiB

Raw Blame History

AI 工单平台设计沟通记录

日期：2026-06-30
项目目录：E:\JavaCode\ai-ticket-platform
参考旧项目：E:\JavaCode\finance-it-support

1. 文档目的

本文记录从“现有工单系统 AI 能力增强”到“新建 AI-native 技术支持工单产品”的完整讨论过程。它不是逐字聊天稿，而是面向后续产品设计、架构实现和新会话接管的中文决策日志。

后续回顾某个功能点时，优先按本文的主题章节查找讨论背景，再阅读正式设计文档和实施计划。

文档	用途
`docs/product/blueprint.md`	基于本记录与当前代码现状重新规划的唯一主蓝图

2. 初始背景：从现有系统 AI 工单识别开始

最开始的问题是：AI Agent 已经从 prompt 演进到具备一定自主决策能力的 agent，现有项目是否还应该只用工作流实现工单填写和技术支持分析。

对旧项目 finance-it-support 做了上下文调研：

观察点	内容
当前分支	`feat_260626_agent`
近期提交	`feat: 优化AI工单识别回填`
后端 AI 能力	`IssueWorkOrderServiceImpl#createAiApplicationChat` 根据配置路由到 Dify 或 MaxKB
MaxKB 接入	`AiMaxKbService` / `AiMaxKbServiceImpl` 负责创建会话和发送消息
Dify 接入	`AiDifyService` 工作流返回 outputs 后解析 JSON
当前能力本质	输入描述，调用 Dify/MaxKB，解析 JSON，回填工单草稿字段
关键限制	更像“字段抽取和回填”，还不是完整 Agent

讨论结论：

现有能力适合继续作为参考，但不应该成为新产品的架构上限。真正有价值的方向是让 AI 围绕工单生命周期进行受控分析、追问、知识检索、方案推荐、沉淀知识和执行审计。

3. 第一轮产品方向：建单 Agent 与技术支持 Agent

最初提出两个方向：

方向	目标
建单 Agent	帮用户把问题描述转成完整、规范、可处理的工单
技术支持分析 Agent	帮技术人员快速理解问题、查找相似工单、推荐方案、生成排查清单

用户反馈：

两者都需要，但建单人员填写工单占比可能更高，因为很多技术问题仍然需要技术人员手动排查，不能完全交给 Agent。

形成的判断：

建单侧更适合第一批落地，因为它主要做信息结构化、补全、追问和推荐，风险较低。
技术支持侧应定位为辅助分析，不替代人工排查，不默认给最终结论。
Agent 的价值不是“自动处理一切”，而是减少返工、提升信息质量、缩短技术人员进入排查状态的时间。

4. 关键转向：从旧系统增强转为新建长期产品

用户提出新的设想：

新建一个项目，主要目标是技术支持工单。除了工单查询、导出等正常功能外，重点支持配置 Agent、Skill、MCP，并内置向量知识库。后端倾向 Python，AI 接入参考 OpenAI SDK，同时支持自定义渠道的大语言模型、图片理解模型、混合模型和向量模型。

讨论后形成的产品定位：

项目定位	决策
产品类型	面向技术支持场景的 AI-native 工单系统
是否通用 Agent 平台	否，Agent/Skill/MCP 都围绕工单和知识库服务
是否旧系统外挂 AI	否，这是长期新产品
AI 能力边界	可配置、可审计、可替换模型，但业务写入默认人工确认

5. 方案 A 与方案 B：替代旧系统还是 AI 工单中台

讨论了两种路线：

路线	含义	优点	缺点
方案 A：替代当前系统	新 Python 项目负责工单、权限、知识库、AI、审计等全套能力	架构干净，适合长期产品化，AI 可以深度嵌入工单生命周期	初期成本高，需要重做用户、权限、菜单、审计、基础工单能力
方案 B：AI 工单中台	当前 Java 系统仍是主系统，Python 项目只提供 AI/Agent/知识库能力	落地快、风险低、复用现有工单和权限	长期体验容易割裂，受旧系统数据模型限制

用户最终选择：

选择 方案 A：替代当前系统。

用户理由：

想做长期新产品。
不希望被现有系统结构限制。
数据迁移只计划迁移历史工单，其他数据可以重新设计。

对应设计影响：

新项目必须独立目录、独立 Git 仓库。
不追求旧系统字段完全兼容。
历史工单迁移服务于检索、知识沉淀和方案复用，而不是还原旧系统所有业务细节。

6. 后端基础框架讨论

用户担心方案 A 初期成本高，尤其是用户、角色、权限、菜单等基础能力，询问是否可以用 GitHub 现有基础框架。

讨论了三条 Python 技术路线：

路线	判断
Django + Django Ninja	推荐。Django 自带用户、组、权限、Admin、ORM、迁移，适合企业后台底座；Django Ninja 补 API 和 OpenAPI 能力
FastAPI + SQLAlchemy + SQLAdmin + FastAPI Users	AI 服务体验灵活，但基础后台能力需要拼装，产品底座成本更高
Frappe Framework	企业 CRUD 和权限很快，但框架约束强，与 PostgreSQL + pgvector 路线不完全一致

最终建议：

采用 Django + Django Ninja + PostgreSQL/pgvector + Celery/Redis + MinIO。

原因：

新产品首先是企业工单系统，不是纯 AI API 服务。
Django 能显著降低用户、组、权限、后台管理、迁移、审计等基础成本。
AI 能力可以作为独立模块设计，不和 Django Admin 强绑定。

7. 前端框架与 UI 风格讨论

用户表达：

前端希望好看一些。
可以接受 React，不必须使用 Vue。
产品风格更偏企业后台管理系统，因为这是本企业的单独业务场景。
UI 风格偏简约。

讨论过的前端方向：

技术方向	判断
Vue 3 + Arco Design Vue	适合 Vue 团队，后台组件完整，视觉比 Element Plus 更新
Vue 3 + Element Plus	稳妥但默认视觉较传统，需要额外主题设计
React + Ant Design Pro	企业后台成熟，但视觉容易偏传统
React + shadcn/ui + Tailwind	更适合做有设计感的新产品，组件可控性强

最终方向：

采用 React + Vite + Tailwind CSS + shadcn/ui/Radix UI + TanStack Table。

后续用户进一步强调：

前端应拥有自己的组件库，或基于开源组件库建立自己的产品级组件库。所有新开发 UI 必须先有统一主题标准，再进行业务页面开发。

形成硬性原则：

shadcn/ui / Radix UI / Tailwind
        ↓
产品级 Design System
        ↓
业务组件
        ↓
页面

开发规则：

不允许业务页面随意写颜色值。
不允许每个页面自己定义按钮、状态标签、表格样式。
统一主题 token、状态色、优先级色、风险色、表格密度、表单规范。
AI 面板也必须使用统一的 Agent 执行轨迹、知识引用和方案推荐组件。

8. 部署与权限边界

用户确认：

当前只做单企业私有化部署。
不做多租户 SaaS。
用户只需要添加用户组，确保不同角色有不同访问权限。

设计结论：

项目	决策
部署形态	单企业私有化部署
租户模型	不做租户表，不做租户隔离
权限模型	RBAC：用户、用户组、角色、权限点、菜单权限、按钮权限
企业治理	权限和审计一次到位，不作为后期优化项

预置角色：

系统管理员
知识库管理员
技术支持
普通建单人
只读审计员

9. MVP 范围选择

提出过三种 MVP 范围：

方案	内容	结论
A	工单主流程 + 建单 Agent + 知识库检索	太保守，不能体现完整产品架构
B	工单主流程 + 建单 Agent + 支持分析 Agent + Agent 配置台	AI 特征明显，但平台骨架不完整
C	工单、知识库、模型网关、Agent、Skill、MCP、审计都做基础版本	用户选择

用户选择 C：完整平台雏形。

进一步确认：

第一版不是每个模块都做深，而是把系统整体架构布局确定下来。
后续只需要针对具体模块优化升级。
工单和业务知识库是核心重点。
AI 平台能力必不可缺，且必须灵活配置，方便尝试不同模型并比较差异。
企业后台权限应一步落地。

10. 整体架构确定

最终架构从三层扩展为四层：

层级	职责
工单业务层	工单、分类、状态、处理记录、评论、附件、导入导出、统计
业务知识库层	文档知识、历史工单、解决方案、FAQ、系统手册、排查模板
AI 平台能力层	模型渠道、模型配置、Agent、Skill、MCP、向量检索、执行轨迹
企业后台治理层	用户、用户组、角色、菜单权限、按钮权限、操作审计、系统配置

核心原则：

工单和知识库是业务资产，
AI 平台是能力放大器，
权限审计是可信边界。

关键设计边界：

Agent 不直接成为业务主表的主人。
Agent 产生建议、草稿、分析和执行记录。
真正改变工单状态、发布知识、确认解决方案，默认需要用户确认。

11. 核心模块与 MVP 边界

第一版必须具备完整闭环，但每个模块只做必要深度。

模块	第一版必须包含
工单	创建、列表、详情、编辑、状态流转、评论、附件、导出、AI 建单辅助、AI 支持分析
知识库	知识分类、文档上传、解析、切片、Embedding、检索、工单转知识草稿
模型网关	供应商配置、OpenAI-compatible 接口、模型类型、默认模型、Agent 级模型选择、模型测试
Agent	建单 Agent、支持分析 Agent、知识沉淀 Agent
Skill	配置型 Skill，包含 prompt 模板、输入 schema、输出 schema
MCP	服务注册、工具同步、权限控制、工具调用日志、风险等级
企业后台	用户、用户组、角色、菜单权限、按钮权限、操作审计、系统配置

明确不做：

多租户 SaaS
复杂 BPMN 工作流
自动派单闭环
自动关闭工单
任意 Python 代码型 Skill
多 Agent 自主协作
高风险 MCP 自动执行
旧系统字段完全兼容

12. 技术架构与服务边界

最终采用模块化单体，而不是一开始拆微服务。

原因：

第一版模块多，但数据模型和需求仍在定型。
微服务会增加认证、权限、事务、部署、调试和日志复杂度。
模块化单体可以先把边界设计清楚，后续再拆 Agent worker、document worker、embedding worker 等重任务模块。

边界	决策
工单服务与模型	工单服务不直接调用模型，只发起 AI 分析请求
Agent Runtime	负责模型、知识库、Skill、工具调用
知识库	同时服务人和 Agent，引用必须可追溯
模型网关	业务层不关心具体供应商
MCP 工具	默认受控，需绑定 Agent 权限和审计
Agent 输出	默认是建议、草稿和可采纳产物

13. 数据模型讨论：从宽表到瘦主表

最初的数据模型建议里，ticket 主表包含较多字段，例如：

legacy_ticket_id
legacy_source
legacy_raw_data
solution
ai_summary
collaborator_ids

用户指出：

legacy_ticket_id 和 legacy_source 不需要，因为这是新系统，不与旧系统匹配。
这些字段会让核心表过于臃肿。
数据可能堆积，主表不应该什么都放。

修正后的原则：

瘦主表 + 强子表 + AI 产物独立 + 迁移临时化

ticket 主表只回答：

这张工单是什么？
当前处于什么状态？
谁提出？
谁负责？
什么时间创建、解决、关闭？

从主表移出的内容：

内容	目标表或处理方式
旧系统 ID、旧来源、旧原始 JSON	仅放临时迁移 staging，不进入正式业务表
协作人	`ticket_collaborator`
附件	`ticket_attachment`
评论	`ticket_comment`
状态变化和字段变更	`ticket_event`
解决方案	`ticket_resolution` 和 `solution`
AI 摘要和 AI 建议	`ticket_ai_artifact` 和 `agent_run`

14. 解决方案复用设计

用户进一步指出：

解决方案很容易重复。同一个问题经常出现时，解决方案通常相同。

因此将“本次处理结果”和“可复用解决方案”拆开：

表	作用
`ticket_resolution`	记录某张工单最终怎么处理，属于实例级记录
`solution`	记录可复用解决方案，属于知识资产
`ticket_solution_link`	记录工单和解决方案之间的推荐、采纳或参考关系

形成的长期价值：

高频问题可以自然沉淀。
Agent 可以推荐已有 solution。
技术人员采纳后增加引用关系。
可以统计哪些方案最常用、最有效、需要更新。
避免每张工单重复复制大段解决方案文本。

15. 知识库定位

知识库不是 AI 的附属品，而是和工单同级的业务资产。

知识类型分成两类：

类型	内容
文档型知识	手册、FAQ、制度、接口文档、日志说明、系统说明
解决方案型知识	从工单处理中沉淀出来的高价值方案

知识库必须支持：

文档上传
文档解析
文档切片
向量化
结构化知识条目维护
来源追溯
Agent 引用来源展示

16. Agent、Skill、MCP 边界

用户确认继续进入 Agent、Skill、MCP 设计边界。

最终定义：

Agent = 负责任务目标和决策流程
Skill = 可复用的专业能力模板
MCP = 可调用的外部工具接口

内置 Agent：

Agent	目标	自动写业务数据
建单 Agent	帮用户补全工单、追问缺失信息、推荐分类和相似工单	否
支持分析 Agent	帮技术人员生成可能原因、排查步骤、推荐方案和回复草稿	否
知识沉淀 Agent	从已解决工单生成解决方案草稿和知识条目草稿	否

Skill 第一版只做配置型：

名称
描述
适用场景
Prompt 模板
输入 schema
输出 schema
可用知识库和工具范围
启用状态

不做代码型 Skill，原因：

安全风险高。
沙箱复杂。
权限边界难。
审计和回滚成本高。

MCP 第一版原则：

原则	说明
只读优先	先接日志、监控、CMDB、文档等查询类工具
工具授权	Agent 只能调用绑定过的工具
风险分级	low、medium、high
高风险确认	修改配置、执行命令、重启服务等不进入 MVP，或必须人工确认
全量审计	每次调用进入 `tool_call` 和 `agent_step`

17. 前端产品形态

前端定位：

简约、有设计感的企业 AI 工单工作台。

不是传统蓝白后台，也不是聊天工具。核心是让技术支持人员快速理解工单、处理工单、复用知识，并可信地使用 Agent。

导航分组：

工作台
工单
知识库
解决方案
Agent
模型与工具
系统管理

最重要的三个体验：

体验	说明
工单详情 + AI 支持分析	在一个页面中查看工单、评论、附件、相似工单、推荐方案、AI 排查建议和引用来源
创建工单 + 建单 Agent	用户输入自然语言和截图，Agent 生成字段草稿、追问缺失信息、推荐分类和相似问题
模型/Agent 配置与调试	管理员配置模型渠道，对比模型效果，调整 Agent、Skill、知识库和工具权限

设计系统要求：

先建立主题 token，再开发业务页面。
所有业务页面必须使用项目封装组件。
AI 面板不是普通聊天框，而是结构化分析面板。
Agent 执行过程、知识引用、方案推荐必须有统一组件。

18. 开发阶段拆分

最终阶段拆分：

阶段	名称	目标
阶段 0	产品骨架与设计系统	项目初始化、后端/前端底座、RBAC、审计、主题和组件标准
阶段 1	工单主流程	工单闭环、评论、附件、事件、导出、解决方案复用
阶段 2	知识库与向量检索	文档上传、解析、切片、Embedding、检索、知识条目
阶段 3	模型网关与 Agent/Skill	模型供应商、模型测试、多模型对比、Skill、内置 Agent、执行轨迹
阶段 4	MCP 工具与企业可信边界	MCP 注册、工具同步、风险等级、Agent 工具调用、人工确认
阶段 5	历史工单迁移与产品打磨	历史工单导入、向量化、解决方案/知识草稿、统计和试运行打磨

用户确认认可该阶段划分。

19. 新项目仓库创建

用户提出：

这是一个新项目，不希望污染当前项目目录。应新建工程目录，并且所有代码都应该适应 Git 作为版本管理。

实际执行：

项目	内容
新目录	`E:\JavaCode\ai-ticket-platform`
Git 仓库	已执行 `git init`
当前分支	`master`
旧项目影响	未修改 `finance-it-support` 中既有变更

已提交：

Commit	内容
`3a5953c docs: add AI ticket platform design`	创建 README、`.gitignore` 和正式设计文档
`cd20d59 docs: add implementation roadmap and stage 0 plan`	创建实施路线图和阶段 0 详细计划

20. 正式设计文档产出

文档内容包括：

产品定位
核心原则
四层架构
MVP 范围
推荐技术栈
数据模型基线
Agent/Skill/MCP 边界
前端产品形态
设计系统要求
开发里程碑
历史工单迁移
第一版架构验收标准
未决问题

21. 实施计划产出

阶段 0 计划目标：

建立可运行项目底座，包括：

Django 后端项目
Django Ninja API root
health endpoint
accounts/audit/system app
权限种子命令
audit model 和 API
Vite React 前端
Tailwind 主题 token
产品组件预览页
Docker Compose 本地运行环境
.env.example
本地启动文档

22. 当前已经明确的产品约束

主题	约束
产品形态	单企业私有化部署
长期路线	新产品替代旧系统，不做 AI 中台外挂
数据迁移	只迁历史工单，不迁旧权限和旧组织结构
工单表	瘦主表，避免堆积
解决方案	通用 solution 独立，工单通过 link 复用
知识库	与工单同级，是核心业务资产
Agent	默认只建议和生成草稿，不自动写业务数据
Skill	MVP 只做配置型，不做代码型
MCP	只读优先，高风险工具不自动执行
权限	RBAC、用户组、菜单权限、按钮权限一步落地
前端	React 可接受，必须先有统一设计系统
UI 风格	简约、有设计感、企业后台
版本管理	新项目独立 Git 仓库

23. 后续新会话接管建议

建议新会话按以下顺序读取：

README.md
docs/product/blueprint.md
docs/communication/2026-06-30-ai-ticket-platform-discussion-log.md

如果要开始编码，建议从阶段 0 开始，并遵守以下说明：

按 task 逐项执行
每个可验证任务单独提交
不跳过测试和构建验证

24. 当前未决问题

问题	当前状态	建议处理时机
主键使用 bigint 还是 uuid	尚未最终决定	阶段 0/1 建模前决定
前端是否保留 Vite 还是改 Next.js	当前倾向 Vite	阶段 0 开始前确认即可
代码型 Skill	MVP 不做	第二阶段以后重新评估沙箱
高风险 MCP 工具	MVP 不做自动执行	MCP 阶段再设计确认流
工作流引擎	MVP 只做简单状态流转	如果 SLA/升级复杂再引入

25. 复盘结论

本次讨论完成了三个关键收敛：

从“旧系统 AI 增强”收敛为“新建长期 AI-native 技术支持工单产品”。
从“AI 功能堆叠”收敛为“工单 + 知识库 + AI 平台 + 企业治理”的四层架构。
从“泛泛方案”落地为独立 Git 仓库、正式设计文档、实施路线图和阶段 0 执行计划。

后续重点不再是继续扩大愿景，而是从阶段 0 开始把项目底座、设计系统和可运行开发环境做扎实。

20 KiB Raw Blame History Unescape Escape