qiaoqichao/mini-openclaw

Fork 0

Files

T

qiaoqichao 9d2399feed

verify / test-and-build (push) Canceled after 0s

Details

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

2026-09-28 17:02:33 +08:00

13 KiB

Raw Blame History

URD 模板（User Requirements Document）

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

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

0.1 文档关系

商业/产品设想（PRD 草稿、口头想法）
        │ 提炼、确认边界
        ▼
本 URD —— 用户可感知的功能需求（本文档）
        │ 拆解为可实现的单点需求
        ▼
阶段①规格（BR/E/AC）→ ② 架构 → ③ 详细设计 → ④ UI Spec → 实现 → 测试

URD 回答 "用户要什么、为什么、长什么样、做到什么程度算好"；
阶段 ① 规格回答 "这一版改动具体怎么实现、怎么验收"；
URD 讲用户语言，不写内部实现（不写表结构、类名、内部工具调用）；确有底层约束须写"约束与假设"。

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

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

0.3 书写纪律（继承仓库阶段①规则）

每条功能点 = 一个用户可感知的行为，写成"用户可验证"的描述；散文式一段话超过 5 行 → 拆成行为列表。
每个功能点必须写 主流程（happy path）与 异常/边界（用户会遇到的不顺路径），禁止只写 happy path。
写不动的先 TBD / OQ-xx（带 owner 与期限），禁止编造。
优先级统一 P0（MVP 必做）/ P1（近期待做）/ P2（远期）。
所有状态、权限、阈值是可配置项时写明"默认值 + 可配置范围"，不写死。

1. 文档控制

1.1 文档信息

项	内容
文档名称	`<产品名> 用户需求文档（URD）`
文档编号	`URD-<产品简称>-<版本>`
版本 / 日期	`V<0.x> · <yyyy-mm-dd>`
产品名称 / 版本	`<对外名称> V<目标版本>`
文档状态	草稿 / 评审中 / 已确认 / 已发布
作者 / 评审人	`<姓名或角色>`
维护位置	`<仓库路径>`

1.2 历史记录

日期	版本	作者	变更记录
yyyy-mm-dd	V0.1	xxx	首次创建；<列出范围，如"第 1–3 章 + MOD-01" >

1.3 评审与分发

角色	评审关注点
产品负责人	范围、优先级、验收标准是否符合商业意图
设计（UI/UX）	功能点的用户流程与界面要求是否可实现
研发负责人	是否存在未定义边界或不可实现的约束
测试负责人	每条功能点是否可验证、异常是否齐全
市场/实施	话术与演示脚本是否与功能一致

2. 目的与范围

2.1 文档目的

一句话：本文档定义 <产品名> 的用户需求——<它解决谁的什么问题，交付什么结果>。说明：本文档的读者（产品/设计/研发/测试/市场）、文档如何被使用（培训材料？需求基线？）。

2.2 产品定义

项	内容
一句话结论	`<产品做什么、为谁做、交付物>`
核心价值	`<用户购买/使用它的理由，1–3 条>`
交付结果	`<安装包/服务/平台等>`

2.3 目标范围（In Scope）

<范围一：……>
<范围二：……>

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

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

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

<首个版本成功的硬性标志，如：客户经理可完成一次带证据引用和补件清单的项目预审>

3. 参考文献

文档/来源	版本/日期	与本文档的关系
`<产品定义 PRD>`	V0.1	本文档的功能蓝本
`<代码功能事实：codewiki / docs 架构文档>`	生成日期	现状能力基线
`<竞品/标准/协议>`		约束来源
`<阶段①规格草稿>`		已确认决策的回写来源

4. 术语、角色与成功标准

4.1 术语表

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

4.2 用户角色

角色	画像	主要任务	成功标准	常用模块
`<角色>`	`<谁，技术背景>`	`<日常要完成什么>`	`<做到什么算好>`	MOD-xx
例：客户经理	熟悉融资租赁业务	提交材料并理解预审意见	明确项目障碍与下一步	MOD-02/05

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

	MOD-01	MOD-02	MOD-03	…
角色 A	使用	使用	–
角色 B	–	审核	使用

5. 产品概览与核心体验

5.1 产品背景与目标

<为什么做这个产品；本版本要证明什么（如：证明某类用户能独立完成某闭环）。>

5.2 信息架构与模块关系

一级入口/模块树（文字树或图）
├── <模块一>
│   ├── <子功能>
└── ...

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

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

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

5.4 体验原则

<先给结果，再邀请对话>（示例原则，按产品改写）
<每个结论可解释>
<异常与关键选择集中呈现，普通状态不打扰>
<任何能力可见、可停用、可替换>
...

5.5 交付面与平台约束

交付面	说明	优先级
`<客户经理工作台 / 评审工作台 / 管理配置>`	`<项目权限、材料来源、运行状态、异常恢复>`	P0/P1

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

6.1 模块清单与划分说明

划分原则：按用户任务闭环划分模块（不是按技术层）；模块间尽量低耦合、每个模块有明确负责人与验收场景。

模块模块名一句话职责主要角色简码优先级

MOD-01 <名称> <为谁解决什么> <STU/DASH…> P0

MOD-02 ...

模块	模块名	一句话职责	主要角色	简码	优先级
MOD-01	`<名称>`	`<为谁解决什么>`		`<STU/DASH…>`	P0
MOD-02	...

模块依赖图（可选）：MOD-02 依赖 MOD-01 的发布产物 等。

6.2 各模块详细需求

每模块复制下面一节；模板中 MOD-xx 以 MOD-01 为例。

MOD-01 `<模块名>`

模块概述

项	内容
目的	`<该模块在用户任务闭环中的位置与作用>`
用户	`<角色>`
入口	`<从哪个一级入口/页面进入>`
依赖	`<依赖哪些其他模块或外部系统>`
核心对象	`<用户在该模块操作的对象：如 Agent、面板、版本>`

功能点总览

编号	功能名称	用户可完成的任务	优先级
FR-XXX-01	`<名称>`	`<一句话用户价值>`	P0
FR-XXX-02	...		P1

功能点详述

FR-XXX-01 `<功能名称>`（P0）

功能描述：<该功能是什么；用户可用它完成什么；关键行为逐条列出，如：>
1. <行为一>
2. <行为二>
前置条件：<进入该功能前必须满足的条件，如已登录、已有数据源授权>（无则写"无"）
主流程：

步骤用户操作系统响应

1 <操作> <响应/界面变化>

2 ...
行为规则与边界：
- <规则/边界一：如"默认展示最近 7 天，可配置 1–90 天">
异常与边界场景：

编号场景用户可见行为后备方案

EX-XXX-01 <如：数据源超时> <提示什么> <重试/降级显示陈旧数据并标注>
UI 与交互要求：<布局要点、状态（空/加载/错误/正常）、交互手势、可访问性>（详见阶段 ④ UI Spec）
权限与安全：<该功能涉及的权限等级（见第 9 章 L0–L3）、确认点、审计>（无则写"无额外要求"）
验收要点：<该功能可验证的 3–6 条要点，对应第 11 章 AC>：
- 要点一
- 要点二
关联与备注：<关联功能点/引用文献/开放问题 OQ-xx>（无则写"—"）

步骤	用户操作	系统响应
1	`<操作>`	`<响应/界面变化>`
2	...

编号	场景	用户可见行为	后备方案
EX-XXX-01	`<如：数据源超时>`	`<提示什么>`	`<重试/降级显示陈旧数据并标注>`

FR-XXX-02 …（复制上面小节）

7. 数据与内容需求（若产品以数据/面板/内容为核心）

7.1 数据类型与口径

内容	用户要定义什么	系统如何使用

7.2 内容/数据生成规则

7.3 展示与交互要求（数据面）

8. 非功能需求

编号	类别	需求	目标/阈值
NFR-01	性能	`<首屏/操作响应>`	`<如 ≤2s>`
NFR-02	可用性	`<新用户无培训完成核心任务>`	`<如 ≤60 分钟>`
NFR-03	可靠性与离线	`<数据源/服务不可用时的降级>`
NFR-04	兼容性	`<OS/浏览器/分辨率>`
NFR-05	可访问性	`<键盘/读屏/对比度>`
NFR-06	国际化与本地化	`<语言/时区/货币/格式>`
NFR-07	数据与隐私	`<数据保留/删除/导出>`
NFR-08	可观测性	`<日志/审计/用量统计>`
NFR-09	安装升级	`<安装包、升级与回滚>`

每行写清"可度量阈值"，无阈值 = 不可验收。

9. 安全、权限与信任

9.1 用户可理解的动作等级

等级	含义	产品行为
L0 查看	只读取和展示	授权后自动运行，留读取记录
L1 准备	生成草稿不对外提交	可自动完成，用户可编辑
L2 确认后执行	改变外部系统/通知他人	必须展示详情由用户确认
L3 强确认	金钱/敏感/不可逆	二次确认或强身份验证，默认不批量

9.2 必须由产品层提供的能力（按产品改写）

Scope 隔离 / 最小权限 / 凭证托管 / 执行确认 / 可撤销与熔断 / 全链路记录 / 发布前安全测试

9.3 信任界面要求

<每个展示面与动作卡应呈现的信任信息：版本、数据时间、来源、权限等级、失败后果>

10. MVP 范围与版本规划

10.1 MVP 目标与样板场景

目标	验证重点	最低闭环

10.2 P0 / P1 / P2 范围表

产品/模块	P0（MVP）	P1	P2（明确不做入近期）

10.3 推荐交付阶段

阶段	产品结果	验收门

11. 验收标准与产品指标

11.1 端到端验收

编号	验收标准（按角色、可执行）
AC-01	`<Given/When/Then 或可执行描述>`

11.2 核心产品指标

指标	定义	目标
`<首次价值时间>`	`<定义>`	`<阈值>`

12. 假设与待决策事项

编号	事项	V0.x 默认假设	需要的产品决策	Owner	期限
OQ-01	`<如：首端平台>`	`<默认>`	`<待决问题>`

未决事项不阻止开始原型，但进入正式排期前必须关闭。

附录

A. 功能点索引（全部 FR / EX 编号 → 模块位置，自动核对用）

编号	功能	模块	优先级	状态（草稿/已确认/withdrawn）

B. 产品话术与演示脚本（可选）

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

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

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

写清主审 Agent、专项判断模型和正式审批的职责；不把 Jev 单题输出当作审批决定。
历史经验须描述争议、核查、证据和判断变化；仅有最终结果时标过程缺失。
每项功能明确材料来源、项目/数据域权限、模拟与正式结果边界、失败与人工复核路径。
没有真实校准数据时不承诺通过率、准确率或改善幅度；未决项有 owner 和进入阶段。
规格、架构、UI 和测试均回链到功能编号。可参考兴邦v2 URD。

13 KiB Raw Blame History Unescape Escape