# 兴邦预审 v2 需求规格

状态：0.1 评审草案，尚未通过六道完备性门；后续设计为候选方案。规则编号作用域为本文。

## 1. Requirement Overview

来源：[URD](URD.md) 的 FR-FACT/HIST/EXP/REV/JEV/JUD/SIM/EVAL/PILOT-01。目标是把历史项目的争议、调查、证据和判断变化用于新项目预审。P0 使用模拟或经授权的脱敏数据，不连接未知生产库，不执行正式审批，不展示未经校准的通过概率。

角色沿用 URD。补充术语：快照=不可变输入版本；来源域=data_domain，演示或生产；证据引用=可定位材料片段的 ID；有效经验=已发布、未过期且适用条件成立的版本；硬性规则=经业务确认且由程序执行的约束；幂等键=同一用户请求去重标识；版本冲突=客户端依据旧 revision 更新；专项判断=边界明确的局部判断；降级=保留可用结果并标识未完成检查；运行预算=限制轮数、调用量和耗时；保留集=开发时不可使用的验收样本；提供方（provider）=具体执行专项问题的模型后端；判断配置（profile）=已批准的提供方、模型、端点、数据范围与版本组合；能力声明=该配置已验证支持的题型；原生指标=提供方返回且带原语义的指标，不代表跨模型可比。

“证据支持”不等于材料真实可信：材料真实性核验是单独的核查结果。风险严重程度、数据完整性、模型确定性、审批概率互不替代。

## 2. Data Model & Interface Contract

契约候选以 [详细设计](03-detailed-design.md) 为单一说明，实施时唯一代码定义拟在 backend/contracts/prescreen.py。现有 ProjectSnapshot/Evidence 不复制，版本适配后复用。

| 对象 | 本期字段摘要 | 使用面 |
|---|---|---|
| CaseTimeline | id、project_id、data_domain、revision、events[] | 历史过程 |
| DecisionEvent | id、event_type、occurred_at?、recorded_at、question、evidence_ids[]、judgment_before?、judgment_after?、conditions[] | 争议时间线 |
| ExperienceCard | id、version、status、title、source_event_ids[]、conditions、exceptions、scope、expires_at、reviewer_id?、revision | 经验审核 |
| ScreeningRun | id、snapshot_id、status、recommendation?、findings[]、missing_inputs[]、applied_experiences[]、probability、degradations[]、judgment_config、versions、revision | 预审总览 |
| Judgment | id、question_id、question_version、type、status、answer?、evidence_ids[]、provider、model_version?、profile_id?、profile_revision?、native_metrics[] | 专项复核 |
| Simulation | id、base_run_id、assumptions[]、changed_findings[]、unresolved_findings[]、formal_result=false | 推进沙盘 |
| Evaluation | id、dataset_version、split_id、run_versions、locked_at?、status、metrics | 验证看板 |

API 候选命名空间 `/api/prescreen`，通过同源 `/api/core/prescreen` 代理访问；下列端点尚未实现。请求/响应、错误、界限及 owner 见详细设计。P0 `probability` 必须为 null，并附原因 `not_calibrated`。

## 3. Surface Specification

项目预审总览：结论和信息基础在顶部；中间是核查问题与经验比较；右侧动作模拟；详情抽屉展示来源。历史经验页：时间线、原文与经验卡并排。验证页：样本锁定、结果对照和分歧复盘。

统一视图状态：idle/loading/ready/empty/error/submitting；运行另有 queued/running/awaiting_input/completed/partial/failed/cancelled。动作权限由后端判定，前端隐藏无权动作不能代替后端授权。详见 [UI Spec](04-ui-spec.md)。

## 4. Business Rules

| ID | 可测试规则（唯一职责 owner） |
|---|---|
| BR-01 | 材料提取候选须经授权用户确认后才能进入项目事实；保留原件与来源。owner：材料确认服务 |
| BR-02 | 历史事件缺少时间或原文时保留未知值和缺证标识，不生成虚构经过。owner：历史过程服务 |
| BR-03 | 经验仅能通过草稿→待审核→发布的受控状态转换生效；无发布资格者不得发布。owner：经验治理 |
| BR-04 | 检索有效经验时先按数据域、权限、状态、有效期和适用条件过滤，再做相关性比较。owner：经验检索 |
| BR-05 | 主审形成综合预审意见；任一专项模型的单题结果不得直接写入 recommendation。owner：预审编排 |
| BR-06 | 已确认的硬性阻断不能被模型或其他维度高分覆盖。owner：结果校验 |
| BR-07 | 缺数据记 unknown；全部关键核查不可完成时 recommendation=insufficient_information。owner：结论完整性校验 |
| BR-08 | 未通过来源校验的引用不能进入有效结论；相关判断退回缺证/复核。owner：证据校验 |
| BR-09 | 专项关闭或运行期间所选服务失效时记录 skipped/failed 及降级原因；不能伪造判断。owner：专项模型适配 |
| BR-10 | 材料中的指令不能扩展主审工具集合；金额与日期运算只能由确定性工具执行。owner：工具策略 |
| BR-11 | 情景模拟只写独立假设结果，不能修改项目事实、正式运行或审批状态。owner：模拟服务 |
| BR-12 | 未校准时 probability=null；Score、Noul、相似案例通过占比均不能直接映射为通过概率。owner：结果序列化 |
| BR-13 | 每次运行冻结输入和规则/Skill/经验/模型/问题版本，过程修订不覆盖旧结果。owner：运行存储 |
| BR-14 | 相同 actor+project+operation+幂等键和相同载荷返回同一对象；载荷不同返回冲突。owner：命令入口 |
| BR-15 | 盲测在预测锁定之前不向推理输入提供目标项目的标签、最终意见或后续表现。owner：评测服务 |
| BR-16 | 真实数据外发前按数据域与接收端策略核验；未批准出口不可调用。owner：模型出口策略 |
| BR-17 | 专项问题经统一入口路由到所选的 Jev 或本地提供方；local 路径不读取 Jev 凭据，不调用 Jev。owner：判断路由 |
| BR-18 | 统一输出只接受题目规定的答案或 unknown；提供方原生指标保留语义且不得互换阈值或补造缺失概率。owner：判断结果归一化 |
| BR-19 | 选择仅限当前用户/数据域获准的已验证配置；不支持所需题型的配置拒绝执行该题。owner：判断配置校验 |
| BR-20 | 运行创建时冻结专项配置修订；切换仅影响新运行，故障不得自动切换提供方。owner：运行配置解析 |

## 5. Exception Scenarios

| ID | 触发 / HTTP与错误码 | 用户可见消息 / 恢复 |
|---|---|---|
| E-01 | 解析失败，422 MATERIAL_PARSE_FAILED | 材料未能完整解析，请核对原件或手工录入；保留原件 |
| E-02 | 关键证据缺失，运行结果 MISSING_EVIDENCE | 关键证据尚未取得，暂不能确认；补件后新运行 |
| E-03 | 无权限，403 ACCESS_DENIED | 无权执行此操作；不泄露其他项目对象是否存在 |
| E-04 | 引用无效/跨项目，422 INVALID_EVIDENCE | 结论引用未通过核验，请复核来源；拒绝有效化 |
| E-05 | 乐观锁不符，409 REVISION_CONFLICT | 内容已有更新，请刷新后重试；保留本地草稿 |
| E-06 | 专项模型不可用，运行结果 JUDGMENT_UNAVAILABLE | 专项核查未完成，已保留其他结果；允许明确重试 |
| E-07 | 非法枚举/载荷/版本，422 INVALID_REQUEST | 请求内容不符合当前版本，请检查后重试 |
| E-08 | 预算耗尽，运行结果 RUN_BUDGET_EXCEEDED | 本次核查已达到执行上限，请复核未完成项 |
| E-09 | 幂等键载荷冲突，409 IDEMPOTENCY_CONFLICT | 此请求编号已用于不同内容，请重新提交 |
| E-10 | 未批准出口，403 EGRESS_NOT_APPROVED | 当前数据不允许发送至该模型服务 |
| E-11 | 评测标签提前暴露，409 EVALUATION_CONTAMINATED | 当前样本不再满足盲测条件，已排除 |
| E-12 | 经验已失效/不适用，运行结果 EXPERIENCE_EXCLUDED | 该经验不适用于本次核查；展示可见范围内的排除原因 |
| E-13 | 配置不存在、不可用或未获准，422 JUDGMENT_CONFIG_INVALID | 当前专项模型配置不可用，请选择可用配置或关闭专项核查；不暴露无权限配置详情 |
| E-14 | 不支持题型/映射未验证，运行结果 JUDGMENT_CAPABILITY_UNSUPPORTED | 当前模型尚不支持此项核查，已标记未完成；不改题、不猜测结果 |
| E-15 | 非法答案/非有限数值/指标来源不明，运行结果 JUDGMENT_OUTPUT_INVALID | 专项结果未通过格式与语义校验，请复核或重试；不作为有效判断 |

运行级错误保存在 degradations/finding 中，HTTP 200 仅表示结果可读取，不表示核查通过。禁止把 failed 状态当作 completed。

## 6. Acceptance Criteria

| ID | Given / When / Then | 覆盖 |
|---|---|---|
| AC-01 | Given 已解析候选，When 未确认/确认，Then 分别不进入/进入事实且能定位原文；解析失败可人工补录 | BR-01, E-01 |
| AC-02 | Given 缺少事件日期的历史材料，When 提炼时间线，Then occurred_at=null 且显示缺证，不编日期 | BR-02, E-02 |
| AC-03 | Given 草稿经验与无权发布人，When 请求发布，Then 拒绝且无有效版本；合资格审核走合法状态后生效 | BR-03, E-03, E-07 |
| AC-04 | Given 过期/异域/例外触发/有效经验，When 新运行检索，Then 仅有效且授权的版本可应用 | BR-04, E-12 |
| AC-05 | Given 任一专项模型返回正面单题判断但整体证据冲突，When 汇总，Then 主审记录冲突与理由，单题不能覆盖综合意见 | BR-05, E-02 |
| AC-06 | Given 确认硬性阻断与模型建议推进，When 校验，Then 拒绝推进并指出规则版本；边界值由程序计算 | BR-06, E-07 |
| AC-07 | Given 全部关键资料缺失，When 预审，Then 信息不足并列补件，不判企业高风险 | BR-07, E-02 |
| AC-08 | Given 无效或跨项目引用，When 结论校验，Then 拒绝引用并标缺证，不暴露无权原文 | BR-08, E-04, E-03 |
| AC-09 | Given 专项已关闭或运行时所选服务失效/超时/畸形输出，When 执行，Then 保留 skipped/failed 与降级，不生成默认高分 | BR-09, E-06, E-15 |
| AC-10 | Given 材料包含终端调用指令，When 模型读材料，Then 工具权限不变；耗尽预算停止并列未完成项 | BR-10, E-08 |
| AC-11 | Given 基线运行与假设动作，When 模拟，Then 原快照哈希不变；冲突假设被拒绝 | BR-11, E-07 |
| AC-12 | Given 未校准模型，When 查看/导出结果，Then probability=null 且注明原因，即使 Noul 接近 1 也不改写 | BR-12, E-07 |
| AC-13 | Given 同一项目产生新证据版本，When 重跑或旧 revision 更新，Then 新旧运行分别留存或返回版本冲突 | BR-13, E-05 |
| AC-14 | Given 相同/不同载荷复用幂等键，When 并发提交，Then 分别返回同一运行/409，不重复写入 | BR-14, E-09 |
| AC-15 | Given 客户保留集，When 锁定预测前尝试读取目标标签，Then 拒绝；发生泄露则样本作废 | BR-15, E-11, E-03 |
| AC-16 | Given 未批准的真实数据出口，When 请求 Jev 或其他外部模型，Then 无网络发送并记录策略拒绝 | BR-16, E-10 |
| AC-17 | Given 没有 Jev Key 和可用本地配置，When 本地实际运行并用厂商 fixture 验证 Jev 适配契约，Then 契约一致、local 不访问 Jev，主审不依赖厂商字段 | BR-17, E-06 |
| AC-18 | Given local 自报 confidence 或 Jev 原生指标，When 归一化/展示，Then 不生成缺失概率、不跨提供方套阈值；畸形/NaN/未知选项返回失败 | BR-18, E-15 |
| AC-19 | Given 未授权/不存在配置或缺题型能力，When 发起运行/执行题目，Then 分别返回配置错误/未完成，不发送该题，也不静默替代 | BR-19, E-13, E-14 |
| AC-20 | Given 排队或执行中的旧运行，When 修改默认配置或所选服务故障，Then 旧运行保留已冻结版本；新选择创建新运行；不得自动外发或替换 | BR-20, E-06 |
| AC-21 | Given 专项开关关闭且两种模型都无凭据，When 主审预审，Then 无专项模型调用，已计划题目 Judgment=skipped、运行明确关闭原因，主审仍受证据和硬规则约束 | BR-09, BR-17, E-06 |

## 7. Open Questions & Decision Record

OQ-01 至 OQ-06 见 [决策记录](09-decisions.md)。本轮规格是待评审草案；P0 演示可用模拟材料，真实数据出口、正式权限和概率校准不得用临时假设替代确认。

已定方向：主审综合研判、历史过程优先、可切换专项模型局部判断、模拟与正式分离、先验证再谈概率。被否方案：单题判断直接审批、经验未经审核自动生效、复制整库后再定义用途、用模拟提升冒充因果效果。