100 lines
7.9 KiB
Markdown
100 lines
7.9 KiB
Markdown
# 兴邦预审 v2 架构设计
|
|
|
|
状态：候选设计 0.1，等待阶段①评审；本文件严格区分当前事实与拟议架构。
|
|
|
|
## 1. 概览与已核验基线
|
|
|
|
代码快照 4d5a420 已保存在 Gitea。当前架构从代码确认如下，图中不包含尚未实现的新模块：
|
|
|
|
```mermaid
|
|
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/可切换专项判断 → 验证证据与规则 → 主审综合预审 → 独立复核/正式审批入口。
|
|
|
|
历史经验用于选择核查动作和比较适用条件，不能用“相似案例通过”直接推出当前项目通过。专项模型的判断置信与主审解释都不是独立的真实性认证。
|
|
|
|
## 3. 数据模型与持久化
|
|
|
|
P0 候选使用现有 SQLite 事务存储承载新增对象类型。历史事件、经验版本、运行、判断、模拟和评测各有唯一 owner。schema 变更追加迁移，保留旧表；完整 DDL 与兼容策略在详细设计阶段定案。
|
|
|
|
本轮“v2”指产品代际。既有 xingbang_v2.py 和 schema_v2 是历史实现命名，不应重命名或删除。
|
|
|
|
材料保存原件哈希、段落/页码、发生时间和录入时间。经验同时记录来源事件、制度版本、专家确认及有效期。只持有最终批复的案例应标“过程不完整”。
|
|
|
|
演示和真实数据域分别存储或通过受测权限边界隔离；生产隔离架构未确认前只运行演示数据。版本冻结后撤回经验不删除历史记录，但新运行不得再应用；旧结果需标记失效经验并提示复核。
|
|
|
|
## 4. 关键流程与恢复
|
|
|
|
- 历史导入失败：保留原件和失败事件，允许补充/重新提炼，不伪造缺失过程。
|
|
- 主审识别矛盾：记录待核查事项，使用授权证据工具验证，达到预算停止为 partial/awaiting_input。
|
|
- 所选专项模型不可用或关闭：缺失项进入 degradations；主审只能依据已完成检查给出有限意见。
|
|
- 硬规则冲突：结果校验阻断建议推进，保留模型原始结构化提案供审计。
|
|
- 新证据进入：产生新快照、新运行，旧结果保留；模拟不进入这条正式更新路径。
|
|
- Worker 恢复：复用持久任务机制；幂等范围包含 actor/project/operation/key，禁止重复生成运行。
|
|
|
|
## 5. 接口与集成
|
|
|
|
内部 API 以 /api/prescreen 为候选命名空间；沿用当前项目鉴权和同源代理。前端不能直接访问模型厂商。现有 assistant_model 的受信端点规则不自动适用于 Jev，专项模块需独立出口与域策略；local 也只能使用管理员批准的端点，不能从浏览器传入任意 URL。
|
|
|
|
Jev 接口概念参考 TypeSafe 官方文档：https://docs.typesafe.ai/introduction 、https://docs.typesafe.ai/confidence 。当前没有 SDK 安装、Key、版本或延迟实测；实施前重核版本与中文金租样本效果。Jev 是可选提供方，本地开源模型通过独立适配器执行同一业务任务；拿不到 Jev Key 不阻塞本地路径。统一契约和差异处理见 [专项判断模型切换](11-judgment-providers.md)。
|
|
|
|
概率预测为后续独立模型，输入仅使用预测时可得事实和判断特征。主审解释模型输出但不能改写原始概率；审批阶段、样本偏差和校准结果未明确前 probability=null。
|
|
|
|
## 6. 副作用边界
|
|
|
|
真实数据外发、经验发布、正式审批是不同权限。模型只能读冻结事实和生成候选意见；发布经验由授权人操作，正式审批不在 v2 自动化范围。普通聊天的终端/文件工具不能进入预审工具白名单。
|
|
|
|
本轮只进行本地文档写入与用户授权的 Gitea 分支备份；没有模型数据外发、云端部署、数据库迁移或镜像发布。
|
|
|
|
## 7. ADR
|
|
|
|
ADR-01 保留现有技术基线，按模块增量扩展，否决全面换框架。
|
|
ADR-02 主审综合判断+确定性约束+可切换专项复核，否决单模型 yes/no 审批。
|
|
ADR-03 经验以过程和来源为核心，否决只按最终结果记忆。
|
|
ADR-04 经验发布复用现有治理，否决自动从反馈直接生效。
|
|
ADR-05 先做验证和数据合作，再建设概率校准，否决专家分数转百分比。
|
|
ADR-06 v2 独立目录与资源，旧版保留；本轮先文档后迁移，目录尚未创建。
|
|
|
|
状态、影响和未决项统一维护在 [决策记录](09-decisions.md)。
|
|
|
|
## 8. 拟建立的架构验证
|
|
|
|
业务 service 不导入 src；预审工具集合不含 terminal/任意 SQL；跨域经验不可检索；引用必须属于授权快照；模拟不修改真实快照；无校准时概率为 null；经验发布只能经过一个治理入口。专项模型只能通过统一接口接入；local 不依赖 Jev 凭据；配置冻结且故障不自动切换。映射 AC-04/06/08/10/11/12/16/17/18/19/20/21。
|
|
|
|
这些是待实施的机器检查；现有测试覆盖另列，不能标成 v2 已通过。
|