From 9d2399feed06699d2d4134d60cca199ae6a2c47a Mon Sep 17 00:00:00 2001 From: qiaoqichao Date: Mon, 28 Sep 2026 17:02:33 +0800 Subject: [PATCH] =?UTF-8?q?docs(xingbang):=20=E9=80=82=E9=85=8D=E9=A1=B9?= =?UTF-8?q?=E7=9B=AE=E5=BC=80=E5=8F=91=E6=B5=81=E7=A8=8B=E5=B9=B6=E5=BB=BA?= =?UTF-8?q?=E7=AB=8B=E7=BB=8F=E9=AA=8C=E9=A9=B1=E5=8A=A8=E9=A2=84=E5=AE=A1?= =?UTF-8?q?=E6=96=B0=E7=89=88=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 46 ++++-- docs/project-process/01-requirement.md | 10 +- docs/project-process/02-architecture.md | 22 +-- docs/project-process/03-detailed-design.md | 12 +- docs/project-process/04-ui-spec.md | 22 +-- docs/project-process/05-implementation.md | 32 ++-- docs/project-process/06-validation.md | 24 +-- docs/project-process/07-delivery.md | 156 +++++------------- docs/project-process/08-learning.md | 8 +- docs/project-process/README.md | 101 +++++------- docs/project-process/XINGBANG-ADAPTATION.md | 37 +++++ .../templates/URD-Template.html | 13 +- .../project-process/templates/URD-Template.md | 24 ++- docs/v2/01-requirements.md | 100 +++++++++++ docs/v2/02-architecture.md | 99 +++++++++++ docs/v2/03-detailed-design.md | 83 ++++++++++ docs/v2/04-ui-spec.md | 68 ++++++++ docs/v2/05-implementation-plan.md | 47 ++++++ docs/v2/06-validation.md | 55 ++++++ docs/v2/07-deployment-and-gitea.md | 89 ++++++++++ docs/v2/08-data-pilot-and-demo.md | 58 +++++++ docs/v2/09-decisions.md | 49 ++++++ docs/v2/10-delivery-record.md | 50 ++++++ docs/v2/DESIGN.md | 61 +++++++ docs/v2/README.md | 40 +++++ docs/v2/URD.md | 124 ++++++++++++++ 26 files changed, 1164 insertions(+), 266 deletions(-) create mode 100644 docs/project-process/XINGBANG-ADAPTATION.md create mode 100644 docs/v2/01-requirements.md create mode 100644 docs/v2/02-architecture.md create mode 100644 docs/v2/03-detailed-design.md create mode 100644 docs/v2/04-ui-spec.md create mode 100644 docs/v2/05-implementation-plan.md create mode 100644 docs/v2/06-validation.md create mode 100644 docs/v2/07-deployment-and-gitea.md create mode 100644 docs/v2/08-data-pilot-and-demo.md create mode 100644 docs/v2/09-decisions.md create mode 100644 docs/v2/10-delivery-record.md create mode 100644 docs/v2/DESIGN.md create mode 100644 docs/v2/README.md create mode 100644 docs/v2/URD.md diff --git a/AGENTS.md b/AGENTS.md index e3f6d45..accf09c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,8 +1,18 @@ # AGENTS.md — mini-OpenClaw 兴邦金租 AI 评审平台 -> 本文件是仓库唯一事实来源,供 Codex / Claude / 其他 AI 编码代理读取。 +> 本文件是仓库开发规则的统一入口，供 Codex / Claude / 其他 AI 编码代理读取；运行事实以代码、测试和已核验记录为准。 > **先读本文件,再动手;开发全程遵守「改动纪律」,尤其是有序验证命令。** +## 项目开发流程（强制） + +1. 所有需求、修复、重构、UI、接口与交付工作，先读 [项目流程](docs/project-process/README.md) 和 [兴邦适配说明](docs/project-process/XINGBANG-ADAPTATION.md)，进入阶段前再读对应的 `01` 至 `08` 章节。 +2. 按「需求与规格 → 架构 → 详细设计 → UI Spec → 实现 → 验证 → 交付 → 沉淀」执行。阶段完成条件没有证据时标记未完成；可以记录后续阶段的候选设计，但不得把草案当成已过门禁并开始业务实现。 +3. 需求须有稳定的 `BR-*` / `E-*` / `AC-*` 编号；异常绑定错误码和用户文案，验收使用 Given/When/Then。编号只追加，废弃保留编号并标记 withdrawn。小改动可走流程中的轻量路径并记录理由。 +4. `docs/project-process` 正文已适配兴邦 Next.js + FastAPI 项目，按各章实际目录、契约、测试和部署要求执行；适配记录说明来源和未建设的机制。不得引用不存在的命令或把规划当实现。本文件的兴邦硬约束继续有效。 +5. 新版需求与设计入口是 [docs/v2/README.md](docs/v2/README.md)。该目录保存入库评审草案及后续基线；必须区分已实现、规划、模拟演示和真实验证，不能用文件存在证明功能已完成。 +6. 行为改动沿用本文件的测试与 `backend/venv` 要求，必须运行 `python scripts/verify.py` 并保存 `test-evidence/`。文档改动至少检查链接、编号覆盖、事实来源及 `git diff --check`；不得声称未接入的 CI、Jev 或概率模型已生效。 +7. 提交使用 Conventional Commits 类型前缀加中文一句话说明；默认分支从 Gitea 实际读取，不照搬来源项目的 `build`。备份分支只代表恢复点，不等于评审通过、合并或发布。 + ## ▶️ 接手当前进度(每次新对话/会话开始时先做,别当新项目从零写) > 本文件写的是**规则,不是进度**。你的进度在**代码 + git 工作区 + 会话历史**里,不在本文件里。 @@ -22,28 +32,28 @@ - `src/` — **Next.js 前端**(默认端口 **3000**),页面/组件在 `src/app/`、`src/components/` - `backend/` — **FastAPI 后端**(默认端口 **8002**),Python + LangChain,工具在 `backend/tools/`、Agent 调度在 `backend/graph/`、API 路由在 `backend/api/` -- 关键业务模块:`review_assist.py`(评审提效)、`risk_*`(风控)、`coordination_agent.py`(协调)、`report_agent.py`(报告)、`graph/risk_task.py`,数据在 `backend/backend/xingbang_data/` +- 关键业务模块:`review_assist.py`(评审提效)、`risk_*`(风控)、`coordination_agent.py`(协调)、`report_agent.py`(报告)、`graph/risk_task.py`,当前项目助手数据在 `backend/xingbang_data/project_assistant.sqlite3`（见 `backend/services/project_assistant.py`）；旧目录需按实际调用确认，不能作为默认迁移源 -## 启动与验证命令(改动后必跑) +## 启动与验证命令（项目实际入口） -```bash -# 后端(必须用项目虚拟环境,下同) -cd /f/mini-OpenClaw/backend -source venv/Scripts/activate # git-bash; Windows CMD 用 venv\Scripts\activate.bat -./start_backend.sh # 或 start_backend.bat ; 后端 http://localhost:8002 (docs 在 /docs) -# 或直接: uvicorn backend.backend.main:app --port 8002 +以下为当前旧版工作区的 PowerShell 命令；v2迁移后改用其独立路径和已确认端口。 -# 前端(另开终端) -cd /f/mini-OpenClaw -npm run dev # 前端 http://localhost:3000 +```powershell +# 后端：start_backend.bat 使用 backend/venv 并禁用进程内代理 +Set-Location F:\mini-OpenClaw-local-stable\backend +.\start_backend.bat +# 实际应用是 app.py；需要指定隔离端口时使用项目venv的 uvicorn app:app -# 自测(改动相关模块后至少跑相关测试) -cd /f/mini-OpenClaw/backend && source venv/Scripts/activate -python test_risk_agent_completion.py -python test_review_assist.py 2>/dev/null || echo "无该测试,视改动定" -# API 自检: curl http://localhost:8002/docs / 或 /api/… 看路由响应 +# 前端：另开终端 +Set-Location F:\mini-OpenClaw-local-stable +npm run dev + +# 行为改动后的统一验证，包含后端测试、前端构建和Compose配置 +.\backend\venv\Scripts\python.exe scripts/verify.py ``` +后端默认8002，前端开发默认3000；API健康检查为 `/api/xingbang/health`。验证日志在 `test-evidence/`；失败不得发布镜像。端口占用先核对进程归属，不能为启动v2停止旧版或其他任务。 + ## 🛑 变更纪律(核心。防止把已跑通的逻辑改坏) 1. **最小改动**:只改本次任务直接相关的范围。禁止顺手重构、重排、重命名、改格式;看到能优化的代码**先不动**,除非它挡事。 @@ -55,7 +65,7 @@ python test_review_assist.py 2>/dev/null || echo "无该测试,视改动定" ## 已知坑(务必遵守) - **系统代理 127.0.0.1:7890**:后端 `llm`/网络调用会被全局代理干扰,`Connection error / 代理错误` 时用项目自带启动脚本(已自动禁用代理)或 `no_proxy`。别手动留代理变量。 -- **端口占用**:8002 被占 → `netstat -ano | findstr :8002` + `taskkill /F /PID `;前端 3000 冲突同理。 +- **端口占用**：先用 `netstat -ano | findstr :8002` 确认占用与进程归属；仅停止本任务明确可停止的进程，否则为v2选择隔离端口并同步代理与测试配置。前端3000同理。 - **必须用 `backend/venv` 虚拟环境**,别用系统 Python。LlamaIndex/依赖都在这个 venv 里。 - **节点 3000 前端是 Next.js**:改页面后不如鉴是 Node build;SSR/客户端组件区别,别引入后端跑不动的代码。 diff --git a/docs/project-process/01-requirement.md b/docs/project-process/01-requirement.md index f8139fa..ddb5c9b 100644 --- a/docs/project-process/01-requirement.md +++ b/docs/project-process/01-requirement.md @@ -12,10 +12,10 @@ ### 1.1 进入条件 - 需求来源明确（谁提的、要解决什么问题、对哪些角色生效）。 - 明确本轮范围 vs 明确不在本轮范围（out-of-scope 与 in-scope 同等重要）。 -- 单一交付面还是多交付面已确认（web / Electron 主进程 / 硬件网关 / 设置面板……每个交付面都会让规格多一段）。 +- 单一交付面还是多交付面已确认（客户经理工作台 / 评审工作台 / 管理配置 / 后端 API……每个交付面都会让规格多一段）。 ### 1.2 完成条件（DoD） -- [ ] 七段结构齐全（多交付面则第 3 段重复），每个领域术语都进术语表 +- [ ] 七段结构齐全（多交付面则第 3 段重复），每个领域术语都进术语表（预审/正式审批、经验适用、缺证、模拟/真实、概率校准必须分清） - [ ] 每条业务规则 `BR-xx` 可测试（能说清"什么输入让它过、什么输入让它挂"） - [ ] 每条规则隐含的失败路径都有 `E-xx`，异常"用户可见消息 ↔ 后端错误码"绑定 - [ ] 每条 `BR-xx` / `E-xx` 至少被一条 `AC-xx` 引用；验收含正常/异常/边界三类用例 @@ -55,7 +55,7 @@ Decision Record ``` -> 参考模板：`vendor/better-harness/references/bootstrap/examples/frontend-web-spec.md`（前端表面）、`backend-service-spec.md`（多交付面）、`mobile-app-spec.md`（离线/权限/版本）。**复用结构，不复用表名/端点/阈值/角色名。** +> 产品级模板见 [URD模板](templates/URD-Template.md)，兴邦规格示例见 [v2需求](../v2/01-requirements.md)。复用结构，不复制其他项目的表名、端点、阈值和角色。模拟数据、真实数据及正式审批边界必须明确。 ### 3.2 六道完备性门（任一不过，禁止进入实现） @@ -69,7 +69,7 @@ | **Decision gate 决策门** | 本轮范围内没有未决问题阻塞规则；要么移出范围，要么解决 | ### 3.3 交付物清单 -- 规格文档（本地草稿放 `docs/plans/`，**不入库**，见 `.gitignore`；需入库的规格随 PR 放 `docs/` 对应目录，命名 `<日期>-<主题>-spec.md`） +- 规格文档放 `docs/v2/` 或对应业务文档目录并入库，标明草稿/已确认；临时试验可放 `test-evidence/`，不假设其他目录已被Git忽略。 - （可选）给 UI 需求的面：指向 [04-ui-spec.md](04-ui-spec.md) 的表面规格拆分 --- @@ -85,3 +85,5 @@ - 阶段 ② [02-architecture.md](02-architecture.md)、阶段 ④ [04-ui-spec.md](04-ui-spec.md) - 规格→实现→验证的流程闭环定义见 [README.md](README.md) 全景 + +变更：XB-1.0 / 2026-09-28，按兴邦 Next.js + FastAPI 项目事实适配；稳定规则编号保留。 diff --git a/docs/project-process/02-architecture.md b/docs/project-process/02-architecture.md index 9555e33..4471a19 100644 --- a/docs/project-process/02-architecture.md +++ b/docs/project-process/02-architecture.md @@ -17,8 +17,8 @@ - [ ] 分层与依赖方向明确：数据只能往哪个方向流、禁止哪些反向依赖 - [ ] 每个模块有唯一 owner 与清晰职责；没有"第二份 owner"（同一概念不复制两处实现） - [ ] 关键决策以 ADR 形式记录（结论 + 被否方案 + 理由），决策号稳定（如 D1/D2） -- [ ] 数据流/主链路（含失败路径）有图或文字描述，与现有架构基线（`docs/architecture/architecture-overview.md` 分层图）能对上 -- [ ] 风险与副作用边界已标注：哪些是高危操作（生产数据、硬件写、外发请求）、默认拒绝还是需审批 +- [ ] 数据流/主链路（含失败路径）有图或文字描述，与现有架构基线（`docs/兴邦金租对公智能评审平台技术路径与AgentLoop说明-v1.0.md` 及已检查代码）能对上 +- [ ] 风险与副作用边界已标注：哪些是高危操作（生产数据、经验发布、外发请求）、默认拒绝还是需审批 - [ ] 架构不变量可被机器验证的部分列出（对应 lint/architecture test/契约测试） --- @@ -27,12 +27,12 @@ | 编号 | 规则 | |---|---| -| R-2.1 | **依赖单向**：renderer → preload → IPC handler → domain service → state / Pi runtime；service 不依赖 UI 层与宿主；禁止跨层绕行。本仓现状：`src/main/`（Electron 宿主：index/preload/app-menu/macos/update/host）· `packages/agent-sdk/`（服务主体，零 electron 导入）· `packages/web-ui/`（renderer SPA）· `packages/api/`（dk-api 契约）。 | -| R-2.2 | **唯一 owner**：跨进程/跨模块的类型只在共享层定义一次，其余侧只 `import type`；禁止本地镜像同一契约。 | +| R-2.1 | **依赖单向**：src页面/组件 → Next同源代理 → backend/api → backend/services → 受控工具/存储/模型；service不依赖UI。业务模型通过冻结快照和工具白名单访问事实，不能绕过授权直连数据库。 | +| R-2.2 | **唯一owner**：既有业务模型以backend/contracts/project_assistant.py及实际请求模型为基线；新契约明确唯一Pydantic定义和前端同步方式，不在多处手工维护冲突语义。自动生成链未实现前不能宣称已防漂移。 | | R-2.3 | **架构不变量写入文档且可验证**：能用测试/静态检查强制的（模块边界、依赖方向、迁移追加、白名单），不许只写文档；验证不了的规则不写进"不可违背"清单。 | | R-2.4 | **决策要留痕**：架构层面的每个取舍写成 ADR（背景/决策/被否方案/影响），不搞口头决定。被否方案是决策记录的一部分。 | | R-2.5 | **分层不做多余抽象**：无第二调用方的接口不抽象；不为想象中的灵活性提前配置化（Karpathy 准则：最小代码解决当前问题）。 | -| R-2.6 | **边界即安全**：跨进程 IPC、硬件写、外发请求、文件写入都有明确边界与校验点；高危路径默认拒绝或显式审批（见 [07-delivery.md](07-delivery.md) 高风险审批）。 | +| R-2.6 | **边界即安全**：API、SQL数据卡、文件、模型出口、经验发布和部署都有校验/权限/审计；生产数据和外发依任务授权或已批准策略执行。 | | R-2.7 | **架构图遵守作者契约**：用图时按下方 §3.2 的五类图规则（架构/工作流/时序/数据流/生命周期）绘制，只画验证过的事实，不画"可能"的关系。 | --- @@ -45,14 +45,14 @@ 1. 概览（一屏） 一句话定位 + 分层图 + 本改动在哪个层 2. 分层与模块边界 模块清单：职责 / owner / 依赖方向 / 禁止的反向依赖 3. 数据模型与持久化 表/文件/状态的归属与迁移策略（追加式迁移，禁改历史） -4. 关键流程 主链路 + 失败/恢复路径（任务运行、硬件发现、网关、升级等） -5. 接口与集成点 跨进程契约、外部依赖（硬件协议、网关、云服务）、版本约束 +4. 关键流程 主链路 + 失败/恢复路径（任务运行、材料确认、经验发布、模型调用、补件重跑等） +5. 接口与集成点 跨进程契约、外部依赖（业务数据库、模型端点、数据出口和云服务）、版本约束 6. 风险与副作用边界 高危操作清单：触发条件 / 审批点 / 审计点 / 回滚 7. 决策记录（ADR） D1/D2…：决策 + 被否方案 + 影响 8. 验证方式 架构不变量对应的测试/门禁 ``` -> 本仓已有基线：`docs/architecture/architecture-overview.md`（分层总览）+ `docs/architecture/codemap.md`（模块地图，头部统计由 `scripts/repo-stats.mjs` 生成）。新架构文档放在 `docs/architecture/`（入库基线）或 `docs/plans/`（本地草稿，不入库，见 `.gitignore`），并保持与基线一致；基线变更要同步。 +> 当前基线见 [既有技术路径](../兴邦金租对公智能评审平台技术路径与AgentLoop说明-v1.0.md)，新版提案见 [v2架构](../v2/02-architecture.md)。架构草案入库并标状态；模块统计和调用关系要实际检查，不引用不存在的生成脚本。 ### 3.2 架构图规范（五类，摘要） @@ -64,7 +64,7 @@ | Dataflow | 阶段=转换/保管；行=并行流；只标注数据契约与跨边界移动 | | Lifecycle | 主相位列 0..4；可恢复失败必须有真实回迁转换 | -> 构图约定：图以 Mermaid / 文本图为主（见 `docs/architecture/flows.md`、`docs/release-process.md` 既有图例），只画代码检查证实的事实，不画"可能"的关系，并保证 lint/渲染校验可通过。 +> 构图以 Mermaid / 文本图为主。现状图只画代码证实的事实；目标图单独标“候选/未实现”，不能混画。验证结构和可读性，未实际渲染时如实说明。 ### 3.3 交付物清单 - 架构文档（含分层/边界/数据流/风险） @@ -77,7 +77,7 @@ ## 4. 轻量路径（小改动） - 单模块内、无跨进程/持久化/外部的改动：架构要求并入详细设计开头一小节（边界 + owner + 依赖方向），不单独成文。 -- 改动触碰 `packages/api/src/contracts.ts`（跨进程契约）、IPC、迁移、安全边界时，**必须**走完整架构设计。 +- 触碰 `backend/contracts/`、公开API/事件、数据迁移、权限或模型数据出口时，必须走完整架构设计。 --- @@ -86,3 +86,5 @@ - 输入：阶段 ① [01-requirement.md](01-requirement.md) - 输出到：阶段 ③ [03-detailed-design.md](03-detailed-design.md) - 变更矩阵（架构文档随代码同步）：[05-implementation.md](05-implementation.md) §3.3 + +变更：XB-1.0 / 2026-09-28，按兴邦 Next.js + FastAPI 项目事实适配；稳定规则编号保留。 diff --git a/docs/project-process/03-detailed-design.md b/docs/project-process/03-detailed-design.md index 7176161..b533c92 100644 --- a/docs/project-process/03-detailed-design.md +++ b/docs/project-process/03-detailed-design.md @@ -14,7 +14,7 @@ - 规格的 `BR-*`/`E-*`/`AC-*` 全部可映射到具体接口/数据/状态。 ### 1.2 完成条件（DoD） -- [ ] 每个公开接口（函数/方法/事件/IPC 通道/硬件协议命令）有签名、入参校验规则、返回与错误语义 +- [ ] 每个公开接口（HTTP/SSE端点、函数、模型工具及业务事件）有签名、入参校验规则、返回与错误语义 - [ ] 每个数据结构（表/文件/状态对象）有字段、类型、可空性、owner；变更走追加式迁移且有守卫 - [ ] 每个有状态视图/流程有状态机（状态全集 + 合法转换 + 每个状态的禁用手势） - [ ] 规格中每条 `E-*` 都能落到具体错误码 + 处理路径（重试/降级/回滚） @@ -28,7 +28,7 @@ | 编号 | 规则 | |---|---| | R-3.1 | **契约先行且单一**：接口与数据契约在详细设计中定案，实现只落契约不发明契约；跨进程契约只放共享层一处（G-1）。 | -| R-3.2 | **入参显式校验**：每个对外接口（IPC、命令、硬件写入、外部请求）的入参都有校验（类型/枚举/边界），禁止裸用；"无入参"是唯一例外。通用校验器不得被滥用成"非空字符串检查"。 | +| R-3.2 | **入参显式校验**：每个对外接口（HTTP、文件上传、SQL数据卡参数、模型请求和服务命令）的入参都有校验（类型/枚举/边界），禁止裸用；"无入参"是唯一例外。通用校验器不得被滥用成"非空字符串检查"。 | | R-3.3 | **状态机完备**：状态全集含加载/空/错误/提交中等"非 happy path"状态；每个状态定义允许的动作与禁用手势。折叠状态机（如把 Loading 与 Submitting 合并成一个布尔）会丢失关键行为，禁止。 | | R-3.4 | **异常必有归属**：每条失败路径有明确处理语义（重试上限、降级、回滚、幂等）与错误码；静默失败是设计缺陷。 | | R-3.5 | **迁移只追加**：持久化结构变更只能追加带守卫的迁移（版本号递增 + 幂等守卫），禁止修改历史迁移；迁移只跑一次。 | @@ -54,12 +54,12 @@ ``` ### 3.2 契约声明（可落地的部分） -- 类型定义：跨进程契约先写在 `packages/api/src/contracts.ts`（唯一事实源），宿主与各包只 `import type`；包内契约就近在包内共享层声明。 +- 类型定义：新增共享业务契约优先位于 `backend/contracts/`，由FastAPI请求/响应模型引用；前端同步以已验证的生成物或契约测试为准。当前不存在完整OpenAPI生成流水线，建设前标为待实现。不要顺手重排旧API的所有请求模型。 - 数据结构草案：DDL/迁移骨架，标注幂等守卫。 - 状态机表：Markdown 表格即可，复杂流程可配 sequence 图（见 [02-architecture.md](02-architecture.md) §3.2）。 ### 3.3 交付物清单 -- 详细设计文档（本地草稿 `docs/plans/`（不入库，见 `.gitignore`），需入库随 PR 放 `docs/` 对应目录） +- 详细设计文档入 `docs/v2/` 或相应业务目录，注明草案/定案和所覆盖需求编号。 - 契约草案（类型/迁移/错误码表） - 测试映射表（为 ⑥ 验证做准备） @@ -68,7 +68,7 @@ ## 4. 轻量路径（小改动） - 单接口小改：契约 + 边界 + 测试映射合并为设计文档中的 2-3 小节。 -- 触碰共享契约、迁移、状态机、硬件协议：必须完整走详细设计。 +- 触碰共享契约、迁移、状态机、模型工具与数据出口：必须完整走详细设计。 --- @@ -77,3 +77,5 @@ - 输入：阶段 ① [01-requirement.md](01-requirement.md)、阶段 ② [02-architecture.md](02-architecture.md) - UI 相关设计拆到：阶段 ④ [04-ui-spec.md](04-ui-spec.md) - 实现时按此设计编码：阶段 ⑤ [05-implementation.md](05-implementation.md) + +变更：XB-1.0 / 2026-09-28，按兴邦 Next.js + FastAPI 项目事实适配；稳定规则编号保留。 diff --git a/docs/project-process/04-ui-spec.md b/docs/project-process/04-ui-spec.md index 7b16dc4..6516d91 100644 --- a/docs/project-process/04-ui-spec.md +++ b/docs/project-process/04-ui-spec.md @@ -5,7 +5,7 @@ > **输出**：表面规格 + DESIGN.md（含 token）+ i18n 约束。 > **进入下一阶段（⑤ 实现）**：状态机、动作权限、设计 token、i18n 全部定案。 -> 适用判定：本阶段仅当改动拥有用户可见 UI（web 界面、Electron 窗口、设置面板、硬件设备界面）时强制；纯后端/网关/CLI 改动标记 `not applicable`。 +> 适用判定：本阶段仅当改动拥有用户可见 UI（项目工作台、评审页面、材料与配置界面、证据/模拟面板）时强制；纯后端/网关/CLI 改动标记 `not applicable`。 --- @@ -19,7 +19,7 @@ - [ ] 每个交付面有：页面骨架 + 组件粒度边界 + 完整状态机 + 动作×权限表 - [ ] 每个 UI 提交/展示的字段能在规格 §2 找到（契约门） - [ ] 视觉 token（颜色/字号/间距/圆角/组件）有语义化来源，不出现临时发明的 `blue500` 类裸色 -- [ ] 全部 UI 文案走 i18n（本仓：`packages/web-ui/src/i18n/messages.ts`，zh-CN/en-US 双语），无硬编码用户可见字符串 +- [ ] 新版文案有统一维护方式、错误码映射和语言范围；当前主要中文组件内文案，统一key化方案待建设，不声称已有双语语言包 - [ ] 可访问性约束写明：对比度（WCAG AA）、focus-visible、颜色不单独承载状态、reduced-motion - [ ] 异常态（加载/空/错误/禁用/提交中）有明确视觉与文案定义（对应规格 `E-*`） @@ -42,9 +42,9 @@ | 编号 | 规则 | |---|---| -| R-4.7 | **视觉事实源唯一**：有 UI 的项目维护唯一的视觉 token 事实源（本仓现状：`packages/web-ui/src/theme/tokens.css`，语义 token + CSS 变量，经 `styles.css` `@import` 消费；若将来建根级 `DESIGN.md` 则与之对齐）；禁止在组件里临时发明颜色/间距/字号。 | +| R-4.7 | **视觉来源明确**：先检查src/app/globals.css、src/components/xingbang/navigation.css和当前页面CSS；v2视觉契约在docs/v2/DESIGN.md，统一token实现待建设。避免新增互相冲突的裸色/间距，不顺手重构无关旧页。 | | R-4.8 | **语义 token 优先**：token 用语义角色（`primary`/`surface`/`danger`），不用调色板名（`teal-500`）；组件 token 带状态（如 `button-primary-hover`、`text-input-focused`）。 | -| R-4.9 | **token 可导出可防漂移**：token 能导出为 CSS 变量/主题，并用 lint/diff/单测检查漂移（本仓：`tokens.css` 变量 + `styles.test.ts` 等单测守卫；`useAppearance.ts` 归一化主题 id）；"文件存在"不等于"被使用"（G-3）。 | +| R-4.9 | **防漂移须执行**：新token统一来源需有实际消费和可运行检查。当前scripts/test_ui_readability.cjs是源码守卫，不是完整token导出检查；缺少机制列待办。 | | R-4.10 | **可访问性硬约束**：正文与 focus 态满足 WCAG AA 对比度；错误/成功/选中状态不得只靠颜色表达；支持 reduced-motion；表单与错误态有明确指引。 | | R-4.11 | **不强推框架外规范**：后端/CLI/纯数据项目标记 `not applicable`，不套用视觉契约。 | @@ -52,9 +52,9 @@ | 编号 | 规则 | |---|---| -| R-4.12 | 所有用户可见文案走 key 化翻译（本仓：`packages/web-ui/src/i18n/messages.ts`，扁平 key + `t(key, params?)`，key 按命名空间组织：`common.*`/`task.*`/`settings.*`/`shell.*`/`inspector.*`/`mode.*`）；禁止硬编码中文/英文串。 | -| R-4.13 | 多语言文案与 UI 状态同步维护；新增文案必须同时补齐既有语言包。 | -| R-4.14 | 设备端/子窗口界面不做 i18n 决策，文案由宿主统一注入（避免每窗口维护语言状态）。 | +| R-4.12 | 新版文案按业务域规划key并绑定错误码；实际文件位置和调用方法在UI设计阶段明确。当前仅有中文文案，不能凭空引用语言包；旧页面修复遵循最小范围。 | +| R-4.13 | 已支持的语言与UI状态同步维护；增加语言需明确范围和验收，不因来源模板写有双语就扩充产品需求。 | +| R-4.14 | API返回稳定错误码，前端统一映射业务文案；同源代理转发错误语义，不自行生成另一套判断或吞错。 | --- @@ -72,7 +72,7 @@ Interaction 交互约束：URL 状态、选择集规则、确认对话 Constraints ``` -> 模板参考：`vendor/better-harness/references/bootstrap/examples/frontend-web-spec.md` 的 §3（复用结构，内容必须基于本仓事实）。 +> 兴邦表面规格示例见 [v2 UI Spec](../v2/04-ui-spec.md)，需求编号仍回链至对应规格。 ### 3.2 DESIGN.md 结构 @@ -85,11 +85,11 @@ Markdown（人读） Overview / Colors / Typography / Layout / Elevat + 每个 token 的"何时用 / 何时不用 / 防止什么 agent 错误" ``` -> 完整示例：`vendor/better-harness/case-studies/project-harness/design-md-complete-example.md`（结构性回退模板，数值必须替换为本仓已核实的来源）。若项目尚无 DESIGN.md：从现有代码/主题推断并标注"推断"，未决品牌决策标记 `needs-design-decision`，禁止编造。 +> 参考 [v2 DESIGN.md](../v2/DESIGN.md)。已观察值注明CSS来源，推断标“推断”，未定品牌决策标needs-design-decision；候选契约未被CSS消费不能宣称视觉系统已统一。 ### 3.3 交付物清单 - 每个交付面的表面规格 -- `DESIGN.md`（若建）或其缺失项清单；本仓现状：视觉 token 事实源为 `packages/web-ui/src/theme/tokens.css`（含证据分级：Present / Structured / Token-ready / Agent-ready / Aligned / Backstopped） +- `DESIGN.md`或缺失清单；现有来源为src/app/globals.css和业务CSS。记录Present/Structured/Token-ready/Aligned/Backstopped证据等级，不能跳级。 - i18n key 清单（新增/变更） - UI 验收映射：表面规格的每条交互约束 ↔ 规格 `AC-xx` ↔ [06-validation.md](06-validation.md) 的测试点（组件/E2E） @@ -114,3 +114,5 @@ Markdown（人读） Overview / Colors / Typography / Layout / Elevat - 输入：阶段 ① [01-requirement.md](01-requirement.md) §3、阶段 ③ [03-detailed-design.md](03-detailed-design.md) - 验证：阶段 ⑥ [06-validation.md](06-validation.md)（UI 驱动平面与裁判分离约束） + +变更：XB-1.0 / 2026-09-28，按兴邦 Next.js + FastAPI 项目事实适配；稳定规则编号保留。 diff --git a/docs/project-process/05-implementation.md b/docs/project-process/05-implementation.md index a923bc1..fa2459e 100644 --- a/docs/project-process/05-implementation.md +++ b/docs/project-process/05-implementation.md @@ -15,7 +15,7 @@ ### 1.2 完成条件（DoD） - [ ] 每个提交只做一件事（Conventional Commits），变更可逐行追溯到请求范围 -- [ ] 新行为有 colocated 测试（与源码同目录 `*.test.ts`，vitest；E2E 在 `e2e/`，playwright。本仓测试体系见 `docs/architecture/testing-architecture.md`） +- [ ] 行为新增/修改有对应backend/test_*.py或适用前端行为测试；保留现有scripts/test_*.cjs守卫并明确其覆盖边界；不虚构已存在的E2E套件 - [ ] 无未使用 import/变量/函数（由本次改动产生的孤儿已清理；存量死代码只提不改，G-4） - [ ] 变更矩阵已同步（见 §3.3）：契约、文档、i18n、迁移、架构图 - [ ] 本阶段自测（lint/typecheck/相关单测）全绿 @@ -33,15 +33,15 @@ | R-5.3 | **外科手术式改动**：只碰必须碰的；不顺手"改进"相邻代码/注释/格式；不重构没坏的东西；风格跟随现有代码。 | | R-5.4 | **规模红线**：新文件 ≤500 行；既有大文件只减不增；新增依赖必须先评估体积与必要性（依赖红线见仓库约定）。 | | R-5.5 | **状态持久化白名单**：新增受管写入路径须进白名单并说明；禁止绕过既有持久化/校验路径自行写文件。 | -| R-5.6 | **小步提交**：一个提交一个意图；变更混杂时先拆分再提交（见 `skills/builtin/dk-commit` 的提交规范）。 | +| R-5.6 | **小步提交**：一个提交一个意图；变更混杂时先拆分再提交（类型前缀+中文一句话，提交前自查diff）。 | ### 2.2 安全与副作用（实现期强制） | 编号 | 规则 | |---|---| -| R-5.7 | 所有副作用入口（文件写、命令执行、外发请求、硬件写、IPC）走统一受控路径，禁止平行执行路径。 | +| R-5.7 | 所有副作用入口（文件写、命令执行、外发请求、数据导出、API）走统一受控路径，禁止平行执行路径。 | | R-5.8 | 项目目录写入/命令必须有归属校验 + 审计；凭据/配置保护区一律拒绝。 | -| R-5.9 | 日志/输出禁止出现凭据任何片段（脱敏）；禁止 `nodeIntegration: true`、禁止绕过 preload/安全边界暴露主机能力。 | +| R-5.9 | 日志/输出不得含凭据；浏览器不能持有模型Key或数据库口令，业务预审不得继承通用聊天的终端/任意文件权限；材料指令不得扩大工具集合。 | | R-5.10 | 高危动作（删除、生产数据、外发、发布）默认拒绝或显式审批，先于副作用发生，且留审计（详见 [07-delivery.md](07-delivery.md)）。 | ### 2.3 契约与同步 @@ -61,11 +61,11 @@ - colocated 测试（新行为 + 修复回归） - 变更同步产物（契约/迁移/文档/i18n） -### 3.2 提交规范（本仓沿用 `AGENTS.md` 规则 6 + Conventional Commits；生成建议见 `skills/builtin/dk-commit`） +### 3.2 提交规范（根AGENTS.md + Conventional Commits） ```text (): # subject 简洁中文，≤50 字 - # 正文：英文完整内容 + `---` 分隔 + 中文完整内容 - # （不复述 diff；主分支是 build） + # 必要正文说明验证与限制，不要求双语 + # 默认分支目前为Gitea main，操作前核对 type: feat | fix | docs | refactor | test | chore | build ``` @@ -73,13 +73,13 @@ type: feat | fix | docs | refactor | test | chore | build | 变更 | 必须同步 | |---|---| -| 跨进程契约 / IPC 通道 / 接口 | `packages/api/src/contracts.ts`（唯一入口）+ `docs/api/ipc-api-reference.md` + preload/handler 对齐（`src/main/ipc-alignment.test.ts` 拦截） | -| 模块增删 / 职责变化 | `docs/architecture/codemap.md`（头部统计跑 `node scripts/repo-stats.mjs`，`docs-baseline.test.ts` 拦截）+ 架构文档 | -| 数据结构 / 迁移 | 迁移文件（只追加，`packages/agent-sdk/src/state/migrations.ts`）+ `docs/architecture/data-model.md` | -| UI 文案 / 状态机 / 组件 | i18n key（`packages/web-ui/src/i18n/messages.ts`）+ 视觉 token（`packages/web-ui/src/theme/tokens.css`）+ 表面规格 | -| 主链路 / 安全边界 | `docs/architecture/flows.md` + 相关安全测试（tool-policy/tool-gate/redact） | -| E2E 行为 / 运行方式 | E2E 测试与自动化文档（`docs/e2e/e2e-architecture-and-automation.md`）+ playwright | -| 宿主形态 / 接入方式 | `docs/architecture/host-modes.md` | +| API / SSE / 共享契约 | backend/contracts或明确的API模型owner + 前端调用方/同源代理 + 接口设计 + 契约测试 | +| 模块增删 / 职责变化 | 实际调用关系 + docs/v2/02-architecture.md或对应架构文档，已实现与提案分开 | +| 数据结构 / 迁移 | 追加带守卫的迁移 + 数据契约 + 幂等/版本兼容测试，旧表和生产数据保留 | +| UI 文案 / 状态机 / 组件 | 文案与错误映射 + 实际CSS来源/视觉契约 + 表面规格 + UI测试 | +| 主链路 / 安全边界 | 运行/经验/模型出口设计 + 权限、注入、跨域、证据与模拟隔离测试 | +| E2E 行为 / 运行方式 | 实际浏览器测试入口和前后端启动说明；静态正则检查不能替代E2E | +| 部署 / 数据源接入 | Compose与环境模板 + 部署文档 + config验证；真实数据出口另验 | --- @@ -104,4 +104,6 @@ type: feat | fix | docs | refactor | test | chore | build - 编码前确认设计：阶段 ③ [03-detailed-design.md](03-detailed-design.md)、阶段 ④ [04-ui-spec.md](04-ui-spec.md) - 自测通过后进入：阶段 ⑥ [06-validation.md](06-validation.md) -- 提交与审查技能：`skills/builtin/dk-commit`、`skills/builtin/dk-review` +- 提交与审查按根AGENTS和阶段⑥执行；本仓不依赖未安装的提交/评审技能。 + +变更：XB-1.0 / 2026-09-28，按兴邦 Next.js + FastAPI 项目事实适配；稳定规则编号保留。 diff --git a/docs/project-process/06-validation.md b/docs/project-process/06-validation.md index c07c22e..33611a7 100644 --- a/docs/project-process/06-validation.md +++ b/docs/project-process/06-validation.md @@ -16,7 +16,7 @@ - [ ] 每个实质改动映射到最小且覆盖它的项目检查（单测/契约/集成/E2E/视觉/迁移/打包之一），并在最后一次编辑后运行 - [ ] 验证失败按"复现 → 定位（可归因的诊断）→ 因果假设 → 最小 owner 修复"链处理；重试不加诊断 ≠ 修复证据 - [ ] 修复后在最终状态上**重跑同一检查**（或记录等价性理由） -- [ ] 评审（dk-review 四维）完成：正确性/一致性/安全/测试，无未解决的阻塞项 +- [ ] 评审（正确性/一致性/安全/测试四维）完成：正确性/一致性/安全/测试，无未解决的阻塞项 - [ ] 门禁结果与最终修订绑定（不是"跑过"而是"这个 revision 过了"） --- @@ -62,22 +62,22 @@ 残余风险： 未覆盖范围、跳过守卫的用例、需人工确认项 ``` -### 3.2 验证分层建议（本仓） +### 3.2 验证分层与实际入口 | 层 | 内容 | 触发 | |---|---|---| -| L0 静态 | typecheck（`npm run typecheck`：tsc --noEmit + 双 tsconfig） | 每次提交 | -| L1 单测 | 组件/工具/逻辑（vitest，colocated `*.test.ts`，`npm test`） | 每次提交 | -| L2 契约/守卫 | 跨进程契约对齐（`src/main/ipc-alignment.test.ts`）、迁移守卫（`migrations.test.ts`）、架构守卫（`architecture-guardrails.test.ts`）、docs 基线 | 触碰共享层/迁移 | -| L3 集成 | 主进程+渲染、宿主装配 | 主链路 | -| L4 E2E | `npm run test:e2e`（playwright，需先构建） | 关键用户流/发布前 | -| L5 打包冒烟 | `build/ci-local.ps1`（Windows）/ `build/ci-local.sh`（macOS/Linux）：干净安装+全量门禁+安装包+启动冒烟 | 发布前 | +| L0 静态 | git diff --check；npm run build包含类型检查；文档链接/编号/事实检查 | 对应改动后 | +| L1 单测 | 在backend工作目录用其venv执行python -m unittest discover -s . -p test_*.py -v；建议由verify统一执行 | 后端行为修改 | +| L2 契约/守卫 | backend/test_assistant_components.py等已有测试与scripts/test_*.cjs；按新契约增加反例 | 契约/权限/页面规则修改 | +| L3 集成 | API + services + 临时测试数据库/fixtures，禁依赖真实客户库 | 主链路 | +| L4 E2E | 真实浏览器按本批用例操作并断言，记录实际入口/环境；当前未确认统一E2E套件 | 关键用户流 | +| L5 打包冒烟 | Docker Compose config；获授权后独立资源上运行verify.py --docker，另做目标环境验收 | 发布前 | -> 本仓测试体系单一事实源：`docs/architecture/testing-architecture.md`；E2E 执行线见 `docs/e2e/e2e-architecture-and-automation.md`。验证要求按此落地，发现矩阵缺口在阶段 ⑧ 反馈。 +> 实际总入口为 `scripts/verify.py`：项目backend/venv执行，日志在test-evidence。当前没有package.json中的typecheck、test或test:e2e脚本，不得写成已执行。新版测试规划见 [v2验证](../v2/06-validation.md)。行为修改必须跑总入口，纯文档可用相关链接/编号/路径/diff检查。 ### 3.3 交付物清单 - 验证记录（含失败→修复→复验链） -- 审查结论（dk-review 输出，阻塞项清零） +- 审查结论（四维逐项记录；独立评审未完成须说明，不能自称已获他人批准） - 测试覆盖增量说明（新增测试对应的 AC/BR/E） --- @@ -94,7 +94,7 @@ ## 5. 轻量路径（小改动） -- 一行修复：对应单测 + 全量 typecheck + 该模块相关测试，记录即可。 +- 小行为修复：对应测试 + scripts/verify.py，保留完整日志；纯文档：链接、编号、事实与diff检查。 - 任何改动都不得跳过 R-6.3/R-6.4（诊断与复验）与 R-6.7（门禁）。 --- @@ -104,3 +104,5 @@ - 输入：阶段 ⑤ [05-implementation.md](05-implementation.md)、规格 [01-requirement.md](01-requirement.md) 的 AC - UI 验证细则：阶段 ④ [04-ui-spec.md](04-ui-spec.md) §4 - 通过后进入：阶段 ⑦ [07-delivery.md](07-delivery.md) + +变更：XB-1.0 / 2026-09-28，按兴邦 Next.js + FastAPI 项目事实适配；稳定规则编号保留。 diff --git a/docs/project-process/07-delivery.md b/docs/project-process/07-delivery.md index ef5f612..1ba36f5 100644 --- a/docs/project-process/07-delivery.md +++ b/docs/project-process/07-delivery.md @@ -1,143 +1,69 @@ -# 阶段 ⑦ 交付与发布（Delivery & Release） +# 阶段 ⑦ 交付与发布 -> **定义**：让当前结果在**真实交付边界**被接受——真实的评审、必需的 CI、合并、发布——且高风险动作有风险匹配的审批、副作用有可用的回滚/恢复路径。本地测试与 agent 一句"done"属于阶段 ⑥，不属于交付。 -> **输入**：⑥ 已通过的实现（验证记录 + 门禁结果 + 审查结论）。 -> **输出**：已接受的修订 + 构建/安装包 + 发布记录 + 审计。 -> **进入下一阶段（⑧ 学习与沉淀）**：交付边界接受完成、发布记录落档。 +输入：验证通过的修订及证据。输出：实际目标分支/环境接受记录、产物和回滚路径。备份、合并、镜像推送、云端部署是四个不同边界。 ---- +## 1. 要求与DoD -## 1. 要求（Requirements） +- [ ] 明确本次是源码备份、文档交付、代码合并还是部署，不能混称上线。 +- [ ] 验证绑定最终源码修订；未通过时不发布镜像。 +- [ ] 外部/生产/共享状态变更有任务授权及可核验记录；已有授权无需重复确认。 +- [ ] 分支/镜像/数据资源有明确恢复路径和owner。 +- [ ] 目标环境实际观测成功；未观测项标Unobserved。 -### 1.1 进入条件 -- 阶段 ⑥ 全部质量门通过，无未解决阻塞项。 +## 2. 规则 -### 1.2 完成条件（DoD） -- [ ] 真实接受边界（合并/发布/部署）绑定到**当前修订**，有修订级决策证据（不是"跑过 CI"而是"这个 revision 合并了/发布了"） -- [ ] 每个高风险动作（发布、删除、生产数据、外发、签名）在副作用**之前**获得所需审批并留审计 -- [ ] 实际副作用有风险匹配的回滚/恢复路径（回滚、恢复、重试、补偿、幂等重放、安全中止之一）且含 owner 与后置条件 -- [ ] 发布记录（版本、变更、产物、验证）落档 - ---- - -## 2. 规则（Rules） - -### 2.1 接受边界 - -| 编号 | 规则 | +| ID | 规则 | |---|---| -| R-7.1 | **真实边界证据**：把真实接受决策绑定到当前修订与目标分支/环境。本地测试、自测、agent 完成声明均不是交付证据；外部边界打不开时记 `Unobserved`，不编造缺失的 PR/部署。 | -| R-7.2 | **合并路径**：改动经默认分支可比较的 diff 进入（分支/PR 或等价受控路径）；直接在默认分支开发、无可评审 base diff 属交付缺陷。 | -| R-7.3 | **必需检查绑定**：合并前必需检查对最终修订全绿，且与本地命令一致或有明确差异说明。 | +| R-7.1 | 真实边界证据绑定revision：远程分支SHA、合并记录、镜像摘要、目标健康检查分别记录；本地通过不能冒充部署 | +| R-7.2 | 改动通过可比较的分支/PR进入默认分支；本项目当前main，操作前核对；不直接覆盖main | +| R-7.3 | 必需检查绑定最终源码修订；验证之后有行为变化须重验相关检查 | +| R-7.4 | 删除、生产数据、模型外发、镜像发布和部署须在副作用前具有相应用户/策略授权；不足时明确具体阻塞点 | +| R-7.5 | 审计记录谁、何时、何操作、作用资源、授权来源和结果；日志不含凭据 | +| R-7.6 | 无高风险操作的项标N/A并说明；纯文档不能被误当成必须部署 | +| R-7.7 | 恢复方式绑定具体提交、镜像和数据资源，owner与恢复后检查明确 | +| R-7.8 | 可用性以安全验证支持，不能为证明回滚去破坏当前运行；未演练标未演练 | +| R-7.9 | 失败/超时也须可恢复；代码回退不等于数据恢复，迁移不得依靠删库回退 | -### 2.2 高风险审批 +## 3. 本项目执行路径 -| 编号 | 规则 | -|---|---| -| R-7.4 | 破坏性/特权/外部/不可逆/共享状态/凭据/发布/生产动作，在效果发生**前**取得所需的人或策略 owner 决策；安全拒绝 + 可用升级路径是正确的控制行为，不是失败。 | -| R-7.5 | 高风险动作留审计：谁、何时、什么、批准人/策略、审计引用。 | -| R-7.6 | 确认无高风险动作时记 `N/A`（须经检查证明），不允许无理由的 N/A 阻塞结果。 | +### 3.1 源码备份 -### 2.3 回滚与恢复 +先git status/log确认用户改动→检查新增凭据/运行数据→显式暂存选定文件→在codex/备份分支提交→推送已确认origin→git ls-remote比对SHA。备份可保存未完成状态，必须注明测试状态，不充当发布候选。 -| 编号 | 规则 | -|---|---| -| R-7.7 | 每个实际副作用有风险比例匹配的回滚/恢复路径，且绑定到受影响资源/入口/owner/后置条件。 | -| R-7.8 | 回滚/恢复须可验证（安全模拟、演练、可比的保留任务或实际恢复结果）；禁止仅为提高证据强度而执行破坏性回滚。 | -| R-7.9 | 恢复路径对失败与超时也要可运行（清理不得只在成功路径执行）。 | +不提交.env、server-deploy.conf、.docker-codex、会话/数据库/日志、Office锁文件；代码内样例须标演示。已跟踪文件不因.gitignore自动移出历史，迁移时另外检查。恢复用新目录克隆指定分支，不重置用户现有目录。 ---- +### 3.2 合并前验证 -## 3. 输出规范 +仓库根目录使用项目虚拟环境： -### 3.1 发布流程（本仓） - -> 发布链唯一权威：`docs/release-process.md`（ci-local 门禁 / release.mjs / 四包发布 / pack-audit / install-acceptance / 签名 / OTA）；签名细节 `docs/release-signing.md`；本地最短路径 `docs/local-build-quickstart.md`。以下为阶段 ⑦ 在本仓的落地步骤，任一步非零即中止。 - -```text -Step 0 离线门禁（提交/合并/发布前必过） - Windows: build\ci-local.ps1 · macOS/Linux: build/ci-local.sh → run-local-ci.mjs 八步： - ① 删 release/ → ② npm ci 离线干净安装 → ③ npm run ci:check - （build:verify:runtime → vitest 全量 → build）→ ④ playwright E2E（不重构建） - → ⑤ electron-builder --publish never 打安装包 → ⑥ package:audit - （asar 禁 dist/mac-*、release/、.map/.d.ts/.ts；体积预算 140 MiB） - → ⑦ verify-packaged-app（extraResources 五件断言 + 真启动 5s 冒烟） - → ⑧ write-build-report（逐产物 SHA-256 → build-report + SHA256SUMS） - -Step 1 版本与变更（SDK 四包发布时） - node scripts/release.mjs --registry <内网源URL> [--bump patch|minor|major] - [--skip-publish] [--dry-run] - 九步编排：install → build（拓扑序 api→agent-sdk→account→web-ui） - → sync-web-ui-dist（dist/renderer → packages/web-ui/dist，断言 index.html 字节一致） - → test → pack-audit → bump（四包+根 lockstep，dk-* 互引钉新版，再生 lockfile） - → publish-sdks.mjs 逐包 npm publish 内网源 → install-acceptance - → npm run package - 日常验证用 --dry-run --skip-publish（shouldPublish 独立纯函数，零副作用有测试断言） - -Step 2 构建安装包 + 产物审计 - npm run package = build + electron-builder --publish never + package:audit + pack:sdks - 审计（scripts/pack-audit.mjs）：tarball 顶层 ⊆ {dist, bin, README, LICENSE, package.json}； - 零测试产物；dk-account 防误发（registry 锁内网 GitLab）；公开三包无 /account/ 路径泄漏 - 安装验收（scripts/install-acceptance.mjs）：spawn dk-web → listening banner → - GET /health 200 + GET / 200 含
+ 入口 JS 200 - -Step 3 签名与公证（对外发布 / CI 打 Git tag 触发） - build/sign-local.sh（mac/Linux）/ build/sign-local.ps1（Windows）→ run-signing-build.mjs - （仅 darwin/win32；保留 APPLE_*/CSC_* 变量且不设断网） - npm ci → build → electron-builder --config.forceCodeSigning=true → package:audit - → 验签：mac codesign --verify --deep --strict；win Get-AuthenticodeSignature 双件 Valid - → 有 APPLE_APP_SPECIFIC_PASSWORD 时 DMG 公证 + stapler 装订 → 冒烟 + 构建报告 - -Step 4 OTA 更新（走 OTA 通道时） - npm run ota:manifest（scripts/ota/generate-manifest.mjs）：扫 release/ 安装包算 SHA-256 - → scripts/ota/latest.json；强制单一版本、单平台唯一；缺平台填全 0（运行侧 A6 守卫拒绝） - -Step 5 发布记录落档 - build-report + SHA256SUMS（产物校验值）· 版本与变更（release.mjs bump）· - 验证摘要（⑥ 门禁结果绑定修订）· 审批人/审计引用（高风险动作） +```powershell +.\backend\venv\Scripts\python.exe scripts/verify.py ``` -> 合并/发布边界绑定：改动经默认分支（`build`）可比较的 diff 进入；必需检查（ci-local 全链）对最终修订全绿。本仓无 CHANGELOG/RELEASE_NOTES 文件，版本与变更由 `scripts/release.mjs` 编排。 +报告位于test-evidence//REPORT.md。PR至少一人评审，目标分支和最终SHA明确。Gitea runner和必需检查未核验时如实说明，不借GitHub YAML宣称已有Gitea门禁。 -### 3.2 交付记录模板 +### 3.3 镜像与部署 -```text -目标边界： 分支 / 环境 / 发布通道 -修订绑定： 合并/发布的 revision 与决策证据（PR 号 / 发布记录） -高风险动作： 动作 | 审批人/策略 | 时间 | 审计引用 -回滚路径： 受影响资源 | 路径 | owner | 后置条件 | 验证方式 -验证摘要： ⑥ 的门禁结果绑定 -残余风险： 未覆盖边界、需人工确认项 -``` +现有入口：Dockerfile、docker-entrypoint.sh、docker-compose.yml、deploy/docker-compose.aliyun.yml；发布脚本scripts/publish-acr.ps1和scripts/publish-acr.sh；部署脚本scripts/deploy-aliyun.sh。 -### 3.3 交付物清单 -- 合并/发布证据（绑定修订） -- 构建产物 + 审计记录（build-report / SHA256SUMS / package:audit 结果） -- 发布记录（版本/变更/验证/审批） -- 回滚路径文档（高风险动作必填） +只有授权发布时才运行。发布前复查脚本参数与目标，因为当前配置是旧版资源。先verify→构建→使用不可变Git标签和镜像摘要→推ACR→目标拉取→Compose up→检查前端、/api/xingbang/health和关键业务操作→保存服务器结果。实际脚本若不足以执行某门禁，应补齐并测试后再宣称机制成立。 ---- +当前云端Compose仅绑定127.0.0.1；保持授权访问边界，公网开放需要另行定义身份、TLS和访问控制。使用示例环境文件准备实际配置，密钥经受控渠道配置；文档不存真实值。 -## 4. 反模式 +### 3.4 v2隔离 -- **本地验证冒充交付**：只有本地测试支持交付声明。 -- **先斩后奏的审批**：效果发生了才补审批，或自查自批。 -- **回滚路径悬空**：有"看起来像回滚"的文件/命令，但连不上实际资源/修订/权限/后置条件（文件名匹配不算证据）。 -- **只走发布后自动化**：仅在推到默认分支/发布时跑的检查不算接受时验证。 -- **无边界的高危可达性**：默认路径能触达生产/凭据/破坏性命令而无边界。 +v2必须独立目录、Compose项目、容器名、卷、镜像和宿主端口。未完成隔离时不得直接用旧版Compose部署新版。数据库迁移先备份并演练；不运行down -v或清理脚本删除旧业务数据。配置和脚本存在不代表隔离已验证。 ---- +## 4. 交付记录模板 -## 5. 轻量路径（小改动） +目标边界；源码SHA/分支；验证命令与日志；镜像标签/摘要（如适用）；环境与数据资源；授权来源；接受证据；回滚方式与owner；尚未验证的范围。通过率/模型效果须有业务评估，不能写成部署成功的附带结论。 -- 内部改动：合并路径 + 必需检查即可，无发布/回滚部分（记 N/A 需检查证明）。 -- 任何触达发布/生产/凭据的动作：审批与审计条款不可省略。 +## 5. 轻量路径 ---- +纯文档：链接/编号/格式/事实检查、独立提交、所需远程备份核验；镜像/部署N/A。源码恢复快照记录原样保留的检查失败，但不能因此发布。行为变更仍执行阶段⑥和AGENTS规定的verify。 ## 6. 相关文档 -- 输入：阶段 ⑥ [06-validation.md](06-validation.md) -- 发布链唯一权威与签名：`docs/release-process.md`、`docs/release-signing.md`（本仓无 CHANGELOG/RELEASE_NOTES 文件，版本与变更由 `scripts/release.mjs` 编排） -- 本地/CI 补充：`docs/local-build-quickstart.md`、`docs/ci-runner-setup.md`、`docs/architecture/reproducible-build-baseline.md` -- 完成后进入：阶段 ⑧ [08-learning.md](08-learning.md) +[验证](06-validation.md) · [学习](08-learning.md) · [当前部署和Gitea](../v2/07-deployment-and-gitea.md) · [本次交付](../v2/10-delivery-record.md)。 + +变更：XB-1.0 / 2026-09-28，改为Gitea+Docker+ACR/ECS流程，未执行云端部署。 diff --git a/docs/project-process/08-learning.md b/docs/project-process/08-learning.md index c7d1b98..6e185e9 100644 --- a/docs/project-process/08-learning.md +++ b/docs/project-process/08-learning.md @@ -53,10 +53,10 @@ | 捕获类型 | 落点（本仓） | |---|---| | 流程/阶段缺陷 | 本目录对应阶段文档（带版本变更记录） | -| 代码事实/架构决策 | `docs/architecture/`（architecture-overview / codemap / flows / data-model 等基线）、ADR | +| 代码事实/架构决策 | docs/v2/02-architecture.md与09-decisions.md，或对应已存在业务文档 | | 重复过程/命令 | 脚本、`scripts/`、技能（`skills/`） | -| 测试缺口 | `docs/architecture/testing-architecture.md`（测试体系单一事实源） | -| 长期记忆 | agent 记忆系统 / 项目 memory（本仓：`docs/memory/` 本地工作文档与记忆架构，不入库） | +| 测试缺口 | docs/v2/06-validation.md、backend/test_*.py与相关scripts检查；待实现不标通过 | +| 长期记忆 | 工程决策入库docs；业务经验通过assistant_experiences治理；会话/真实案例/凭据不因沉淀而提交Git | ### 3.3 交付物清单 - 学习捕获记录（模板一份，可并入交付总结） @@ -86,3 +86,5 @@ - 输入：阶段 ⑦ [07-delivery.md](07-delivery.md) 及全程证据 - 流程总览与变更记录：[README.md](README.md) + +变更：XB-1.0 / 2026-09-28，按兴邦 Next.js + FastAPI 项目事实适配；稳定规则编号保留。 diff --git a/docs/project-process/README.md b/docs/project-process/README.md index 6a01a12..0715b82 100644 --- a/docs/project-process/README.md +++ b/docs/project-process/README.md @@ -1,84 +1,63 @@ -# Project Process — DK Forge（pi-desktop）开发流程规范 +# Project Process — 兴邦金租 AI 评审平台开发流程 -> **本文档是本仓库项目开发的强制流程**。做任何项目需求（新功能、修复、重构、UI 改动、IPC/契约变更、发布）时，都必须按本流程的阶段执行：进入每个阶段先读对应章节，满足**要求**、遵守**规则（Rule）**、按**输出规范**产出交付物，检查清单全过才算完成本阶段。 +> 本目录是 mini-OpenClaw / 兴邦 AI 预审 v2 的强制开发流程。进入每个阶段先读对应章节，以代码、测试和真实环境证据判断完成状态。 -- 版本：v1.2 · 2026-09-04 -- 适用范围：本仓库（`pi-desktop`，发布名 **DK Forge**）全部功能开发，包括 Electron 宿主（`src/main/`）、renderer SPA（`packages/web-ui/`）、服务主体与 SDK 包（`packages/agent-sdk` 等）、E2E 与发布。仓库硬约束以 `AGENTS.md` 为准，本文档是执行流程（不与其冲突） -- 来源：本规范由既有工程规则体系沉淀提炼（spec-structure / Agent Work Loop / Software Fluency / DESIGN.md Contract / Harness Engineering，规则参考 `vendor/better-harness/`），并按本仓技术栈（Electron + Node.js + React + TypeScript strict ESM monorepo）与 `AGENTS.md` 既有约定适配（v1.1：清除上游仓库残留引用，对齐本仓目录/契约/测试/发布事实） -- 语言约定：流程文档正文用中文；标识符、类型、API、命令、文件路径一律用英文 +版本：XB-1.0 · 2026-09-28。适用技术：Next.js / React / TypeScript 前端，FastAPI / Python 后端，Agent 与工具、业务数据和 Docker 部署。根 [AGENTS.md](../../AGENTS.md) 是规则统一入口；[适配记录](XINGBANG-ADAPTATION.md)说明本项目实际落点及尚未建设的机制。 ---- +来源规范已备份在 Gitea 提交 4d5a420，本目录正文已按用户要求直接适配兴邦。中文用于正文，类型、API、路径、命令使用英文。旧系统运行事实和新版设计草案必须区分。 -## 1. 流程全景（八个阶段） +## 1. 八阶段流程 ```text -① 需求与规格 ─→ ② 架构设计 ─→ ③ 详细设计 ─→ ④ UI Spec ─→ ⑤ 实现 - │ -⑥ 验证与质量门 ←─────────────────────────────────────┘ - │ -⑦ 交付与发布 ─→ ⑧ 学习与沉淀 +① 需求与规格 → ② 架构设计 → ③ 详细设计 → ④ UI Spec → ⑤ 实现 + ↓ +⑧ 学习与沉淀 ← ⑦ 交付与发布 ← ⑥ 验证与质量门 ``` -| 阶段 | 文档 | 一句话定义 | 核心输出 | -|---|---|---|---| -| ① 需求与规格 | [01-requirement.md](01-requirement.md) | 把意图变成一份"实现者无需猜"的规格（scope + 规则 id + 验收标准） | 规格文档（BR/E/AC 编号） | -| ② 架构设计 | [02-architecture.md](02-architecture.md) | 定分层、模块边界、数据流与关键技术决策 | 架构文档 + ADR + 架构图 | -| ③ 详细设计 | [03-detailed-design.md](03-detailed-design.md) | 把架构落到可实现的接口、数据结构、状态机与异常处理 | 详细设计文档 + 接口/数据契约 | -| ④ UI Spec | [04-ui-spec.md](04-ui-spec.md) | 定义每个交付面的 UI 规则与约束（骨架/状态机/动作权限 + 设计系统 token） | DESIGN.md / 表面规格 / i18n 约束 | -| ⑤ 实现 | [05-implementation.md](05-implementation.md) | 小步、可验证、范围受控地把设计变成代码 | 代码 + colocated 测试 + 变更同步 | -| ⑥ 验证与质量门 | [06-validation.md](06-validation.md) | 用最小且相关的检查验证最终改动，失败可诊断、修复后复验 | 测试/门禁/审查记录 | -| ⑦ 交付与发布 | [07-delivery.md](07-delivery.md) | 在真实交付边界被接受，高风险有审批，可回滚 | 构建产物 + 发布记录 + 审计 | -| ⑧ 学习与沉淀 | [08-learning.md](08-learning.md) | 识别重复工作与熵增，沉淀可复用改进并长期验证 | 学习捕获（docs/skills/memory） | +| 阶段 | 章节 | 兴邦产物 | +|---|---|---| +| ① | [需求规格](01-requirement.md) | URD、BR/E/AC规格、范围与未决项 | +| ② | [架构](02-architecture.md) | 页面/API/service/工具/存储边界，主审与经验架构，ADR | +| ③ | [详细设计](03-detailed-design.md) | Pydantic/API/事件契约、状态机、权限、迁移和异常 | +| ④ | [UI Spec](04-ui-spec.md) | workbench表面规格、状态和动作权限、视觉与文案约束 | +| ⑤ | [实现](05-implementation.md) | 最小代码、对应测试、契约与文档同步 | +| ⑥ | [验证](06-validation.md) | 项目虚拟环境测试、前端构建、Compose校验和完整证据 | +| ⑦ | [交付](07-delivery.md) | Gitea修订核验、评审、镜像/部署记录及可恢复路径 | +| ⑧ | [沉淀](08-learning.md) | 决策、缺口与可复用改进，长期效果单独验证 | -> **规模适配**：小改动（一行修复、文案调整）不必产出全部文档——规格/设计可合并为短说明（见各阶段"轻量路径"）。但**要求与规则始终有效**，越级必须有理由并记录。 +小改动可以走各章轻量路径，合并规格/设计但不省略验收。阶段DoD没有证据时保持未完成；可以记录后续候选方案，不得把草案当作门禁已通过而开始业务实现。 ---- +## 2. 全局规则 -## 2. 全局规则（所有阶段适用） +- **G-1 唯一事实源**：契约定义归其明确owner。现有项目业务模型在 backend/contracts/project_assistant.py，部分请求模型仍在 backend/api；新增/变更契约必须明确归属并同步消费者。v2拟建立统一Pydantic→OpenAPI→前端类型链，当前未实现。不能把拟议路径写成既成事实。 +- **G-2 可追溯**：BR/E/AC编号稳定，只追加不重排；每个行为、异常都有验收，撤销标withdrawn。 +- **G-3 配置不等于机制**：文件、技能、流水线配置存在不代表实际使用；结论须有调用/测试/环境证据。 +- **G-4 范围受控**：改前读调用方，前后端字段联动检查，保留用户已有改动和已合并页面；无关问题只记录。 +- **G-5 小步可恢复**：大改前保留恢复点；每批可验证；不删除工作区、真实数据或旧生产资源来图方便。 +- **G-6 机械约束优先**：权限、证据、域隔离、模型出口、模拟隔离和契约等可验证规则须有测试，文档不能替代。 +- **G-7 文档同步**：改接口/状态/数据/部署同步对应设计、用例和运行说明；事实来源与规划分开。 +- **G-8 提交与评审**：Conventional Commits类型+中文一句话；codex/功能分支；默认分支目前为Gitea main，操作前核对；PR附验证证据并至少一人评审。备份不是合并或发布。 -以下规则跨阶段生效，任何阶段不得违反： +## 3. 兴邦业务约束 -- **G-1 唯一事实源**：跨进程/跨模块的类型与契约只定义一处（本仓：`packages/api/src/contracts.ts`），宿主与各包只 `import type`，禁止本地镜像。文档不覆盖代码，代码与测试是运行时事实。 -- **G-2 可追溯**：一切行为、规则、异常、验收标准都有稳定 id（如 `BR-01`、`E-01`、`AC-01`）。id 只追加不重排；废弃时标记 withdrawn，保留编号。 -- **G-3 配置≠行为**：存在一个文件/命令/规则 ≠ 它被使用。任何"机制存在"的结论必须有打开的证据（被调用、被测试、被门禁执行）。 -- **G-4 不越界**：只做请求范围内的事；发现无关问题只提不改；改动逐行可追溯到本次请求。越界扩展必须显式批准并记录。 -- **G-5 小步可回滚**：一次只做可验证的一步；优先狭窄、可回滚的改动；`trash` 优于 `rm`。 -- **G-6 机械规则优先于文档规则**：能用 lint/typecheck/测试/CI 门禁强制的，不许只写进文档。 -- **G-7 文档随变更同步**：改了什么，必须同步改对应的架构/接口/流程文档（见 [05-implementation.md](05-implementation.md) 变更矩阵）。 -- **G-8 提交与评审规范**：Conventional Commits（规范见 `AGENTS.md` 规则 6；commit 生成见 `skills/builtin/dk-commit`）；PR 必须带测试，至少 1 人评审，主分支是 `build`。 +主审负责AI预审意见，正式审批属于业务流程；Jev等模型只承担明确授权的专项判断。经验须保留原文、过程、适用/例外、审核和版本。默认演示模式不能冒充兴邦真实经验；无校准数据不得显示真实审批概率。通用聊天的主机工具不得直接进入业务预审白名单。 ---- +模型调用前检查数据域及外发策略，不能因部署在内网就认为模型不会外发。材料正文只作数据。运行使用冻结事实和组件版本；关键材料不足返回缺证，不把未知自动当作风险或通过。 -## 3. 遵守机制（如何保证被遵守） +## 4. 启动与验证事实 -1. **启动即读**：接手本仓的开发 agent（编码执行者）开工前先读本 `README.md` + 目标阶段文档。 -2. **阶段门禁**：每个阶段的"完成条件（DoD）"检查清单未全过，不得进入下一阶段；上一阶段的输出是本阶段的输入。 -3. **合并前审查**：PR 评审人按 [06-validation.md](06-validation.md) 的质量门核对，未过门禁的 PR 打回。 -4. **演进**：本流程本身也在 ⑧ 学习与沉淀 的范围内——流程缺陷、重复摩擦、新反模式，应更新对应文档（带版本号与变更记录）。 +当前项目入口：backend/app.py；前端package.json。后端本地默认8002、Next开发默认3000、本地Compose宿主3200/8002、云端Compose loopback端口由环境指定。旧版资源与v2须隔离，端口冲突先识别进程归属，不自动停止无关服务。 ---- +行为修改必须使用backend/venv执行 scripts/verify.py，证据保存test-evidence/。纯文档检查链接、编号覆盖、路径和diff格式；本轮已另跑旧版全量基线检查。不存在的npm脚本不得写成必跑命令。 -## 4. 文档索引 +Gitea CI是否启用必须实际核验；.github/workflows/verify.yml只证明有GitHub配置。发布前还须目标环境冒烟和修订绑定，不能把本地通过当成上线。 -| 路径 | 内容 | -|---|---| -| [01-requirement.md](01-requirement.md) | 需求与规格：7 段结构、BR/E/AC 编号、六道完备性门 | -| [02-architecture.md](02-architecture.md) | 架构设计：分层/边界/数据流/决策记录、架构图规范 | -| [03-detailed-design.md](03-detailed-design.md) | 详细设计：接口契约/状态机/异常/迁移/边界条件 | -| [04-ui-spec.md](04-ui-spec.md) | UI Spec：表面规格（骨架/组件/状态机/权限）+ 设计系统（DESIGN.md） | -| [05-implementation.md](05-implementation.md) | 实现：编码规则、规模红线、变更矩阵、自测 | -| [06-validation.md](06-validation.md) | 验证与质量门：分层验证、失败诊断与复验、评审 | -| [07-delivery.md](07-delivery.md) | 交付与发布：构建/签名/发布记录/回滚 | -| [08-learning.md](08-learning.md) | 学习与沉淀：循环工程、知识捕获、长期验证 | -| **templates/**（模板库） | 产品/文档模板：**[URD-Template.md](templates/URD-Template.md)**（用户需求文档模板，产品级需求描述，软件项目通用；[HTML 看板](templates/URD-Template.html)） | +## 5. 模板与新版入口 -**快速开始**：新需求 → 读 [01-requirement.md](01-requirement.md)；涉及 UI → 同时读 [04-ui-spec.md](04-ui-spec.md)；改动进入实现前 → 过 [01-requirement.md](01-requirement.md) 的完备性门 + [03-detailed-design.md](03-detailed-design.md) 的契约检查；提交前 → 过 [06-validation.md](06-validation.md) 门禁。 - ---- +- [URD Markdown模板](templates/URD-Template.md) / [HTML阅读版](templates/URD-Template.html)。 +- [兴邦v2文档入口](../v2/README.md)、[规格](../v2/01-requirements.md)、[验证](../v2/06-validation.md)、[部署/Gitea](../v2/07-deployment-and-gitea.md)。 +- 日常规则以本目录为准，不能为了适配文档顺手升级框架、修改业务阈值或重构全仓。 ## 变更记录 -- v1.3（2026-09-05）：新增 §4 模板库索引——`templates/URD-Template.md`（URD 模板，含使用说明/编号规则/章节结构）及其 HTML 看板；模板为软件项目产品级需求文档的通用起点（输入到阶段 ①）。 -- v1.2（2026-09-04）：阶段 ⑦ 发布流程按本仓真实编译打包链路重写——离线门禁（ci-local 八步）→ release.mjs 九步编排 → pack-audit/install-acceptance → sign-local 签名公证 → OTA manifest，全部对齐 `docs/release-process.md`。 -- v1.1（2026-09-04）：适配本仓（pi-desktop / DK Forge）事实——清除上游仓库残留（decokee-deck / Vue2 / `src/shared` / CONTRIBUTING 等引用），目录、契约、测试、发布与文档引用对齐 `AGENTS.md`。 -- v1.0（2026-08-16）：初始版本，基于既有工程规则体系建立八阶段流程。 +XB-1.0（2026-09-28）：按用户要求直接改为兴邦项目规范；保留八阶段及稳定规则编号，替换不适用的目录、测试、契约和发布要求。来源原文可从备份提交恢复，不再要求开发者自行映射。 diff --git a/docs/project-process/XINGBANG-ADAPTATION.md b/docs/project-process/XINGBANG-ADAPTATION.md new file mode 100644 index 0000000..9ffb417 --- /dev/null +++ b/docs/project-process/XINGBANG-ADAPTATION.md @@ -0,0 +1,37 @@ +# 兴邦流程适配记录与当前事实 + +版本：XB-1.0 · 2026-09-28。 + +## 1. 本次处理 + +用户要求直接将流程改成适用于兴邦的版本。当前README、01–08正文和URD模板已适配，开发人员按正文执行即可，不必自行翻译来源项目特例。原始规范保存在Gitea提交4d5a420，可按路径比对和恢复。 + +根AGENTS是统一入口。本记录说明映射依据和仍待建设的机制，不另立第二套规则。用户明确指令优先；本仓硬约束与流程通用要求同时遵守。 + +## 2. 已核对的落点 + +| 内容 | 当前事实 | 新版拟议 / 限制 | +|---|---|---| +| 页面与代理 | src/app、src/components/xingbang、src/app/api/core、src/app/api/risk-agent | 先查workbench合并现状，不恢复旧独立页 | +| API与业务 | backend/app.py、backend/api、backend/services | 业务service不能反向依赖UI；新领域不堆巨大service | +| 契约 | backend/contracts/project_assistant.py及部分API请求模型 | prescreen.py与OpenAPI类型生成待实现；不能宣称当前全量统一 | +| Agent与工具 | backend/graph、backend/tools、assistant_model.py | 专业预审不继承通用终端和任意SQL权限 | +| 数据与经验 | assistant_store.py、assistant_experiences.py、fixtures | 已有经验治理，不代表拥有真实客户经验 | +| 测试 | backend/test_*.py、scripts/test_*.cjs、scripts/verify.py | UI源码断言不是浏览器端到端测试 | +| 视觉与文案 | globals.css、业务CSS和组件内中文文案 | 统一token和key化文案链待建立，不凭空引用文件 | +| Git | origin为内网Gitea，默认main，另有github-backup | 当前只备份origin；Gitea Actions未核验 | +| 部署 | Dockerfile、Compose、ACR/ECS脚本 | v2资源需独立；本轮未部署 | + +## 3. 保留与调整 + +保留：八阶段、G-1–8、BR/E/AC追溯、R规则编号、阶段门、最小改动、验证失败诊断、修订绑定和回滚要求。 + +调整：将来源项目的桌面进程、特定目录、包发布和自动更新命令替换为兴邦Web/API/Agent和容器部署；不要求不存在的技能或npm脚本。URD评审草案入docs/v2并随Git保存，不假设docs/plans已被忽略。 + +## 4. 机制状态 + +当前可以实际执行：Git状态/差异检查、backend/venv内unittest、现有JS守卫、Next build、Compose config、Gitea远程SHA核验。 + +待建设/确认：前端契约自动生成、统一i18n/token、v2浏览器E2E、Gitea CI、真实数据权限/出口、Jev适配及概率校准。这些列入新版计划，不因写入规范就视为完成。 + +本轮规范与设计文档属于文档交付；v2业务实现仍须各阶段门禁确认。既有规则使用其稳定ID，新增要求必须新增ID或关联原规则，不悄悄修改业务口径。 diff --git a/docs/project-process/templates/URD-Template.html b/docs/project-process/templates/URD-Template.html index a82ccb2..527ca16 100644 --- a/docs/project-process/templates/URD-Template.html +++ b/docs/project-process/templates/URD-Template.html @@ -61,7 +61,7 @@ strong{color:#16233c}

URD 模板（User Requirements Document）

定位：URD（用户需求文档，与 PRD 等价）是产品级需求描述——定义"产品是什么、为谁服务、用户要完成哪些任务、每个功能如何被用户感知和使用"。它是软件项目一切后续文档的输入：阶段 ① 需求规格（BR/E/AC）、② 架构、③ 详细设计、④ UI Spec、测试用例，都必须能追溯到本文档的功能条目。
-
适用：本模板用于 DK Forge 及后续所有软件项目的产品需求文档撰写。
+
适用：本模板用于兴邦金租 AI 评审平台及新版 AI 预审的用户需求撰写；正文按业务人员语言描述，区分演示、真实数据试点与正式审批。
用法：复制本文件为 <产品名>-URD-<版本>-<日期>.md，按占位符 <...> 填写；删除不适用章节并记录删除理由；编号规则见第 0 节，不得破坏。

0. 使用说明与编号规则（写文档前先读；成稿后可删）

@@ -79,7 +79,7 @@ strong{color:#16233c}
  • 阶段 ① 规格回答 "这一版改动具体怎么实现、怎么验收"；
    • -
  • URD 讲用户语言，不写内部实现（不写表结构、类名、IPC 通道）；确有底层约束须写"约束与假设"。 +
  • URD 讲用户语言，不写内部实现（不写表结构、类名、内部工具调用）；确有底层约束须写"约束与假设"。

    • 0.2 编号规则（只追加、不重排、弃用标记 withdrawn）

    前缀含义示例
    MOD-xx模块编号MOD-03
    FR-<模块简码>-功能点编号（模块简码见 6.1 清单）FR-STU-04
    EX-<模块简码>-功能点的异常/边界场景EX-DASH-02
    NFR-xx非功能需求NFR-07
    SEC-xx安全/权限需求SEC-03
    AC-xx端到端验收标准AC-10
    OQ-xx待决策/开放问题OQ-04
    @@ -117,7 +117,7 @@ strong{color:#16233c}

    2.4 非目标（Out of Scope）——与范围同等重要，逐条写明排除理由

    排除项理由可能时机
    <明确不做的事><为什么本期不做>后续版本 / 永不
    <例如：开放第三方市场><例如：首版只支持受控模板>V2+

    2.5 成功标准（产品级，一句话可判）

    -
  • <首个版本成功的硬性标志，如：不写代码的业务人员可在 60 分钟内发布一个可用 Agent> +
  • <首个版本成功的硬性标志，如：客户经理可完成一次带证据引用和补件清单的项目预审>

    • 3. 参考文献

    @@ -127,7 +127,7 @@ strong{color:#16233c}

    4.1 术语表

    术语定义（用户语言，可配图）
    <领域词，如 Agent / 面板 / Scope><一句话说清>

    4.2 用户角色

    -
    角色画像主要任务成功标准常用模块
    <角色><谁，技术背景><日常要完成什么><做到什么算好>MOD-xx
    例：培训者懂业务不写代码制作并发布一个 Agent不改代码完成首版MOD-02/05
    +
    角色画像主要任务成功标准常用模块
    <角色><谁，技术背景><日常要完成什么><做到什么算好>MOD-xx
    例：客户经理熟悉融资租赁业务提交材料并理解预审意见明确项目障碍与下一步MOD-02/05

    4.3 角色 × 模块 关注矩阵（可选）

    MOD-01MOD-02MOD-03…
    角色 A使用使用–
    角色 B–审核使用
    @@ -143,7 +143,7 @@ strong{color:#16233c}

    <模块之间的依赖与数据走向一句话说明。>

    5.3 核心用户流程（端到端）

    -

    <步骤表：用户从进入到完成一次价值闭环的全过程>（例：安装 → 授权 → 首次运行 → 理解 → 协作）

    +

    <步骤表：用户从进入到完成一次价值闭环的全过程>（例：选择项目 → 确认材料 → 发起预审 → 查看证据 → 补件复核）

    5.4 体验原则

  • <先给结果，再邀请对话>（示例原则，按产品改写）
    • @@ -156,7 +156,7 @@ strong{color:#16233c}
  • ...

    • 5.5 交付面与平台约束

    -
    交付面说明优先级
    <桌面 Electron / Web / 移动 / 硬件><能力边界、离线、多端同步>P0/P1
    +
    交付面说明优先级
    <客户经理工作台 / 评审工作台 / 管理配置><项目权限、材料来源、运行状态、异常恢复>P0/P1

    6. 功能模块需求（本文档主体）

    6.1 模块清单与划分说明

    @@ -249,4 +249,5 @@ strong{color:#16233c}

    C. 变更对照（本版相对上一版的增删）

    模板维护：本模板本身受仓库 ⑧ 学习与沉淀 约束——使用中发现结构缺陷，更新本文档并记入"变更记录"（放文末）。
    +

    兴邦填写约束（XB-1.0 · 2026-09-28）

    • 明确主审 Agent、专项判断模型和正式审批职责；Jev 单题不能直接审批。
    • 历史经验包含争议、核查、证据和判断变化；过程缺失须标未知。
    • 定义项目权限、数据域、模拟与正式结果、失败与人工复核路径。
    • 无真实校准时不承诺通过率、准确率或改善幅度；未决项标 owner 与阶段。
    • 本文为阅读模板，正式编辑与编号以同目录 URD-Template.md 为准。
    \ No newline at end of file diff --git a/docs/project-process/templates/URD-Template.md b/docs/project-process/templates/URD-Template.md index 717761c..cd1769c 100644 --- a/docs/project-process/templates/URD-Template.md +++ b/docs/project-process/templates/URD-Template.md @@ -1,7 +1,7 @@ # URD 模板（User Requirements Document） > **定位**：URD（用户需求文档，与 PRD 等价）是**产品级**需求描述——定义"产品是什么、为谁服务、用户要完成哪些任务、每个功能如何被用户感知和使用"。它是软件项目**一切后续文档的输入**：阶段 ① 需求规格（BR/E/AC）、② 架构、③ 详细设计、④ UI Spec、测试用例，都必须能追溯到本文档的功能条目。 -> **适用**：本模板用于 DK Forge 及后续所有软件项目的产品需求文档撰写。 +> **适用**：本模板用于兴邦金租 AI 评审平台及新版 AI 预审的用户需求撰写；正文按业务人员语言描述，区分演示、真实数据试点与正式审批。 > **用法**：复制本文件为 `<产品名>-URD-<版本>-<日期>.md`，按占位符 `<...>` 填写；删除不适用章节并记录删除理由；编号规则见第 0 节，不得破坏。 --- @@ -20,7 +20,7 @@ ``` - URD 回答 **"用户要什么、为什么、长什么样、做到什么程度算好"**； - 阶段 ① 规格回答 **"这一版改动具体怎么实现、怎么验收"**； -- URD 讲用户语言，不写内部实现（不写表结构、类名、IPC 通道）；确有底层约束须写"约束与假设"。 +- URD 讲用户语言，不写内部实现（不写表结构、类名、内部工具调用）；确有底层约束须写"约束与假设"。 ### 0.2 编号规则（只追加、不重排、弃用标记 withdrawn） | 前缀 | 含义 | 示例 | @@ -95,7 +95,7 @@ | `<例如：开放第三方市场>` | `<例如：首版只支持受控模板>` | V2+ | ### 2.5 成功标准（产品级，一句话可判） -- `<首个版本成功的硬性标志，如：不写代码的业务人员可在 60 分钟内发布一个可用 Agent>` +- `<首个版本成功的硬性标志，如：客户经理可完成一次带证据引用和补件清单的项目预审>` --- @@ -120,7 +120,7 @@ | 角色 | 画像 | 主要任务 | 成功标准 | 常用模块 | |---|---|---|---|---| | `<角色>` | `<谁，技术背景>` | `<日常要完成什么>` | `<做到什么算好>` | MOD-xx | -| 例：培训者 | 懂业务不写代码 | 制作并发布一个 Agent | 不改代码完成首版 | MOD-02/05 | +| 例：客户经理 | 熟悉融资租赁业务 | 提交材料并理解预审意见 | 明确项目障碍与下一步 | MOD-02/05 | ### 4.3 角色 × 模块 关注矩阵（可选） | | MOD-01 | MOD-02 | MOD-03 | … | @@ -145,7 +145,7 @@ `<模块之间的依赖与数据走向一句话说明。>` ### 5.3 核心用户流程（端到端） -`<步骤表：用户从进入到完成一次价值闭环的全过程>`（例：安装 → 授权 → 首次运行 → 理解 → 协作） +`<步骤表：用户从进入到完成一次价值闭环的全过程>`（例：选择项目 → 确认材料 → 发起预审 → 查看证据 → 补件复核） ### 5.4 体验原则 1. `<先给结果，再邀请对话>`（示例原则，按产品改写） @@ -157,7 +157,7 @@ ### 5.5 交付面与平台约束 | 交付面 | 说明 | 优先级 | |---|---|---| -| `<桌面 Electron / Web / 移动 / 硬件>` | `<能力边界、离线、多端同步>` | P0/P1 | +| `<客户经理工作台 / 评审工作台 / 管理配置>` | `<项目权限、材料来源、运行状态、异常恢复>` | P0/P1 | --- @@ -194,8 +194,8 @@ **功能点详述** ##### FR-XXX-01 `<功能名称>`（P0） -- **功能描述**：`<该功能是什么；用户可用它完成什么；关键行为逐条列出，如：>` - 1. `<行为一>` +- **功能描述**：`<该功能是什么；用户可用它完成什么；关键行为逐条列出，如：>` + 1. `<行为一>` 2. `<行为二>` - **前置条件**：`<进入该功能前必须满足的条件，如已登录、已有数据源授权>`（无则写"无"） - **主流程**： @@ -303,3 +303,11 @@ --- > **模板维护**：本模板本身受仓库 ⑧ 学习与沉淀 约束——使用中发现结构缺陷，更新本文档并记入"变更记录"（放文末）。 + +## 兴邦填写约束（XB-1.0 · 2026-09-28） + +- 写清主审 Agent、专项判断模型和正式审批的职责；不把 Jev 单题输出当作审批决定。 +- 历史经验须描述争议、核查、证据和判断变化；仅有最终结果时标过程缺失。 +- 每项功能明确材料来源、项目/数据域权限、模拟与正式结果边界、失败与人工复核路径。 +- 没有真实校准数据时不承诺通过率、准确率或改善幅度；未决项有 owner 和进入阶段。 +- 规格、架构、UI 和测试均回链到功能编号。可参考 [兴邦v2 URD](../../v2/URD.md)。 diff --git a/docs/v2/01-requirements.md b/docs/v2/01-requirements.md new file mode 100644 index 0000000..5c0895f --- /dev/null +++ b/docs/v2/01-requirements.md @@ -0,0 +1,100 @@ +# 兴邦预审 v2 需求规格 + +状态：0.1 评审草案，尚未通过六道完备性门；后续设计为候选方案。规则编号作用域为本文。 + +## 1. Requirement Overview + +来源：[URD](URD.md) 的 FR-FACT/HIST/EXP/REV/JEV/SIM/EVAL/PILOT-01。目标是把历史项目的争议、调查、证据和判断变化用于新项目预审。P0 使用模拟或经授权的脱敏数据，不连接未知生产库，不执行正式审批，不展示未经校准的通过概率。 + +角色沿用 URD。补充术语：快照=不可变输入版本；来源域=data_domain，演示或生产；证据引用=可定位材料片段的 ID；有效经验=已发布、未过期且适用条件成立的版本；硬性规则=经业务确认且由程序执行的约束；幂等键=同一用户请求去重标识；版本冲突=客户端依据旧 revision 更新；专项判断=边界明确的局部判断；降级=保留可用结果并标识未完成检查；运行预算=限制轮数、调用量和耗时；保留集=开发时不可使用的验收样本。 + +“证据支持”不等于材料真实可信：材料真实性核验是单独的核查结果。风险严重程度、数据完整性、模型确定性、审批概率互不替代。 + +## 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[]、versions、revision | 预审总览 | +| Judgment | id、question_id、question_version、type、status、answer?、evidence_ids[]、provider、model_version? | 专项复核 | +| 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 | 主审形成综合预审意见；Jev 的单题结果不得直接写入 recommendation。owner：预审编排 | +| BR-06 | 已确认的硬性阻断不能被模型或其他维度高分覆盖。owner：结果校验 | +| BR-07 | 缺数据记 unknown；全部关键核查不可完成时 recommendation=insufficient_information。owner：结论完整性校验 | +| BR-08 | 未通过来源校验的引用不能进入有效结论；相关判断退回缺证/复核。owner：证据校验 | +| BR-09 | Jev 未配置、未批准或调用失败时记录 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：模型出口策略 | + +## 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 | 该经验不适用于本次核查；展示可见范围内的排除原因 | + +运行级错误保存在 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 Jev 返回正面单题判断但整体证据冲突，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 Jev 未配置/超时/畸形输出，When 调用，Then 保留 skipped/failed 与降级，不生成默认高分 | BR-09, E-06, E-07 | +| 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 | + +## 7. Open Questions & Decision Record + +OQ-01 至 OQ-06 见 [决策记录](09-decisions.md)。本轮规格是待评审草案；P0 演示可用模拟材料，真实数据出口、正式权限和概率校准不得用临时假设替代确认。 + +已定方向：主审综合研判、历史过程优先、Jev 局部判断、模拟与正式分离、先验证再谈概率。被否方案：单题判断直接审批、经验未经审核自动生效、复制整库后再定义用途、用模拟提升冒充因果效果。 diff --git a/docs/v2/02-architecture.md b/docs/v2/02-architecture.md new file mode 100644 index 0000000..e907811 --- /dev/null +++ b/docs/v2/02-architecture.md @@ -0,0 +1,99 @@ +# 兴邦预审 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/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 独立目录与资源，旧版保留；本轮先文档后迁移，目录尚未创建。 + +状态、影响和未决项统一维护在 [决策记录](09-decisions.md)。 + +## 8. 拟建立的架构验证 + +业务 service 不导入 src；预审工具集合不含 terminal/任意 SQL；跨域经验不可检索；引用必须属于授权快照；模拟不修改真实快照；无校准时概率为 null；经验发布只能经过一个治理入口。映射 AC-04/06/08/10/11/12/16。 + +这些是待实施的机器检查；现有测试覆盖另列，不能标成 v2 已通过。 diff --git a/docs/v2/03-detailed-design.md b/docs/v2/03-detailed-design.md new file mode 100644 index 0000000..6c6d990 --- /dev/null +++ b/docs/v2/03-detailed-design.md @@ -0,0 +1,83 @@ +# 兴邦预审 v2 详细设计候选 + +状态：0.1 草案，阶段①/②未定案；以下端点和新类型尚未实现。覆盖 BR-01–16 / E-01–12 / AC-01–16，先形成可评审的契约，再编写代码。 + +## 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 个 Jev 问题、每题最多 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 | +| POST /projects/{project_id}/runs | snapshot_id:string, enable_judgment:boolean=false | 202 ScreeningRun queued | prescreen；E-03/07/09/10 | +| 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}[]；versions:{schema,policy,skills,experiences,model,questions}；created_at；finished_at:datetime? | 运行存储 | +| Judgment | id, run_id, question_id, question_version；type:choice/score/noul；status:completed/skipped/failed；answer:object?；evidence_ids:string[]；provider:string；model_version:string?；error_code: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 | + +Jev answer 为严格可辨识类型：Choice={choice:string, probabilities:map, confidence:float[0..1]}；Score={score:float, probabilities:map, confidence:float[0..1]}，范围按问题等级；Noul={noul:float[0..1]}，无独立 confidence。必须与已冻结题型/选项/等级吻合；畸形、NaN、未知选项都记 failed。具体厂商 envelope 由适配器转换，不能把任意 JSON 直接存成有效判断。 + +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；工具策略→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 和进入条件。本文件不可直接作为已批准实现合同。 diff --git a/docs/v2/04-ui-spec.md b/docs/v2/04-ui-spec.md new file mode 100644 index 0000000..b36dfc8 --- /dev/null +++ b/docs/v2/04-ui-spec.md @@ -0,0 +1,68 @@ +# 兴邦预审 v2 UI Spec + +状态：候选表面规格，未开发、未做浏览器验收；不把本文件当作可点击原型。输入：需求规格与详细设计草案。 + +## 1. 交付面与骨架 + +| 表面 | 区域 / 信息层级 | 消费契约 | +|---|---|---| +| 预审总览 | 项目与数据域→意见及缺证状态→主要问题→经验对照→证据抽屉 | ScreeningRun、Finding、Evidence | +| 历史过程 | 左：来源材料；中：争议/补件时间线；右：经验卡草稿与审核记录 | CaseTimeline、DecisionEvent、ExperienceCard | +| 推进沙盘 | 左：证据→动作→问题变化图；右：假设动作；底：真实与模拟差异 | Simulation、ScreeningRun | +| 验证看板 | 数据集版本/保留状态→对照指标→分歧案例→人工复盘 | Evaluation | + +拟集成至 xingbang-workbench / review-workbench 的项目上下文，实际路由与组件拆分在 UI 实现前定案，不恢复已合并的旧页面。 + +## 2. 组件所有权 + +ProjectContext 拥有 project_id、data_domain 和当前 run_id；RunSummary 只展示运行结果；CaseTimelinePanel 拥有选中事件；EvidenceDrawer 拥有证据展开状态；ExperienceEditor 拥有草稿和 expected_revision；ScenarioPanel 拥有 assumptions，不能写真实项目事实；EvaluationPanel 拥有数据集选择，不能提前获得保留标签。 + +组件名为提案，尚未创建。URL 仅保存 project_id/run_id/tab 等非敏感可分享状态；身份令牌、材料文本和假设正文不放 URL。切换项目清空选中证据与模拟动作。 + +## 3. 状态机 + +| 状态 | 可见内容 | 允许动作 / 禁用动作 | +|---|---|---| +| idle | 项目说明与启动入口 | 有权限可发起；无项目不发请求 | +| loading | 对应区域骨架与加载文案 | 可退出；禁重复提交 | +| ready | 已获数据与版本信息 | 按权限操作 | +| empty | “尚无历史经验”或“尚无运行”及下一步 | 可导入/发起；不能绘制虚构节点 | +| error | 错误码映射的文案、请求编号和恢复入口 | 仅可恢复错误显示重试 | +| submitting | 保留原内容，显示提交中 | 禁二次提交；不清除草稿 | +| stale（ready 附加标识） | “项目已有新版本，当前为历史结果” | 可查看/新运行；禁止覆写旧结果 | + +业务运行 queued/running/awaiting_input/completed/partial/failed/cancelled 单独展示；partial 必须突出未完成项。更新失败时回 ready/error 且保留草稿，版本冲突提示刷新后合并。 + +## 4. 动作与权限 + +| 动作 | 客户经理 | 评审员/发布人 | 管理员 | 只读访客 | +|---|---|---|---|---| +| 查看项目结果和证据 | 授权项目 | 授权范围 | 授权范围，非默认全量 | 仅指定演示项目 | +| 确认材料、发起预审 | 项目授权 | 项目授权 | 不自动继承业务权限 | 隐藏 | +| 模拟动作 | 项目授权 | 项目授权 | 项目授权 | 仅演示授权 | +| 编辑经验候选 | 提议权限 | 编辑权限 | 不自动继承 | 隐藏 | +| 审核发布/撤回 | 隐藏 | 独立发布资格且不可自批 | 治理授权后 | 隐藏 | +| 修改模型出口与数据域 | 隐藏 | 隐藏 | 策略管理资格 | 隐藏 | +| 揭示保留集结果 | 隐藏 | 指定验证负责人且预测已锁定 | 不因管理员身份自动开放 | 隐藏 | + +后端始终重验权限。无权限动作不显示控件；有权限但条件未满足显示禁用原因。经验发布前展示范围、例外、有效期和变更差异；撤回说明新运行不再使用、历史引用保留。 + +## 5. 沙盘视觉规则 + +证据→动作→受影响问题→预审意见；线宽最多三档，对应已定义影响等级，不能直接代表概率提升。未验证假设使用虚线和“模拟”文字；真实核验使用实线及来源。通过点击/键盘打开依据，颜色不单独传意。 + +一次只突出当前选中问题的关联路径，其他弱化；未知项不伪装为否定。补件可能发现新风险，允许意见变得更谨慎。图旁提供等价列表，缩小窗口时改纵向排列，不依赖复杂图才能理解结果。 + +P0 顶部不显示百分比“通过率”。展示 recommendation、missing_inputs、degradations 和数据域/版本；不凭空生成完整度或置信度数字。评分若后续加入，须另有明确算法和契约。 + +## 6. 文案与视觉 + +[DESIGN.md](DESIGN.md) 管理语义 token 候选。新增文案拟 key 化：prescreen.result.*, prescreen.error.*, experience.status.*, simulation.*, evaluation.*；每个错误 key 对应规格 E-*，中英文范围在 UI 门禁前确定。当前无对应 i18n 实现，不伪称可用。 + +正文按现有 16px 基线，主动作可键盘访问；可见 focus、表单 label、错误定位、减少动效、文本与图的等价表达。长标题换行，证据抽屉不截断关键原文。产品页面默认不暴露 question_version 等实现细节，只在“依据与版本”展开。 + +## 7. 验收映射与未决 + +来源点击与权限 AC-01/08；未知时间 AC-02；经验审核 AC-03/04；降级 AC-07/09；模拟隔离 AC-11；无伪概率 AC-12；盲测标签 AC-15。 + +UI 门禁尚未通过：路由位置、统一 token 实现、i18n 文件、视觉稿、键盘和对比度验收待完成。截图自评不能单独算通过，应有可复现的 DOM/行为断言及独立评审记录。 diff --git a/docs/v2/05-implementation-plan.md b/docs/v2/05-implementation-plan.md new file mode 100644 index 0000000..ce9dd32 --- /dev/null +++ b/docs/v2/05-implementation-plan.md @@ -0,0 +1,47 @@ +# 兴邦 v2 实施与迁移计划 + +状态：计划，未执行 v2 代码迁移。当前用户最新指令优先：接入流程、备份现状、编写新版文档。 + +## 1. 迁移边界 + +拟目标目录 F:/mini-OpenClaw-v2，当前尚不存在。先保护旧版，再从已备份提交白名单迁移，禁止把整个工作区连同数据/密钥/依赖一起复制。新仓库远程和独立部署资源见 OQ-06。 + +| 候选迁移内容 | 依赖理由 | 验证 | +|---|---|---| +| src/ 当前页面、组件、代理与 lib | workbench 和鉴权相互依赖，先保留可运行闭环 | 生产构建及既有 UI 脚本 | +| backend/api、services、contracts、graph、tools、data_layer | app.py 注册路由与服务调用链 | unittest + 导入/启动冒烟 | +| backend/skills、fixtures、requirements.txt | 固定方法和演示种子是运行/测试依赖 | fixtures 标为 demo，运行不读取旧数据目录 | +| backend/app.py、config.py 与必要无密钥默认配置 | 真正入口是 app.py，不照抄旧文档的 backend.backend.main | 独立进程和健康检查 | +| package*.json、Next/TS/CSS 配置、Dockerfile、入口脚本 | 构建完整性 | npm ci/build、Compose config | +| backend/test_*.py、相关 scripts 测试与 verify.py | 保留既有回归能力 | 同一验证入口在 v2 运行 | +| docs/project-process、docs/v2、根 AGENTS.md | 新流程与设计基线 | 链接/规则覆盖检查 | + +排除：.env、server-deploy.conf、.docker-codex、node_modules、venv、.next*、日志、sessions/storage/raw_logs、实际 xingbang_data、原始客户材料、_backup*、office 临时文件。旧 DELIVERY.md 含凭据，不能原样进入新仓库；部署文档采用重写后的不含密钥说明。代码内默认演示数据需标注来源，不把默认频次当成客户经验。 + +抽取前按 import 与路由调用图确认必要依赖。先建立可运行基座，再根据测试逐项裁剪，不能按文件名猜核心。原版始终保留，禁止恢复用户此前主动合并删除的旧页。 + +## 2. 分批交付 + +| 里程碑 | 产出 | 进入条件 / 完成证据 | +|---|---|---| +| M0 文档与恢复点（本轮） | Gitea 快照、流程适配、URD/规格草案 | 远程 SHA 一致；文档检查；不是新版功能交付 | +| M1 独立基座 | v2 源码、环境模板、契约生成与追加迁移骨架 | 阶段①–③相应门禁通过；独立路径、完整构建、回归通过 | +| M2 历史过程与经验 | 时间线、原文定位、审核发布和检索 | AC-01/02/03/04/08/13，模拟与真实域隔离 | +| M3 主审与专项判断 | 有界 Agent Loop、Jev 可选适配、证据和硬规则约束 | AC-05/06/07/09/10/12/14/16；先 mock，再批准环境小样本 | +| M4 沙盘与展示 | UI 状态、假设动作、正式/模拟对照 | UI门禁通过，AC-11；源快照哈希不变 | +| M5 脱敏试点 | 数据授权清单、保留集盲测和复盘 | AC-15/16，专家评审、指标事先锁定 | +| M6 概率校准（后续） | 事件口径、训练/校准/测试、漂移监测 | OQ-05 关闭且样本支持；审批概率与违约风险分开 | + +一次只交付一个可验证业务切片。新增文件按流程 ≤500 行；既有巨大 service 只接薄入口，不继续堆独立领域逻辑。新依赖先评估必要性和大小。 + +## 3. 每批标准动作 + +读 AGENTS 和对应流程 → 检查 status/log/调用方 → 更新需求规则与接口 → 增加行为测试 → 最小实现 → 相关测试 → 项目 verify.py → diff 自查 → 文档同步 → 独立提交和评审。 + +行为涉及权限、证据、模拟、外发时必须有反例；不以静态页面或模型的一句解释替代行为断言。失败先定位，不能反复重跑直到偶然通过。 + +## 4. 配置、迁移与回滚 + +代码通过可回滚提交/镜像标签恢复。数据迁移追加并有幂等守卫；旧库先快照，升级/回退边界经测试后才部署。回退代码不等于撤销已写入数据。v2 使用独立工作目录、Compose 项目、容器名、数据卷及端口，具体值在 OQ-06 定案。 + +本轮不实施剪裁、不改业务行为、不创建远程 v2 仓库、不部署。先把评审文档写清，避免规范到位后返工。 diff --git a/docs/v2/06-validation.md b/docs/v2/06-validation.md new file mode 100644 index 0000000..877d69b --- /dev/null +++ b/docs/v2/06-validation.md @@ -0,0 +1,55 @@ +# 兴邦 v2 验证与质量门 + +状态：新版验证计划；以下 AC 测试为待实现，不能以旧版测试通过替代。 + +## 1. 可追溯测试矩阵 + +| 用例组 | 规格 AC | 层级 / 断言 | +|---|---|---| +| 材料确认与历史时间线 | AC-01/02 | 单测/集成：未确认不入事实；未知时间不补造；解析失败保留原件 | +| 经验审核、检索与版本 | AC-03/04/13 | 权限/集成：无资格、不适用、过期、撤回、异域不可应用；旧版本可追溯 | +| 主审与硬约束 | AC-05/06/07 | 有冲突和缺证的固定样例：单题正面不覆盖硬规则，缺数据不判高风险 | +| 证据真实性边界 | AC-08 | 伪造 ID、跨项目、无权片段被拒；有引用不等于真实性已证实 | +| Jev 降级 | AC-09/16 | mock：未配置、超时、畸形响应、未批准出口；零伪造判断、零未授权发送 | +| Agent 工具与预算 | AC-10 | 注入材料无法调用 terminal/任意SQL；预算耗尽确实停止 | +| 模拟隔离 | AC-11 | 真实快照哈希/数据库记录前后不变；关联改进不可简单相加 | +| 概率门禁 | AC-12 | UI/API/导出均无未经校准概率；Noul、Score不转审批率 | +| 幂等与并发 | AC-14 | 同键同载荷只一条运行；同键异载荷409；Worker重启不重复落库 | +| 盲测 | AC-15 | 预测先锁定，标签后揭示；同项目不跨开发/验收集；泄漏样本作废 | + +## 2. 工程验证顺序 + +使用 backend/venv，先运行本批相关 unittest 与 UI 检查，再运行根目录的 `backend/venv/Scripts/python.exe scripts/verify.py`。Linux 对应 backend/venv/bin/python。命令、cwd、revision、fixture 和完整日志保存在 test-evidence。 + +现有 verify.py 实际包含：git diff、全部 backend unittest、四项 UI 源码守卫、Next.js build、本地/云端 Compose config；这些 UI 脚本不等于真实浏览器 E2E。--docker 会构建并启动本地 Compose，有端口与停止副作用，不能在与旧版冲突的资源上随意运行。 + +文档任务运行链接、编号覆盖、文件来源、格式检查。GitHub workflow 文件存在不代表 Gitea CI 已执行；远程检查未观测记 Unobserved。 + +## 3. 业务验证设计 + +同一批材料按版本冻结比较：A=现有助手；B=主审+历史经验；C=B+Jev。对照回答“经验有没有帮助”和“Jev有没有额外收益”，不把两项改进混成一个原因。先用合成反例暴露故障，再用客户持有的脱敏保留集检验。 + +样本包含通过、退回、否决、附条件通过、资料不全及意见分歧。按项目分组、按预测时间截断，只使用当时已取得的材料；区分首次提交通过和补件后最终通过。开发集不能看到保留集答案，也不能通过完整历史报告间接泄漏目标答案。 + +| 指标 | 计算口径 | 限制 | +|---|---|---| +| 重大问题漏检 | 专家标注重大问题中未识别数 / 专家标注总数 | 先定义重大问题；无标注不计算 | +| 无依据结论 | 复核为无依据的实质判断 / 被复核判断 | 引用存在但不支持也算无依据 | +| 误报 | 被专家认定不成立的问题 / 系统提出问题 | 专家分歧单列 | +| 有效补件 | 解决预定争议的补件 / 已完成补件 | 不把补件数量当质量 | +| 一致性 | 与参考意见一致的项目 / 可比较项目 | 不等于正确率；分歧要复核 | +| 效率与成本 | 相同边界下的人工耗时、端到端耗时、调用成本 | 同时检查重大问题漏检，不能只追求快 | + +分母为0返回 not_applicable，不填0%。指标验收阈值在盲测前与兴邦锁定（OQ-04），不能看结果后调线。少量案例用于可行性和故障发现，不支持总体准确率宣传。 + +## 4. 概率后续门禁 + +定义审批事件、预测时点、样本纳入范围和制度时期；只观察已送审项目会有选择偏差。独立保留时间段测试校准情况，记录 Brier/校准曲线等指标并说明不确定性；通过概率不代表投放后无违约。具体样本量、模型选择和阈值另立规格，不在无数据时承诺。 + +动作模拟的分数变化属于模型条件判断，不能直接当作措施造成通过率提升的因果结论。 + +## 5. 失败和发布门 + +失败→复现→定位→最小修复→同一检查复验，完整记录。未解决故障不得发布镜像。仅保存源码恢复快照不等同发布，快照注明验证状态。 + +人工评审按正确性、一致性、安全、测试四维；未经独立评审不标通过。线上效果须在真实交付环境观测，本地测试不能替代。 diff --git a/docs/v2/07-deployment-and-gitea.md b/docs/v2/07-deployment-and-gitea.md new file mode 100644 index 0000000..57397d8 --- /dev/null +++ b/docs/v2/07-deployment-and-gitea.md @@ -0,0 +1,89 @@ +# 部署与 Gitea 使用说明 + +日期：2026-09-28。本文区分已核验、本地配置、历史记录和未来提案；不包含密钥。本轮没有实际部署。 + +## 1. Git 远程事实 + +| 项 | 已核验值 | +|---|---| +| 当前 Gitea 远程 | origin | +| SSH 仓库 | ssh://git@192.168.10.111:2222/qiaoqichao/mini-openclaw.git | +| Web 地址线索 | http://8.163.107.248:13000/qiaoqichao/mini-openclaw （Gitea push 回执提供，网页本轮未单独测试） | +| 默认分支 | main，git ls-remote --symref origin HEAD 已核对 | +| 另一个远程 | github-backup → git@github.com:NathanAlex7/mini_openclaw.git；本轮未推送 | +| 源码恢复点 | codex/backup-before-ai-prescreen-v2-20260928 / 4d5a420671cb073a56335bd617e7d0812b8179a9 | +| 文档工作分支 | codex/xingbang-v2-docs-20260928 | + +备份分支包含此次会话之前的 9 个已修改文件和选定的未跟踪源码、文档、流程原文，共37个变更文件；未改默认分支。其父提交为 b10093f。快照保存当时源码状态，不等同所有功能已验收。 + +## 2. 常用命令 + +先确认身份、网络和现有 SSH host key；不要为连接便利关闭主机指纹校验，不把口令放 URL。 + +```powershell +git status --short +git remote -v +git ls-remote --symref origin HEAD +git fetch origin +git switch -c codex/ +# 只暂存本次已检查文件，避免 git add . 带入临时凭据 +git add -- +git diff --cached --check +git commit -m "docs(v2): 说明改动与结果" +git push -u origin HEAD +git rev-parse HEAD +git ls-remote --heads origin +``` + +本地 HEAD 与指定远程分支 SHA 相同才可说“已备份”。只 commit、只 push 输出、网页旧分支都不能替代核验。需合并时在 Gitea 创建面向 main 的 PR，按流程至少一人评审并绑定最终修订验证；本轮不自动合并。 + +## 3. 无损恢复 + +恢复到全新目录检查，不在有工作成果的目录执行 reset --hard/clean。 + +```powershell +git clone --branch codex/backup-before-ai-prescreen-v2-20260928 --single-branch ssh://git@192.168.10.111:2222/qiaoqichao/mini-openclaw.git F:\mini-OpenClaw-restore-20260928 +git -C F:\mini-OpenClaw-restore-20260928 rev-parse HEAD +``` + +预期提交：4d5a420671cb073a56335bd617e7d0812b8179a9。目标须不存在。当前仅验证远程可提供该提交，未执行恢复目录创建或破坏性恢复演练。 + +这是源码备份：不包括实际业务数据库、上传文件、运行日志、会话、密钥或 Docker 数据卷；这些资产需要另行按部署环境建立备份。现有 Git 历史中的旧交付文档含遗留凭据，未重写既有历史；新文档和未来新仓库不得继续复制这些值。 + +## 4. 当前运行与部署事实 + +| 项 | 来源 / 状态 | +|---|---| +| 后端 | backend/app.py，python app.py 固定监听8002；或在 backend 工作目录用 uvicorn app:app --port 明确指定 | +| 前端 | package.json 的 next dev/start，默认3000；Next代理默认后端127.0.0.1:8002 | +| 本地 Compose | docker-compose.yml，容器 mini-openclaw-stable，宿主3200/8002 | +| 云端 Compose | deploy/docker-compose.aliyun.yml，容器 mini-openclaw，loopback FRONTEND_PORT默认80/BACKEND_PORT默认8002 | +| ECS 本机配置 | server-deploy.conf 指向 8.163.107.248:22，用户 qykj_qqc；不复制此含密钥文件 | +| 旧项目远程目录 | /home/qykj_qqc/mini-OpenClaw，来自此前会话只读检查；本轮未复查服务器 | +| 云端实时健康 | Unobserved，本轮未发起 SSH、重启或模型调用 | + +当前 Dockerfile 在一个镜像中运行 Next 和 FastAPI，容器内部端口3000/8002；卷保存 xingbang_data 与日志。云端浏览器通过同源代理访问后端。受信模型 endpoint、密钥和 ERP 连接由环境提供，不提交到 Git。 + +## 5. 现有验证与发布链 + +```powershell +.\backend\venv\Scripts\python.exe scripts/verify.py +``` + +先安装项目依赖；必须使用项目虚拟环境。测试报告在 test-evidence，配置示例 deploy/aliyun.env.example 只有占位值。当前脚本 publish-acr.ps1/.sh 会验证、构建、推送；deploy-aliyun.sh 会 pull/up 并健康检查，这些是有副作用的发布脚本，不在本轮执行。 + +发布要求：验证通过、不可变镜像标签、部署配置单独保管、既有数据卷有备份、目标端口和容器隔离已确认。回滚用已验证的旧镜像标签；数据库变更的回退另行设计，不能把换镜像等同数据恢复。 + +## 6. v2 部署隔离提案 + +目标独立目录 F:/mini-OpenClaw-v2；独立 Git 项目、Compose 项目名、镜像名、容器、数据卷和宿主端口须在实施前确定。当前没有创建 v2 远程、部署文件或分配实际端口。不要执行原版 Compose 去部署 v2，否则会复用旧容器名和数据。 + +前端代理可通过 CORE_BACKEND_URL / RISK_AGENT_BACKEND_URL 指向隔离后端；启动命令和测试 smoke URL 必须随端口同步。将代码从旧版复制出来不自动完成资源隔离。 + +真实材料是否可发往 DeepSeek/Jev，取决于客户数据策略及实际部署方式；不能用“部署在客户服务器”推断“数据不会外发”。模型出口需要独立核对。 + +## 7. Gitea CI 状态 + +当前仓库只有 .github/workflows/verify.yml，未发现 .gitea/workflows。Gitea Actions 开关、runner、required checks 均未核验。不能声称 Gitea 已自动测试。 + +后续接入 CI 时：先核对服务器能力和 runner→使用同一本地验证入口→上传 test-evidence→验证失败阻断发布→确认对最终 SHA 真正执行。只新增 YAML 不算 CI 接入完成。 diff --git a/docs/v2/08-data-pilot-and-demo.md b/docs/v2/08-data-pilot-and-demo.md new file mode 100644 index 0000000..616b191 --- /dev/null +++ b/docs/v2/08-data-pilot-and-demo.md @@ -0,0 +1,58 @@ +# 历史经验数据试点与客户展示方案 + +状态：产品方案草案，演示数据与真实验证必须分开。 + +## 1. 客户沟通目标 + +争取客户开放一批用途明确、范围可控的历史评审过程数据，通过盲测判断是否继续扩大。核心表达：让每个新项目调用兴邦历史上处理类似争议的核查方法。没有真实数据时不能证明真实判断准确，也不以模型品牌代替效果证据。 + +## 2. 四幕展示脚本 + +| 场景 | 屏幕内容 | 现场操作 | 能证明什么 / 不能证明什么 | +|---|---|---|---| +| 历史经验提炼 | 原始材料→问询→补件→判断变化→经验候选 | 点击争议展开原文；删掉发生日期 | 能展示来源和未知处理；模拟案例不能证明懂兴邦历史 | +| 经验用于新项目 | 当前争议与正反历史案例并排 | 切换无经验/有经验两次实际运行 | 展示查什么、为什么查；不能预设“有经验必然更好” | +| 项目推进沙盘 | 证据→动作→问题→建议变化 | 加保证、补回款证据、调融资额 | 展示条件推演；不能把模拟差值称为因果提升 | +| 客户保留集验证 | 锁定预测→揭示参考→人工复盘 | 客户现场出题或持有未见案例 | 给出可核对的验证过程；小样本不宣传总体准确率 | + +示例故事：利润增长但现金流偏弱，最初要求回款核查；部分证据支持正常账期，部分显示恶化；主审比较差异后形成补件或附条件推进意见。明确标“虚构演示案例”，不使用真实客户名称作背书。 + +技术展开层展示：冻结快照、命中经验版本、工具调用结果、Jev具体问题、缺失项和硬规则。主页面显示业务含义，避免用技术图掩盖未验证结论。 + +## 3. 首批数据清单 + +| 数据 | 最小字段/材料 | 用途 | 缺失处理 | +|---|---|---|---| +| 项目索引 | 匿名project_id、业务类型、行业、阶段时间 | 同项目关联与分组 | 无稳定ID不用于跨版本比较 | +| 初始送审材料 | 当时版本、取得时间、来源 | 恢复初始信息条件 | 不拿最终报告冒充初稿 | +| 问询/评审意见 | 问题、提出时间、角色 | 识别争议和核查策略 | 角色用岗位或假名 | +| 补件与答复 | 对应问题、材料版本、取得时间 | 看证据是否回应问题 | 无对应关系人工确认 | +| 方案调整 | 金额/期限/增信等前后版本 | 区分补信息与改业务条件 | 不推断变化原因 | +| 批复及附带条件 | 审批阶段、结果、日期、条件 | 决策标签与条件 | 与审批通过预测输入隔离 | +| 当时制度 | 版本、适用时间和范围 | 判断旧经验是否适用 | 未知制度版本限制迁移 | +| 后续表现（可后续） | 条件落实、回款/风险事件时间 | 另行检验经验有效性 | 不作为早期预测时可得输入 | + +优先完整的少量案例链，数量和行业由双方确认。客户保留“原始身份→匿名ID”的映射；同项目全流程保持同一假名。不要求首先开放整库、全量个人信息或生产写权限。 + +## 4. 经验访谈提纲 + +1. 当时首先担心哪一件事，为什么？ +2. 哪条信息改变了你的判断；没有它还会同意吗？ +3. 哪项补件只是增加信息，哪项措施真正改变了项目条件？ +4. 这条经验有哪些例外，在哪类项目中会失效？ +5. 当时是否有分歧、例外授权或资料之外的背景？ +6. 后续结果是否支持当时判断，哪些结论仍不确定？ + +访谈是待确认意见，必须与原文和事件关联；不能把个人偏好直接发布成公司规则。 + +## 5. 数据流与边界 + +客户选择范围/匿名处理→授权导入→材料来源与时间核验→经验草稿→专家确认→开发样本验证→冻结保留集→独立预测→揭示结果→共同复盘。 + +部署前明确：原文保存位置、读取角色、模型出口、是否保留供应商日志、保留期限和删除责任。供应商条款及私有化能力尚未核验，不承诺 Jev 可本地部署。默认不把真实材料发送外部服务。 + +## 6. 试点验收与扩展条件 + +使用验证文档的重大问题漏检、无依据结论、误报、有效补件、专家分歧与效率指标。阈值先约定，结果差也如实展示；基线/经验增强/Jev增强分开测。客户数据从开发样本到保留样本逐步开放，不以模型推荐代替专家复盘。 + +通过试点后再扩大业务范围；失败则给出问题归因（提取、检索、经验适用、主审推理、数据缺失），不靠调漂亮分数掩盖。数据接入后的价值应通过相同边界的对照证明。 diff --git a/docs/v2/09-decisions.md b/docs/v2/09-decisions.md new file mode 100644 index 0000000..b3d40cb --- /dev/null +++ b/docs/v2/09-decisions.md @@ -0,0 +1,49 @@ +# 决策、未决项与学习记录 + +日期：2026-09-28。状态区分“用户已明确的方向”和“工程候选待评审”。 + +## 1. ADR + +| ID | 决策 / 状态 | 被否方案 / 理由 | 影响 | +|---|---|---|---| +| ADR-01 | 复用 Next.js+FastAPI 与现有组件，工程候选 | 全面换框架；无法复用已验证链路 | 先迁移可运行基座，再逐步拆模块 | +| ADR-02 | 主审综合意见、Jev局部判断，用户已明确 | Jev单题直接决定通过；缺乏整体研判 | 证据与硬规则约束最终有效输出 | +| ADR-03 | 历史评审过程是核心资产，用户已明确 | 只存通过/不通过标签；丢失核查和判断变化 | 优先收集问询、补件、修改和批复条件 | +| ADR-04 | 经验经审核、有适用范围，工程候选 | 自动把任意反馈变成规则；会固化错误 | 复用现有经验治理，建立历史过程关联 | +| ADR-05 | 无真实校准前不宣称审批概率，已讨论方向 | 分数/Noul直接转通过率；没有业务验证 | P0概率字段为空；先做可追溯预审和试点 | +| ADR-06 | 独立v2代码目录待迁移，当前先备份与文档，用户最新顺序 | 直接覆盖现有部署；难回退 | 旧版Gitea恢复点先核验；v2目录尚未建立 | +| ADR-07 | 按用户最新要求直接适配流程正文，原文保留在Gitea恢复点 | 照搬Electron路径/发布命令；无法执行 | AGENTS统一入口，正文按兴邦事实执行 | + +## 2. Open Questions + +needed-by 是明确阶段门，不虚构双方尚未约定的日历时间。 + +| ID | 待定内容 | 当前处理 | owner | needed-by | +|---|---|---|---|---| +| OQ-01 | 首批业务类型、关键核查项、正式硬规则 | 只使用标注演示规则；不宣称兴邦制度 | 项目负责人+兴邦评审专家 | M2真实经验建模前 | +| OQ-02 | 经验发布资格、独立复核、真实身份体系 | 演示角色明确标示；生产数据入口不开启 | 兴邦业务负责人+系统管理员 | M2生产权限实现前 | +| OQ-03 | Jev/主审模型端点、客户数据出口、保留策略 | mock/合成样本；不发送真实材料 | 兴邦数据负责人+技术负责人 | 任何真实材料模型调用前 | +| OQ-04 | 验收阈值、时延预算、资源/费用上限 | 文档工程限制仅提案，报告耗时不承诺效果 | 产品+测试+实施负责人 | M3配置定案及M5盲测前 | +| OQ-05 | “通过”阶段、预测时点、样本量与选择偏差 | probability=null | 兴邦审批负责人+建模负责人 | M6概率需求进入架构前 | +| OQ-06 | v2新仓库、云端目录、端口、容器/卷 | 暂用当前独立文档分支；不复用旧生产资源 | 项目负责人+运维 | M1迁移及任何v2部署前 | + +以上待定不阻止当前文档交付；阻止相应业务实现/真实数据阶段越过门禁。用户新指令可直接关闭或调整范围，不重复请求已授权事项。 + +## 3. 当前阶段门检查 + +| 门 | 状态 / 证据缺口 | +|---|---| +| Term | 草案已列术语，待业务评审 | +| Contract | 已有候选字段/状态/错误；未生成类型或确认DDL | +| Rule | BR-01–16已拆分并标职责，待评审 | +| Exception | E-01–12有错误和文案，契约校验仍待实现 | +| Coverage | 文档AC覆盖机械检查本轮执行；新功能行为测试未实现 | +| Decision | OQ项按里程碑阻断，未宣告需求阶段全过 | + +## 4. 学习与持久缺口 + +- 流程适配：来源文档含项目特例，最小owner是 XINGBANG-ADAPTATION.md 和根AGENTS入口；以后每次新增规范检查失效路径。当前完成文件与链接核验，不等同长期遵守效果。 +- 经验数据：默认团队模式和简化案例检索容易被误认为真实学习；owner为架构/产品说明，后续演示必须标来源。 +- Gitea CI：仅有GitHub YAML，runner与门禁未核验；owner运维，在首次v2合并前确认。 +- 历史文档密钥：旧DELIVERY.md有遗留凭据，当前恢复快照不改历史；新仓库迁移禁止携带；凭据有效性与轮换由凭据owner另行处理，本轮未访问验证。 +- 本地工具：沙箱进程初始化失败，已通过受审的升权命令完成工作；不将该环境问题误判为代码故障。 diff --git a/docs/v2/10-delivery-record.md b/docs/v2/10-delivery-record.md new file mode 100644 index 0000000..a2d5655 --- /dev/null +++ b/docs/v2/10-delivery-record.md @@ -0,0 +1,50 @@ +# 本次交付记录：流程接入、版本备份和新版文档 + +日期：2026-09-28。业务实现未启动；文档仍为评审草案。 + +## 1. 用户授权与边界 + +用户要求：把 docs/project-process 接入 agent 开发规则；确保当前版本在 Gitea 备份；随后编写兴邦新版开发文档。沿用仓库唯一入口 AGENTS.md，不再建平行的 agent.md。 + +实际副作用：本地文档写入、创建Git分支/提交、向已配置origin推送独立分支。未部署、未调用真实模型、未更改数据库、未推送github-backup、未修改main。 + +## 2. 原版备份 + +- 原分支：codex/deploy-stable-20260909；上游origin/main。 +- 原HEAD：b10093f9d8a949c6a6f8f8ed6d5b9c1bb044b569。 +- 备份分支：codex/backup-before-ai-prescreen-v2-20260928。 +- 备份SHA：4d5a420671cb073a56335bd617e7d0812b8179a9。 +- 远程：ssh://git@192.168.10.111:2222/qiaoqichao/mini-openclaw.git。 +- 证据：git push成功后，git ls-remote返回完全相同SHA。 +- 内容：37个变更文件，包含用户已有未提交代码、测试、部署配置、脚本、resetdata页面、业务文档及新流程原文。 +- 排除：.docker-codex、本地Office锁文件、重复的project-process.zip；本来忽略的.env、server-deploy.conf、运行数据等均未加入。 + +备份扫描检查了新变更的常见凭据模式，包括docx XML，未发现匹配项；这不是完整历史密钥审计。已有旧文档凭据问题未扩散到新文档。 + +原始新增文档有11处行尾空格（部分为Markdown换行），备份原样保留并记录在baseline-whitespace.log；恢复快照不声称达到发布门禁。本轮新写文档另做diff检查。 + +## 3. 本次文档范围 + +根AGENTS流程入口、项目流程兴邦适配、docs/v2目录中的URD、七段规格、架构、详细设计、UI、视觉约束、迁移、验证、部署/Gitea、数据试点、决策和本记录。 + +按用户后续要求，project-process的README、01–08及两份URD模板已直接适配兴邦；保留八阶段与原规则编号，原始内容可从4d5a420恢复。根AGENTS同时修正为真实后端app.py和项目工作目录。 + +文档分支：codex/xingbang-v2-docs-20260928。最终提交与远程状态使用git rev-parse HEAD及git ls-remote核验；不把文档提交等同正式需求评审或新版发布。 + +## 4. 本轮验证 + +状态：旧版代码全量验证通过；规范和新版文档的机械检查通过。证据目录：test-evidence/20260928-v2-planning/。 + +2026-09-28 执行 backend/venv/Scripts/python.exe scripts/verify.py，工作目录为仓库根；报告在 test-evidence/20260928-164935-4d5a420/REPORT.md。124个后端测试、4项UI源码守卫、Next生产构建、本地与云端Compose配置及diff检查全部通过（9项检查）。未执行--docker，未启动/发布容器。后续仅修改规范文档，业务源码保持备份哈希不变；最终文档检查单独绑定最终文件摘要。 + +测试环境使用占位模型Key和测试开关，不复制真实密钥。Gitea CI、真实浏览器E2E和云端实时健康均未在本次验证。 + +本轮文档检查：25份Markdown、87个本地链接、16条BR/12条E/16条AC的唯一性与覆盖通过；原流程各R-*编号集合保持一致，来源项目无效命令/路径残留清除。26个非流程备份文件的字节哈希未变，确认未修改既有业务代码。新增文档摘要保存在final-document-hashes.json；git diff格式检查通过。HTML模板仅调整项目说明和例子，未变更脚本/样式，未做浏览器视觉验收。 + +审阅：已检查正确性（当前入口/路径）、一致性（前后端及草案状态）、安全（密钥与数据范围）、测试（检查覆盖与未完成项）。这是本轮作者自查；独立业务/技术评审尚未发生，不宣称需求阶段获批。旧版通过也不代表v2功能通过。 + +## 5. 回滚与剩余工作 + +源码恢复可从已核验分支克隆到新目录，不重置当前工作区。文档修改保留独立提交，可通过后续revert撤销，不删除原始规范。远程资源仅新增分支，无main改写；无需进行破坏性恢复演练。 + +剩余：需求与方案评审、独立v2代码抽取、真实权限/模型出口确认、历史过程提炼、Jev适配、沙盘实现、脱敏盲测与后续概率校准。全部列入实施计划和OQ，当前未宣称完成。 diff --git a/docs/v2/DESIGN.md b/docs/v2/DESIGN.md new file mode 100644 index 0000000..70893b9 --- /dev/null +++ b/docs/v2/DESIGN.md @@ -0,0 +1,61 @@ +--- +status: candidate-not-implemented +colors: + primary: "#17634c" + surface: "#ffffff" + text: "#1d1d1f" +typography: + bodySize: "16px" + bodyLineHeight: 1.6 + family: '"Microsoft YaHei", "PingFang SC", sans-serif' +rounded: + navigationItem: "9px" +spacing: + navigationHorizontal: "24px" +components: + primaryAction: + background: "{colors.primary}" + foreground: "{colors.surface}" + surfacePanel: + background: "{colors.surface}" + color: "{colors.text}" +--- + +# 兴邦 v2 视觉契约草案 + +## Overview + +当前是基于已观察代码整理的候选契约。此文件尚未被 CSS 或构建消费，状态为 Present，不能声称 Token-ready/Aligned/Backstopped。正式 token 文件路径、导出与防漂移测试在 M1/M4 决定并实现。 + +## Colors + +primary #17634c 来自 src/components/xingbang/navigation.css 的 xb-brand-mark 及 src/app/globals.css 的 xingbang-mark；surface 白色取自现有业务面板；text #1d1d1f 来自 globals.css。当前全局 accent 是蓝色 #002fa7，与业务导航绿色并存，不能声称已经统一品牌主题。 + +提案：业务预审延续深绿和白色证据面板，减少装饰色。primary 用于主动作和品牌，不代表风险结论；成功/警告/阻断必须文字标识。辅助状态色和对比度尚待审查，未擅自编造正式 token。 + +## Typography + +正文 16px、行高 1.6 来自 globals.css；中文字体延续现有字体栈。预审结果、问题、证据三层信息明确，不把大量技术标签放在首页。数字不得比证据更突出，尤其不放未验证的通过概率。 + +## Layout + +项目与版本头部 → 判断摘要 → 核查/经验主区 → 证据抽屉/动作侧栏。小窗口切换为纵向，路径图始终有文字列表。导航水平 padding 24px 与导航项圆角 9px 来自 navigation.css 的后置业务可读性规则；不意味着其他组件强制使用这些值。 + +## Elevation & Depth / Shapes + +只对抽屉与浮层建立必要层次。面板阴影、圆角、间距完整尺度待视觉评审，禁止各组件自行新增任意裸值。已观察导航值不等于全站设计系统。 + +## Components + +RunSummary、EvidenceDrawer、CaseTimelinePanel、ExperienceEditor、ScenarioPanel、EvaluationPanel 均为提案，状态和权限以 UI Spec 为准。动作 hover/disabled/focus token 待补齐并验证；原型与正式实现必须使用同一来源。 + +## Do / Don't + +- 用“依据、差异、尚未验证”帮助业务人员理解；不要用黑盒发光大脑代替证据链。 +- 线宽代表定义明确的等级；不要把模拟路径长度、线宽或模型确信度当作概率。 +- 减少动效可关闭动画；焦点、错误、成功必须有文字和可见形状。 +- 实施时验证正文/焦点对比度达到流程要求；当前尚未执行，不能标已通过。 + +## 缺口与门禁 + +needs-design-decision：完整状态色、间距尺度、响应断点、组件状态 token；owner 前端负责人；needed-by UI 实现前。需要 token 导出检查、对比度测试、键盘测试及文案 key 检查，结果纳入 test-evidence。 diff --git a/docs/v2/README.md b/docs/v2/README.md new file mode 100644 index 0000000..cada4d5 --- /dev/null +++ b/docs/v2/README.md @@ -0,0 +1,40 @@ +# 兴邦智审 v2：开发文档入口 + +版本：0.1 · 2026-09-28 · 状态：评审草案。 + +产品方向：评审经验驱动的 AI 预审。主审 Agent 综合判断，Jev 承担局部判断，确定性程序执行计算和规则；历史评审过程是核心经验来源。当前没有兴邦真实历史数据，演示不能宣称真实审批通过概率。 + +## 当前工作边界 + +本轮已先保存原版源码恢复点，再编写流程与新版文档。未创建独立 v2 代码目录、未实施新版 API / Jev / 历史过程提炼、未部署或覆盖现有服务。迁移仍是后续任务，见实施计划；不能把现有名字含 v2 的旧模块误认为本轮新版已完成。 + +备份基线：`4d5a420671cb073a56335bd617e7d0812b8179a9`，Gitea `codex/backup-before-ai-prescreen-v2-20260928`；已通过远程 SHA 比对。此前主线：`b10093f9d8a949c6a6f8f8ed6d5b9c1bb044b569`。详情见交付记录。 + +## 阅读顺序 + +| 文档 | 用途 | +|---|---| +| [流程适配](../project-process/XINGBANG-ADAPTATION.md) | 如何执行同事提供的八阶段规范 | +| [URD](URD.md) | 用户、产品目标、功能、分期与产品验收 | +| [需求规格](01-requirements.md) | 七段规格、BR/E/AC 可追溯规则 | +| [架构](02-architecture.md) | 已有能力、目标边界、职责与 ADR | +| [详细设计](03-detailed-design.md) | 候选接口、数据契约、状态、失败处理 | +| [UI Spec](04-ui-spec.md) | 页面骨架、状态、权限和演示交互 | +| [设计契约](DESIGN.md) | 已观察视觉来源、语义 token 提案及缺口 | +| [实施计划](05-implementation-plan.md) | 核心代码迁移与分批交付 | +| [验证方案](06-validation.md) | 自动化、专家盲测和概率验证边界 | +| [部署与 Gitea](07-deployment-and-gitea.md) | 当前真实入口、备份恢复和 v2 隔离要求 | +| [数据试点与展示](08-data-pilot-and-demo.md) | 争取历史数据开放的演示脚本与试点方案 | +| [决策与未决项](09-decisions.md) | 已接受方向、候选决策、owner 与到期阶段 | +| [本次交付记录](10-delivery-record.md) | 备份证据、检查结果和未完成事项 | + +## 阶段状态 + +- ① 产品目标来自本次会话；需求规格为草案，尚待产品及兴邦评审人员确认。 +- ②–④ 为支持需求评审提前记录的候选设计，不视为阶段门禁完成。 +- ⑤–⑧ 文档描述未来实施、验证、交付和经验沉淀方式；本轮只实际执行文档检查和源码备份。 +- 现有基线测试结果仅证明旧版状态，不证明 v2 功能已经实现。 + +## 下一步 + +先评审 URD 和需求规格，优先确定首批业务类型、经验审核角色、数据使用边界。确认后按实施计划建立独立 v2 目录，逐批迁移与验证；真实数据试点和概率校准分别设门禁。 diff --git a/docs/v2/URD.md b/docs/v2/URD.md new file mode 100644 index 0000000..cf6793a --- /dev/null +++ b/docs/v2/URD.md @@ -0,0 +1,124 @@ +# 兴邦智审 v2 用户需求文档 + +## 1. 文档控制 + +| 项 | 内容 | +|---|---| +| 编号 | URD-XB-V2-0.1 | +| 日期 / 状态 | 2026-09-28 / 草稿待评审 | +| 需求来源 | 用户本次会话：聚焦 AI 预审、历史评审经验、Jev 辅助判断和数据开放展示 | +| 产品 owner | 项目负责人；业务评审 owner 为兴邦指定评审专家，待指派 | +| 维护位置 | docs/v2/URD.md | + +变更记录：0.1 首次整理；本文为后续规格输入，不代表客户已确认。 + +## 2. 目的与范围 + +帮助客户经理在项目早期获得有依据的推进建议、主要障碍、最小补件路径；帮助评审人员将历史项目中的调查方法沉淀为可审核、可复用、可撤回的经验。 + +P0 范围：受控演示、项目事实与证据、历史案例过程与经验卡、主审综合预审、Jev 可选专项核查、情景模拟、对照验证。先演示并验证经验链，再争取一批脱敏历史案例。 + +不在 P0：自动正式审批、自动放款、未经校准的通过概率、默认访问兴邦生产库、个人评审员通过倾向预测、用真实材料直接训练外部模型。这些能力或不属于本产品职责，或依赖另行确认的数据和验证条件。 + +成功条件：在明确标注的演示材料上，用户能追溯判断依据，理解新增材料为何改变或没有改变结论；脱敏试点效果经客户持有的保留样本验证后单独报告。 + +## 3. 参考 + +- [项目流程](../project-process/README.md)及 [URD 模板](../project-process/templates/URD-Template.md)。 +- [当前技术路径](../兴邦金租对公智能评审平台技术路径与AgentLoop说明-v1.0.md)。 +- [新版需求规格](01-requirements.md)、[架构](02-architecture.md)、[决策记录](09-decisions.md)。 + +## 4. 术语与角色 + +| 术语 | 用户语言定义 | +|---|---| +| 主审 Agent | 组织核查、比较证据并形成 AI 预审意见的助手 | +| 预审意见 | 建议推进、补充后再判断、暂不建议推进、信息不足；均非正式审批 | +| 经验卡 | 某类争议如何调查、哪些证据改变判断、适用与例外条件的记录 | +| 判断节点 | 一项具体争议及其核查、证据和当时意见 | +| 情景模拟 | 在假设动作完成的条件下重新评估，尚未改变真实项目事实 | +| 审批概率 | 指定审批阶段和时间口径下的获批估计，须独立历史校准 | +| 盲测 | 系统先锁定结果，再与保留的专家意见和结果对照 | + +| 角色 | 任务 | 成功表现 | +|---|---|---| +| 客户经理 | 提供材料、理解障碍、补件 | 知道下一步优先做什么及依据 | +| 评审员 | 核实经验、复核争议 | 看得懂证据链，能纠正和说明分歧 | +| 经验发布人 | 审核适用范围、发布和撤回经验 | 候选经验不会未经审核直接生效 | +| 数据/系统管理员 | 管理数据范围、模型出口和版本 | 每次运行有明确数据范围和访问记录 | +| 项目负责人/只读访客 | 观看演示、比较效果 | 分清模拟能力和实测效果 | + +发布人独立资格与真实身份接入方式见 OQ-02；P0 演示用明示的模拟角色，不当作生产鉴权。 + +## 5. 核心体验 + +历史档案 → 争议时间线 → 专家确认经验 → 新项目核查 → 补充证据与模拟 → 复核与对照验证。 + +页面入口拟整合到项目工作台：预审总览、历史经验、证据详情、推进沙盘、验证看板。保持当前项目上下文；不新增一批与现有工作台重叠的孤立旧页面。 + +交付面为中文 Web；保留现有 Next.js + FastAPI 技术基线。桌面应用、移动专用端暂不纳入。 + +## 6. 功能模块需求 + +| 模块 | 功能编号 | 用户任务 / 主流程 | 异常与用户行为 | 验收 | +|---|---|---|---|---| +| MOD-01 项目事实 | FR-FACT-01 | 上传材料→查看提取候选→确认事实与来源 | EX-FACT-01 解析失败：保留原件，允许人工录入并标注来源 | AC-U01 | +| MOD-02 历史过程 | FR-HIST-01 | 导入案例→整理争议、补件、证据、决定的时间线 | EX-HIST-01 时间或来源缺失：显示未知，禁止补造 | AC-U02 | +| MOD-03 经验治理 | FR-EXP-01 | 提炼候选→专家修改→审核发布→必要时撤回 | EX-EXP-01 无审核资格/过期：不进入有效经验集 | AC-U03 | +| MOD-04 主审预审 | FR-REV-01 | 发起预审→查看核查过程→获得意见与补件清单 | EX-REV-01 关键材料不足/工具失败：显示信息不足或部分结果 | AC-U04 | +| MOD-05 专项核查 | FR-JEV-01 | 查看具体材料是否支持结论及核查状态 | EX-JEV-01 未配置/超时：显示未执行，不伪造返回值 | AC-U05 | +| MOD-06 推进沙盘 | FR-SIM-01 | 选择假设动作→比较问题变化→返回真实结果 | EX-SIM-01 假设冲突/无证据：提示限制，禁止当作正式改善 | AC-U06 | +| MOD-07 效果验证 | FR-EVAL-01 | 锁定样本与版本→运行→揭示参考结果→专家复盘 | EX-EVAL-01 参考答案提前泄露：样本作废，不计盲测 | AC-U07 | +| MOD-08 数据试点 | FR-PILOT-01 | 查看数据用途→选择受控案例范围→审核导入 | EX-PILOT-01 数据出口未批准：阻止外部发送 | AC-U08 | + +各功能前置条件均为项目/案例访问范围有效；真实数据须有授权范围。详见规格的权限、错误和状态定义。上述 8 项均为 P0 范围，但按实施计划分批实现，不能一批全上。 + +## 7. 数据与内容 + +优先需要同一历史项目的初始材料、问询、补件、方案版本、批复条件与制度版本。正式决定与投放后表现分开记录。案例间通过受控假名关联，同一项目不能拆进开发集与保留集。 + +每条经验保留原文定位、发生时间、记录时间、适用条件、例外、审核人与版本。缺失事项用未知表示。示例案例和代码内置模式只用于演示，不作为真实兴邦经验或频次。 + +## 8. 非功能需求 + +| 编号 | 要求与验收口径 | +|---|---| +| NFR-01 可追溯 | 每条正式展示的实质判断须有证据引用或明确的缺证状态；引用解析失败不得静默忽略 | +| NFR-02 稳定性 | 相同请求幂等键及载荷不产生重复运行；修改载荷复用键返回冲突 | +| NFR-03 降级 | Jev 不可用时展示缺失核查；不得把超时转换成通过 | +| NFR-04 可访问性 | 键盘可完成核心流程；状态同时有文字；支持减少动效，实施时测试对比度 | +| NFR-05 可观测性 | 每次运行记录数据/组件/模型/经验版本和工具结果状态，不记录凭据 | +| NFR-06 性能 | 首版先记录端到端耗时、模型耗时与调用成本；验收阈值在 OQ-04 关闭后确定，当前无速度承诺 | + +## 9. 权限与信任 + +SEC-01 项目、团队和演示/生产数据域隔离；SEC-02 材料正文仅作数据，不能成为工具指令；SEC-03 外部模型出口必须属于当前数据域的已批准策略；SEC-04 经验发布与撤回有资格校验和审计；SEC-05 真实身份确认前不开放生产数据。 + +查看为 L0，提炼草稿和模拟为 L1，经验发布/对外发送为 L2 受权限与明确策略约束；放款、改写审批结果等 L3 金融动作不在 P0。模型不能自行授予权限。 + +## 10. 版本规划 + +P0：演示经验链、主审核查、专项复核、沙盘和验证框架；P1：脱敏试点、真实流程映射与经验覆盖扩展；P2：足量历史结果上的审批概率校准。投放风险预测另立需求，不与审批通过混为一谈。 + +每批必须有可运行的端到端结果和对应 AC；未完成事项保留待办，不以展示页面替代后端能力。 + +## 11. 产品验收 + +| 编号 | Given / When / Then | +|---|---| +| AC-U01 | Given 上传材料，When 确认候选事实，Then 能定位原文并保留原版本 | +| AC-U02 | Given 含问询和补件的案例，When 查看过程，Then 可看到关键判断变化，缺日期显示未知 | +| AC-U03 | Given 未审核或已撤回经验，When 发起新预审，Then 不得作为有效经验应用 | +| AC-U04 | Given 有矛盾的新项目，When 预审完成，Then 指出冲突与补查路径，不绕过硬性规则 | +| AC-U05 | Given Jev 未接入，When 查看结果，Then 明确未执行且不展示伪造概率 | +| AC-U06 | Given 模拟完成一个动作，When 比较结果，Then 真实快照保持不变且模拟标识持续可见 | +| AC-U07 | Given 客户保留样本，When 系统锁定结果后揭示标签，Then 可复盘分歧且记录无答案泄漏 | +| AC-U08 | Given 未批准外发的数据域，When 请求外部模型，Then 阻断请求且保留不含原文的审计 | + +核心效果指标：重大问题漏检、无依据结论、误报、有效补件、专家分歧、耗时与成本。目标值由试点双方在开测前确定；不预先承诺准确率。 + +## 12. 假设与未决项 + +当前假设：中文 Web、无真实历史库、先用标注演示数据、主审负责综合意见。首批行业、专家发布权限、模型数据出口、验收阈值和“通过”的阶段定义均见 [OQ 清单](09-decisions.md)，有 owner 与 needed-by。真实试点前必须关闭对应阻塞项。 + +附录：全部 FR/EX 索引在第 6 节；演示脚本见 [数据试点与展示](08-data-pilot-and-demo.md)。本版从既有综合平台聚焦经验驱动预审，保留旧能力供迁移，不声称重写完成。