HaiLin/ai-ticket-platform
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: complete Chinese project documentation

Browse Source
This commit is contained in:
hailin
2026-07-27 19:08:08 +08:00
parent b02d18d3b9
commit 78a70ee7c2
20 changed files with 3441 additions and 654 deletions
Download Patch File Download Diff File Expand all files Collapse all files

82
docs/product/acceptance/blueprint-external-evidence.template.json Normal file
View File

@@ -0,0 +1,82 @@
{
"schema_version": 1,
"gates": {
"stage3_retrieval": {
"status": "not_run",
"verified_at": "",
"reviewer": "",
"artifact_refs": [],
"environment": "postgresql",
"embedding_deployment": "",
"rerank_deployment": "",
"sample_count": 0,
"thresholds_met": false,
"metrics": {
"recall_at_5": 0,
"p95_latency_ms": 0
},
"hnsw": {
"m": 0,
"ef_construction": 0,
"ef_search": 0
}
},
"stage4_distillation": {
"status": "not_run",
"verified_at": "",
"reviewer": "",
"artifact_refs": [],
"sample_count": 0,
"independent_review": false,
"anonymization_review_passed": false,
"published": false,
"retrieved_after_publish": false,
"services": []
},
"stage4_documents": {
"status": "not_run",
"verified_at": "",
"reviewer": "",
"artifact_refs": [],
"failure_recovery_verified": false,
"formats": [],
"services": []
},
"stage6_channel": {
"status": "not_run",
"verified_at": "",
"reviewer": "",
"artifact_refs": [],
"provider": "",
"signature_verified": false,
"inbound_verified": false,
"outbound_verified": false,
"receipt_verified": false,
"idempotency_verified": false
},
"stage6_identity": {
"status": "not_run",
"verified_at": "",
"reviewer": "",
"artifact_refs": [],
"oidc_provider": "",
"ldap_directory": "",
"oidc_login_verified": false,
"group_claim_verified": false,
"failure_fallback_verified": false,
"ldap_directory_sync_verified": false
},
"stage6_production_ops": {
"status": "not_run",
"verified_at": "",
"reviewer": "",
"artifact_refs": [],
"alert_receiver": "",
"backup_schedule": "",
"offsite_storage": "",
"alerts_verified": false,
"backup_schedule_installed": false,
"offsite_encrypted_copy_verified": false
}
}
}

299
docs/product/acceptance/blueprint-readiness.current.json Normal file
View File

@@ -0,0 +1,299 @@
{
"schema_version": 1,
"generated_at": "2026-07-27T09:32:44.783410+00:00",
"status": "not_ready",
"exit_ready": false,
"summary": {
"passed_gate_count": 1,
"total_gate_count": 9,
"remaining_gate_count": 8
},
"gates": [
{
"code": "stage2_intake",
"title": "阶段 2：脱敏真实案例智能建单",
"status": "not_ready",
"source": "database_evaluation",
"reasons": [
"尚未导入启用的脱敏真实案例。"
],
"evidence": {
"schema_version": 1,
"generated_at": "2026-07-27T09:32:44.780018+00:00",
"scope": "anonymized_real",
"status": "not_ready",
"exit_ready": false,
"reasons": [
{
"code": "missing_real_cases",
"message": "尚未导入启用的脱敏真实案例。"
}
],
"modality_coverage": {
"text_case_count": 0,
"image_case_count": 0,
"multi_image_case_count": 0,
"document_case_count": 0,
"mixed_text_image_case_count": 0,
"valid_input_case_count": 0,
"invalid_input_case_count": 0
},
"metrics": {
"include_synthetic": false,
"operational": {
"valid_input_count": 1,
"auto_created_count": 0,
"auto_creation_rate": 0.0
},
"evaluation": {
"enabled_case_count": 0,
"reviewed_case_count": 0,
"coverage_rate": null,
"valid_input_count": 0,
"auto_created_count": 0,
"auto_creation_rate": null,
"correct_field_count": 0,
"evaluated_field_count": 0,
"field_accuracy": null,
"evidence_covered_field_count": 0,
"evidence_field_count": 0,
"evidence_coverage_rate": null,
"correct_timeline_item_count": 0,
"evaluated_timeline_item_count": 0,
"timeline_accuracy": null,
"result_selection": "latest_per_case"
},
"targets": {
"auto_creation_rate": 0.7,
"field_accuracy": 0.9,
"coverage_complete": false,
"auto_creation_rate_met": null,
"field_accuracy_met": null
}
},
"case_results": []
}
},
{
"code": "stage3_support",
"title": "阶段 3：脱敏真实案例支持闭环",
"status": "not_ready",
"source": "database_evaluation",
"reasons": [
"阶段 3 验收数据不可读取，请先在目标环境执行最新数据库迁移"
],
"evidence": {
"status": "not_ready",
"exit_ready": false,
"metrics": {},
"reasons": [
{
"code": "database_schema_unavailable",
"message": "阶段 3 验收数据不可读取，请先在目标环境执行最新数据库迁移"
}
]
}
},
{
"code": "stage3_retrieval",
"title": "阶段 3：PostgreSQL 混合检索与重排",
"status": "not_ready",
"source": "external_evidence_manifest",
"reasons": [
"验收状态尚未标记为 passed",
"verified_at 必须是带时区的 ISO 8601 时间",
"缺少验收人 reviewer",
"artifact_refs 必须包含至少一个非空证据引用",
"thresholds_met 必须为 true",
"embedding_deployment 不能为空",
"rerank_deployment 不能为空",
"sample_count 必须大于 0"
],
"evidence": {
"status": "not_run",
"verified_at": "",
"reviewer": "",
"artifact_refs": [],
"environment": "postgresql",
"embedding_deployment": "",
"rerank_deployment": "",
"sample_count": 0,
"thresholds_met": false,
"metrics": {
"recall_at_5": 0,
"p95_latency_ms": 0
},
"hnsw": {
"m": 0,
"ef_construction": 0,
"ef_search": 0
}
}
},
{
"code": "stage4_distillation",
"title": "阶段 4：真实模型知识蒸馏闭环",
"status": "not_ready",
"source": "external_evidence_manifest",
"reasons": [
"验收状态尚未标记为 passed",
"verified_at 必须是带时区的 ISO 8601 时间",
"缺少验收人 reviewer",
"artifact_refs 必须包含至少一个非空证据引用",
"independent_review 必须为 true",
"anonymization_review_passed 必须为 true",
"published 必须为 true",
"retrieved_after_publish 必须为 true",
"sample_count 必须大于 0",
"services 缺少: embedding, postgresql, rerank, text_model"
],
"evidence": {
"status": "not_run",
"verified_at": "",
"reviewer": "",
"artifact_refs": [],
"sample_count": 0,
"independent_review": false,
"anonymization_review_passed": false,
"published": false,
"retrieved_after_publish": false,
"services": []
}
},
{
"code": "stage4_documents",
"title": "阶段 4：真实文档安全导入闭环",
"status": "not_ready",
"source": "external_evidence_manifest",
"reasons": [
"验收状态尚未标记为 passed",
"verified_at 必须是带时区的 ISO 8601 时间",
"缺少验收人 reviewer",
"artifact_refs 必须包含至少一个非空证据引用",
"failure_recovery_verified 必须为 true",
"formats 缺少: DOCX, LOG, PDF, PPTX, TXT, XLSX",
"services 缺少: clamav, embedding, minio, postgresql"
],
"evidence": {
"status": "not_run",
"verified_at": "",
"reviewer": "",
"artifact_refs": [],
"failure_recovery_verified": false,
"formats": [],
"services": []
}
},
{
"code": "stage6_channel",
"title": "阶段 6：真实企业渠道",
"status": "not_ready",
"source": "external_evidence_manifest",
"reasons": [
"验收状态尚未标记为 passed",
"verified_at 必须是带时区的 ISO 8601 时间",
"缺少验收人 reviewer",
"artifact_refs 必须包含至少一个非空证据引用",
"signature_verified 必须为 true",
"inbound_verified 必须为 true",
"outbound_verified 必须为 true",
"receipt_verified 必须为 true",
"idempotency_verified 必须为 true",
"provider 不能为空"
],
"evidence": {
"status": "not_run",
"verified_at": "",
"reviewer": "",
"artifact_refs": [],
"provider": "",
"signature_verified": false,
"inbound_verified": false,
"outbound_verified": false,
"receipt_verified": false,
"idempotency_verified": false
}
},
{
"code": "stage6_identity",
"title": "阶段 6：真实企业身份与目录",
"status": "not_ready",
"source": "external_evidence_manifest",
"reasons": [
"验收状态尚未标记为 passed",
"verified_at 必须是带时区的 ISO 8601 时间",
"缺少验收人 reviewer",
"artifact_refs 必须包含至少一个非空证据引用",
"oidc_login_verified 必须为 true",
"group_claim_verified 必须为 true",
"failure_fallback_verified 必须为 true",
"ldap_directory_sync_verified 必须为 true",
"oidc_provider 不能为空",
"ldap_directory 不能为空"
],
"evidence": {
"status": "not_run",
"verified_at": "",
"reviewer": "",
"artifact_refs": [],
"oidc_provider": "",
"ldap_directory": "",
"oidc_login_verified": false,
"group_claim_verified": false,
"failure_fallback_verified": false,
"ldap_directory_sync_verified": false
}
},
{
"code": "stage6_production_ops",
"title": "阶段 6：生产告警、调度与异地备份",
"status": "not_ready",
"source": "external_evidence_manifest",
"reasons": [
"验收状态尚未标记为 passed",
"verified_at 必须是带时区的 ISO 8601 时间",
"缺少验收人 reviewer",
"artifact_refs 必须包含至少一个非空证据引用",
"alerts_verified 必须为 true",
"backup_schedule_installed 必须为 true",
"offsite_encrypted_copy_verified 必须为 true",
"alert_receiver 不能为空",
"backup_schedule 不能为空",
"offsite_storage 不能为空"
],
"evidence": {
"status": "not_run",
"verified_at": "",
"reviewer": "",
"artifact_refs": [],
"alert_receiver": "",
"backup_schedule": "",
"offsite_storage": "",
"alerts_verified": false,
"backup_schedule_installed": false,
"offsite_encrypted_copy_verified": false
}
},
{
"code": "stage6_recovery",
"title": "阶段 6：隔离一致性恢复",
"status": "passed",
"source": "recovery_evidence",
"reasons": [],
"evidence": {
"schema_version": 1,
"status": "passed",
"verified_at": "2026-07-27T09:24:21Z",
"compose_project": "ai-ticket-restore-drill-5124",
"backup_id": "20260727T092235Z",
"duration_seconds": 106.57,
"database_smoke": "ticket_and_attachment_restored",
"object_storage_smoke": "marker_restored",
"django_check": "passed",
"artifact_refs": [
"docs/operations/recovery-drill-2026-07-27.md"
]
}
}
]
}

64
docs/product/acceptance/blueprint-readiness.md Normal file
View File

@@ -0,0 +1,64 @@
# 产品蓝图统一验收
## 目的
`report_blueprint_readiness` 将产品蓝图阶段 2～6 的最终退出条件收敛为一个机器可读报告。
报告不会因为工程测试通过而替代真实案例或真实环境证据，也不会把合成案例计入阶段退出。
当前共检查 9 个门槛：
1. 阶段 2 脱敏真实案例智能建单指标。
2. 阶段 3 脱敏真实案例支持闭环指标。
3. 阶段 3 PostgreSQL、Embedding 与重排基准。
4. 阶段 4 真实模型知识蒸馏、独立审核、发布与重新检索。
5. 阶段 4 MinIO、ClamAV、PostgreSQL、Embedding 和六类文档导入。
6. 阶段 6 企业渠道签名、收发、回执与幂等。
7. 阶段 6 OIDC、组织声明、故障降级与 LDAP 目录同步。
8. 阶段 6 真实告警、备份调度与异地加密副本。
9. 阶段 6 数据库与对象存储隔离一致性恢复。
## 准备证据
阶段 2、3 的业务指标从平台评审记录实时计算。先按对应说明导入案例并逐案评审：
- `stage2-evaluation.md`
- `stage3-evaluation.md`
其余真实环境验收从以下模板开始：
```powershell
Copy-Item `
docs/product/acceptance/blueprint-external-evidence.template.json `
docs/product/acceptance/blueprint-external-evidence.json
```
只能填写验收结果、环境代号、指标和证据文件引用。清单会递归拒绝字段名包含
`password`、`secret`、`token` 或 `credential` 的内容，不得在其中保存任何真实凭据。
每个通过项必须包含带时区的 `verified_at`、`reviewer` 和至少一个 `artifact_refs`。
## 运行
目标数据库必须先应用当前迁移：
```powershell
cd backend
python manage.py migrate
python manage.py report_blueprint_readiness `
--evidence ../docs/product/acceptance/blueprint-external-evidence.json `
--output ../docs/product/acceptance/blueprint-readiness.current.json
```
CI 或正式退出评审使用非零退出码阻断未满足项：
```powershell
python manage.py report_blueprint_readiness `
--evidence ../docs/product/acceptance/blueprint-external-evidence.json `
--format json `
--fail-on-not-ready
```
若数据库未迁移、证据文件缺失、契约字段不完整、恢复记录无效或任一业务指标未达标，
命令都会输出 `not_ready`。只有 9 个门槛全部通过时，顶层 `exit_ready` 才会为 `true`。
仓库中的 `blueprint-readiness.current.json` 是当前环境快照，不是永久通过证明；每次正式
验收都应重新生成，并保留它引用的原始指标、运行日志、截图或审批记录。

63
docs/product/acceptance/stage2-evaluation.md Normal file
View File

@@ -0,0 +1,63 @@
# 阶段 2 智能受理评估说明
该目录提供可重复执行的评估框架。`stage2-sample-cases.json` 仅包含合成脱敏样例，
用于验证导入、比对和指标计算，不得作为“脱敏真实案例集已验收”的证据。
`stage2-real-cases.template.json` 是禁用状态的真实案例结构模板，也不能直接作为证据。
## 真实案例要求
技术支持提供的案例应设置 `source_kind` 为 `anonymized_real`，并在导入前确认：
- 原始聊天、截图、日志和文档已经移除客户名称、账号、手机号、IP、业务编号等标识；
- `expected_fields` 由技术支持人工标注，而不是复制模型输出；
- `valid_input`、`expected_auto_created` 和 `expected_similar_ticket` 有明确审核结论；
- 对聊天顺序和业务时间有要求时提供 `expected_timeline`；时间原文、解析值与时区分开标注；
- 同一个案例可以对应多次受理运行，但指标会保留每次运行结果以便审计。
真实案例文件还需要覆盖以下输入组合，否则阶段退出报告会保持 `not_ready`：
- 至少一个图片案例；
- 至少一个文本加图片混合案例；
- 至少一个文档或日志案例；
- 至少一个无效输入案例，用于验证追问与人工接管路径。
## 执行流程
```powershell
cd backend
python manage.py import_intake_evaluation_cases ..\docs\product\acceptance\stage2-cases.json
python manage.py record_intake_evaluation --case <case-key> --draft <draft-public-id>
python manage.py report_stage2_acceptance --output ..\reports\stage2-acceptance.json
```
指标接口：`GET /api/tickets/intake-quality-metrics`。默认只统计
`anonymized_real` 案例；显式传入 `include_synthetic=true` 才会包含合成样例。
CI 或正式验收应增加严格退出检查：
```powershell
python manage.py report_stage2_acceptance `
--output ..\reports\stage2-acceptance.json `
--fail-on-not-ready
```
该命令仅在真实案例评审覆盖完整、输入模态覆盖完整、自动建单率和字段准确率达标，
且非空评估字段全部有证据时返回成功。使用 `--include-synthetic` 时报告状态固定为
`diagnostic`，永远不会把合成案例判定为阶段退出证据。
指标口径：
- 运行态自动建单率：所有 `problem_valid=true` 的非拒绝、非过期受理中，
`decision=auto_created` 且关联正式工单的比例。
- 案例集自动建单率：有效案例结果中实际自动建单的比例。
- 字段准确率：所有已评估字段中，与人工基准归一化后完全一致的字段比例；
按字段数量加权，不对空案例伪造 100%。
- 字段证据覆盖率：非空预期字段中，存在材料引用、原文摘录、定位、原始值或生成规则
的字段比例；该指标用于审计证据链，不替代字段准确率。
- 消息时间线准确率：按预期顺序逐项比对人工标注的角色、内容、时间原文、解析时间和
时区；案例可只声明需要核对的键。
- 同一案例存在多次评审运行时，当前质量指标只使用最新一次结果；历史结果仍保留用于
审计，避免旧模型运行与当前版本混算。
- 自动建单率和字段准确率只有在所有启用案例都完成评审后才返回达标/未达标结论；
覆盖不完整时达标状态保持 `null`。
- 真实案例未导入或未执行时，相关比率返回 `null`，达标状态也返回 `null`。

145
docs/product/acceptance/stage2-real-cases.template.json Normal file
View File

@@ -0,0 +1,145 @@
{
"schema_version": 1,
"description": "阶段 2 脱敏真实案例模板。复制为 stage2-cases.json、替换全部 REPLACE_* 内容并完成脱敏复核后再导入；本模板全部 disabled，不能直接作为验收证据。",
"cases": [
{
"key": "real-mixed-images-REPLACE_001",
"name": "文本加多图混合输入",
"source_kind": "anonymized_real",
"valid_input": true,
"input_manifest": {
"source_text": "REPLACE_脱敏后的补充说明",
"materials": [
{
"file_name": "REPLACE_chat-01.png",
"type": "png"
},
{
"file_name": "REPLACE_chat-02.png",
"type": "png"
}
],
"anonymization_review": {
"reviewer": "REPLACE_复核人",
"reviewed_at": "REPLACE_YYYY-MM-DD",
"removed_identifiers": [
"客户名称",
"账号",
"手机号",
"IP",
"业务编号"
]
}
},
"expected_fields": {
"description": "REPLACE_人工标注的问题描述",
"category_code": "REPLACE_business_issue|technical_issue|data_issue|operation_issue",
"environment": "REPLACE_明确环境或空字符串",
"problem_started_at": "REPLACE_带时区 ISO 8601 或空字符串"
},
"expected_timeline": [
{
"role": "customer",
"content": "REPLACE_人工标注的脱敏消息",
"occurred_at": "REPLACE_带时区 ISO 8601 或空字符串",
"occurred_at_raw": "REPLACE_原始时间文本或空字符串",
"timezone": "REPLACE_原文时区或空字符串"
}
],
"expected_auto_created": true,
"expected_similar_ticket": false,
"notes": "REPLACE_审核结论与边界说明",
"enabled": false
},
{
"key": "real-image-only-REPLACE_002",
"name": "仅图片输入",
"source_kind": "anonymized_real",
"valid_input": true,
"input_manifest": {
"source_text": "",
"materials": [
{
"file_name": "REPLACE_chat.png",
"type": "png"
}
],
"anonymization_review": {
"reviewer": "REPLACE_复核人",
"reviewed_at": "REPLACE_YYYY-MM-DD",
"removed_identifiers": []
}
},
"expected_fields": {
"description": "REPLACE_人工标注的问题描述",
"category_code": "REPLACE_business_issue|technical_issue|data_issue|operation_issue"
},
"expected_timeline": [
{
"role": "customer",
"content": "REPLACE_人工标注的脱敏消息"
}
],
"expected_auto_created": true,
"expected_similar_ticket": false,
"notes": "REPLACE_审核结论与边界说明",
"enabled": false
},
{
"key": "real-document-REPLACE_003",
"name": "文档或日志输入",
"source_kind": "anonymized_real",
"valid_input": true,
"input_manifest": {
"source_text": "REPLACE_可选补充说明",
"materials": [
{
"file_name": "REPLACE_service.log",
"type": "log"
}
],
"anonymization_review": {
"reviewer": "REPLACE_复核人",
"reviewed_at": "REPLACE_YYYY-MM-DD",
"removed_identifiers": []
}
},
"expected_fields": {
"description": "REPLACE_人工标注的问题描述",
"error_information": "REPLACE_错误信息",
"attempted_actions": "REPLACE_已尝试动作或空字符串"
},
"expected_timeline": [
{
"role": "customer",
"content": "REPLACE_人工标注的脱敏消息"
}
],
"expected_auto_created": true,
"expected_similar_ticket": false,
"notes": "REPLACE_审核结论与边界说明",
"enabled": false
},
{
"key": "real-invalid-REPLACE_004",
"name": "无有效问题描述",
"source_kind": "anonymized_real",
"valid_input": false,
"input_manifest": {
"source_text": "REPLACE_脱敏后的无效输入",
"materials": [],
"anonymization_review": {
"reviewer": "REPLACE_复核人",
"reviewed_at": "REPLACE_YYYY-MM-DD",
"removed_identifiers": []
}
},
"expected_fields": {},
"expected_timeline": [],
"expected_auto_created": false,
"expected_similar_ticket": false,
"notes": "应进入追问或人工补充，不得自动创建正式工单。",
"enabled": false
}
]
}

137
docs/product/acceptance/stage2-sample-cases.json Normal file
View File

@@ -0,0 +1,137 @@
{
"schema_version": 1,
"description": "阶段 2 评估框架示例。全部为合成脱敏数据，不计入真实业务验收。",
"cases": [
{
"key": "synthetic-text-login-001",
"name": "生产环境登录失败文本",
"source_kind": "synthetic",
"valid_input": true,
"input_manifest": {
"source_text": "客户机构 A 反馈生产环境统一登录从 10:00 起提示服务异常。",
"materials": []
},
"expected_fields": {
"title": "生产环境统一登录服务异常",
"description": "客户机构 A 反馈生产环境统一登录从 10:00 起提示服务异常。",
"category_code": "technical_issue",
"environment": "生产环境"
},
"expected_auto_created": true,
"expected_similar_ticket": false,
"notes": "验证纯文本有效问题自动建单。"
},
{
"key": "synthetic-log-timeout-002",
"name": "日志附件接口超时",
"source_kind": "synthetic",
"valid_input": true,
"input_manifest": {
"source_text": "请排查回调任务持续超时。",
"materials": [
{"file_name": "callback-sanitized.log", "type": "log"}
]
},
"expected_fields": {
"description": "回调任务持续超时",
"category_code": "technical_issue"
},
"expected_auto_created": true,
"expected_similar_ticket": false,
"notes": "验证文档材料可读时仍按有效输入统计。"
},
{
"key": "synthetic-invalid-greeting-003",
"name": "无具体问题的问候",
"source_kind": "synthetic",
"valid_input": false,
"input_manifest": {
"source_text": "你好，在吗？",
"materials": []
},
"expected_fields": {},
"expected_auto_created": false,
"expected_similar_ticket": false,
"notes": "验证无有效问题时进入追问而不是建单。"
},
{
"key": "synthetic-duplicate-sync-004",
"name": "重复同步异常材料再次建单",
"source_kind": "synthetic",
"valid_input": true,
"input_manifest": {
"source_text": "生产环境数据同步任务停止更新，错误码 SYNC-504。",
"materials": [
{"file_name": "sync-504-sanitized.txt", "type": "text"}
]
},
"expected_fields": {
"description": "生产环境数据同步任务停止更新，错误码 SYNC-504。",
"category_code": "data_issue",
"environment": "生产环境"
},
"expected_auto_created": true,
"expected_similar_ticket": true,
"notes": "重复输入仍应创建独立工单，同时出现非阻断相似候选。"
},
{
"key": "synthetic-context-timeline-005",
"name": "结构化上下文与带时区消息时间线",
"source_kind": "synthetic",
"valid_input": true,
"input_manifest": {
"source_text": "2026-07-27 10:00（UTC+8），客户机构 A 反馈生产环境订单中心退款模块报错 REFUND-502；已重试三次，当前仍失败，希望尽快恢复。",
"materials": []
},
"expected_fields": {
"description": "生产环境订单中心退款模块报错 REFUND-502",
"environment": "生产环境",
"product_name": "订单中心",
"module_name": "退款模块",
"attempted_actions": "已重试三次",
"error_information": "REFUND-502",
"customer_request": "尽快恢复",
"current_result": "当前仍失败",
"problem_started_at": "2026-07-27T10:00:00+08:00"
},
"expected_timeline": [
{
"role": "customer",
"content": "生产环境订单中心退款模块报错 REFUND-502",
"occurred_at": "2026-07-27T10:00:00+08:00",
"occurred_at_raw": "2026-07-27 10:00（UTC+8）",
"timezone": "UTC+8"
}
],
"expected_auto_created": true,
"expected_similar_ticket": false,
"notes": "验证业务上下文、显式时区、字段证据和消息时间线。"
},
{
"key": "synthetic-ambiguous-time-006",
"name": "无时区时间不得猜测",
"source_kind": "synthetic",
"valid_input": true,
"input_manifest": {
"source_text": "客户说今天 10:00 起生产报表一直无法生成，但没有说明所在时区。",
"materials": []
},
"expected_fields": {
"description": "生产报表一直无法生成",
"environment": "生产环境",
"problem_started_at": ""
},
"expected_timeline": [
{
"role": "customer",
"occurred_at": "",
"occurred_at_raw": "今天 10:00",
"timezone": ""
}
],
"expected_auto_created": true,
"expected_similar_ticket": false,
"notes": "验证问题描述有效时仍可建单，但无时区的业务时间保持缺失并等待人工补全。"
}
]
}

108
docs/product/acceptance/stage3-evaluation.md Normal file
View File

@@ -0,0 +1,108 @@
# 阶段 3 支持分析验收
本目录只提供评估框架、案例格式和执行口径。仓库中的合成数据只能验证工具链，不能作为
“脱敏真实案例已验收”或阶段 3 已退出的证据。
## 1. 案例文件
案例文件使用 UTF-8 JSON，`schema_version` 固定为 `1`：
可从 `stage3-real-cases.template.json` 复制真实案例模板；`stage3-sample-cases.json`
只用于本地验证导入和报告工具。
```json
{
"schema_version": 1,
"cases": [
{
"key": "order-status-auto-resolve",
"name": "订单状态回写延迟",
"source_kind": "anonymized_real",
"input_manifest": {
"ticket_no": "脱敏工单编号",
"ticket_summary": "生产环境订单状态未更新",
"expected_reason": "已发布方案匹配且风险策略允许"
},
"expected_solution_ids": [12],
"expected_auto_resolve": true,
"expected_manual_fallback": false,
"notes": "方案 ID 必须来自当前验收环境中的已发布方案",
"enabled": true
}
]
}
```
要求：
- `source_kind` 只能是 `anonymized_real` 或 `synthetic`；默认报告只统计前者。
- `expected_solution_ids` 使用验收环境中的正式方案 ID。没有正确方案时使用空数组。
- `expected_auto_resolve` 与 `expected_manual_fallback` 必须且只能有一个为 `true`。
- 自动解决案例必须提供至少一个期望方案 ID。
- 真实案例必须提供非空 `input_manifest`，但不得写入客户、人员、组织、账号、密钥或原始
附件内容。
导入：
```powershell
python manage.py import_support_evaluation_cases docs/product/acceptance/stage3-cases.local.json
```
## 2. 记录评审
先在真实 PostgreSQL、Embedding/重排和文本模型环境完成支持分析，再把案例与分析记录
绑定：
```powershell
python manage.py record_support_evaluation --case order-status-auto-resolve --analysis 123
```
也可调用：
```text
POST /api/tickets/support-evaluations
{
"case_key": "order-status-auto-resolve",
"analysis_id": 123
}
```
只有 Agent 运行成功且支持分析已完成后处理的记录可以进入指标。记录时会冻结并核对：
- Agent 候选方案是否命中期望方案。
- 引用序号是否全部存在于本次冻结引用列表。
- 符合条件的案例是否实际自动解决。
- 应人工处理的案例是否进入 `manual_recommendation`。
- 自动采纳的方案是否落在期望方案集合中。
同一案例可以评审多次，报告只使用该案例最新一条结果；历史结果保留用于审计。
## 3. 指标与退出报告
指标接口：
```text
GET /api/tickets/support-quality-metrics
```
生成可归档的 JSON 报告：
```powershell
python manage.py report_stage3_acceptance `
--format json `
--output artifacts/stage3-acceptance.json `
--fail-on-not-ready
```
默认退出要求：
- 所有启用的脱敏真实案例都有评审结果。
- 案例集同时覆盖允许自动解决、人工降级和无正确方案场景。
- 已发布方案自动匹配率不低于 50%。
- 符合自动处理条件的工单自动解决率不低于 30%。
- 错误自动复用率不高于 5%。
- 人工降级场景全部正确阻断自动解决。
- 所有评审结果的引用序号均可追溯到冻结引用。
`--include-synthetic` 只用于验证评估框架，报告状态固定为 `diagnostic`，永远不会把
`exit_ready` 设为 `true`。

20
docs/product/acceptance/stage3-real-cases.template.json Normal file
View File

@@ -0,0 +1,20 @@
{
"schema_version": 1,
"cases": [
{
"key": "replace-with-anonymized-case-key",
"name": "替换为脱敏真实案例名称",
"source_kind": "anonymized_real",
"input_manifest": {
"ticket_no": "替换为脱敏工单编号",
"ticket_summary": "替换为不含客户身份和敏感信息的问题摘要",
"expected_reason": "说明允许自动解决或必须人工降级的业务依据"
},
"expected_solution_ids": [123],
"expected_auto_resolve": true,
"expected_manual_fallback": false,
"notes": "123 必须替换为验收环境中的已发布方案 ID",
"enabled": true
}
]
}

47
docs/product/acceptance/stage3-sample-cases.json Normal file
View File

@@ -0,0 +1,47 @@
{
"schema_version": 1,
"cases": [
{
"key": "synthetic-auto-resolve",
"name": "合成：高分低风险方案自动解决",
"source_kind": "synthetic",
"input_manifest": {
"ticket_summary": "生产环境订单状态长时间未更新",
"expected_reason": "已发布方案高分匹配、范围一致且风险策略允许"
},
"expected_solution_ids": [900001],
"expected_auto_resolve": true,
"expected_manual_fallback": false,
"notes": "仅验证评估框架，900001 需在测试环境替换为实际方案 ID",
"enabled": true
},
{
"key": "synthetic-risk-fallback",
"name": "合成：生产变更方案人工降级",
"source_kind": "synthetic",
"input_manifest": {
"ticket_summary": "需要修改生产配置才能恢复",
"expected_reason": "方案涉及生产变更，必须人工处理"
},
"expected_solution_ids": [900002],
"expected_auto_resolve": false,
"expected_manual_fallback": true,
"notes": "仅验证评估框架",
"enabled": true
},
{
"key": "synthetic-no-match",
"name": "合成：无正确方案",
"source_kind": "synthetic",
"input_manifest": {
"ticket_summary": "新问题，没有适用的已发布方案",
"expected_reason": "不得错误复用，应进入人工推荐"
},
"expected_solution_ids": [],
"expected_auto_resolve": false,
"expected_manual_fallback": true,
"notes": "仅验证评估框架",
"enabled": true
}
]
}