# ConsensusFlow

**Repository Path**: zhou24/consensus-flow

## Basic Information

- **Project Name**: ConsensusFlow
- **Description**: Consensus Flow 是一款面向软件研发团队的 认知对齐与协作闭环平台。在 AI 编码工具显著提升单点生产效率的背景下，跨角色沟通与认知对齐已成为研发流程中的核心瓶颈。Consensus Flow 通过 “问答驱动”的协作模式，将需求澄清、设计评审、用例生成、变更确认等环节结构化、可追溯化，构建研发全链路的共识基底。
- **Primary Language**: Java
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-18
- **Last Updated**: 2026-05-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Consensus Flow

> 共识驱动的研发语义中枢 —— 结构化问答 · AI 辅助检查 · Git 无感版本管理

**当前阶段**：MVP V1.0 开发中  
**技术栈**：Java / Spring Boot + MyBatis‑Plus + H2  |  Vue  
**核心假设**：结构化澄清 + 强追溯能显著降低需求理解偏差导致的返工

---

## 1. 极速启动

### 1.1 一分钟理解业务
核心链路：**创建需求 → AI 预处理（风险识别）→ 异步问答澄清 → 规格锁定（Specified）**。  
价值点：让每一次需求沟通沉淀为可追溯的决策资产，而非散落在聊天记录中。

### 1.2 启动项目
1. **后端** (`backend/`)
   - 配置 `application.yml`（H2 文件路径、Git 仓库路径）
   - 执行 `mvn spring-boot:run`，自动初始化数据库
   - 健康检查 `http://localhost:8080/actuator/health`
2. **前端** (`frontend/`)
   - `npm install && npm run dev`
   - 访问 `http://localhost:5173`
3. **跑通第一个需求**
   - 参照 `docs/task-dev-checklist.md` 完成 **P0‑01 项目骨架**，再执行 **P1‑02 需求创建与流转**

---

## 2. 项目结构

```
/
├── README.md                   # 项目总纲
├── backend/                    # Spring Boot 后端
│   ├── api/                    # HTTP 接口层
│   ├── application/            # 业务编排层
│   ├── domain/                 # 领域模型、状态机、权限判定
│   └── infrastructure/         # H2/MyBatis‑Plus、Git、消息、缓存
├── frontend/                   # Vue 前端
│   ├── pages/                  # 按一级菜单拆分页面
│   ├── components/             # 通用组件
│   └── stores/                 # 状态管理
├── docs/                       # 文档总目录（正式入口 + 历史草稿）
│   ├── design/                 # 核心设计文档（正式）
│   │   ├── design-prd-mvp.md
│   │   ├── design-db.md
│   │   ├── design-ui-ux.md
│   │   └── design-architecture.md
│   ├── specs/                  # 工程规范文档（正式）
│   │   ├── spec-terms-event.md
│   │   ├── spec-permission-matrix.md
│   │   ├── spec-async-archive.md
│   │   └── spec-polymorphic-integrity.md
│   ├── draft/                  # 历史草稿与拆分材料（仅参考）
│   │   ├── ConsensusFlow-*.md
│   │   ├── MENU-PRD/
│   │   └── SYS-PRD/
│   └── task-dev-checklist.md   # AI 主导开发任务清单（可验收）
```

---

## 3. 文档导航与使用准则

### 第一梯队：核心设计（开发必读）
| 正式文档 | 用途 |
|:---|:---|
| `docs/design/design-prd-mvp.md` | 产品需求唯一执行标准，明确 MVP 边界与验收口径 |
| `docs/design/design-db.md` | 所有表结构、约束、索引定义，后端建表唯一依据 |
| `docs/design/design-ui-ux.md` | 页面布局、交互规范、视觉设计 Token |
| `docs/design/design-architecture.md` | 目录分层、核心服务、数据链路、前后端职责边界 |

### 第二梯队：工程规范（AI 编写代码必守）
| 正式规范 | 约束要点 |
|:---|:---|
| `docs/specs/spec-terms-event.md` | 实体命名、事件键、拒绝码，所有枚举值必须引用此文档 |
| `docs/specs/spec-permission-matrix.md` | 角色‑对象‑动作授权规则，前后端鉴权同一数据源 |
| `docs/specs/spec-async-archive.md` | 异步归档 Outbox 模式、幂等键、重试策略与可观测指标 |
| `docs/specs/spec-polymorphic-integrity.md` | `target_type+target_id` 三层防护，避免悬挂引用 |
| `docs/design/` | 面向研发执行的详细设计文档目录 |

### 第三梯队：参照与历史
| 草稿/任务文件 | 说明 |
|:---|:---|
| `docs/draft/ConsensusFlow-PRD-Full.md` | 全版本能力蓝图，仅用于理解演进方向，**当前不按此开发** |
| `docs/draft/Consensus Flow 综合优化建议报告.md` | 早期阶段优化建议与评审结论，作为参考输入，不作为开发约束 |
| `docs/task-dev-checklist.md` | AI 执行任务清单，每项任务含产出物、验收点与完成定义 |

### 使用准则（执行顺序）
1. **先读正式入口文档**：所有开发、评审、联调默认以 `docs/design/` 与 `docs/specs/` 为准。  
2. **草稿仅作补充**：`docs/draft/` 中内容仅用于追溯历史或补充上下文，不能覆盖正式口径。  
3. **变更必须双同步**：更新正式文档时，需同步更新本 README 的结构与导航。  
4. **命名保持稳定**：新增正式文档优先沿用 `design-*` / `spec-*` 前缀，避免语义分散。  

---

## 4. AI 开发核心约束（Codex 规则）

开发过程中，AI 必须将以下规则作为系统指令：

1. **跳转协议**：所有跨对象跳转必须使用 `target_type + target_id`，禁止页面私有字段拼装路由。  
2. **错误可见**：所有权限拒绝、状态非法、资源不存在等必须返回标准 `reason_code`，前端必须显式展示原因，禁止静默失败。  
3. **状态流转卡点**：`Clarifying -> Specified` 流转时，必须强制检查 AI 风险项是否全部解决/豁免，否则**阻塞流转并弹窗提示**。  
4. **数据与 Git 分离**：文档内容只存 Git 仓库，DB 仅存元数据。所有 Git 操作异步执行，具备幂等、重试、失败可观测能力。  
5. **MVP 边界**：功能入口可预留，但任何标注 `V1.5+` 或 `V2.0+` 的逻辑**坚决不实现**，仅提供禁用态按钮与版本说明。

---

## 5. 进度与验收

- **当前阶段**：P0 工程基线（项目骨架、字典、数据库初始化、异步适配器）  
- **关键指标**  
  - 异步归档成功率 ≥ 99.5%  
  - 站内通知投递成功率 ≥ 99.9%  
  - 核心链路（创建需求 → 澄清 → 规格锁定）3 分钟内可闭环  
- **下一步**：执行 `docs/task-dev-checklist.md` 中 **P0‑01**，完成后进入后端核心模块开发

---

## 6. 参与贡献

1. Fork 本仓库
2. 新建 Feat_xxx 分支
3. 提交代码
4. 新建 Pull Request

---

*维护方式：个人与 AI 协作，文档迭代后需同步更新本 README。最后同步：2026-04-28*