docs(xingbang): 适配项目开发流程并建立经验驱动预审新版文档

2026-09-28 17:02:33 +08:00
parent 4d5a420671
commit 9d2399feed
26 changed files with 1164 additions and 266 deletions
@@ -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 项目事实适配；稳定规则编号保留。
@@ -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 项目事实适配；稳定规则编号保留。
@@ -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 项目事实适配；稳定规则编号保留。
@@ -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 项目事实适配；稳定规则编号保留。
@@ -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
 <type>(<scope>): <subject>        # 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 项目事实适配；稳定规则编号保留。
@@ -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 项目事实适配；稳定规则编号保留。
@@ -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 含 <div id="root"> + 入口 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/<run-id>/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流程，未执行云端部署。
@@ -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 项目事实适配；稳定规则编号保留。
@@ -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）：按用户要求直接改为兴邦项目规范；保留八阶段及稳定规则编号，替换不适用的目录、测试、契约和发布要求。来源原文可从备份提交恢复，不再要求开发者自行映射。
@@ -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或关联原规则，不悄悄修改业务口径。
@@ -61,7 +61,7 @@ strong{color:#16233c}
 <main class="content">
 <h1 id="sec-1-urd-模板-user-requirements-document-" class="doc-h1">URD 模板（User Requirements Document）</h1>
 <blockquote><strong>定位</strong>：URD（用户需求文档，与 PRD 等价）是<strong>产品级</strong>需求描述——定义"产品是什么、为谁服务、用户要完成哪些任务、每个功能如何被用户感知和使用"。它是软件项目<strong>一切后续文档的输入</strong>：阶段 ① 需求规格（BR/E/AC）、② 架构、③ 详细设计、④ UI Spec、测试用例，都必须能追溯到本文档的功能条目。</blockquote>
-<blockquote><strong>适用</strong>：本模板用于 DK Forge 及后续所有软件项目的产品需求文档撰写。</blockquote>
+<blockquote><strong>适用</strong>：本模板用于兴邦金租 AI 评审平台及新版 AI 预审的用户需求撰写；正文按业务人员语言描述，区分演示、真实数据试点与正式审批。</blockquote>
 <blockquote><strong>用法</strong>：复制本文件为 <code><产品名>-URD-<版本>-<日期>.md</code>，按占位符 <code><...></code> 填写；删除不适用章节并记录删除理由；编号规则见第 0 节，不得破坏。</blockquote>
 <hr>
 <h2 id="sec-2-0-使用说明与编号规则-写文档前先读-成稿后可删-" class="doc-h2">0. 使用说明与编号规则（写文档前先读；成稿后可删）</h2>
@@ -79,7 +79,7 @@ strong{color:#16233c}
 </li>
 <li>阶段 ① 规格回答 <strong>"这一版改动具体怎么实现、怎么验收"</strong>；
 </li>
-<li>URD 讲用户语言，不写内部实现（不写表结构、类名、IPC 通道）；确有底层约束须写"约束与假设"。
+<li>URD 讲用户语言，不写内部实现（不写表结构、类名、内部工具调用）；确有底层约束须写"约束与假设"。
 </li>
 <h3 id="sec-3-0-2-编号规则-只追加-不重排-弃用标记-withdrawn-" class="doc-h3">0.2 编号规则（只追加、不重排、弃用标记 withdrawn）</h3>
 <div class="tbl-wrap"><table><thead><tr><th data-c="前缀">前缀</th><th data-c="含义">含义</th><th data-c="示例">示例</th></tr></thead><tr><td><code>MOD-xx</code></td><td>模块编号</td><td><code>MOD-03</code></td></tr><tr><td><code>FR-<模块简码>-<nn></code></td><td>功能点编号（模块简码见 6.1 清单）</td><td><code>FR-STU-04</code></td></tr><tr><td><code>EX-<模块简码>-<nn></code></td><td>功能点的异常/边界场景</td><td><code>EX-DASH-02</code></td></tr><tr><td><code>NFR-xx</code></td><td>非功能需求</td><td><code>NFR-07</code></td></tr><tr><td><code>SEC-xx</code></td><td>安全/权限需求</td><td><code>SEC-03</code></td></tr><tr><td><code>AC-xx</code></td><td>端到端验收标准</td><td><code>AC-10</code></td></tr><tr><td><code>OQ-xx</code></td><td>待决策/开放问题</td><td><code>OQ-04</code></td></tr></table></div>
@@ -117,7 +117,7 @@ strong{color:#16233c}
 <h3 id="sec-3-2-4-非目标-out-of-scope-与范围同等重要-逐条写明排除理由" class="doc-h3">2.4 非目标（Out of Scope）——与范围同等重要，逐条写明排除理由</h3>
 <div class="tbl-wrap"><table><thead><tr><th data-c="排除项">排除项</th><th data-c="理由">理由</th><th data-c="可能时机">可能时机</th></tr></thead><tr><td><code><明确不做的事></code></td><td><code><为什么本期不做></code></td><td>后续版本 / 永不</td></tr><tr><td><code><例如：开放第三方市场></code></td><td><code><例如：首版只支持受控模板></code></td><td>V2+</td></tr></table></div>
 <h3 id="sec-3-2-5-成功标准-产品级-一句话可判-" class="doc-h3">2.5 成功标准（产品级，一句话可判）</h3>
-<li><code><首个版本成功的硬性标志，如：不写代码的业务人员可在 60 分钟内发布一个可用 Agent></code>
+<li><code><首个版本成功的硬性标志，如：客户经理可完成一次带证据引用和补件清单的项目预审></code>
 </li>
 <hr>
 <h2 id="sec-2-3-参考文献" class="doc-h2">3. 参考文献</h2>
@@ -127,7 +127,7 @@ strong{color:#16233c}
 <h3 id="sec-3-4-1-术语表" class="doc-h3">4.1 术语表</h3>
 <div class="tbl-wrap"><table><thead><tr><th data-c="术语">术语</th><th data-c="定义（用户语言，可配图）">定义（用户语言，可配图）</th></tr></thead><tr><td><code><领域词，如 Agent / 面板 / Scope></code></td><td><code><一句话说清></code></td></tr></table></div>
 <h3 id="sec-3-4-2-用户角色" class="doc-h3">4.2 用户角色</h3>
-<div class="tbl-wrap"><table><thead><tr><th data-c="角色">角色</th><th data-c="画像">画像</th><th data-c="主要任务">主要任务</th><th data-c="成功标准">成功标准</th><th data-c="常用模块">常用模块</th></tr></thead><tr><td><code><角色></code></td><td><code><谁，技术背景></code></td><td><code><日常要完成什么></code></td><td><code><做到什么算好></code></td><td>MOD-xx</td></tr><tr><td>例：培训者</td><td>懂业务不写代码</td><td>制作并发布一个 Agent</td><td>不改代码完成首版</td><td>MOD-02/05</td></tr></table></div>
+<div class="tbl-wrap"><table><thead><tr><th data-c="角色">角色</th><th data-c="画像">画像</th><th data-c="主要任务">主要任务</th><th data-c="成功标准">成功标准</th><th data-c="常用模块">常用模块</th></tr></thead><tr><td><code><角色></code></td><td><code><谁，技术背景></code></td><td><code><日常要完成什么></code></td><td><code><做到什么算好></code></td><td>MOD-xx</td></tr><tr><td>例：客户经理</td><td>熟悉融资租赁业务</td><td>提交材料并理解预审意见</td><td>明确项目障碍与下一步</td><td>MOD-02/05</td></tr></table></div>
 <h3 id="sec-3-4-3-角色-模块-关注矩阵-可选-" class="doc-h3">4.3 角色 × 模块 关注矩阵（可选）</h3>
 <div class="tbl-wrap"><table><thead><tr><th data-c=""></th><th data-c="MOD-01">MOD-01</th><th data-c="MOD-02">MOD-02</th><th data-c="MOD-03">MOD-03</th><th data-c="…">…</th></tr></thead><tr><td>角色 A</td><td>使用</td><td>使用</td><td>–</td><td></td></tr><tr><td>角色 B</td><td>–</td><td>审核</td><td>使用</td><td></td></tr></table></div>
 <hr>
@@ -143,7 +143,7 @@ strong{color:#16233c}
 </code></pre>
 <p><code><模块之间的依赖与数据走向一句话说明。></code></p>
 <h3 id="sec-3-5-3-核心用户流程-端到端-" class="doc-h3">5.3 核心用户流程（端到端）</h3>
-<p><code><步骤表：用户从进入到完成一次价值闭环的全过程></code>（例：安装 → 授权 → 首次运行 → 理解 → 协作）</p>
+<p><code><步骤表：用户从进入到完成一次价值闭环的全过程></code>（例：选择项目 → 确认材料 → 发起预审 → 查看证据 → 补件复核）</p>
 <h3 id="sec-3-5-4-体验原则" class="doc-h3">5.4 体验原则</h3>
 <li><code><先给结果，再邀请对话></code>（示例原则，按产品改写）
 </li>
@@ -156,7 +156,7 @@ strong{color:#16233c}
 <li>...
 </li>
 <h3 id="sec-3-5-5-交付面与平台约束" class="doc-h3">5.5 交付面与平台约束</h3>
-<div class="tbl-wrap"><table><thead><tr><th data-c="交付面">交付面</th><th data-c="说明">说明</th><th data-c="优先级">优先级</th></tr></thead><tr><td><code><桌面 Electron / Web / 移动 / 硬件></code></td><td><code><能力边界、离线、多端同步></code></td><td>P0/P1</td></tr></table></div>
+<div class="tbl-wrap"><table><thead><tr><th data-c="交付面">交付面</th><th data-c="说明">说明</th><th data-c="优先级">优先级</th></tr></thead><tr><td><code><客户经理工作台 / 评审工作台 / 管理配置></code></td><td><code><项目权限、材料来源、运行状态、异常恢复></code></td><td>P0/P1</td></tr></table></div>
 <hr>
 <h2 id="sec-2-6-功能模块需求-本文档主体-" class="doc-h2">6. 功能模块需求（本文档主体）</h2>
 <h3 id="sec-3-6-1-模块清单与划分说明" class="doc-h3">6.1 模块清单与划分说明</h3>
@@ -249,4 +249,5 @@ strong{color:#16233c}
 <h3 id="sec-3-c-变更对照-本版相对上一版的增删-" class="doc-h3">C. 变更对照（本版相对上一版的增删）</h3>
 <hr>
 <blockquote><strong>模板维护</strong>：本模板本身受仓库 ⑧ 学习与沉淀 约束——使用中发现结构缺陷，更新本文档并记入"变更记录"（放文末）。</blockquote>
+<section><h2>兴邦填写约束（XB-1.0 · 2026-09-28）</h2><ul><li>明确主审 Agent、专项判断模型和正式审批职责；Jev 单题不能直接审批。</li><li>历史经验包含争议、核查、证据和判断变化；过程缺失须标未知。</li><li>定义项目权限、数据域、模拟与正式结果、失败与人工复核路径。</li><li>无真实校准时不承诺通过率、准确率或改善幅度；未决项标 owner 与阶段。</li><li>本文为阅读模板，正式编辑与编号以同目录 URD-Template.md 为准。</li></ul></section>
 </main></div></body></html>
@@ -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)。