This commit is contained in:
@@ -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）：按用户要求直接改为兴邦项目规范；保留八阶段及稳定规则编号，替换不适用的目录、测试、契约和发布要求。来源原文可从备份提交恢复，不再要求开发者自行映射。
|
||||
|
||||
Reference in New Issue
Block a user