# SmartDock 使用指引 以三个角色的完整一天为线索,串起全部功能入口。 ## 0. 登录 浏览器打开系统地址,默认账号(口令 `admin123`): | 账号 | 角色 | 会看到 | |---|---|---| | `admin` | 超级管理员 | 全部菜单 | | `user001` | 成员(张三) | 待办/消息/看板 + AI 助手 | | `user002` | 成员(李四) | 待办/消息/看板 + AI 助手 | | `user003` | 成员(王五) | 待办/消息/看板 + AI 助手 | ## 1. 发布人(管理员/组长)的一天 ### 1.1 建任务并发布 1. 「任务中心 → 任务管理」→ **新建任务**; 2. 填标题/说明/截止日期;**目标成员**填成员 userId(演示账号为 `9100000001,9100000002,9100000003`,逗号分隔,填错的会被拒收); 3. **填报字段**按需增行:字段名 + 类型(文本/数字/日期/单选/多选)+ 是否必填; 单选/多选再填候选值(逗号分隔); 4. 「保存草稿」→ 列表出现新行(草稿态)→ **发布** → 状态变为 **收集中**,成员收到 `新任务` 站内通知。 ### 1.2 收集期 - 「数据看板」双视角统计卡:我发布的任务(草稿/收集中/已关闭)与我的填报(待完成/待审核/已通过/被退回); - 「审核队列」处理待审提交:**通过** 或 **退回**(退回必须填理由);**轨迹** 按时间线回放历次决定; - 决定一经作出,提交人立即收到站内通知(通过/退回)。 ### 1.3 关闭任务 收集结束点「关闭」;若有在途待审提交系统会拦截,先审完再关。 ## 2. 成员的一天 1. 「我的待办」= 收集中且我未交/被退回的任务,点 **去填报**; 2. 详情页按字段定义渲染表单(必填校验),提交后进入 **待审核**; 3. 被退回的任务重新出现在待办,原版本保留在「我的提交历史」,修订后 **提交新版本**; 4. 「我的消息」看通知(新任务/审核结果),点击行即标记已读;顶栏铃铛为最近 8 条 + 未读数。 ## 3. AI 助手(悬浮球) - 按当前页面 + 角色给建议(成员问"我有哪些待办",发布人问"谁还没交"); - 流式回答;可追问、可收藏常用问题; - 联网搜索/思考档位在输入框旁开关(需管理员配置 Key 后可用)。 ## 4. 用户画像与数据分析 「画像与分析」下三个入口(2026-10 起菜单收敛:一级只留两页,其余收进「引擎与运维」折叠组): | 菜单 | 能做什么 | |---|---| | 数据分析 | 使用概览/页面/漏斗/留存/使用明细,读真实业务事件 | | 用户画像 | 看本单位全员名单与画像详情(各维度最新得分 + 历史走势,没产生过操作的人也列出);页内「低分复核」抽屉看低于阈值的主体并确认/驳回,可调复核阈值与「自动记录行为」开关 | | 引擎与运维(折叠组) | 画像工作室(维度/权重治理)、画像 RFM(模型运行与分层)、画像分群、合规中心,以及引擎运维页——数据回放/保留期/身份合并、引擎健康巡检、重算与协议 Schema/测试发送三合一 | 画像与分析读同一套统一记录源(`profile_event.source = 'dcs'`)。接入订单、供应链、工程等系统时, 业务代码直接向事件协议发事件即可,维度/模型/分群对全部业务事件统一生效。 (2026-10-28 单源起)页面级「业务源」切换与「来源管理」入口已退役:来源下拉不再出现在画像页; 存量多源历史数据仍按源保留、可读。 ### 4.0 给你的系统接画像 完整接入指南见 **[profile-integration.md](profile-integration.md)**(挂模块五步、事件编号规则、通用四步设计法+多场景速查表、六坑对照);系统内置的「任务转发」演示模块就是官方参考实现。要点三句: - 接入 = 业务代码里注入 `ProfileEventPublisher` 发事件(同仓 Java 模块);非 Java 项目走「数据分析 → 数据导入」CSV 补录,同样进事件账本; - 发出去之后画像页立刻能看到主体,**分数需要先在「画像工作室」配维度**:未配时不显示分数、标注「未配置打分规则」(不冒充 50 分),从模板卡(活跃度/完成率/内容消费/流失风险)挑一张一键预填、换成自己的事件名即可; - 想先验证格式:「引擎与运维 → 引擎运维 → 引擎管理 → 测试发送」粘一段 JSON 事件数组发一条,发完点「去画像页看效果」。 ## 4.1 数据分析中心 「画像与分析 → 数据分析」:同一本事件账本的流量侧视图,第一个页签是**数据导入**,其余为分析页签: | 页签 | 能看什么 | |---|---| | **数据导入** | CSV 离线补录(最多 5000 行,按 eventUid 幂等)+ 全域总览(跨业务源事件账本直读);外部网站接入能力已于 2026-10-23 移除 | | 使用概览 | 使用次数/人数/会话数/新同事/单页离开率/平均停留 + 趋势 + 终端/浏览器(页面浏览类指标只对接入页面埋点的数据有数) | | 页面与搜索 | 页面浏览量/人数/会话数/占比、搜索词排行、事件分布 | | 路径分析 | 页面间流转路径(进入/去向/跳出页)与步骤明细 | | 活跃分析 | 按日活跃访客与事件量趋势 | | 转化漏斗 | 内置「访问 → 搜索 → 注册」漏斗;可新建/编辑/删除;按访客顺序与窗口计算 | | 持续使用 | 按首见日分组的 7/14/30 天回访热力表 | | 使用明细 | 会话列表(终端/浏览器/单页离开筛选)+ 事件时间线抽屉 | | 自定义分析 | 11 种维度 × 4 种指标(浏览量/人数/会话数/事件数)自由组合 | | 实时看板 | 最近 5 分钟事件流与活跃用户 | 演示数据:前后端启动后执行 `backend/script/demo/seed-analytics-demo.js`(管理员 账号经 CSV 导入端点写入,**同一天内**可重复执行、按 eventUid 幂等,跨天重跑会生成 一批新事件;目标环境需关闭验证码),再点「重建汇总」。 业务系统接入走事件协议(`ProfileEventPublisher`),离线数据走「数据导入 → CSV 补录」。 ## 5. 管理员进阶配置 - **AI 供应商**:「系统 → AI 配置」录入各供应商 base_url + API Key(装好系统后第一步), 再维护模型价格与积分套餐; - **文件安全**:OSS 上传自动过守卫(宏/伪装/敏感词),待审件进「文件审核」队列; 白名单/类目豁免在风控中心配置; - **通知幂等**:业务通知带 dedup_key,重复事件不会给用户刷屏; - **MCP 外部工具**:见 §5.1。 ### 5.1 MCP 外部工具(接入与演示) **是什么**:助手对话里可以调用外部 MCP(Model Context Protocol)服务的工具; `backend/mcp-demo/weather-server.mjs` 是内置演示服务(查天气 + 反问补城市),零 npm 依赖, 需 node ≥ 18,STDIO 传输。 **服务端配置项**(application.yml,均有默认值): | 配置 | 默认 | 说明 | |------|------|------| | `smartdock.mcp.allowed-dirs` | 空(禁用 STDIO 注册) | STDIO 脚本允许目录(绝对路径,逗号分隔,防目录穿越) | | `smartdock.mcp.allowed-http-hosts` | `localhost,127.0.0.1` | HTTP 传输 host 白名单 | | `smartdock.mcp.elicit-timeout-seconds` | 300 | 工具反问的答题等待上限(60–540 钳位) | | `smartdock.mcp.tool-budget-seconds` | 120 | 单次工具调用自身预算(不含答题) | **注册步骤**(管理台 → AI 助手 → AI 助手管理 → 外部工具页签): - STDIO 示例:传输类型选 STDIO,命令 `node`,脚本路径 `["<仓根>/backend/mcp-demo/weather-server.mjs"]`(JSON 数组;脚本须在 allowed-dirs 内); - HTTP 示例:传输类型选 STREAMABLE_HTTP,服务地址 `http://127.0.0.1:3000/mcp` (host 须在白名单);鉴权头填在「请求头」JSON 对象(值加密存储,列表只显示键名); - 保存后打开「立即启用」;同名工具冲突整服务拒收。 **演示验证**:对话问「北京今天天气怎么样」→ 助手调 weather 工具 → 外部工具页签审计表 出现 CALL_OK;`ask_weather` 工具缺城市时会弹「反问卡」(选城市/补充备注),提交后工具 继续执行不中断对话;超时未答自动关闭并记 ELICIT_TIMEOUT。 **下线演练**:外部工具页签关掉「启用」开关(或直接停掉 server 进程)= 下一轮新会话 不再挂载,进行中的对话不受影响;工具开关矩阵里 `mcp:<服务名>` 行配 off 可只对本租户关闭。 **安全边界**:STDIO 仅允许 node + 目录白名单;HTTP host 白名单;请求头值 AES 加密落库、 回显只出键名、管理日志不落请求体;试点只收只读服务(read_only 恒 1),写类工具注解 (readOnlyHint=false 或写类服务)自动进确认卡;调用限频 30 次/分/租户;全部动作留审计 (挂载/调用/限频/反问五类),审计保留 90 天自动清理。 **已知限制**:STDIO 运行时仅 node 且不支持请求头;单次调用多轮反问共享同一预算; 反问卡刷新后丢失(超时自动关闭兜底);工具开关矩阵管到服务粒度(mcp:服务名), 未到单个工具粒度;未声明 readOnlyHint 注解的工具在只读服务(试点恒 1)下默认放行 ——放开写类服务前须逐服务核对注解(注解是服务自声明,防说谎的总闸排在后续版本); 请求头加密密钥随开源代码发布,防护口径是"拿到数据库看不到原文",密钥配置化已立题。 ## 6. 常见问题 - **登录提示 clientid 为空**:用系统自带登录页登录;直接调 API 需携带与前端相同的 clientid 请求头。 - **上传附件进不了审核**:检查文件安全总开关与类目配置(判定序见架构文档 §4)。 - **AI 助手无回答**:先在 AI 配置里启用至少一个供应商并配好 Key。