85 lines
9.6 KiB
Markdown
85 lines
9.6 KiB
Markdown
# 兴邦预审 v2 详细设计候选
|
||
|
||
状态：0.1 草案，阶段①/②未定案；以下端点和新类型尚未实现。覆盖 BR-01–20 / E-01–15 / AC-01–21，先形成可评审的契约，再编写代码。
|
||
|
||
## 1. 约定与契约归属
|
||
|
||
唯一代码 owner 拟为 backend/contracts/prescreen.py，复用既有 Evidence / ProjectSnapshot，通过适配器处理版本差异；前端类型生成链在 M1 实现。API 路由仅授权和校验，业务决策在 service。
|
||
|
||
共同字段：id/project_id/snapshot_id 等为非空字符串（1–128 字符），revision 为正整数，时间为带时区 ISO-8601；未知发生时间允许 null，记录时间必填；data_domain 为 demo/production；所有输入禁止未知字段。列表分页候选 limit 默认 20，范围 1–100，cursor 可空。
|
||
|
||
P0 初始工程限制提案（非业务阈值）：沿用单材料 10 MB；单次最多 10 个专项判断问题、每题最多 20 条证据、每次最多 10 个模拟动作；工具最多 20 次、总运行 120 秒、单次模型请求 30 秒、可重试故障最多重试 1 次且计入总预算。管理员只能在部署配置中降低初期限制；放宽须重新验证并更新规格。这些值在 OQ-04 定案前不得当作性能承诺。
|
||
|
||
## 2. 接口草案
|
||
|
||
路径前缀 /api/prescreen，写请求须身份、项目权限和 Idempotency-Key；更新已有对象需 expected_revision。Error 响应统一为 `{error:{code,message,retryable,request_id}}`，不得带密钥或无权限原文。
|
||
|
||
| 方法 / 路径 | 入参 | 成功响应 | owner / 主要异常 |
|
||
|---|---|---|---|
|
||
| POST /projects/{project_id}/case-timelines | document_ids:string[1..100] | 202 {timeline:CaseTimeline}，状态 processing | history_cases；E-01/03/07/09 |
|
||
| GET /case-timelines/{id} | 无 body | 200 CaseTimeline | history_cases；E-03；不存在统一 404 NOT_FOUND |
|
||
| POST /case-timelines/{id}/experiences | title:string[1..200], source_event_ids:string[1..50], conditions:Condition[], exceptions:Condition[], scope:project/team, expires_at:datetime | 201 ExperienceCard draft | 经验治理；E-03/04/07/09 |
|
||
| POST /experiences/{id}/transitions | action:submit/approve/reject/withdraw, expected_revision:int, note:string[1..2000] | 200 ExperienceCard | 复用经验治理；E-03/05/07 |
|
||
| GET /projects/{project_id}/judgment-profiles | 无 body | 200 {profiles:[{id,revision,display_name,provider,capabilities}],default_profile_id:string?}；仅授权可用项 | 判断配置；不存在/无权项目404；详见专项设计 |
|
||
| POST /projects/{project_id}/runs | snapshot_id:string, enable_judgment:boolean=false, judgment_profile_id:string? | 202 ScreeningRun queued | prescreen；E-03/07/09/10/13 |
|
||
| GET /runs/{id} | 无 body | 200 ScreeningRun | prescreen；E-03；不存在 404 NOT_FOUND |
|
||
| POST /runs/{id}/cancel | expected_revision:int | 200 ScreeningRun | prescreen；E-03/05/07 |
|
||
| POST /runs/{id}/simulations | assumptions:Assumption[1..10] | 201 Simulation | scenario_service；E-03/05/07/09 |
|
||
|
||
材料上传/候选确认沿用已存在的项目助手接口，开发前核对调用方。此处不新增平行上传入口。
|
||
|
||
不存在与无访问权的对象统一对外为 404 NOT_FOUND，页面文案“对象不可访问或不存在”；E-03 用于已授权对象上的无权动作。评测先做离线内部入口，不开放目标标签 API 给主审。
|
||
|
||
## 3. 数据字段候选
|
||
|
||
| 对象 | 字段 / 类型 / 空值 | owner |
|
||
|---|---|---|
|
||
| CaseTimeline | id, project_id, data_domain, revision；status:processing/ready/partial/failed；events:DecisionEvent[]；warnings:string[] | history_cases |
|
||
| DecisionEvent | id；event_type:question/evidence/action/opinion/decision；occurred_at:datetime?；recorded_at:datetime；question:string；evidence_ids:string[]；judgment_before:string?；judgment_after:string?；conditions:string[] | history_cases |
|
||
| Condition | field:string（标准字段白名单）；operator:eq/in/present/absent；value:string/bool/string[]/null；数据类型按 operator 校验，不执行表达式 | 经验治理 |
|
||
| ExperienceCard | id, project_id, data_domain, revision；version:string；title；status:draft/in_review/published/rejected/withdrawn；source_event_ids:string[]；conditions/ exceptions:Condition[]；scope:project/team；team_id:string?；expires_at；reviewer_id:string?；policy_version:string? | 经验治理 |
|
||
| Finding | 复用既有 Finding；展示 title/result/evidence_ids/basis_ids/suggested_action/status；无依据只能 unknown，已有枚举不改名 | 预审编排 |
|
||
| ScreeningRun | id, project_id, data_domain, revision, snapshot_id；status 见第4节；recommendation:advance/supplement/stop/insufficient_information/null；findings:Finding[]；missing_inputs:string[]；applied_experiences:{id,version,reason,evidence_ids}[]；probability:null；probability_reason:not_calibrated；degradations:{code,message}[]；judgment_config:{enabled,profile_id?,profile_revision?,provider,model_version?,adapter_version?,prompt_version?,mapping_version?}；versions:{schema,policy,skills,experiences,model,questions}；created_at；finished_at:datetime? | 运行存储 |
|
||
| Judgment | id, run_id, question_id, question_version；type:choice/score/binary；status:completed/skipped/failed；answer:JudgmentAnswer?；evidence_ids:string[]；provider:jev/local/disabled；profile_id:string?；profile_revision:int?；model_version:string?；native_metrics:NativeMetric[]；error_code:string?；skip_reason:string? | judgment_provider |
|
||
| Assumption | action_id:string；description:string[1..1000]；field_changes:{field,value}[]；required_evidence_ids:string[] | scenario_service |
|
||
| Simulation | id, project_id, base_run_id；assumptions:Assumption[]；changed_findings:{code,before,after,basis_ids}[]；unresolved_findings:string[]；formal_result:false；created_at | scenario_service |
|
||
| Evaluation | id, dataset_version, split_id；run_versions:object；locked_at:datetime?；status:prepared/running/locked/revealed/invalidated；metrics:{name,numerator,denominator,value?,scope}[] | prescreen_evaluation |
|
||
|
||
JudgmentAnswer、NativeMetric、JudgmentProfile 及配置选择规则统一详见 [专项判断模型切换](11-judgment-providers.md) 第3–5节。题型统一为 choice/score/binary；原草案中的 noul 是厂商语义，改由 Jev 适配器处理，不再进入业务题型。该草案从未实现，无已上线 API 迁移。未知可作为显式答案；completed 只表示完成该题处理与校验（允许缺证直接返回 unknown），不表示支持结论或项目通过。
|
||
|
||
Evidence 来源可定位不代表真实性已核验，真实性结果须单列 Finding。conditions 非空，team 范围必有 team_id；例外命中即排除；首次发布缺失 reviewer_id 不合法。撤回不删除历史引用。
|
||
|
||
迁移拟新增有版本守卫的历史事件/预审对象存储，具体 DDL 在 M1 定案；禁止覆写旧 schema_v2 初始化或复用旧生产库测试。
|
||
|
||
## 4. 状态机与权限
|
||
|
||
| 对象 | 合法转换 | 守卫与失败 |
|
||
|---|---|---|
|
||
| 历史过程 | processing→ready/partial/failed | 部分缺日期为 partial；重新提炼生成新 revision |
|
||
| 经验 | draft→in_review→published/rejected；rejected→draft；published→withdrawn | submit 由编辑者；approve/reject/withdraw 由发布角色；审核不能自批，编辑后重提审；过期在读取时排除 |
|
||
| 运行 | queued→running→completed/partial/awaiting_input/failed；queued/running→cancelled | awaiting_input 补件后创建新运行，旧运行保留；completed 不允许原地覆写 |
|
||
| 模拟 | 创建→独立结果 | 不存在“应用到真实项目”捷径；真实材料按原确认流程进入新快照 |
|
||
| 评测 | prepared→running→locked→revealed；任一未完状态→invalidated | locked 前标签不可进入推理；发现泄漏保留作废理由 |
|
||
|
||
recommendation 在 queued/running 时为 null，终态仍可能为 insufficient_information；partial 不是通过。过时结果允许查看但显示版本差异，不能静默升级到新版本。
|
||
|
||
## 5. 错误与恢复
|
||
|
||
错误码与文案统一引用规格第5节，防止维护两份。补充 NOT_FOUND 的语义见第2节。403/422 不自动重试；408/429/5xx/连接错误可按预算重试一次，使用同一幂等键。无可恢复工作时终止并保留日志；不自动切换未批准厂商。
|
||
|
||
硬规则冲突保留原模型提案但有效 recommendation=stop；来源无法验证的判断为 unknown。若综合意见失去关键依据，降为 insufficient_information 或 supplement，必须记录缺失事项；具体业务“关键项”列表依方案版本管理，需 OQ-01 确认。
|
||
|
||
## 6. 边界清单
|
||
|
||
空材料/空经验集：展示 empty，允许现有规则核查，明确无历史经验支持。版本不支持：422；对象过时：409；跨项目和跨域：过滤+授权拒绝。不能将 lack of evidence 当成 yes/no 否定事实。
|
||
|
||
幂等键唯一范围 actor_id+project_id+operation+key，记录请求哈希；相同请求返回原对象，冲突 E-09。并发更新通过 revision 和事务；先写运行记录再入队，取消后禁止写成功结果。实施阶段须覆盖 Worker 崩溃后恢复。
|
||
|
||
## 7. 测试映射
|
||
|
||
history_cases→AC-01/02；经验治理与检索→AC-03/04/13；prescreen+policy→AC-05/06/07/08/12；judgment_provider→AC-09/16/17/18/19/20/21；工具策略→AC-10；scenario_service→AC-11；命令入口→AC-14；evaluation→AC-15。具体测试提案见验证方案，当前均不是已执行的新功能测试。
|
||
|
||
## 8. 未决项
|
||
|
||
OQ-01 业务类型和关键项；OQ-02 审核权限；OQ-03 模型出口；OQ-04 性能/预算与验收阈值；OQ-05 概率事件；OQ-06 独立仓库和部署资源。全部在决策记录中有 owner 和进入条件。本文件不可直接作为已批准实现合同。
|