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

演示流程（照着走）

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

---

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（幂等），几秒内把 20 只产品行情全部刷新，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 且无任何报错

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

0.4 开场前自检（务必做）

两条线互补，都跑一遍：

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

看最后一行：40/40 与 41 项全通过才开始演示。有 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 秒返回：本平台 20 只场内基金的管理费率 0.15%～1.20%/年，并列出 ETF 与 LOF 的差异

这体现什么：客服不是"模型随便聊"，而是检索已发布知识后作答，答案可追溯； 延迟稳定在 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 只持仓）

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

点左侧「我的持仓」「资金流水」「成交明细」各看一眼即可。

⚠️ 刻意不要指着"今日盈亏"讲 —— 该字段目前是占位 0（硬编码，见 §3 同名问答与 SRS Q22）。 讲「持有盈亏」「总市值」「可用资金」这三项，它们都是真实计算的。 被追问时按 §3 的话术回答，不要现编。

场景 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=4.579（真实行情价）、 成交金额 457.90、手续费 0.05、实际扣款 457.95（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
预期	概览：未闭环预警数、高风险数、待处理、已超时

操作顺序（这是核心闭环）：

1. 点预警队列里的某条 → 打开详情；
2. 详情里有八类证据入口：客户、产品、交易、资金流水、持仓、登录记录、预警、通知；
3. 点「确认接收」→ 状态变为已确认；
4. 点「进入调查」→ 状态变为调查中；
5. 点「完成结案」→ 状态变为已结案，并且按风险等级扣减客户行为分。

这体现什么：预警处置是有状态机、有留痕、有连带影响的 —— 不是改个字段。每一步都记审计（谁、何时、做了什么）。

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

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

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

场景 6 · 风控日报（1 min）

操作	风控工作台 → 日报 → 生成
预期	文本流式逐段出现（SSE），完成后可填多个邮箱发送

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

场景 7 · 投顾工作台（1 min）

打开	http://127.0.0.1:8000/portal/employee-advisor/dashboard/
账号	advisor_t / abc12345
预期	一张「投资目标方案书 · 客户 9001」卡片，含发布时间与方案内容

这体现什么：投顾看到的是自己服务的客户的已发布交付物。 数据范围按 sys_customer_assignment 归属关系判定（不是按 data_scope —— 那会把 all 级权限放大成"看全部客户"）。

方案书的审核与发布都要求管理员（admin=True），投顾自己发不出来。 这是有意的复核环节，不是缺陷。

场景 8 · 管理员治理（1.5 min）

打开	http://127.0.0.1:8000/portal/employee-console/workspace/
账号	admin_t / 88888888
预期	四个指标卡 + 六个标签页

挨个点一遍，每处一句话：

标签页	讲解要点
角色权限	五个角色，权限数分别是 admin 59 / advisor 28 / customer 26 / risk_operator 10 / operator 2
配置发布	工具白名单、提示词走发布状态机（校验→审核→激活），不是改配置文件
审计	每一次权限判定、工具调用都有记录
转人工工单	场景 4 建的工单在这里；不返回客户标识与原始对话（脱敏）
模型端点	当前用 deepseek-flash（意图分类）+ qwen 向量（embedding）

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

---

2. 备选场景（时间充足时）

场景	怎么演	体现什么
配置发布四态	管理员工作台建一个草稿版本 → 提交校验 → 审核 → 激活	改配置是走流程的，可回滚
五角色权限对比	用五个账号分别登录，看入口守卫各跳哪里	越权在前端就被挡，服务端还有一层
知识入库	python tools/seed_knowledge_demo.py 后复测场景 1	知识是可运营的，不是写死的
平台体检	python tools/e2e_smoke_test.py	40 项全绿，交付质量可自证

---

3. 可能被问到的问题（建议话术）

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

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

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

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

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

Q：客户看板上的"今日盈亏"为什么是 0？ A：这项本期是占位值，不是真实算出来的，不回避这一点。 代码里 today_profit_loss / today_profit_loss_ratio 目前是硬编码 ZERO （app/service/trade_service.py 的持仓列表 L678、账户看板 L748–749）； 而它旁边的**"持有盈亏"是真算的**（market_value − cost_amount，L660 / L726）。 所以「持有盈亏 / 总市值 / 可用资金」可以照着讲，"今日盈亏"不要当成真实数字念。

是否本期实现已列为待业务确认项（docs/软件需求文档-2026-09-14.md Q22）， 并且已经实测过两条口径的可行性：

口径	数据现状	结论
用行情算（今收 − 昨收）	fin_market_price 只在同步时才写行，实测每个产品只有 2 行	❌ 取不到连续"昨收"
用净值算（今净值 − 上一交易日净值）	fin_nav_history 每个产品 120~160 行连续交易日净值	✅ 建议按这个口径做

⚠️ 同时要讲清语义：净值是日终数据，所以它其实是"最近一个交易日的盈亏"， 不是盘中实时 —— 这一点业务确认时要一并定下来。

💡 时间紧、不想被追问的话：场景 2 讲解时避开"今日盈亏"这一栏， 只讲持有盈亏、总市值、可用资金。万一被直接问到，就按上面这段答， 不要含糊过去也不要现编 —— 它属于"已知且已登记的范围边界"，不是缺陷。

---

4. 出问题怎么办

现象	原因	怎么办
客户下单返回 503 行情已过期	行情快照过期（有效期仅 15 分钟）	python tools/sync_market_prices.py —— 立即生效，无需重启服务
客服一直"繁忙/超时"	Worker 没在跑	看 start.ps1 起的第二个窗口；或 python -m app.worker
改了页面看不到效果	浏览器缓存	Ctrl+F5 硬刷新
知识库问答答不上	向量没同步	确认 Worker 在跑，然后跑 tools/seed_knowledge_demo.py
平台起不来	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            # 全量体检（40 项）
python tools/e2e_smoke_test.py --read-only # 只读体检，不动数据

已知的空数据（演示时别点进去尴尬）

位置	现状
运营工作台	场外邮件 0 条、邮箱未初始化（需要真实邮件源）
管理员 · 画像候选	0 条（需要客户对话触发画像抽取）

端口：API 8000 / MySQL 3306 / Redis 6379 / Milvus 19530