技术路线
按工作台 index.html 自上而下各区块，对应前端事件、HTTP 接口与服务层实现。
1. 页面骨架与静态资源
| 工作台对应 | 整页 docs-shell；三栏 doc-layout（左站点、中主栏、右本页目录） |
|---|---|
| 实现 | web/index.html 结构；样式 web/styles.css；逻辑 web/app.js；主题 web/docs-theme.js（本页仅加载主题脚本） |
| Flask 下发 | api_server.py：GET / 返回 index.html；GET /styles.css、GET /app.js 与根路径相对引用对齐 |
2. 顶下工具带（检索增强 · 会话指标）
| DOM | #useRag 复选框；#metricTotal、#metricHigh 数值 |
|---|---|
| 实现 | app.js 中 refreshToolbarMetrics()：GET /api/performance，取 performance.total 与风险计数中高/紧急之和写入工具带 |
| 服务端 | api_server.py → build_performance_overview(session_store)（src/services/workbench_service.py） |
3. 语音接警（内部流水线）
| DOM | 警情编号/补充字、#ingestAudioFile、#ingestVoiceWorkbenchHint |
|---|---|
| 鉴权 | 若需 Bearer：可将令牌写入 localStorage.plice_internal_token（本页已不提供输入框），或由网关注入；请求头由 internalAuthOnlyHeaders() / internalRequestHeaders() 附带 Authorization、X-Caller-Service、X-Request-Id |
| 主流程 | initWorkbenchVoice() → 选文件后 runVoiceWorkbenchPipeline()：POST /internal/v1/uploads（multipart/form-data，含 auto_process、auto_analyze、use_rag 及接警字段）→ 轮询 GET /internal/v1/media-jobs/{id} → 若有 analyze_job_id 则轮询 GET /internal/v1/jobs/{id} → applyLatestInternalAnalysis() 调 GET …/incidents/{id}/analyze/latest 取结构化结果并复用 renderAnalyzeResultFromApi() |
| 说明 | 工作台不展示 Canonical JSON；流程末仍会 GET /internal/v1/incidents/{id} 取 ASR 等字段回填报警原文。对接排错可直接调该 API。 |
| 后端入口 | api_server.py 注册 build_internal_blueprint(_ingest_service)，前缀 /internal/v1（src/adapters/http/blueprint.py + IngestService） |
4. 警情输入与研判记录
| DOM | #exampleSelect、#alarmText、#analyzeBtn、#analyzeHint、#historyList |
|---|---|
| 文字研判 | 点击「开始研判」→ POST /api/analyze，JSON 体 { alarm_text, use_rag }；成功则 renderAnalyzeResultFromApi() 更新摘要/风险/法律依据等，并 renderHistory() |
| 服务端 | analyze_alarm_with_bukong() → record_analysis()；可选内联布控写入会话；snapshot_bukong_to_session()；返回 markdown、bukong、officer_brief、history（接口仍可能含 disposal_nav，工作台页不展示） |
| 历史列表 | GET /api/history；refreshHistory() 在首屏与研判成功后调用 |
5. 研判结果、关键信息、法律依据
| DOM | #resultMeta、#missingHint、#workBukongHint、#summaryBox、#suggestionBox、#keyInfoBox、#work-bukong-output / #bukongBox、#lawBox |
|---|---|
| 实现 | renderAnalyzeResultFromApi() 拼表与摘要；renderKeyInfo()；mergeBukongFromAnalyze() 根据 bukong 回填表单并写入 #bukongBox；接口 markdown 已含布控（merge_incident_and_bukong_markdown） |
| 数据形状 | 与 services/workbench_service 中研判结构化字段一致（警情类型、风险、摘要、处置建议、法律依据、关键信息等） |
研判记录总览（/judgments）
| 页面 | web/judgments.html、web/judgments.js；左侧窄栏为条目列表，右侧为与研判专页相同的 presentation 布局（共用 ar-presentation-render.js） |
|---|---|
| 列表数据 | GET /api/history?limit=120；前端将返回的 history 逆序后渲染为可点击条目 |
| 详情数据 | 点击条目后 GET /api/analysis-presentation/<analysis_id>，响应含 presentation、analysis_id、user_feedback，由 window.pliceArPresentation.renderAnalysisPresentation() 写入右侧 DOM |
研判专页置信度（模型自评 + 规则校准）
专页与总览右侧仅展示「置信度 N%」，不在界面展示下列长说明；数据仍写入 presentation.ai.confidence_provenance 供排障与审计。
| 实现 | src/services/analysis_confidence.py → build_confidence_bundle()；研判落库时经 attach_confidence_bundle() 写入 result，再进入 presentation |
|---|---|
| 正常路径 |
方法 model_calibrated_blend：取模型自评分 analysis_confidence（整数 1–100）与规则校准分（考察关键信息完整度、报警原文长度、规程检索上下文、摘要/处置建议/法律依据等信号），按权重
0.42（模型）+ 0.58（规则）加权后取整并限制在约 22–96 区间。面向用户的原文案形如：「综合模型自评（例如 85%）与规则信号（例如 80%）加权得到；规则侧考察关键信息完整度、规程上下文与输出充实度。」（百分数为当次计算值，非固定）
|
| 模型说明 | 若模型返回 confidence_rationale，会写入 confidence_provenance.model_rationale；历史上前端曾将其以「（模型说明：…）」拼在置信度说明后，现已不在界面展示 |
| 无自评 | 方法 calibration_only：模型未输出 analysis_confidence 时，展示分为规则校准分；原文案说明以规则信号为主（关键信息、规程检索、摘要建议等） |
| 解析失败 | 方法 parse_fallback：JSON 解析失败时置信度保守压低，原文案提示务必人工复核 |
6. 布控（研判同次输出 + 可选校正）
| DOM | 主区 #work-bukong-output；可选折叠 #work-bukong-adjust 内含 #incidentBg、#suspectDesc、.js-bukong-ex、#bukongBtn、#downloadBukongBtn |
|---|---|
| 会话回填 | loadWorkbenchBukongSnapshot() → GET /api/session-snapshot，与研判返回的 bukong 共用会话态 |
| 手动重算 | POST /api/bukong；成功后 mergeLatestMarkdownWithBukong() 更新主下载用 Markdown |
| 下载 | 主按钮 incident_analysis.md（研判+布控）；bukong_plan.md 为仅布控 |
7. 复核与导出
| DOM | 单选 reviewChoice、#reviewNote、#saveReviewBtn、#downloadMdBtn、#downloadJsonBtn、#reviewHint |
|---|---|
| 保存复核 | POST /api/review，JSON 含 review_choice、review_note、analysis_id、可选 incident_type_override（人工校正类别）→ build_review_record()、save_review_record() |
| 导出 | 研判 Markdown 来自内存态 state.latestMarkdown；复核 JSON 由当前表单与 state.latestResult 组装，均用 downloadText() 本地下载 |
8. 性能统计（独立页 /performance）
| DOM | web/performance.html 中 #sec-perf-main：五卡、风险条、耗时表、复核分布表、#perfScoreTable；web/performance.js 绑定 #refreshPerfBtn |
|---|---|
| 数据拉取 | 工作台 refreshToolbarMetrics() 与性能页 performance.js 共用 GET /api/performance；响应含 performance、risk_counts、elapsed_trend、review_distribution、scorecard |
| 服务端 | build_performance_overview、build_elapsed_trend、build_review_distribution；scorecard 由 api_server._build_scorecard() 组装评审维度行与布控计数 |
9. 关键源码索引
- Flask 与 REST：
api_server.py - 会话与研判/布控/绩效：
src/services/workbench_service.py - 专网内部 API：
src/adapters/http/blueprint.py、src/adapters/ingest/service.py - 性能统计专页：
web/performance.html、web/performance.js - 规格说明：
docs-md/04-说明/PRIVATE_NETWORK_ADAPTER_SPEC.md