Files
group_fqcd_jr/docs/44-演示流程.md
T

26 KiB
Raw Blame History

演示流程(照着走)

读者:负责演示的人。本文按"操作 → 看到什么 → 这体现什么"三段式写, 可以直接照着念。 主线时长:约 8 分钟;含讲解约 15 分钟。 全部内容均已实测;标 ⚠️ 的地方是容易翻车的点。

2026-09-14 复核:本文档已按当天实测数据更新四处(「今日盈亏」已实现、投顾推荐方案 已开放自助审核发布、管理员工作台为八个标签页、角色权限数与已知空数据)。数字类结论都标了 实测日期——换环境或换库后要重查。

配套文档(想看"为什么"而不是"怎么演"就看这两份):

  • docs/演示用/全功能流程-大白话版.md —— 从登入讲到六个门户的全部流程,不用术语;
  • docs/演示用/记忆架构与Worker工作流程-大白话版.md —— 记忆链路与后台 Worker 的详细工作流程;
  • docs/演示用/今日盈亏实现说明-2026-09-14.md —— 「今日盈亏」的口径、数据坑与复算命令。

0. 演示前准备

0.1 准备演示数据(首次、或换了机器才需要)

python tools/seed_demo_data.py

10 步:账号权限 → 演示口令 → 客户账户 → 场内行情 → 风控预警样本 → 投顾数据 → 三类发布配置 → 知识库素材。脚本会逐步打印完成/失败。

⚠️ 第 2 步不是幂等的:重跑等于重设密码(bcrypt 每次加盐不同)。

0.2 一条必须知道的硬规则:行情有效期只有 15 分钟

下单要求行情快照落在 15 分钟内(app/service/trade_service.py 的 MAX_QUOTE_AGE), 系统没有任何自动刷新机制 —— 超时后所有委托直接返回 503 行情已过期。

演示时踩过这个坑:明明上午刷过行情,下午演示第一单就 503。

怎么办:start.ps1 已经会替你刷新一次(见 0.3),所以正常不用管。 万一演示中途下单报 503 —— 在新窗口跑一次就行,不用重启任何服务(已实测):

python tools/sync_market_prices.py

它按产品 upsert(幂等),几秒内把**全部产品(当前库里 26 只)**行情刷新,15 分钟窗口重新计时。

不想让启动脚本联网刷行情:start.ps1 -SkipPriceSync

0.3 启动平台

最省事的办法:双击桌面上的 启动金融Agent平台.bat。 不用开 PowerShell、不用敲命令。 (仓库根目录也有一份 启动平台.bat,是同一个东西。)

⚠️ 启动金融Agent平台.bat 在桌面上,不在仓库里(2026-09-14 补注): 仓库中只有 启动平台.bat 这一份(Glob 启动*.bat 只命中它)。 两份内容是同一个东西、由同一个生成器产出:

python tools/make_launcher_bat.py     # 改完 start.ps1 或想换路径就重跑它,桌面与仓库两份一起更新

不要手写那个 bat —— 它必须同时满足 GBK 编码 + CRLF 换行 + 无 BOM, 缺任何一条 cmd 都会解析错乱(LF 换行会把 echo 的说明文字当命令执行, 实测报 AT 命令已弃用、']' 不是内部或外部命令)。

它按顺序做六件事:找解释器 → 检查 MySQL/Redis/Milvus → 刷新行情 → 起两个窗口 → 等 API 真正应答 → 自动开浏览器,然后打印访问入口与账号。

重复双击是安全的:API 按端口判断、Worker 按进程判断,已经在跑的不会起第二份。 演示前如果服务已经开着,直接双击它就等于"刷新行情 + 打开页面"。

想传参数就用命令行(bat 会把参数原样转给 start.ps1):

powershell -ExecutionPolicy Bypass -File start.ps1              # 等价于双击
powershell -ExecutionPolicy Bypass -File start.ps1 -NoBrowser   # 不自动开浏览器
powershell -ExecutionPolicy Bypass -File start.ps1 -Port 8100   # 换端口(8000 被别的程序占了)

它开两个窗口:

窗口 作用 少了它会怎样
API 所有接口与页面 什么都没有
Worker Agent 真正执行、领域事件投递、知识向量同步、记忆抽取与画像投影、会话片段聚合、场外收件 客服对话一直"超时";新知识不进 Milvus(无任何报错);记忆不更新;场外收不到邮件

⚠️ 两个窗口都别关。启动脚本自己的窗口跑完就可以关(服务在独立窗口里)。

注:风控定时扫描不在这个 Worker 里 —— 它是独立进程 (python -m app.worker.risk_scan_scheduler)且默认关闭;演示时用的是风控工作台上的 「扫描」按钮(同步执行,最长 60 秒)。 详细分工见 docs/演示用/记忆架构与Worker工作流程-大白话版.md。

0.4 开场前自检(务必做)

两条线互补,都跑一遍:

python tools/e2e_smoke_test.py --read-only    # 业务链路:登录→下单→成交、风控闭环、客服问答
python tools/portal_api_check.py              # 接口契约:按前端的方式核对每个端点的状态码与字段

看最后一行:40/40 与 41 项全通过才开始演示(用例数会随开发增减, 判断健康的准则是 0 FAIL,不是绝对条数)。有 FAIL 就按 §4 排查。

两者的分工:e2e_smoke_test.py 回答"这条业务走得通吗", portal_api_check.py 回答"接口返回的东西前端能不能正确显示"。 后者是 2026-09-13 那轮"照着接口把前端测一遍"的固化 —— 当时靠它查出 6 个真缺陷 (知识库页永远显示 0 块、详情页 5 行全是 --、配置项首次编辑必然 409、非法场景值冒成 500 等)。 加 --write 会再测一遍写操作(会产生数据);--dangerous 会动生效配置,演示前不要加。

0.5 打开第一个页面

http://127.0.0.1:8000/portal/


1. 主线场景

场景 1 · 访客咨询与知识边界(1.5 min)

打开 http://127.0.0.1:8000/portal/guest/products/
操作 点右下角客服浮窗 → 输入「场内基金的管理费率是多少」→ 发送
预期 约 3–4 秒返回:本平台场内基金的管理费率区间(0.15%~1.20%/年),并列出 ETF 与 LOF 的差异

⚠️ 知识库文案是人工审核入库时的快照(当前 active 知识 24 份、元数据 199 行), 里面写的产品数量可能与产品列表的当前数量不一致。 被问到时如实说:"这是知识库里的内容,知识是人工入库的,产品列表取的是实时数据。" 不要现场改知识库文案来对齐数字。

这体现什么:客服不是"模型随便聊",而是检索已发布知识后作答,答案可追溯; 延迟稳定在 3–4 秒(一次意图分类 + 一次向量检索)。

接着再问一句(体现安全边界):「我的账户里有多少钱?」 → 预期:回复"该服务需要登录后才能查询您的个人信息",不编造账户数字。

产品页的数据来自真实接口(GET /api/v1/products):产品与净值取自 fin_product, 行情由 tools/sync_market_prices.py 从行情源同步,页面底部有来源声明。

⚠️ 两个可能被问到、但其实不是故障的地方:

  • 「最近涨跌」列取的是行情源直接给出的当日涨跌幅(腾讯返回,存在 fin_market_price.change_pct),已接入。若某只显示"暂无",说明它走的是净值降级 路径(源没给涨跌幅),或行情没同步过 —— 跑一次 sync_market_prices.py 即可。 我们不编这个数:缺数据就显示"暂无",而不是 0(0 会被读成"今天平盘")。
  • 产品详情的净值走势图现在是真实数据:fin_nav_history 由 tools/sync_nav_history.py(演示数据第 5 步)从东财净值接口同步,近 120 个交易日。 若图上显示"尚未接入",说明第 5 步没跑 —— 补跑即可,不用重启服务。

场景 2 · 客户资产(1 min)

打开 http://127.0.0.1:8000/portal/customer/login/
账号 cust_t / 123456
预期 自动进资产总览:总资产约 10 万、可用资金、持仓市值(7 只持仓)

这体现什么:持仓按真实行情计价(不是写死的假数);页面底部有数据来源说明。

点顶部导航「我的持仓」「资金流水」「成交明细」「盈亏分析」各看一眼即可。

✅ 「今日盈亏」现在可以直接讲(2026-09-14 起是真实计算,不再是占位 0)。 实测口径与数字(当天数据):cust_t 看板 今日盈亏 −132.70(−0.2528%); 逐只:510300 −94.50、510500 −27.30、159948 −8.80、511810 −1.80、 515450 +2.00、588890 −2.30、160128 0.00。

被追问口径时一句话答:"今天收盘值多少钱 − 昨天收盘值多少钱 − 今天买入花的钱 + 今天卖出收回的钱" (不含手续费);基准优先用行情(和同页的"最新价/市值"同源,客户能自己核对), 行情只有一天的产品回退用净值。 语义上是"最近一个交易日"而不是盘中实时。 想现场证明它没算错:python tools/check_today_profit_loss.py(纯 SQL 独立复算并逐只比对)。 详见 docs/演示用/今日盈亏实现说明-2026-09-14.md。

场景 3 · 客户下单(1.5 min)⭐ 重点

打开 客户页 → 资产总览 → 「去下单」(页面本身就有下单弹窗),或直接用下边的接口
说明 弹窗里填基金代码 / 方向 / 数量即可;接口方式更直观,二者等价
# 演示用:买入 100 份沪深300ETF
$body = '{"product_code":"510300","order_side":"buy","quantity":100}'
$r = Invoke-RestMethod -Uri http://127.0.0.1:8000/api/v1/auth/tokens -Method Post `
     -Body '{"username":"cust_t","password":"123456"}' -ContentType application/json
Invoke-RestMethod -Uri http://127.0.0.1:8000/api/v1/users/me/orders -Method Post `
     -Headers @{ Authorization = "Bearer $($r.data.access_token)"; "Idempotency-Key" = [guid]::NewGuid().ToString("N") } `
     -Body $body -ContentType application/json | ConvertTo-Json -Depth 4

预期:status=已成交;executed_price = 当时的最新行情价(演示前先刷一次行情, 按页面/返回里的真实数字念,别背固定价);成交金额 = 100 × 该价格; 再扣一笔手续费(按费率规则),net_amount 就是实际扣款。

这体现什么:

  • 成交价来自外部行情,不是模拟随机数;
  • 下单前会做适当性校验(风险等级匹配),不匹配直接拒绝;
  • 成交后委托、成交、资金流水、持仓四处同时落账(可当场刷新场景 2 的页面看变化)。

⚠️ 如果返回 503 FUND_QUOTE_UNAVAILABLE → 跑 §0.2 的行情同步。

⚠️ 幂等键只防"同一次请求被重发",在页面上连点两下仍会下两笔(前端每次提交生成新键, 属已知前端缺口)。演示时点一次就好。

场景 4 · 客服对话与转人工(1 min)

操作 客户页右下角浮窗 → 问「基金定投是什么」→ 点「转人工客服」
预期 先得到知识库答案;转人工返回 202,工单进入管理员队列

这体现什么:客户主动请求人工与"答不上来"是两条不同路径 —— 前者建工单, 后者按既定口径引导拨打客服热线(不建工单,符合我们"答不了就转人工、不硬答"的原则)。

场景 5 · 风控预警处置(2 min)⭐ 重点

打开 http://127.0.0.1:8000/portal/employee-console/login/ → risk_t / 666666
预期 概览:未闭环预警数、高风险数、待处理、已超时(2026-09-14 实测:未闭环 7 条 / 预警总数 32 条)

队列空或想现场造一条:页面上的**「扫描」按钮**会同步跑一次风控扫描(最长 60 秒)。 也可以跑 python tools/e2e_smoke_test.py —— 它会自动造一条待处理预警并跑完整闭环。

操作顺序(这是核心闭环):

  1. 点预警队列里的某条 → 打开详情;
  2. 详情里有八类证据入口:客户、产品、交易、资金流水、持仓、登录记录、预警、通知;
  3. 点「确认接收」→ 处置状态不变,只把"确认状态"置为已确认(记录谁、何时看到了这条预警);
  4. 点「进入调查」→ 处置状态:待处理 → 调查中;
  5. 点「完成结案」→ 状态变为已结案(只有"调查中"的才能结案),并且按风险等级扣客户行为分: 低 3 / 中 5 / 高 20(行为分 0–20 封顶)。

另有两个动作可以按需插入:关闭误报(→ 已排除,必须填理由)与升级处理 (只打"已升级"标记,不改处置状态)。

这体现什么:预警处置是有状态机、有留痕、有连带影响的 —— 不是改个字段。每一步都记审计(谁、何时、做了什么),结案还会影响客户行为分。

若队列里没有「待处理」的预警(都已被处置过),跑 python tools/e2e_smoke_test.py —— 它会自动造一条待处理预警并跑完整闭环。

补一步「风控助手」(30 秒,很值得演):点上方「风控助手」标签 → 点预设的 「当前风险概览」按钮 → Agent 调 get_risk_overview 只读工具返回未闭环预警概览, 结尾并声明"以上仅为查询与复核线索,不构成任何已确认、误报、关闭或升级的处置结论, 最终请由风控专员人工复核并留痕"。

这体现什么:Agent 只做只读查询与研判草案,处置动作一律留给人工。 实测这条问法命中的是 risk_overview 意图、置信度 1.0000 —— 是配置好的意图分派,不是让模型自由发挥。

场景 6 · 风控日报(1 min)

操作 风控工作台 → 日报 → 生成
预期 文本流式逐段出现(SSE),一共 9 段;完成后可填多个邮箱发送

这体现什么:长任务走 SSE 流式,而不是让页面转圈等 30 秒。

结尾会标来源:模型可用时是"大模型生成",不可用时自动降级为规则模板并如实标注—— 降级不是报错,被问到就这么讲。 ⚠️ 发送邮件默认是"演练":本机 SMTP 开关默认关着、dry-run 默认开着,所以流程会走完、 状态会返回,但不会真的投递。要真发得先配 SMTP。

场景 7 · 投顾工作台(1 min)

打开 http://127.0.0.1:8000/portal/employee-advisor/dashboard/
账号 advisor_t / abc12345
预期 概览四张卡 + 客户区(页面内置 4 位演示客户:张总/李阿姨/王工/陈医生,对应真实客户号 9101–9104)+ 7 个动作按钮 + 「已发布交付物」

这体现什么:投顾看到的是自己服务的客户的交付物。 数据范围按 sys_customer_assignment 归属关系判定(不是按 data_scope —— 那会把 all 级权限放大成"看全部客户"), 并且有灰度开关:没开放的账号直接 403。

选一个客户点「生成推荐方案」,结果区会给出方案与六步流水线进度。 若候选池为空,页面会把原因写清楚(证据缺失/流动性不够/适当性不匹配/没有客户目标)+ 计数 + 两条出路。

审核与发布的口径(2026-09-14 更新,别再照旧话术讲):

  • 产品推荐方案:投顾可以自助审核 / 驳回 / 发布给客户(本次已开放),管理员复核队列同样能做;
  • 投资目标方案书:投顾做到"录入目标 → 确认目标 → 查看方案书"为止,审核与发布仍归管理员。

没有后端也能演:网址加 ?demo=1 进离线演示模式(本地引擎、无令牌、页面明确标注 "演示模式 · 本地引擎"、方案标"规则模拟,不构成真实推荐")。用它时务必主动说明这是演示模式。

场景 8 · 管理员治理(1.5 min)

打开 http://127.0.0.1:8000/portal/employee-console/workspace/
账号 admin_t / 88888888
预期 四张指标卡(有效角色 / 生效配置版本 / 可用模型端点 / 待人工复核)+ 八个标签页

八个标签页,挨个点一遍,每处一句话:

标签页 讲解要点
角色与权限 五个角色的权限数(2026-09-14 实测):admin 62 / advisor 31 / customer 26 / risk_operator 10 / operator 7;还能按用户 ID 查"服务端实际解析出来的角色与数据范围"
配置与模型 工具白名单、提示词走发布状态机(草稿 → 待审核 → 已审核 → 生效,可回滚;被取代的版本落 superseded),不是改配置文件;模型路由规则也在这里
审计记录 每一次权限判定、工具调用都有记录;没有"看敏感详情"的权限时,详情由服务端脱敏
转人工工单 场景 4 建的工单在这里(当前库里 40 条);不返回客户标识与原始对话(二次脱敏)
画像候选 客服从对话里提炼的画像候选,批准后才进正式记忆
投顾复核 待审的投顾交付物(推荐方案 + 投资方案书)→ 审核通过 / 驳回 / 发布给客户
知识库 上传文档(faq / product / policy)→ 自动切分入库并投向量同步;客服就是靠它作答(当前 active 知识 24 份、知识元数据 199 行)
画像漂移复核 客户重新测评导致画像变化时人工确认是否采纳

这体现什么:权限变更必须过审核流程并留痕 —— 这是金融场景的硬要求, 所以平台刻意不提供"直接改权限"的接口。

⚠️ 三个"前端未接、后端已有"的小缺口,被问到照实说:配置发布页没有"驳回/回滚"按钮、 模型端点页是只读的(当前 3 个端点)、审计页没有筛选框(只看最近 20 条)。


2. 备选场景(时间充足时)

场景 怎么演 体现什么
配置发布四态 管理员工作台建一个草稿版本 → 提交校验 → 审核 → 激活 改配置是走流程的,可回滚
五角色权限对比 用五个账号分别登录,看入口守卫各跳哪里 前端只是体验层,真正的拦截在服务端权限码与数据范围
知识入库 python tools/seed_knowledge_demo.py 后复测场景 1 知识是可运营的,不是写死的
平台体检 python tools/e2e_smoke_test.py 40 项全绿,交付质量可自证
记忆链路 客户连问几轮 → 看 memory_unit 里新增长期记忆 → Worker 投影到 Neo4j/Milvus "记住客户"是可查的,不是模型自己说记住了(见 docs/演示用/记忆架构与Worker工作流程-大白话版.md)
后台排障 停掉 Worker → 客服变"繁忙" → 查 agent_run.status='queued' → 起回 Worker 自动恢复 异步三段式的可观测性

3. 可能被问到的问题(建议话术)

Q:这是真实行情吗? A:行情取自公开数据源(腾讯行情),成交价用的就是它。但交易本身是模拟的 —— 平台是"场内基金模拟交易",不下真实单。

Q:Agent 会不会乱答? A:不会。客服只回答检索到的已发布知识,且有置信度门槛: 命中分数 ≥0.75 直接答;0.55~0.75 之间还要求领先次优 ≥0.07; 不满足就引导人工。宁可转人工也不答错 —— 这是刻意的取舍。

Q:为什么有些问题答不上来? A:知识库是人工审核入库的,目前覆盖交易规则、20 只产品、费率与常见问答。 问不到的地方会转人工,这是设计而不是故障。

Q:数据安全怎么保证? A:三层 —— 前端按权限隐藏入口;服务端每次请求重新解析权限与数据范围(令牌里不带权限); 工单等管理面接口不返回客户标识与原始对话。所有判定都有审计。

Q:为什么不让管理员直接改权限? A:金融场景要求权限变更留痕可追溯,所以统一走配置发布流程(草稿→校验→审核→激活)。

Q:客户看板上的"今日盈亏"是怎么算的? A:2026-09-14 起是真实计算的(此前是占位 0,已修)。一句话口径:

今日盈亏 = 今日市值 − 昨日持仓市值 − 今日买入金额 + 今日卖出金额     (不含交易费用)
昨日持仓数量 = 今日持仓数量 − 今日买入份额 + 今日卖出份额            (由当日成交反推)

基准优先用行情(最近两个交易日收盘价,与同页"最新价/市值"同源、客户能自己核对), 行情只有一天的产品(演示数据里 15911 / 159991-159995)回退用净值。 语义是「最近一个交易日相对前一交易日」的盈亏,不是盘中实时 —— 这句一定要讲, 否则会被当成 bug。

现场可自证:python tools/check_today_profit_loss.py(纯 SQL 独立复算,与接口逐只比对, 不一致会以退出码 1 结束)。实测:cust_t = −132.70(−0.2528%)。 细节见 docs/演示用/今日盈亏实现说明-2026-09-14.md。

💡 当天买卖会让"今日盈亏"包含当日已实现部分(卖出份额仍算"昨收→卖出价", 当日买入的份额只算"买入价→今收")。这是刻意的,不是算错。


4. 出问题怎么办

现象 原因 怎么办
客户下单返回 503 行情已过期 行情快照过期(有效期仅 15 分钟) python tools/sync_market_prices.py —— 立即生效,无需重启服务
客服一直"繁忙/超时" Worker 没在跑 看 start.ps1 起的第二个窗口;或 python -m app.worker
所有页面一起变慢/卡住(不是某一个请求超时,而是客服、风控、看板同时迟钝) 检索层用的是同步 Milvus 客户端,单次 search 卡住会阻塞整个 API 进程(连 Worker 心跳一起停)—— 已知项,见 代码库全面审查报告-2026-09-14.md P1-2 先在 Docker Desktop 确认 Milvus 在跑;不用改代码也不用重启 —— Milvus 恢复后自动正常。这条是「演示版本不修、但要能一眼认出」的典型:平时完全无感,只有 Milvus 抖动时才现形
改了页面看不到效果 浏览器缓存 Ctrl+F5 硬刷新
知识库问答答不上 向量没同步 确认 Worker 在跑,然后跑 tools/seed_knowledge_demo.py
场外发送通知"成功"但对方没收到 SMTP 默认是演练模式(开关关、dry-run 开) 这是刻意配置:要在页面上演示"发送"就走完了;要真发得先配 SMTP(见 §5 已知空数据)
风控扫描报"正在扫描中/忙" 手工扫描与定时扫描共用同一把数据库咨询锁,互斥 等这一轮结束再点(定时扫描默认是关闭的,一般遇不到)
平台起不来 MySQL 没起 看 start.ps1 的依赖检查输出
风控队列没有"待处理"预警 演示样本都被处置过了 python tools/e2e_smoke_test.py(自动造一条)

一条命令定位:

python tools/e2e_smoke_test.py

它逐条打印 6 条线 40 项的结果,FAIL 的那条就是问题所在。


5. 速查

账号

角色 用户名 密码 登录入口
客户 cust_t 123456 /portal/customer/login/
风控专员 risk_t 666666 /portal/employee-console/login/
管理员 admin_t 88888888 同上
投顾 advisor_t abc12345 同上(→ 投顾工作台)
运营 offsite_t offsite123 同上(→ 运营工作台)

⚠️ advisor_t 与 offsite_t 不在 RBAC 种子脚本里(2026-09-14 补注): tools/seed_test_rbac.py 的演示用户只有 4 个——cust_t(9001)、risk_t(9002)、 admin_t(9003)、review_t(9004)。advisor_t(9020) 与 offsite_t(9006) 由 tools/grant_*.py 系列 / 投顾线自己的脚本创建,重跑种子不会重建它们。 换机器时若这两个账号登录失败,先查 sys_user 里到底有没有这两行,而不是查密码。 (此点 docs/40-前端验收清单.md 已有自述。)

另注:sys_user 已改为「存在则更新、不存在才插入」,故重跑种子不会弄丢演示密码。

常用命令

python tools/seed_demo_data.py            # 准备演示数据(10 步,首次/换机器)
python tools/sync_market_prices.py        # 刷行情(15 分钟有效期,下单 503 时补跑)
powershell -ExecutionPolicy Bypass -File start.ps1   # 起 API + Worker(自动刷行情)
python tools/e2e_smoke_test.py            # 全量体检(6 条线 40 项)
python tools/e2e_smoke_test.py --read-only # 只读体检,不动数据
python tools/check_today_profit_loss.py   # 「今日盈亏」纯 SQL 复算并与接口逐只比对
python tools/portal_api_check.py          # 接口契约体检(按前端的方式调,41 项)

已知的空数据 / 会"看着像坏了"的地方(演示时别点进去尴尬;2026-09-14 实测)

位置 现状 原因
运营 · 场外邮件 当前 4 封(不是 0 了),但不会有新的 收件依赖真实可用的邮箱配置与常驻 Worker;发件还依赖 SMTP
运营 · 通知发送 只"演练",不真发 SMTP 开关默认关闭 + dry-run 默认开启
管理员 · 画像候选 0 条 需要客户对话触发候选抽取,且要管理员批准才进正式记忆
投顾 · 客户列表 页面内置 4 位演示客户 前端暂无"查我的客户"接口,真实范围在服务端按归属判定
风控 · 未闭环预警 7 条(总数 32) 想造新的就点页面上的「扫描」

端口:API 8000 / MySQL 3306 / Redis 6379 / Milvus 19530 / Neo4j 7687