一个可本地运行的中文电商售后平台：用户查询订单、咨询 AI、确认售后申请，客服领取并处理工单，管理员维护知识库、账号、工单分配和对话记录。
AI 使用真实接口，不含模拟 AI 开关。 未提供 API 密钥时，账号、订单、物流和工单照常工作；AI 页面明确显示“待配置”。初始化订单和企业资料是演示数据。
需要 Java 21、Maven 3.9+、Node.js 22.12+ 或 24、Docker Desktop（Linux 容器）。首次启动需要下载 Maven、npm 依赖和 Docker 镜像。
在项目根目录运行 PowerShell：
# 仅首次复制；已有 .env 时保留自己的配置
Copy-Item .env.example .env
./scripts/start-local.ps1如果 Windows 执行策略阻止脚本，可仅对当前进程执行 Set-ExecutionPolicy -Scope Process Bypass，再运行上面的启动命令。
脚本启动带持久化卷的 MySQL、Redis，构建并后台启动三个 Java 服务，等待健康检查通过，最后启动前端开发服务器。访问 **http://127.0.0.1:5173**。Java 日志在 logs/。
已构建时使用 ./scripts/start-local.ps1 -SkipBuild；只启动后端使用 -BackendOnly。修改 Java 代码后先运行 ./scripts/stop-local.ps1，再启动构建。修改 .env 后也需要重启 Java 服务。
停止 Java 服务：./scripts/stop-local.ps1。前端在其终端按 Ctrl+C；数据库可用 docker compose stop 停止。普通停止与重启保留全部数据。不要用删除数据卷的命令当作停止命令。
所有初始账号密码为 Aftercare@2026，登录页也提供填入账号按钮。
| 账号 | 角色 | 用途 |
|---|---|---|
customer |
用户 | 五笔示例订单、售后申请、工单和 AI 咨询 |
customer2 |
用户 | 一笔独立订单，用于检查归属隔离 |
agent |
客服 | 领取、留言、内部备注、解决工单和内部知识检索 |
admin |
管理员 | 用户、客服、分配、知识库、模型状态、全部对话 |
注册的新用户拥有独立账号，初始没有订单。示例账号仅在业务库为空时生成；重启不会覆盖密码或业务数据。
| 入口 | 默认地址 |
|---|---|
| Vue 开发页面 | http://127.0.0.1:5173 |
| 网关 | http://localhost:8080/api |
| Business Service / Swagger | http://localhost:8081/swagger-ui/index.html |
| AI Service / Swagger | http://localhost:8082/swagger-ui/index.html |
| 各服务健康检查 | 对应端口的 /actuator/health |
| MySQL | 127.0.0.1:3307 |
| Redis Search + JSON | 127.0.0.1:6380 |
MySQL 业务库为 aftercare_business，AI 库为 aftercare_ai，各服务使用独立账号。Redis 开启 AOF 和 Search/JSON 模块。原始文档默认存放 data/uploads/。数据库和 Redis 使用 Docker 命名卷；后端开发模式的上传文件使用本地目录。
在根目录 .env 中填入后端密钥：
DEEPSEEK_API_KEY=你的DeepSeek密钥
GEMINI_API_KEY=你的GoogleAIStudio密钥
DEEPSEEK_MODEL=deepseek-flash
GEMINI_MODEL=gemini-embedding-2
GEMINI_DIMENSIONS=1536本地模式重新启动 Java 服务；容器模式运行 docker compose --profile full up -d --no-build ai，让新环境变量进入容器。然后用管理员打开“模型连接”，分别测试聊天和向量连接。页面中的“已配置”只表示有密钥，点击测试才会实际调用提供商并显示结果。密钥不经过前端，不会在响应中返回。
然后进入“企业知识库”，为三份初始化资料点击“建立索引”，等待“索引就绪”，再点击“发布”。文档可见范围分别为“客户可见”和“仅内部可见”；不要将内部操作规范改成公开资料。索引操作会产生实际模型调用。
可配置 DEEPSEEK_BASE_URL、GEMINI_BASE_URL、AI_REQUEST_TIMEOUT_SECONDS 和 RAG_SIMILARITY_THRESHOLD。默认关闭 DeepSeek 思考模式。Gemini 使用 Developer API 原生 REST，逐块请求、单块单向量，默认 1536 维，不传旧版 task_type。模型或维度变化后，需要新增版本、重建索引并发布；不同索引不会混用。
无密钥、鉴权失败、额度限制、超时与检索失败均有明确错误提示，不会生成虚构回答。后端机器必须能够访问配置的模型 API 地址。
不安装本地 Java、Maven、Node 时，可由多阶段 Dockerfile 完成构建。先停止本地 Java 服务以释放 8080 端口，再运行：
docker compose --profile full up -d --build
docker compose --profile full logs -f business ai gateway访问 **http://localhost:8090**。Nginx 提供前端并关闭 SSE 缓冲。首次启动请等待 Java 日志显示服务就绪。容器模式的原始文件使用 uploads 命名卷，与本地开发模式的 data/uploads/ 不同；切换模式需要同时迁移原始文件并保持 AI 库中的路径一致。在线编辑的 FAQ 不依赖原始文件路径。
- 用户端：注册登录、历史咨询、订单搜索、物流详情、可编辑售后草稿、确认建单、公开留言、补充信息、取消、关闭、重新打开和评价。
- 客服端：工作概览、待领取与我的工单、关联订单和已分配工单的来源对话、公开回复、内部备注、等待补充与解决、内部知识检索。
- 管理端：统计趋势、全部订单和工单、领取与分配/转派、优先级、账号创建/修改/禁用/重置密码、文档和 FAQ 版本、索引任务与重试、检索测试、对话与工具调用审计、模型连接测试。
- 真实 AI：DeepSeek 流式回答、多轮上下文、按角色开放工具、Gemini 向量检索、真实引用、订单卡片、售后草稿卡片。模型没有创建正式工单或执行任意 SQL 的工具。
- 工单可靠性：数据库事务、确认草稿幂等、领取条件更新、状态校验、内部备注隔离、持久化处理时间线。
common/ JWT、Redis 会话、鉴权过滤器、错误与分页、MyBatis 数据访问
business-service/ 账号、示例订单、物流、草稿、工单、评价、统计
ai-service/ 模型适配、工具、SSE、会话、解析、索引任务、知识检索
gateway/ Spring Cloud Gateway WebFlux、路由、追踪、限流
frontend/ Vue 3 + TypeScript 三角色界面、Playwright
infra/ Java Dockerfile、数据库初始化脚本
scripts/ Windows 启停与测试脚本
docs/ 架构接口、演示步骤、测试说明
sample-documents/ 可上传的示例企业资料
版本：Java 21、Spring Boot 4.0.8、Spring Cloud 2025.1.3、Spring AI 2.0.1、MyBatis Starter 4.0.1、MySQL 8.4、Redis 8.2。前端使用 Vue 3、TypeScript、Vite、Vue Router、Pinia、Element Plus、ECharts。Jedis 显式使用 7.4.1，以满足 Spring AI RedisVectorStore 的 RedisClient 接口要求。npm 依赖由 lockfile 固定。
# Java 单元测试；真实数据库集成测试默认跳过
./scripts/test.ps1
# 使用本地 MySQL、Redis 跑权限、事务、索引、SSE 集成测试
./scripts/test.ps1 -Integration
# 前端类型检查与生产构建
cd frontend
npm.cmd ci
npm.cmd run build
npx.cmd playwright install chromium
npm.cmd run test:e2e前端流协议单元测试：在 frontend 目录执行 npm.cmd run test:unit（Node.js 24）。
浏览器测试需要先启动前后端，默认访问 5173；可通过 APP_URL 修改入口。测试会用演示账号创建验收工单和 FAQ，请对演示数据运行。Java 集成测试使用独立的 aftercare_business_test、aftercare_ai_test 库，真实 Redis Search；只有付费模型的 HTTP 边界使用测试夹具，这些夹具不进入生产应用。
完整操作见 演示步骤，实现细节见 架构与接口，验证范围与待验收项见 测试说明，Docker 与 Windows 启动问题见 本地排障。
本机已通过两家真实模型连接测试和 DeepSeek 订单/物流查询。知识库的中文命中质量、完整售后草稿闭环及不同故障场景仍需按演示步骤继续验收，详见测试说明。支付退款、实时物流接口、多租户、即时人工聊天和扫描件 OCR 不在首版范围；退款、换货、维修结果由客服记录在工单中。
参考官方说明：Spring Cloud、Spring AI DeepSeek、Gemini Embeddings、MyBatis Starter、Redis 8。