兴邦预审 v2 架构设计

状态：候选设计 0.1，等待阶段①评审；本文件严格区分当前事实与拟议架构。

1. 概览与已核验基线

代码快照 4d5a420 已保存在 Gitea。当前架构从代码确认如下，图中不包含尚未实现的新模块：

flowchart LR
  U[业务用户] --> W[Next.js 项目工作台]
  W --> P[同源 Route Handler]
  P --> A[FastAPI 路由与权限]
  A --> S[ProjectAssistantService]
  S --> Q[DurableWorker]
  Q --> X[Skill 与规则执行]
  X --> M[受限模型 Agent Loop]
  S --> DB[SQLite 对象与审计]

已有能力	已检查代码	复用限制
项目快照/证据/问题契约	backend/contracts/project_assistant.py	本期复用，不另造同名概念
项目/任务/事务对象	backend/services/project_assistant.py、assistant_store.py、assistant_worker.py	巨大 service 不继续堆新领域，新增模块通过现有入口调用
数据卡/材料	backend/services/assistant_data.py、assistant_materials.py	继续冻结来源与人工确认候选
受限模型核查	backend/services/assistant_model.py	目前提示词禁止作审批决定；新增预审意见要单独设计并测试，不放宽旧版完整核查的权限
可审核经验	backend/services/assistant_experiences.py	已有范围、有效期、条件、审核发布；不能等同已学到客户历史经验
历史案例	backend/data_layer/history_store.py	实际是 JSONL + 行业/金额等简化筛选；文件注释不证明已建向量库
默认团队模式	backend/data_layer/team_experience.py	内置频次/阈值为代码默认样例，不是真实兴邦统计
模型与组件治理	backend/services/component_registry.py、component_evaluation.py	复用版本和验证机制

2. v2 拟议模块边界

以下是设计目标，尚未生成对应文件或调用链。owner 指代码唯一职责，人员待项目负责人分配。

模块 / 拟议落点	职责	依赖 / 禁止
history_cases / backend/services/history_cases.py	提炼历史事件、来源及未知项	依赖材料与存储；不直接批准经验
experience_catalog / backend/services/experience_catalog.py	关联案例与经验版本、先授权过滤再相关性比较	复用既有经验生命周期，不建立平行发布路径
prescreen / backend/services/prescreen.py	主审制定核查、调用专业能力、综合意见	只访问冻结授权上下文；不直接操作通用 terminal/SQL
judgment_provider / backend/services/judgment_provider.py	Jev 窄问题、schema 校验、预算、失败状态	通过出口策略；不写审批或综合结论
prescreen_policy / backend/services/prescreen_policy.py	硬规则、证据、缺证及概率输出约束	不依赖页面，不以模型高分绕过硬约束
scenario_service / backend/services/prescreen_scenarios.py	保存独立情景与差异	引用不可变基线；不覆盖真实事实
prescreen_evaluation / backend/services/prescreen_evaluation.py	冻结样本、版本、预测及专家对照	标签与推理侧隔离
prescreen contracts / backend/contracts/prescreen.py	新对象与错误契约	后端单一定义，前端由 OpenAPI 生成；生成器待建设

拟议数据流：材料/授权数据 → 标准事实和来源 → 冻结快照 → 硬规则和计算 → 检索有效经验 → 主审提出具体核查问题 → 专业 Skills/Jev → 验证证据与规则 → 主审综合预审 → 独立复核/正式审批入口。

历史经验用于选择核查动作和比较适用条件，不能用“相似案例通过”直接推出当前项目通过。Jev 的判断置信与主审解释都不是独立的真实性认证。

3. 数据模型与持久化

P0 候选使用现有 SQLite 事务存储承载新增对象类型。历史事件、经验版本、运行、判断、模拟和评测各有唯一 owner。schema 变更追加迁移，保留旧表；完整 DDL 与兼容策略在详细设计阶段定案。

本轮“v2”指产品代际。既有 xingbang_v2.py 和 schema_v2 是历史实现命名，不应重命名或删除。

材料保存原件哈希、段落/页码、发生时间和录入时间。经验同时记录来源事件、制度版本、专家确认及有效期。只持有最终批复的案例应标“过程不完整”。

演示和真实数据域分别存储或通过受测权限边界隔离；生产隔离架构未确认前只运行演示数据。版本冻结后撤回经验不删除历史记录，但新运行不得再应用；旧结果需标记失效经验并提示复核。

4. 关键流程与恢复

历史导入失败：保留原件和失败事件，允许补充/重新提炼，不伪造缺失过程。
主审识别矛盾：记录待核查事项，使用授权证据工具验证，达到预算停止为 partial/awaiting_input。
Jev 不可用：缺失项进入 degradations；主审只能依据已完成检查给出有限意见。
硬规则冲突：结果校验阻断建议推进，保留模型原始结构化提案供审计。
新证据进入：产生新快照、新运行，旧结果保留；模拟不进入这条正式更新路径。
Worker 恢复：复用持久任务机制；幂等范围包含 actor/project/operation/key，禁止重复生成运行。

5. 接口与集成

内部 API 以 /api/prescreen 为候选命名空间；沿用当前项目鉴权和同源代理。前端不能直接访问模型厂商。现有 assistant_model 的受信端点规则不自动适用于 Jev，后者需独立出口与域策略。

Jev 接口概念参考 TypeSafe 官方文档：https://docs.typesafe.ai/introduction 、https://docs.typesafe.ai/confidence 。当前没有 SDK 安装、Key、版本或延迟实测；实施前重核版本与中文金租样本效果。

概率预测为后续独立模型，输入仅使用预测时可得事实和判断特征。主审解释模型输出但不能改写原始概率；审批阶段、样本偏差和校准结果未明确前 probability=null。

6. 副作用边界

真实数据外发、经验发布、正式审批是不同权限。模型只能读冻结事实和生成候选意见；发布经验由授权人操作，正式审批不在 v2 自动化范围。普通聊天的终端/文件工具不能进入预审工具白名单。

本轮只进行本地文档写入与用户授权的 Gitea 分支备份；没有模型数据外发、云端部署、数据库迁移或镜像发布。

7. ADR

ADR-01 保留现有技术基线，按模块增量扩展，否决全面换框架。 ADR-02 主审综合判断+确定性约束+Jev 专项复核，否决单模型 yes/no 审批。 ADR-03 经验以过程和来源为核心，否决只按最终结果记忆。 ADR-04 经验发布复用现有治理，否决自动从反馈直接生效。 ADR-05 先做验证和数据合作，再建设概率校准，否决专家分数转百分比。 ADR-06 v2 独立目录与资源，旧版保留；本轮先文档后迁移，目录尚未创建。

状态、影响和未决项统一维护在决策记录。

8. 拟建立的架构验证

业务 service 不导入 src；预审工具集合不含 terminal/任意 SQL；跨域经验不可检索；引用必须属于授权快照；模拟不修改真实快照；无校准时概率为 null；经验发布只能经过一个治理入口。映射 AC-04/06/08/10/11/12/16。

这些是待实施的机器检查；现有测试覆盖另列，不能标成 v2 已通过。

7.4 KiB Raw Blame History