1342 lines
69 KiB
Markdown
1342 lines
69 KiB
Markdown
# PMFlow 产品推进执行标准
|
||
|
||
版本日期：2026-04-24
|
||
|
||
本文档是 PMFlow 产品方案落地的推进标准。它回答四件事：
|
||
|
||
- 当前产品方案推进到哪里了。
|
||
- 下一步应该继续往哪里推进。
|
||
- 每次推进的范围、验收和文档回写怎么做。
|
||
- 新开 Codex 线程时如何接续，避免重做、漏做或偏离方向。
|
||
|
||
产品方向真源仍以 `docs/PMFLOW_PRODUCT_BLUEPRINT.md` 为准。本文档不重新定义战略，只管理落地节奏和进度。
|
||
|
||
## 1. 当前推进判断
|
||
|
||
截至 2026-04-24，PMFlow 已经完成“产品方向收敛 + 前端本地高保真主链 + 后端局部控制面”的阶段，但还没有完成“真实数据闭环产品化”。
|
||
|
||
### 1.1 已经推进到位的部分
|
||
|
||
#### 产品方向
|
||
|
||
- 已明确 PMFlow 不是“聊天工具 + 项目管理工具”，而是“对话驱动的 AI 产品执行操作系统”。
|
||
- 已明确首版方向为 `solo-first, team-ready`，面向个人开发者、一人公司、半技术产品创作者和 1-10 人 AI 应用小团队。
|
||
- 已明确团队协作不是传统多人维护任务表，而是围绕 AI 维护的项目真相层进行异步审查和人机混编执行。
|
||
- 已明确 V1 主链为：`创意输入 -> AI 结构化提取 -> 变更确认 -> 项目对象沉淀 -> 任务拆解 -> 推送 IDE / agent -> 开发与测试回写 -> 发布 -> 数据反馈 -> 下一轮迭代`。
|
||
|
||
真源：
|
||
|
||
- `docs/PMFLOW_PRODUCT_BLUEPRINT.md`
|
||
- `USER.md`
|
||
|
||
#### 前端产品域
|
||
|
||
当前已经存在三条独立产品域：
|
||
|
||
- `frontend/src/features/personal-space/`
|
||
- 空间入口。
|
||
- 用本地 mock 展示继续推进、待我确认、AI 正在推进、暂存想法、草案箱和新建项目入口。
|
||
- `frontend/src/features/project-launch/`
|
||
- 新项目启动台。
|
||
- 用本地状态机覆盖意图输入、AI 工作、人类确认、草案修改、失败态、创建成功态和移动端 bottom sheet。
|
||
- `frontend/src/features/pmflow-os/`
|
||
- PMFlow OS 项目内主体验。
|
||
- 已有本地 truth store 和页面：`CommandCenter / StructuredExtraction / ChangeReview / MemoryWritebackResult / WorkGraph / ExecutionBridge / ReleaseGrowth / TeamLayer / ProjectMemory`。
|
||
- 已有本地状态动作：`sendMessage -> generateExtraction -> acceptChange/editChange/deferChange -> promoteAcceptedToGraph -> pushTaskToExecution -> writeBackExecution -> publishRelease -> ingestGrowthSignal`。
|
||
|
||
当前性质：
|
||
|
||
- 这是产品主链的高保真原型和本地行为闭环。
|
||
- 还不是正式后端数据闭环。
|
||
- 不接真实 AI 提取，不写真实数据库，不消费真实项目对象。
|
||
|
||
#### 后端控制面
|
||
|
||
当前已经出现 AI 应用项目控制面的初步生产化能力：
|
||
|
||
- `backend/app/models/ai_project_control.py`
|
||
- 模型目录、项目模型绑定、模型推荐快照、模型用量、模型评测。
|
||
- Prompt Package。
|
||
- IDE 工作区绑定、Repo 绑定、GitHub App 安装/仓库/webhook 投递。
|
||
- TaskCodeLink、ProgressEvent、DevSession。
|
||
- ReleaseValidationRun、FeedbackIngest、IterationRecommendation、RevenueEvent、ROISnapshot、ComplianceCheckRun、EvidencePack。
|
||
- `backend/app/services/ai_project_control_service.py`
|
||
- 模型推荐、模型绑定、prompt package、开发同步、GitHub/repo 绑定、进度事件、发布验证、反馈/收入/合规等服务能力。
|
||
- `backend/app/api/sstc_api/model_control.py`
|
||
- 模型推荐、模型绑定、模型用量、Prompt Package、发布验证、反馈摄取、收入记录、合规检查等接口。
|
||
- `backend/app/api/dev_sync.py`
|
||
- GitHub App 安装、仓库绑定、开发任务、项目 dev-sync summary、任务进度事件等接口。
|
||
|
||
当前性质：
|
||
|
||
- 后端已经有 V1 产品化需要的部分基础对象和接口。
|
||
- 但它们还没有和 `frontend/src/features/pmflow-os/` 的本地 truth store 正式打通。
|
||
- `ChangeSet / Approval / Evidence / Project Memory` 这条主产品链仍主要停留在前端本地态和旧 SSTC/semantic facts 体系之间，缺少统一的 PMFlow OS 产品级 API 合同。
|
||
|
||
### 1.2 当前缺口
|
||
|
||
当前最大缺口不是再讨论产品方向，而是：
|
||
|
||
**把已经成立的产品主链从本地原型推进成真实可用的数据闭环。**
|
||
|
||
关键缺口按优先级排序：
|
||
|
||
1. `Project Thread / ChangeSet / Evidence / Approval / Project Memory` 的前后端合同没有完全收口。
|
||
2. `project-launch` 还没有接真实 AI 结构化、真实项目创建和真实草案确认。
|
||
3. `pmflow-os` 本地 store 还没有接后端读写，当前仍是 mock truth store。
|
||
4. `ChangeReview` 的接受、修改、暂缓还没有写入正式对象、审批记录和证据链。
|
||
5. `ExecutionBridge` 页面还没有消费 dev-sync / GitHub / PromptPackage 真实接口。
|
||
6. `ReleaseGrowth` 还没有把 release validation、feedback、revenue、ROI、compliance 真实数据串成发布后反馈循环。
|
||
7. `TeamLayer` 仍是产品表达层，缺少真实成员角色、Role Inbox、Decision Desk、Team Feed 的数据模型和审查流程。
|
||
|
||
## 2. 下一步推进方向
|
||
|
||
下一步不要扩大战线，不要新增新的战略产品表面；可以在已确认的 `Main Flow / Space / Account Settings` 这些既有表面内并行推进。正确方向是：
|
||
|
||
**把 V1 主链真实闭环化。**
|
||
|
||
也就是从“本地高保真原型”推进到“真实项目对象 + 真实 AI 提取 + 真实确认写入 + 真实执行回写”。
|
||
|
||
### 2.1 下一阶段总目标
|
||
|
||
阶段目标命名为：
|
||
|
||
**V1 Productized Loop**
|
||
|
||
验收标准：
|
||
|
||
- 用户从 `/project-launch` 输入一个 AI 应用创意。
|
||
- 后端生成可审查的结构化草案或变更集。
|
||
- 用户确认后创建项目，并写入项目真相层。
|
||
- 进入 `/command-center` 后能看到真实项目线程、结构化提取、待确认项和项目对象。
|
||
- 用户接受变更后，正式对象、审批记录、证据链同步更新。
|
||
- 至少一个任务能生成 Prompt Package，并进入 Execution Bridge。
|
||
- Execution Bridge 能消费真实 dev-sync summary 或 progress event。
|
||
- 发布/反馈页能消费至少一类真实 release validation / feedback / revenue / compliance 数据。
|
||
|
||
### 2.2 暂不推进的方向
|
||
|
||
下一阶段暂不推进：
|
||
|
||
- 完整财务系统。
|
||
- 完整合规平台。
|
||
- 企业组织树和复杂权限矩阵。
|
||
- 多项目 portfolio。
|
||
- 应用市场、投融资、孵化生态。
|
||
- 前台多 agent 选择器。
|
||
- 与产品主链无关的后台治理页扩展。
|
||
|
||
这些都不是当前瓶颈。
|
||
|
||
## 3. 推荐推进顺序
|
||
|
||
### 3.0 功能原型一致性治理
|
||
|
||
任何 PMFlow 核心功能在继续出图、重画、实现或新开线程接续前，必须先确认是否已有 canonical 功能契约。若已有契约，后续只能在该契约下新增状态、补充局部区域或做明确版本迭代，不能把同一功能重新设计成另一套页面。
|
||
|
||
功能契约至少包含：
|
||
|
||
- 功能定位
|
||
- 页面/状态列表
|
||
- 固定导航壳
|
||
- 核心对象模型
|
||
- 状态标签体系
|
||
- 用户动作
|
||
- AI 动作
|
||
- 系统状态
|
||
- 移动端规则
|
||
- 不可随意改变的部分
|
||
- 可扩展的部分
|
||
|
||
确认流程：
|
||
|
||
1. 先列出本轮涉及的功能清单。
|
||
2. 每次只提交一个功能契约给用户确认。
|
||
3. 用户确认后，才把该功能契约写入本文档或对应产品真源。
|
||
4. 后续原型图、实现、验收都以已确认契约为准。
|
||
5. 如需重构，必须先说明旧版是什么、新版改什么、迁移影响是什么，并得到明确确认。
|
||
|
||
当前需要逐个确认的功能清单：
|
||
|
||
- 新项目启动台
|
||
- 个人空间首页
|
||
- 项目指挥台
|
||
- 本轮结构化提取
|
||
- 决策与待确认
|
||
- 项目记忆
|
||
- 移动端底部导航
|
||
- 项目切换器
|
||
- 项目工作台
|
||
- 开发执行联动
|
||
- 发布与增长
|
||
- 团队协作
|
||
|
||
### Phase A：产品合同收口
|
||
|
||
目标：
|
||
|
||
把 `pmflow-os` 本地类型、现有 SSTC/semantic facts/ai_project_control 后端对象和 V1 蓝图对象对齐。
|
||
|
||
范围：
|
||
|
||
- 梳理 `ProjectThread / ChangeSet / ChangeItem / Evidence / Approval / ProjectMemory / ExecutionRun` 的后端合同。
|
||
- 明确哪些对象复用现有表，哪些需要新表或投影表。
|
||
- 明确 `frontend/src/features/pmflow-os/types.ts` 如何映射到 API response。
|
||
- 明确哪些接口走已有 `sstc_api` / `dev_sync`，哪些需要新增 `pmflow_os_api`。
|
||
|
||
产物：
|
||
|
||
- API/Schema 设计说明或直接 Pydantic schema。
|
||
- 更新 `docs/architecture/CODE_REFERENCE_INDEX.md`。
|
||
- 如新增表，必须 Alembic migration。
|
||
|
||
验收：
|
||
|
||
- 能回答“前端每一个本地对象从哪个后端字段来，写回到哪里去”。
|
||
- 不能再出现前端原型对象和后端业务对象各讲各话。
|
||
|
||
### Phase B：Project Launch 真实创建链
|
||
|
||
目标：
|
||
|
||
把新项目启动台从本地状态机接到真实项目创建/草案确认主链。
|
||
|
||
范围：
|
||
|
||
- `/project-launch` 意图输入接真实 API。
|
||
- AI 结构化结果必须产出可审查草案，而不是直接静默创建。
|
||
- 用户确认后创建项目，并跳转真实 `/command-center`。
|
||
- 创建结果必须写入项目真相层初始对象：Idea、Requirement、Decision、Risk、Task 或等价 SSTC 对象。
|
||
|
||
验收：
|
||
|
||
- 真实接口创建项目。
|
||
- 失败时显式失败，不用 mock 冒充成功。
|
||
- 创建成功后进入真实项目上下文。
|
||
- 项目创建前移动端仍不展示正式底部导航。
|
||
|
||
### Phase C：Change Review 与 Project Memory 写入
|
||
|
||
目标：
|
||
|
||
让对话/结构化提取生成的 ChangeSet 能被接受、修改、暂缓，并写入正式项目对象和证据链。
|
||
|
||
当前拆分：
|
||
|
||
- C1：真实 Change Review 数据底座与审查状态机，已实现 `ChangeSet / ChangeItem / Approval / EvidenceLink` 表和 `accept / edit / defer`，但不 commit。
|
||
- C2：提交入库，把已接受/已编辑 ChangeItem 写入 `truth_nodes / tasks / semantic_facts` 并完成高风险 approval gate。
|
||
|
||
范围：
|
||
|
||
- `StructuredExtractionPage` 接真实提取结果。
|
||
- `ChangeReviewPage` 接真实 ChangeSet。
|
||
- 接受/修改/暂缓动作调用后端。
|
||
- C2 写入后 `ProjectMemoryPage / WorkGraphPage / TeamFeed` 能读到最新对象。
|
||
|
||
验收：
|
||
|
||
- ChangeSet 有 Evidence。
|
||
- 高风险变更需要 Approval。
|
||
- C1 接受后只进入 `accepted / edited / deferred` 审查状态，不进入 Project Memory。
|
||
- C2 commit 后对象状态从 proposed/draft 进入 confirmed 或对应正式状态。
|
||
- 暂缓后不进入项目真相层，但仍留审计。
|
||
|
||
### Phase D：Execution Bridge 真实开发同步
|
||
|
||
目标：
|
||
|
||
让 PMFlow 真正连接开发执行，而不是只展示执行概念。
|
||
|
||
范围：
|
||
|
||
- `ExecutionBridgePage` 消费 `devSyncApi`。
|
||
- 任务能生成 Prompt Package。
|
||
- 能绑定 repo 或展示 GitHub App 安装状态。
|
||
- 能创建或读取 ProgressEvent。
|
||
- 能把 PR/commit/test 信息回写到任务和 Team Feed。
|
||
|
||
验收：
|
||
|
||
- 至少一个真实任务能进入执行桥。
|
||
- 能看到真实 Prompt Package 或 dev task。
|
||
- 能看到真实 progress event。
|
||
- 任务状态能随回写变化。
|
||
|
||
### Phase E：Release / Growth 轻量闭环
|
||
|
||
目标：
|
||
|
||
上线后反馈进入下一轮迭代，不停在“开发完成”。
|
||
|
||
范围：
|
||
|
||
- `ReleaseGrowthPage` 消费 release validation。
|
||
- 支持 feedback ingest。
|
||
- 支持 revenue event 或基础 ROI snapshot。
|
||
- 支持 compliance check 的轻量门禁。
|
||
- 反馈能生成 IterationRecommendation 或下一轮 ChangeSet。
|
||
|
||
验收：
|
||
|
||
- 发布前有门禁。
|
||
- 发布后有反馈/收入/成本/合规至少一类真实信号。
|
||
- 信号能回流为下一轮建议，不只是展示图表。
|
||
|
||
### Phase F：Team-ready 最小闭环
|
||
|
||
目标：
|
||
|
||
不做重型团队管理，但补齐小团队围绕项目真相层协作的最小能力。
|
||
|
||
范围：
|
||
|
||
- 成员归属。
|
||
- 角色收件箱 Role Inbox。
|
||
- Team Feed。
|
||
- Decision Desk 或高风险变更多人审查。
|
||
- Agent Workforce 的只读可见化。
|
||
|
||
验收：
|
||
|
||
- 不同角色看到不同待处理项。
|
||
- 高风险 ChangeSet 能指定 reviewer/owner。
|
||
- Team Feed 展示 AI 提取、人工确认、执行回写、测试/发布变化。
|
||
|
||
## 4. 单次任务范围标准
|
||
|
||
每次 Codex 执行产品推进任务，必须控制为一个“可闭环增量”，不要跨太多面。
|
||
|
||
### 4.1 默认范围
|
||
|
||
一次任务最多覆盖：
|
||
|
||
- 一个产品表面：如 Project Launch / Change Review / Execution Bridge。
|
||
- 一个后端合同或服务切片。
|
||
- 一个前端接入切片。
|
||
- 对应测试。
|
||
- 对应文档进度回写。
|
||
|
||
如果预计改动超过 5 个核心文件或超过约 200 行业务代码，必须先拆子任务，除非是同一根因的缺陷修复。
|
||
|
||
### 4.2 推荐任务模板
|
||
|
||
每次新任务开始前，先给自己明确：
|
||
|
||
- 本次要推进的 Phase。
|
||
- 本次要打通的用户路径。
|
||
- 涉及的前端入口。
|
||
- 涉及的后端 API / service / model。
|
||
- 本次不处理的边界。
|
||
- 最小验证命令。
|
||
- 完成后要更新的进度文档。
|
||
|
||
### 4.3 禁止范围漂移
|
||
|
||
产品推进任务里禁止顺手做：
|
||
|
||
- 无关视觉重构。
|
||
- 无关后台治理页扩展。
|
||
- 无关权限体系大改。
|
||
- 无关 AI prompt 大改。
|
||
- 无关模型路由策略调整。
|
||
- 无关文案大清洗。
|
||
|
||
除非这些问题直接阻断本次用户路径。
|
||
|
||
### 4.4 Codex 并行推进协议
|
||
|
||
PMFlow 允许多个 Codex 线程并行推进。产品上可以按“大模块 lane”长期并行，例如主流程、空间、个人中心，但实际执行单位仍必须是明确的 `Packet`。不能只用“做空间”“做个人中心”“做主流程”这类模糊大模块直接开工；每个模块 lane 都必须拆成带 `write_scope` 的 Packet。没有 `write_scope` 的任务不允许并行执行。
|
||
|
||
每个并行 `Packet` 开始前必须声明：
|
||
|
||
- `packet_id`
|
||
- `phase`
|
||
- `owner_thread`
|
||
- `base_ref`
|
||
- `read_scope`
|
||
- `write_scope`
|
||
- `forbidden_paths`
|
||
- `shared_files`
|
||
- `depends_on`
|
||
- `merge_after`
|
||
- `verification`
|
||
- `docs_to_sync`
|
||
|
||
并行硬规则：
|
||
|
||
- 只有 `write_scope` 不重叠的 Packet 才允许并行。
|
||
- 任意两个 Packet 若同时需要改 `router / schema / migration / shared API client / shared store / CLAUDE.md / CODE_REFERENCE_INDEX.md`，必须串行。
|
||
- 每轮并行最多保留一个 `contract / migration / router owner`；其它线程只能消费该 owner 已定义的稳定接口。
|
||
- 并行线程不得在自己的 `write_scope` 外做“顺手修复”；发现阻塞问题时，只记录到 integration notes 或新建后续 Packet。
|
||
- 同一批并行开发必须指定一个 `integration owner`，负责最终合并共享文件、跑集成验证和更新进度台账。
|
||
|
||
### 4.4.1 大模块并行治理
|
||
|
||
大模块并行的目标是让不同产品表面长期同时推进，但不让它们抢同一批共享文件、共享状态和共享合同。
|
||
|
||
大模块 lane 可以长期存在；Packet 必须短生命周期。lane owner 负责该产品表面的连续性，Packet owner 负责一次可验证增量。一个 lane 同一时间可以只有一个活跃 Packet，也可以拆成同 lane 内串行小 Packet；不同 lane 只有在 `write_scope` 不重叠时才允许并行。
|
||
|
||
大模块并行必须遵守以下规则：
|
||
|
||
- 先由 `Shell / Integration owner` 冻结公共壳、路由、导航、Provider、共享 API client、共享文档归属。
|
||
- `Main Flow / Space / Account Settings` 等模块线程只能写自己 lane 的 owned files。
|
||
- 任一模块需要改共享文件，必须先把该修改拆给 `Shell / Integration owner`，不能在模块 Packet 里顺手改。
|
||
- 模块之间只能通过稳定合同交互：URL、route params、只读 summary API、事件/待确认摘要、用户偏好 API；禁止跨模块直接 import 对方 store 内部实现。
|
||
- Space 只能聚合和跳转，不直接写 Project Memory、ChangeSet commit、Execution Bridge 回写。
|
||
- Account Settings 只能处理用户资料、偏好、通知和账户壳，不直接改项目主链、权限核心或 AI 路由。
|
||
- Main Flow 可以继续推进 PMFlow OS 主链，但不得顺手重做 Space 首页或个人中心。
|
||
- 每批大模块并行仍必须有一个 integration owner 统一执行 `Parallel Integration Gate`。
|
||
|
||
共享高冲突文件默认只归 `Shell / Integration owner`：
|
||
|
||
- `frontend/src/router/index.tsx`
|
||
- `frontend/src/main.tsx`
|
||
- `frontend/src/lib/api.ts` 或其它共享 API base
|
||
- `frontend/src/features/pmflow-os/components/PMFlowOsFrame.tsx`
|
||
- `frontend/src/features/pmflow-os/components/MobileBottomNav.tsx`
|
||
- `backend/app/api/router.py`
|
||
- `backend/app/models/__init__.py`
|
||
- `backend/alembic/versions/*`
|
||
- `CLAUDE.md`
|
||
- `docs/PMFLOW_PRODUCT_DELIVERY_STANDARD.md`
|
||
- `docs/architecture/CODE_REFERENCE_INDEX.md`
|
||
- `docs/architecture/ARCHITECTURE_INVENTORY.md`
|
||
- `docs/architecture/API_CONTRACTS.md`
|
||
|
||
### 4.4.2 当前大模块 lane 划分
|
||
|
||
#### Lane 0：Shell / Integration
|
||
|
||
定位：
|
||
|
||
- 冻结公共应用壳、路由、移动底部导航、Provider、共享文档和合并顺序。
|
||
- 不承担具体产品表面的大量 UI 实现。
|
||
|
||
默认写范围：
|
||
|
||
- `frontend/src/router/index.tsx`
|
||
- `frontend/src/main.tsx`
|
||
- `frontend/src/features/pmflow-os/components/PMFlowOsFrame.tsx`
|
||
- `frontend/src/features/pmflow-os/components/MobileBottomNav.tsx`
|
||
- `CLAUDE.md`
|
||
- `docs/PMFLOW_PRODUCT_DELIVERY_STANDARD.md`
|
||
- `docs/architecture/CODE_REFERENCE_INDEX.md`
|
||
- `docs/architecture/ARCHITECTURE_INVENTORY.md`
|
||
- `docs/architecture/API_CONTRACTS.md`
|
||
|
||
#### Lane 1：Main Flow / PMFlow OS 主流程
|
||
|
||
定位：
|
||
|
||
- 打穿 V1 主链：Project Thread -> Structured Extraction -> Change Review -> Project Memory -> Execution Bridge -> Release/Growth。
|
||
- 这是产品核心闭环，优先级最高。
|
||
|
||
默认写范围：
|
||
|
||
- `frontend/src/features/pmflow-os/`
|
||
- `frontend/src/api/pmflowOs.ts`
|
||
- `backend/app/api/pmflow_os_api/`
|
||
- `backend/app/services/pmflow_os_projection_service.py`
|
||
- `backend/app/services/pmflow_change_review_service.py`
|
||
- `backend/app/schemas/pmflow_os.py`
|
||
- `backend/tests/test_pmflow_*`
|
||
|
||
默认禁止：
|
||
|
||
- 不改 `frontend/src/features/personal-space/`。
|
||
- 不改 Account Settings 域。
|
||
- 不改共享 router / nav / docs，除非本 Packet 就是 integration owner。
|
||
|
||
#### Lane 2：Space / 个人空间入口
|
||
|
||
定位：
|
||
|
||
- 建设 `/space` 作为所有项目、想法、草案、待确认和 AI 推进状态的上层入口。
|
||
- Space 是聚合与导航层，不是 Project Memory 或 ChangeSet 的写入层。
|
||
|
||
默认写范围：
|
||
|
||
- `frontend/src/features/personal-space/`
|
||
- `frontend/src/pages/PersonalSpacePage.tsx`
|
||
- `frontend/src/api/space.ts`（如需要）
|
||
- `backend/app/api/space_api/`（如需要，只读聚合优先）
|
||
- Space 相关测试
|
||
|
||
默认禁止：
|
||
|
||
- 不改 `frontend/src/features/pmflow-os/store.tsx`。
|
||
- 不改 PMFlow OS 主流程页面。
|
||
- 不改 ChangeSet commit / Execution Bridge 写回服务。
|
||
- 不直接写项目真相层；写动作必须跳转或调用已有主流程合同。
|
||
|
||
#### Lane 3：Account Settings / 个人中心与设置
|
||
|
||
定位：
|
||
|
||
- 建设 `/me`、个人资料、偏好、通知、AI 使用偏好和账户操作。
|
||
- Account Settings 是用户偏好层，不是项目协作层或权限核心重构。
|
||
|
||
默认写范围：
|
||
|
||
- `frontend/src/features/account-settings/`（建议新建）
|
||
- `frontend/src/features/pmflow-os/pages/AccountPage.tsx`
|
||
- `frontend/src/features/pmflow-os/components/AccountControls.tsx`
|
||
- `frontend/src/api/accountSettings.ts`（如需要）
|
||
- `backend/app/api/account_settings_api/`（如需要）
|
||
- Account Settings 相关测试
|
||
|
||
默认禁止：
|
||
|
||
- 不改 Project Memory / ChangeSet / Execution Bridge。
|
||
- 不改 Space 聚合。
|
||
- 不改 OAuth/JWT/auth core；如必须改，另开安全 Packet。
|
||
- 不改共享 router / nav，除非由 integration owner 串行处理。
|
||
|
||
### 4.4.3 P0 公共壳冻结结果
|
||
|
||
截至 2026-04-26，P0 对当前共享壳的冻结结论如下。后续 `main-flow-phase-d-execution / space-v1-workbench / account-settings-v1` 必须按此边界开工。
|
||
|
||
#### Route 归属
|
||
|
||
| 路由 | 当前实现 | 归属 lane | 后续规则 |
|
||
| --- | --- | --- | --- |
|
||
| `/space` | 已存在，`PersonalSpaceStandalone` -> `frontend/src/pages/PersonalSpacePage.tsx` -> `frontend/src/features/personal-space/` | Space | Space lane 可改页面域；不得在本 lane 改 router，除非通过 Shell owner |
|
||
| `/project-launch` | 已存在，`ProjectLaunchStandalone` -> `frontend/src/pages/ProjectLaunchPage.tsx` -> `frontend/src/features/project-launch/` | Project Launch / Shell owned route | 非本批三线程主任务；后续只作为 Space 和 Main Flow 的入口/跳转消费 |
|
||
| `/pmflow-os` | 已存在，alias 到 `CommandCenterStandalone`，支持 `?projectId=<id>` 真实项目上下文 | Main Flow | Main Flow lane 消费；route alias 归 Shell owner |
|
||
| `/command-center` | 已存在，standalone 与 AuthGuard children 双入口均存在 | Main Flow | 当前作为免登录产品预览壳和项目指挥台入口；后续是否收敛双入口由 Shell owner 单独处理 |
|
||
| `/change-review` | 已存在，移动底导“待确认”指向此路由 | Main Flow | Space 只能聚合摘要并跳转，不直接写 Change Review 状态 |
|
||
| `/execution-bridge` | 已存在于 AuthGuard children | Main Flow | Phase D 真实接入由 Main Flow lane 负责 |
|
||
| `/release-growth` | 已存在于 AuthGuard children | Main Flow | Phase E 再推进，不进入本批 Space / Account scope |
|
||
| `/me` | 已存在，standalone 与 AuthGuard children 双入口均存在，页面来自 `frontend/src/features/pmflow-os/pages/AccountPage.tsx` | Account Settings | Account lane 可改 AccountPage/AccountControls；route 归 Shell owner |
|
||
| `/settings` | 当前未实现 | Account Settings reserved | 不在 P0 临时新增；由 `account-settings-v1` 提出需要后，Shell owner 串行加 route |
|
||
|
||
#### Provider 与共享状态
|
||
|
||
- `frontend/src/main.tsx` 当前全局挂载 `QueryClientProvider -> PMFlowOsProvider -> ToastProvider -> RouterProvider`。
|
||
- `PMFlowOsProvider` 当前是全局 provider，但业务所有权归 `Main Flow / PMFlow OS`。
|
||
- Space 和 Account Settings 可读取稳定公开 hook/API，但禁止直接改 `frontend/src/features/pmflow-os/store.tsx` 或依赖其内部 mutation 细节。
|
||
- 如果 Space 需要“待确认 / AI 正在推进 / 最近项目”摘要，优先新增 `frontend/src/api/space.ts` 与只读后端聚合接口，不能从 PMFlow OS store 内部反向拼。
|
||
- 如果 Account Settings 需要用户偏好，优先新增 `frontend/src/api/accountSettings.ts` 与独立后端接口，不能把个人偏好塞进 PMFlow OS truth store。
|
||
|
||
#### 导航与移动底部栏
|
||
|
||
- `frontend/src/features/pmflow-os/components/MobileBottomNav.tsx` 是正式应用壳唯一移动底部导航实现。
|
||
- 当前五项固定为：`空间 -> /space`、`指挥台 -> /command-center`、`待确认 -> /change-review`、`动态 -> /command-center`、`我的 -> /me`。
|
||
- Space / Main Flow / Account 三个模块线程不得各自改底部导航。任何导航项新增、重命名、跳转变更，都必须交给 Shell owner。
|
||
- 当前 `动态` 暂时回到 `/command-center`，属于保留占位；后续如实现 `/activity` 或动态页，必须单独开 Shell / Integration Packet。
|
||
|
||
#### 下一批开工条件
|
||
|
||
- `main-flow-phase-d-execution` 可以直接开工，前提是不改 router、MobileBottomNav、PMFlowOsFrame 的导航归属。
|
||
- `space-v1-workbench` 可以直接开工，前提是只改 `personal-space` owned files 和可选 `space.ts / space_api`，不碰 PMFlow OS store。
|
||
- `account-settings-v1` 可以直接开工，前提是不新增 `/settings` route；如确需 `/settings`，先把 route 需求写入 integration notes，再由 Shell owner 添加。
|
||
|
||
### 4.5 V1 Productized Loop 默认并行切片
|
||
|
||
V1 主链并行开发默认按 lane 切分：
|
||
|
||
- `Contract Lane`：API / Schema / DB migration / 核心对象合同，只允许单线程拥有。
|
||
- `Backend Lane`：service + route + tests，必须依赖 Contract Lane。
|
||
- `Frontend Lane`：`frontend/src/api/` + React Query / store 接入，必须依赖稳定 API 合同。
|
||
- `UI Lane`：页面展示、状态、交互、响应式，只能改功能域内组件，不能改 API 合同。
|
||
- `Docs/Test Lane`：回归补充、文档同步、验证矩阵，可以和非共享代码并行，但最终由 integration owner 统一收口。
|
||
|
||
默认合并顺序：
|
||
|
||
1. Contract / migration
|
||
2. Backend service / API
|
||
3. Frontend API / store
|
||
4. UI / page
|
||
5. Docs / test / integration
|
||
|
||
### 4.6 Phase C2 并行试点拆包
|
||
|
||
当前下一阶段 `Phase C2：ChangeSet commit 入库` 默认拆成四个 Packet：
|
||
|
||
- `C2-contract`
|
||
- Lane：`Contract Lane`
|
||
- 目标：定义 commit API、写入规则、高风险 approval gate、响应合同和失败语义。
|
||
- 写范围：PMFlow OS 产品合同、API 合同、schema 草案或对应设计文档。
|
||
- 退出条件：后端和前端实现线程不需要再自行决定 API shape。
|
||
- `C2-backend`
|
||
- Lane：`Backend Lane`
|
||
- 目标：实现 ChangeSet commit service、route、transaction、权限边界和后端测试。
|
||
- 依赖：`C2-contract`
|
||
- 写范围：`backend/app/api/pmflow_os_api/`、`backend/app/services/pmflow_change_review_service.py`、`backend/app/schemas/pmflow_os.py`、相关 tests；若需要 migration，必须回到 Contract Lane 串行处理。
|
||
- `C2-frontend`
|
||
- Lane：`Frontend Lane`
|
||
- 目标：接入 commit API，更新 `pmflow-os` store、Change Review 状态和错误/成功反馈。
|
||
- 依赖：`C2-contract`
|
||
- 写范围：`frontend/src/api/pmflowOs.ts`、`frontend/src/features/pmflow-os/store.tsx`、`ChangeReviewPage` 或 owned 组件测试。
|
||
- `C2-docs-verification`
|
||
- Lane：`Docs/Test Lane`
|
||
- 目标：同步产品推进台账、代码索引、API 合同、架构库存，并执行最终集成验证。
|
||
- 依赖：`C2-backend`、`C2-frontend`
|
||
- 写范围：文档和验证记录；共享文档由 integration owner 统一合并。
|
||
|
||
`C2-contract` 必须先完成；`C2-backend` 和 `C2-frontend` 只能在合同稳定后有限并行；最终必须由一个 integration owner 统一收口。
|
||
|
||
### 4.7 分支与 worktree 协议
|
||
|
||
并行开发默认使用独立分支和独立 worktree：
|
||
|
||
- 分支命名：`codex/<packet_id>`。
|
||
- 每个 Packet 必须记录启动时的 `base_ref`。
|
||
- 每个并行线程优先使用独立 git worktree，避免同一工作区文件互相覆盖。
|
||
- 合并前必须检查当前分支是否落后主集成分支。
|
||
- 合并前必须检查 `git diff --name-only`，确认没有写出 `write_scope`。
|
||
- 触碰共享高冲突文件时，必须交由 integration owner 合并。
|
||
|
||
### 4.8 Packet commit 协议
|
||
|
||
并行开发不是“每改一行就提交”，也不是“多个 Packet 混在一个长期分支里攒”。默认规则：
|
||
|
||
- 一个 Packet 对应一个短生命周期分支：`codex/<packet_id>`。
|
||
- Packet 完成、验证通过、文档同步完成后，必须形成至少一个可审查 commit。
|
||
- Codex 必须自行执行 commit gate 判定，不把“该不该提交”默认丢给用户判断。
|
||
- 复杂 Packet 可以在同一分支内做多个 checkpoint commit，但每个 commit 都必须是逻辑完整切片，不能提交半成品、失败验证或越界改动。
|
||
- 不允许把多个不同 Packet 的实现混进同一个 commit。
|
||
- 不允许在旧 Packet 分支上继续做新 Packet；新 Packet 必须从最新 integration base 或明确依赖分支重新开 `codex/<new_packet_id>`。
|
||
- 如果新 Packet 依赖尚未合并的 `Contract Lane`，优先等待合同分支合入；确需提前开发时，必须以该合同分支作为 `base_ref`，并在任务包里写明 `depends_on / merge_after`。
|
||
- integration owner 只合并通过 `Parallel Integration Gate` 的 Packet commit；未验证 commit 只能留在 Packet 分支内，不进入主集成分支。
|
||
- 每个 Packet 合并后，旧 Packet 分支只用于追溯，不再追加新业务改动。
|
||
|
||
commit gate 判定：
|
||
|
||
- `auto_commit`：满足全部条件时，Codex 应自行提交当前 Packet 分支。
|
||
- 当前改动全部在 `write_scope` 内。
|
||
- 没有混入用户或其它线程的未归属改动。
|
||
- 触碰共享高冲突文件时，当前线程就是该文件的 owner 或 integration owner。
|
||
- 必要验证已通过；若验证无法执行，原因和影响已经写入结果与任务包。
|
||
- 必要文档已同步。
|
||
- commit 内容只包含当前 Packet。
|
||
- `hold_no_commit`：满足任一条件时，Codex 不得提交，只能报告阻塞和证据。
|
||
- 验证失败且失败与本 Packet 相关。
|
||
- `git diff --name-only` 发现越界改动。
|
||
- 工作区混入无法归属的用户改动或其它线程改动。
|
||
- 发现 migration 多 head、合同不稳定、API shape 未定或依赖 Packet 未完成。
|
||
- 需要破坏性删除、重置、强推、覆盖、批量迁移等高风险操作。
|
||
- `ask_before_commit`：满足任一条件时，Codex 必须先说明事实并等用户拍板。
|
||
- 用户明确要求只改不提交。
|
||
- commit 需要包含共享高冲突文件，但当前线程不是 owner。
|
||
- 验证无法运行且该 Packet 风险较高。
|
||
- 需要把多个 Packet 的改动临时合在一个 commit 里。
|
||
- 需要提交历史遗留脏改动才能让当前 Packet 自洽。
|
||
|
||
推荐 commit 节奏：
|
||
|
||
1. `contract` Packet：合同文档、schema 草案或 migration 约束稳定后 commit。
|
||
2. `backend` Packet：后端实现和对应测试通过后 commit。
|
||
3. `frontend` Packet：API/store/UI 接入和对应前端验证通过后 commit。
|
||
4. `docs-verification` Packet：文档同步、最终验证记录和进度台账完成后 commit。
|
||
|
||
### 4.9 Parallel Integration Gate
|
||
|
||
每批并行开发结束后，integration owner 必须执行集成验收：
|
||
|
||
- `git diff --name-only` 检查每个 Packet 是否越界。
|
||
- 后端改动：`python -m py_compile` + 相关 `pytest`。
|
||
- 前端改动：`npm run typecheck` + `npm run build` + 相关 focused tests。
|
||
- migration 改动：`alembic heads` 必须单 head；必要时执行 `alembic upgrade head`。
|
||
- 文档：产品推进台账、代码索引、API 合同、架构库存同步完成。
|
||
- 若后端或 migration 改动已经落地，按项目规则执行热部署/重启；若不能执行，必须明确写阻塞原因。
|
||
|
||
## 5. 每次完成后的进度回写标准
|
||
|
||
后续 Codex 每完成一个 PMFlow 产品推进任务，必须自己更新进度，不需要用户额外提醒。
|
||
|
||
### 5.1 必须更新的地方
|
||
|
||
每次完成后至少更新：
|
||
|
||
1. 本文档 `## 8. 进度台账`
|
||
- 新增一条记录。
|
||
- 写清完成内容、影响范围、验证结果、下一步建议。
|
||
2. 如果新增/删除/重命名文件或入口：
|
||
- 更新 `CLAUDE.md`
|
||
- 更新 `docs/architecture/ARCHITECTURE_INVENTORY.md`
|
||
- 更新 `docs/architecture/CODE_REFERENCE_INDEX.md`
|
||
3. 如果新增/修改 API/Schema：
|
||
- 更新 `docs/architecture/CODE_REFERENCE_INDEX.md`
|
||
- 必要时更新 `docs/architecture/API_CONTRACTS.md`
|
||
4. 如果新增运行边界、禁止项或系统行为约束：
|
||
- 更新 `docs/architecture/RUNTIME_GUARDRAILS.md`
|
||
5. 如果改变产品战略或不可偏离项：
|
||
- 更新 `docs/PMFLOW_PRODUCT_BLUEPRINT.md`
|
||
- 更新 `USER.md`
|
||
|
||
### 5.2 进度台账记录格式
|
||
|
||
每条记录必须包含：
|
||
|
||
- 日期。
|
||
- Phase。
|
||
- 状态：`done / partial / blocked`。
|
||
- 完成内容。
|
||
- 涉及文件。
|
||
- 验证命令和结果。
|
||
- 未完成或风险。
|
||
- 下一步建议。
|
||
|
||
### 5.3 什么时候不用更新蓝图
|
||
|
||
普通实现、接 API、修 bug、补测试，不更新产品蓝图。
|
||
|
||
只有以下情况才更新蓝图：
|
||
|
||
- 用户改变产品定位。
|
||
- V1 范围改变。
|
||
- 团队方向改变。
|
||
- 新增/删除核心产品表面。
|
||
- 改变不可偏离项。
|
||
|
||
## 6. 新开线程接续标准
|
||
|
||
任何新 Codex 线程，如果用户要求继续 PMFlow 产品推进，必须先读：
|
||
|
||
1. `USER.md`
|
||
2. `docs/PMFLOW_PRODUCT_BLUEPRINT.md`
|
||
3. `docs/PMFLOW_PRODUCT_DELIVERY_STANDARD.md`
|
||
4. `CLAUDE.md`
|
||
5. `docs/architecture/CODE_REFERENCE_INDEX.md`
|
||
|
||
然后再查当前目标相关代码。
|
||
|
||
新线程不得：
|
||
|
||
- 重新讨论 PMFlow 是否应该做对话驱动 OS。
|
||
- 重新建议变成传统项目管理工具。
|
||
- 重新发散大而全模块。
|
||
- 忽略 `## 8. 进度台账` 直接从头设计。
|
||
- 把本地原型当成真实后端闭环。
|
||
- 把已有后端 `ai_project_control / dev_sync / sstc model_control` 忽略后重造一套。
|
||
|
||
## 7. 当前下一步推荐任务
|
||
|
||
当前最建议下一步执行：
|
||
|
||
**Phase D.2：Execution Bridge 执行交接合同。**
|
||
|
||
原因：
|
||
|
||
- A3 已完成真实只读投影，Phase B 已完成真实 Project Launch 创建链。
|
||
- Phase C1 已把项目内消息、结构化候选、审查动作和证据链落到真实表。
|
||
- C2-contract 已锁定 commit API、原子提交规则、响应合同和失败语义。
|
||
- C2-backend 已按合同实现 atomic commit route/service/schema/tests，C2-frontend 已把真实模式写入接到 commit API。
|
||
- Phase D 已把 `ExecutionBridgePage` 切到 `execution-summary` 与 dev-sync 真实数据。
|
||
- 当前缺口是执行桥只读展示已经成立，但还不能把一个已确认任务推进到可追踪的真实执行交接；下一步应实现 `POST /pmflow-os/projects/{project_id}/execution-handoffs`，生成/复用 PromptPackage、绑定 task/repo/runtime，并创建 `handoff_created` progress event 起点。
|
||
|
||
### 7.1 下一批大模块并行建议
|
||
|
||
P0 公共壳冻结已完成，下一批可以进入 `Batch P1` 三模块并行；最终仍必须由 `Batch P2` integration owner 收口。
|
||
|
||
#### Batch P0：Shell / Route / Shared Contract Freeze
|
||
|
||
状态：`done`
|
||
|
||
冻结结论：
|
||
|
||
- 当前已存在 `/space`、`/project-launch`、`/pmflow-os`、`/command-center`、`/change-review`、`/execution-bridge`、`/release-growth`、`/me`。
|
||
- `/settings` 当前未实现，标记为 Account Settings reserved route；不得由业务模块线程顺手新增。
|
||
- 移动端底部导航已固定为 `空间 / 指挥台 / 待确认 / 动态 / 我的`，实现归 `Shell / Integration owner`。
|
||
- `frontend/src/main.tsx` 全局 provider 顺序已确认：`QueryClientProvider -> PMFlowOsProvider -> ToastProvider -> RouterProvider`；后续 provider 变更必须由 Shell owner 串行处理。
|
||
|
||
#### Batch P1：三模块并行
|
||
|
||
在 P0 完成后，可以同时开三个长期 lane 的首个 Packet。
|
||
|
||
##### Main Flow Packet：`main-flow-phase-d2-execution-handoff-contract`
|
||
|
||
目标：
|
||
|
||
- 继续执行 Phase D.2，把 Execution Bridge 从 execution dashboard 推进为 execution command bridge。
|
||
- 新增 `POST /pmflow-os/projects/{project_id}/execution-handoffs`，允许对已确认任务发起真实执行交接。
|
||
- 后端生成/复用 `PromptPackage`，记录 `runtime_target / repo_binding_id / task_id`，并创建 `ProgressEvent(event_type='handoff_created')`。
|
||
- 前端真实模式下“发起执行交接”调用真实 API，成功后 refetch `execution-summary / truth-state`；无 task/repo/prompt 时必须显示明确 warning 和下一步。
|
||
|
||
默认写范围：
|
||
|
||
- `frontend/src/features/pmflow-os/`
|
||
- `frontend/src/api/pmflowOs.ts`
|
||
- `backend/app/api/pmflow_os_api/`
|
||
- `backend/app/services/pmflow_os_projection_service.py`
|
||
- `backend/app/schemas/pmflow_os.py`
|
||
- 相关 tests
|
||
|
||
##### Space Packet：`space-v1-workbench`
|
||
|
||
目标：
|
||
|
||
- 把 `/space` 推进成个人工作面聚合页。
|
||
- 展示继续推进、待我确认、AI 正在推进、暂存想法、草案箱、最近项目。
|
||
- 优先只读聚合；点击项目进入 `/pmflow-os?projectId=...`，不直接写项目真相层。
|
||
|
||
默认写范围：
|
||
|
||
- `frontend/src/features/personal-space/`
|
||
- `frontend/src/pages/PersonalSpacePage.tsx`
|
||
- `frontend/src/api/space.ts`（如需要）
|
||
- `backend/app/api/space_api/`（如需要，只读聚合优先）
|
||
- Space 相关测试
|
||
|
||
##### Account Settings Packet：`account-settings-v1`
|
||
|
||
目标：
|
||
|
||
- 建设 `/me` 和个人设置首版。
|
||
- 覆盖个人资料、AI 偏好、通知偏好、账户操作和移动端 bottom sheet。
|
||
- 不改 OAuth/JWT/auth core，不改项目主链。
|
||
|
||
默认写范围：
|
||
|
||
- `frontend/src/features/account-settings/`（建议新建）
|
||
- `frontend/src/features/pmflow-os/pages/AccountPage.tsx`
|
||
- `frontend/src/features/pmflow-os/components/AccountControls.tsx`
|
||
- `frontend/src/api/accountSettings.ts`（如需要）
|
||
- `backend/app/api/account_settings_api/`（如需要）
|
||
- Account Settings 相关测试
|
||
|
||
#### Batch P2：Integration Owner 收口
|
||
|
||
目标：
|
||
|
||
- 检查三个 Packet 的 `git diff --name-only` 是否越界。
|
||
- 统一处理 router、bottom nav、shared docs、API index 的冲突。
|
||
- 跑后端/前端最小集成验证。
|
||
- 更新 `## 8. 进度台账`、`CODE_REFERENCE_INDEX.md`、`ARCHITECTURE_INVENTORY.md` 与必要的 `CLAUDE.md`。
|
||
|
||
## 8. 进度台账
|
||
|
||
### 2026-04-26 / Space V1 Workbench Hardening / implemented
|
||
|
||
完成内容：
|
||
|
||
- 将 `/space` 收敛为只读个人工作面聚合入口，继续覆盖 `继续推进 / 待我确认 / AI 正在推进 / 暂存想法 / 草案箱 / 最近项目`，不写 Project Memory、ChangeSet 状态或 Execution Bridge event。
|
||
- `frontend/src/api/space.ts` 作为 Space read model wrapper，仅消费项目摘要、PMFlow OS `truth-state` 与 `execution-summary`；项目主动作仍进入 `/pmflow-os?projectId=<id>`。
|
||
- 待确认项只读取 ChangeSet / approvals 摘要，点击进入稳定主流程 `/change-review?projectId=<id>&changeSetId=<id>`，不直接执行 accept/edit/defer/commit。
|
||
- 暂存想法合同已显式建模为 `savedIdeas`；当前后端只读聚合未接入时返回空数组并展示 warning，禁止用 mock/demo 数据冒充真实想法。
|
||
- 移动端继续使用 Space 独立单手路径，补齐最近项目区块，不把桌面多栏布局压缩到手机。
|
||
- 补充 `PersonalSpacePage.test.tsx` focused 回归，锁定六个 Space 区块与“暂存想法未接入不冒充真实数据”的空态。
|
||
|
||
涉及文件：
|
||
|
||
- `frontend/src/api/space.ts`
|
||
- `frontend/src/features/personal-space/PersonalSpacePage.tsx`
|
||
- `frontend/src/features/personal-space/PersonalSpacePage.test.tsx`
|
||
- `frontend/src/features/personal-space/components/SpaceChrome.tsx`
|
||
- `docs/architecture/CODE_REFERENCE_INDEX.md`
|
||
- `docs/architecture/ARCHITECTURE_INVENTORY.md`
|
||
- `docs/PMFLOW_PRODUCT_DELIVERY_STANDARD.md`
|
||
|
||
验证：
|
||
|
||
- `cd frontend && npm run test -- src/features/personal-space/PersonalSpacePage.test.tsx` 通过。
|
||
- `cd frontend && npm run typecheck` 未通过，阻塞来自 Main Flow 越界文件 `frontend/src/features/pmflow-os/pages/ExecutionBridgePage.tsx:21` 的既有 `import type` 语法错误，本 Space 包不跨线修。
|
||
- `cd frontend && npm run build` 未通过，同样阻塞于 `frontend/src/features/pmflow-os/pages/ExecutionBridgePage.tsx:21`，未进入 Vite build 阶段。
|
||
|
||
剩余缺口：
|
||
|
||
- 暂存想法真实只读聚合后端合同尚未实现；当前 Space 明确暴露为空态和 warning，不使用演示数据兜底。
|
||
|
||
### 2026-04-26 / Account Settings V1 / implemented
|
||
|
||
完成内容：
|
||
|
||
- 新增 `frontend/src/api/accountSettings.ts`，定义个人资料、默认语言、AI 回答深度、证据展示偏好和通知偏好前端合同；首版用浏览器本地持久化承接设置保存，不写 PMFlow OS truth store。
|
||
- 新增 `frontend/src/features/account-settings/AccountSettingsPanel.tsx`，承接 `/me` 桌面设置页与移动端分组列表 + bottom sheet。
|
||
- 将 `/me` 的 `AccountPage.tsx` 改为薄入口，继续复用 `AccountControls.tsx` 的退出登录 bottom sheet，不改 router、MobileBottomNav、PMFlow OS store 或 OAuth/JWT/auth core。
|
||
- 通知偏好已覆盖 `待确认 / 执行回写 / 发布门禁 / 失败提醒`，每类支持总开关、桌面提醒和邮件摘要。
|
||
- 保存状态已收口为 `仅本机暂存 / 已保存到当前账号 / 保存失败` 三态；当前 V1 只做本机暂存，不假装云端账号保存。
|
||
- 补充 `frontend/src/features/account-settings/accountSettings.test.ts`，锁定默认设置和持久化行为。
|
||
|
||
涉及文件：
|
||
|
||
- `frontend/src/api/accountSettings.ts`
|
||
- `frontend/src/features/account-settings/AccountSettingsPanel.tsx`
|
||
- `frontend/src/features/account-settings/accountSettings.test.ts`
|
||
- `frontend/src/features/pmflow-os/pages/AccountPage.tsx`
|
||
- `CLAUDE.md`
|
||
- `docs/architecture/ARCHITECTURE_INVENTORY.md`
|
||
- `docs/architecture/CODE_REFERENCE_INDEX.md`
|
||
- `docs/PMFLOW_PRODUCT_DELIVERY_STANDARD.md`
|
||
|
||
验证：
|
||
|
||
- `npm run test -- src/features/account-settings/accountSettings.test.ts` 通过：`3 passed`。
|
||
- `npm run typecheck` 通过。
|
||
- `npm run build` 通过；Vite 仍输出既有 manual chunk circular warning，未阻断构建。
|
||
- Playwright 本地浏览器检查通过：`http://localhost:5186/me` 桌面与 390px 移动视口均可渲染，移动端通知偏好 bottom sheet 可打开。
|
||
|
||
未完成或风险：
|
||
|
||
- 当前 Account Settings V1 是前端合同 + 本地持久化，后续如要跨设备同步，需要独立新增 `backend/app/api/account_settings_api/` 和持久化表，不能塞入 auth core 或 PMFlow OS truth store。
|
||
|
||
### 2026-04-26 / P0 Shell Module Boundaries / done
|
||
|
||
完成内容：
|
||
|
||
- 核对当前公共壳真实落点：`frontend/src/router/index.tsx`、`frontend/src/main.tsx`、`MobileBottomNav.tsx`、`PMFlowOsFrame.tsx`。
|
||
- 冻结大模块 route 归属：`/space` 归 Space，`/project-launch` 作为启动层入口，`/pmflow-os / /command-center / /change-review / /execution-bridge / /release-growth` 归 Main Flow，`/me` 归 Account Settings。
|
||
- 明确 `/settings` 当前未实现，仅作为 Account Settings reserved route；后续如需新增，必须由 Shell / Integration owner 串行处理。
|
||
- 冻结全局 provider 归属：`QueryClientProvider -> PMFlowOsProvider -> ToastProvider -> RouterProvider`，Space / Account 不得直接改 PMFlow OS store 内部 mutation。
|
||
- 冻结移动端底部导航归属：唯一实现为 `MobileBottomNav.tsx`，固定 `空间 / 指挥台 / 待确认 / 动态 / 我的`；其中 `动态` 仍是 `/command-center` 占位，后续要做 `/activity` 必须单独开 Shell Packet。
|
||
- 同步修正 `ARCHITECTURE_INVENTORY.md` 中 C1/C2 commit 的旧描述，明确 C2 backend/frontend commit 已完成。
|
||
|
||
涉及文件：
|
||
|
||
- `docs/PMFLOW_PRODUCT_DELIVERY_STANDARD.md`
|
||
- `docs/architecture/CODE_REFERENCE_INDEX.md`
|
||
- `docs/architecture/ARCHITECTURE_INVENTORY.md`
|
||
- `CLAUDE.md`
|
||
|
||
验证：
|
||
|
||
- `git diff --name-only` 已确认本轮只改文档与约束文件，未改前端共享壳代码。
|
||
- 本轮未修改前端代码，因此未运行 `npm run typecheck`。
|
||
|
||
未完成或风险：
|
||
|
||
- `/settings` 尚未实现；`account-settings-v1` 如需要该入口，必须先把 route 需求交给 Shell / Integration owner。
|
||
- `动态` 底部导航仍指向 `/command-center`，后续如做动态页需独立 Packet。
|
||
|
||
下一步建议：
|
||
|
||
- 并行启动 `main-flow-phase-d-execution`、`space-v1-workbench`、`account-settings-v1`；三个 Packet 均不得改 router/nav/provider/shared docs，最终由 integration owner 收口。
|
||
|
||
### 2026-04-26 / Phase D.2 - Execution Handoff Contract / done
|
||
|
||
完成内容：
|
||
|
||
- 新增 `POST /pmflow-os/projects/{project_id}/execution-handoffs` 后端入口，复用 PMFlow OS 项目成员/OWNER/REVIEWER 权限边界。
|
||
- `PMFlowOSProjectionService.create_execution_handoff` 校验 task/project/tenant 边界，校验可选 active repo binding；无 repo 时允许创建 handoff draft 并保留 repo warning。
|
||
- 对任务复用 active `PromptPackage`；没有 active package 时，从真实 `Project / Task / Project Memory / RepoBinding` 生成 deterministic `PromptPackage(package_kind='execution_handoff')`，不使用 demo 文案。
|
||
- 创建 `ProgressEvent(event_type='handoff_created', source='pmflow_os')` 作为执行起点，payload 记录 `runtime_target / prompt_package_id / repo_binding_id / boundary`。
|
||
- 前端 `ExecutionBridgePage` 在真实模式展示“发起执行交接”按钮，调用 `createPMFlowExecutionHandoff` 后 refetch `truth-state / execution-summary`；demo 模式仍只走本地推进。
|
||
- 无 active task、无 repo、无 prompt package 时继续显示明确 empty/warning 和下一步，不回退假数据。
|
||
|
||
涉及文件：
|
||
|
||
- `backend/app/api/pmflow_os_api/__init__.py`
|
||
- `backend/app/services/pmflow_os_projection_service.py`
|
||
- `backend/app/schemas/pmflow_os.py`
|
||
- `backend/tests/test_pmflow_os_projection_api.py`
|
||
- `frontend/src/api/pmflowOs.ts`
|
||
- `frontend/src/features/pmflow-os/store.tsx`
|
||
- `frontend/src/features/pmflow-os/store.api.test.tsx`
|
||
- `frontend/src/features/pmflow-os/pages/ExecutionBridgePage.tsx`
|
||
- `frontend/src/features/pmflow-os/components/ExecutionBridgeCards.tsx`
|
||
- `docs/architecture/PMFLOW_OS_PRODUCT_CONTRACT.md`
|
||
- `docs/architecture/CODE_REFERENCE_INDEX.md`
|
||
- `docs/architecture/ARCHITECTURE_INVENTORY.md`
|
||
- `docs/PMFLOW_PRODUCT_DELIVERY_STANDARD.md`
|
||
|
||
验证：
|
||
|
||
- `PYTHONPATH=backend /opt/homebrew/bin/python3.11 -m py_compile backend/app/api/pmflow_os_api/__init__.py backend/app/services/pmflow_os_projection_service.py backend/app/schemas/pmflow_os.py` 通过。
|
||
- `PYTHONPATH=backend /opt/homebrew/bin/python3.11 -m pytest backend/tests/test_pmflow_os_projection_api.py -q` 通过：`9 passed`。
|
||
- `cd frontend && npm run test -- src/features/pmflow-os` 通过。
|
||
- `cd frontend && npm run typecheck` 通过。
|
||
- `cd frontend && npm run build` 通过；Vite 仍输出既有 manual chunk circular warning，未阻断构建。
|
||
|
||
未完成或风险：
|
||
|
||
- D.2 只创建 handoff 合同、PromptPackage 与 progress event 起点，不直接执行本机命令；真实命令执行仍必须通过 Local Bridge、Codex、GitHub agent 或兼容 MCP host。
|
||
- 当前未新增 migration，沿用既有 `PromptPackage / RepoBinding / ProgressEvent`。
|
||
|
||
下一步建议：
|
||
|
||
- 进入 D.3：补 Dev Sync 写回闭环，把 Codex/Local Bridge/GitHub agent 的执行结果回写为 branch/commit/PR/test progress event，并把任务状态/证据链投影回 `truth-state`。
|
||
|
||
### 2026-04-26 / Big Module Parallel Governance / done
|
||
|
||
完成内容：
|
||
|
||
- 将大模块并行治理写入产品推进标准：允许 `Main Flow / Space / Account Settings` 作为长期模块 lane 并行，但实际执行仍必须拆成带 `write_scope` 的短生命周期 Packet。
|
||
- 明确 `Shell / Integration owner` 负责共享路由、导航、Provider、共享 API base、共享文档和合并顺序。
|
||
- 定义当前四条 lane：`Shell / Integration`、`Main Flow / PMFlow OS 主流程`、`Space / 个人空间入口`、`Account Settings / 个人中心与设置`。
|
||
- 明确每条 lane 的默认写范围、默认禁止范围和跨模块交互边界。
|
||
- 更新下一批推荐任务：先执行 `P0-shell-module-boundaries`，再并行推进 `main-flow-phase-d-execution / space-v1-workbench / account-settings-v1`，最后由 integration owner 收口。
|
||
|
||
涉及文件：
|
||
|
||
- `docs/PMFLOW_PRODUCT_DELIVERY_STANDARD.md`
|
||
- `docs/architecture/TASK_BRIEF_TEMPLATE.md`
|
||
- `AGENTS.md`
|
||
- `CLAUDE.md`
|
||
|
||
验证：
|
||
|
||
- 文档静态检查完成；本轮只更新治理文档和任务模板，未改代码、API、Schema 或 migration，未运行编译/单测。
|
||
|
||
未完成或风险：
|
||
|
||
- 该记录是大模块治理规则落盘；具体公共壳真实路由和 provider 核对已由后续 `P0 Shell Module Boundaries` 完成。
|
||
|
||
下一步建议：
|
||
|
||
- 后续按 P0 冻结结果同时分派 `main-flow-phase-d-execution`、`space-v1-workbench`、`account-settings-v1` 三个大模块 Packet。
|
||
|
||
### 2026-04-26 / Phase C2 Frontend - ChangeSet Commit Wiring / done
|
||
|
||
完成内容：
|
||
|
||
- 在 `frontend/src/api/pmflowOs.ts` 增加 `commitPMFlowChangeSet`，调用 `POST /pmflow-os/change-sets/{change_set_id}/commit`，默认 `mode=atomic`。
|
||
- 扩展 PMFlow OS 前端类型，允许后端投影返回 `ChangeSet.status=committed/partially_committed` 与 `ChangeItem.status=committed/skipped`。
|
||
- 将 `PMFlowOsProvider.promoteAcceptedToGraph` 的真实模式接到后端 commit API，commit 后 refetch `truth-state`；demo 模式继续使用本地 mutation。
|
||
- 将 `ChangeReviewPage` 的真实模式主按钮从“下一阶段开放”改为“确认写入项目记忆”，不再用前端本地状态冒充正式写入。
|
||
- 补充 API 模式 store 测试，确认 `promoteAcceptedToGraph("11")` 会调用 `commitPMFlowChangeSet("11", { mode: "atomic", ... })`，且不会本地写入 `requirements`。
|
||
|
||
涉及文件：
|
||
|
||
- `frontend/src/api/pmflowOs.ts`
|
||
- `frontend/src/features/pmflow-os/types.ts`
|
||
- `frontend/src/features/pmflow-os/store.tsx`
|
||
- `frontend/src/features/pmflow-os/store.api.test.tsx`
|
||
- `frontend/src/features/pmflow-os/pages/ChangeReviewPage.tsx`
|
||
- `frontend/src/features/pmflow-os/components/ProjectStructuredLoop.tsx`
|
||
- `frontend/src/features/pmflow-os/components/chrome.tsx`
|
||
- `docs/architecture/PMFLOW_OS_PRODUCT_CONTRACT.md`
|
||
- `docs/architecture/CODE_REFERENCE_INDEX.md`
|
||
- `docs/PMFLOW_PRODUCT_DELIVERY_STANDARD.md`
|
||
|
||
验证：
|
||
|
||
- `npm run test -- src/features/pmflow-os/store.api.test.tsx` 通过：`3 passed`。
|
||
- `npm run test -- src/features/pmflow-os` 通过：`4 passed`。
|
||
- `npm run typecheck` 通过。
|
||
- `npm run build` 通过；Vite 仍输出既有 manual chunk circular warning，未阻断构建。
|
||
|
||
未完成或风险：
|
||
|
||
- 前端真实 commit 依赖后端已完成审查状态；若仍存在 `pending_review` item，后端会按合同显式返回 `changeset_not_reviewed`。
|
||
- Release / ModelDecision / MetricSignal commit 仍按 C2 合同暂缓或 fail-closed。
|
||
- 当前为本地开发工作区验证，未执行部署环境热重启。
|
||
|
||
下一步建议：
|
||
|
||
- 执行 Phase D：把 `ExecutionBridgePage` 切到 `GET /pmflow-os/projects/{project_id}/execution-summary` 与 dev-sync 真实数据，继续保留 demo fallback。
|
||
|
||
### 2026-04-26 / Phase C2 Backend - ChangeSet Atomic Commit / done
|
||
|
||
完成内容：
|
||
|
||
- 新增 `POST /pmflow-os/change-sets/{change_set_id}/commit` 后端入口，复用项目成员/OWNER/REVIEWER 权限边界，统一响应包络。
|
||
- 在 `PMFlowChangeReviewService` 实现 atomic commit：只处理 `accepted / edited` 项，默认提交全部 eligible items；存在未审项时阻断全量 commit；任一写入失败则回滚整个事务。
|
||
- 将 `Requirement / Decision / Risk` 写入 `truth_nodes`，将 `Task` 写入 `truth_nodes(node_type='task') + tasks`，并为 truth node/task 写入 `semantic_facts` seed。
|
||
- 补齐高风险 approval gate：`risk_level=high` 必须存在同 item 的 approved/edited approval 与 evidence，否则返回 `409 high_risk_approval_required` 且不写正式对象。
|
||
- 将 `PMFlowChangeSet / PMFlowChangeItem` 序列化扩展到 `committed / partially_committed / skipped` 状态，避免 commit 后投影被误映射为 deferred。
|
||
- 将 `backend/app/api/__init__.py` 改为轻量包入口，避免 focused API 测试导入单个模块时拉起 Feishu/MCP 等可选依赖。
|
||
|
||
涉及文件：
|
||
|
||
- `backend/app/api/__init__.py`
|
||
- `backend/app/api/pmflow_os_api/__init__.py`
|
||
- `backend/app/schemas/pmflow_os.py`
|
||
- `backend/app/services/pmflow_change_review_service.py`
|
||
- `backend/tests/test_pmflow_change_review_api.py`
|
||
- `docs/architecture/PMFLOW_OS_PRODUCT_CONTRACT.md`
|
||
- `docs/architecture/CODE_REFERENCE_INDEX.md`
|
||
- `docs/PMFLOW_PRODUCT_DELIVERY_STANDARD.md`
|
||
|
||
验证：
|
||
|
||
- `/opt/homebrew/bin/python3.11 -m py_compile backend/app/api/__init__.py backend/app/api/pmflow_os_api/__init__.py backend/app/services/pmflow_change_review_service.py backend/app/schemas/pmflow_os.py backend/tests/test_pmflow_change_review_api.py` 通过。
|
||
- `/opt/homebrew/bin/python3.11 -m pytest tests/test_pmflow_change_review_api.py -q` 通过：`6 passed`。
|
||
- `/opt/homebrew/bin/python3.11 -m pytest tests/test_pmflow_change_review_api.py tests/test_pmflow_os_projection_api.py tests/test_pmflow_launch_api.py -q` 通过：`18 passed`。
|
||
|
||
未完成或风险：
|
||
|
||
- C2 V1 暂不支持 `ModelDecision / MetricSignal` commit；按合同必须 fail-closed。
|
||
- 本地仍有未提交删除痕迹，未纳入本次提交。
|
||
- 当前为本地开发工作区验证，未执行部署环境热重启。
|
||
|
||
下一步建议：
|
||
|
||
- 已执行 `C2-frontend`；下一步进入 Phase D Execution Bridge 真实数据接入。
|
||
|
||
### 2026-04-26 / G0 Freeze + C2 Contract / done
|
||
|
||
完成内容：
|
||
|
||
- 将当前非删除工作区成果直接 checkpoint 到 `master`，形成 `b52428f docs: codify PMFlow product delivery governance` 与 `e04ea4d chore: checkpoint current PMFlow workspace` 两个提交；删除痕迹未提交，避免未确认地固化旧截图、表格、tunnel 脚本和临时文件删除。
|
||
- 收口 Phase C2 commit 合同：`POST /pmflow-os/change-sets/{change_set_id}/commit` 的请求体、权限、原子提交模式、响应结构、错误码、高风险 approval gate、C2 V1 objectType 白名单和 ProjectTruthState 投影规则。
|
||
- 明确 C2 V1 默认 `mode=atomic`，任一 eligible item 写入失败时整个 commit 回滚，禁止半写入 Project Memory。
|
||
- 明确 C2 必须实现 `Requirement / Decision / Task / Risk`；`Release` 可选；`ModelDecision / MetricSignal` 暂缓并必须 fail-closed。
|
||
|
||
涉及文件：
|
||
|
||
- `docs/architecture/PMFLOW_OS_PRODUCT_CONTRACT.md`
|
||
- `docs/architecture/API_CONTRACTS.md`
|
||
- `docs/PMFLOW_PRODUCT_DELIVERY_STANDARD.md`
|
||
|
||
验证：
|
||
|
||
- `git status --short --branch` 已确认 checkpoint 后仅剩未提交删除痕迹。
|
||
- `git diff --cached --name-status` 阶段检查未发现删除项被纳入 checkpoint。
|
||
- 本轮 C2-contract 只改合同文档，未新增代码、Schema 或 migration，未运行编译/单测。
|
||
|
||
未完成或风险：
|
||
|
||
- 工作区仍有未提交删除痕迹，需用户单独确认是否删除或恢复。
|
||
- C2 后端 route/service/schema 与前端 API/store 尚未实现。
|
||
|
||
下一步建议：
|
||
|
||
- 执行 `C2-backend`：实现 atomic ChangeSet commit service、route、权限、事务、高风险 gate 与后端测试。
|
||
- 合同稳定后并行执行 `C2-frontend`：接入 commit API，替换真实模式下的 demo-only `promoteAcceptedToGraph`。
|
||
|
||
### 2026-04-26 / Parallel Delivery Governance / done
|
||
|
||
完成内容：
|
||
|
||
- 新增 Codex 并行推进协议，明确并行单位必须是带 `read_scope / write_scope / forbidden_paths / shared_files / base_ref / merge_after` 的 Packet。
|
||
- 建立 V1 Productized Loop 默认并行 lane：`Contract / Backend / Frontend / UI / Docs-Test`，并固定合同、后端、前端、UI、文档集成的合并顺序。
|
||
- 将下一阶段 Phase C2 拆成 `C2-contract / C2-backend / C2-frontend / C2-docs-verification` 四个可分派 Packet，明确依赖和写范围。
|
||
- 新增分支、worktree、Packet commit 与 commit gate 协议：并行线程默认使用 `codex/<packet_id>` 分支、记录 `base_ref`、优先独立 worktree；Packet 完成后由 Codex 自行判定 `auto_commit / hold_no_commit / ask_before_commit`，通过验证后形成可审查 commit，新 Packet 从最新 integration base 或明确依赖分支重新开分支。
|
||
- 新增 `Parallel Integration Gate`，要求 integration owner 检查越界 diff、后端/前端/migration 验证、文档同步和热部署说明。
|
||
|
||
涉及文件：
|
||
|
||
- `docs/PMFLOW_PRODUCT_DELIVERY_STANDARD.md`
|
||
- `docs/architecture/TASK_BRIEF_TEMPLATE.md`
|
||
- `AGENTS.md`
|
||
- `CLAUDE.md`
|
||
- `docs/architecture/ARCHITECTURE_INVENTORY.md`
|
||
|
||
验证：
|
||
|
||
- 文档静态检查通过：新增协议覆盖并行前置条件、Packet 模板、write scope / forbidden paths、共享文件锁、branch / worktree / base ref、Packet commit、commit gate、merge order、integration gate。
|
||
- 本轮只改治理文档，未新增代码、API、Schema 或 migration，未运行编译/单测。
|
||
|
||
未完成或风险：
|
||
|
||
- 当前仓库仍是大面积脏工作区；正式启动多线程并行前，需要先冻结当前改动归属，避免历史脏状态被误判为新冲突。
|
||
|
||
下一步建议：
|
||
|
||
- 以 `C2-contract` 作为第一条并行治理试点 Packet，先锁定 ChangeSet commit 合同，再分派后端和前端线程。
|
||
|
||
### 2026-04-25 / Phase A - PMFlow OS Product Contract / done
|
||
|
||
完成内容：
|
||
|
||
- 新增 PMFlow OS 产品合同，明确 `ProjectTruthState / Thread / Message / ChangeSet / ChangeItem / Evidence / Approval / Requirement / Decision / Task / Risk / ModelDecision / TestRun / Release / MetricSignal / ExecutionContext / TeamFeed` 的前后端映射。
|
||
- 明确复用边界：正式项目对象优先复用 `truth_nodes / tasks / semantic_facts`，AI 应用控制面复用 `ai_project_control` 与 SSTC model_control，执行桥复用 `dev_sync / prompt_packages / progress_events`。
|
||
- 明确建议新增但本轮不建表的 PMFlow OS 专属合同对象：`pmflow_threads / pmflow_thread_messages / pmflow_change_sets / pmflow_change_items / pmflow_approvals / pmflow_evidence_links`。
|
||
- 定义 PMFlow OS API 草案：`truth-state / messages / extractions / change-set detail / accept / edit / defer / commit / execution-summary`。
|
||
- 明确 `accept/edit/defer` 只改变审查状态，`commit` 才写入 `truth_nodes / tasks / semantic_facts` 等正式对象。
|
||
|
||
涉及文件：
|
||
|
||
- `docs/architecture/PMFLOW_OS_PRODUCT_CONTRACT.md`
|
||
- `docs/architecture/CODE_REFERENCE_INDEX.md`
|
||
- `docs/architecture/ARCHITECTURE_INVENTORY.md`
|
||
- `CLAUDE.md`
|
||
- `docs/PMFLOW_PRODUCT_DELIVERY_STANDARD.md`
|
||
|
||
验证：
|
||
|
||
- 静态检查引用路径与核心对象完成。
|
||
- 本轮只改文档，未新增代码、API、Schema 或 migration，未运行编译/单测。
|
||
|
||
未完成或风险：
|
||
|
||
- API 尚未实现，数据库 migration 尚未创建。
|
||
- `truth_nodes.node_type` 的历史值需要在后续 projection 实现时做白名单映射。
|
||
- `ChangeSet / Approval / EvidenceLink / Thread` 仍需后续实现真实表与服务。
|
||
|
||
下一步建议：
|
||
|
||
- 执行 A3 最小真实读路径：新增只读 `pmflow_os_api` projection，先实现 `GET /pmflow-os/projects/{project_id}/truth-state` 与 `GET /pmflow-os/projects/{project_id}/execution-summary`。
|
||
|
||
### 2026-04-25 / A3 - PMFlow OS 最小真实读路径 / done
|
||
|
||
完成内容：
|
||
|
||
- 新增只读后端入口 `backend/app/api/pmflow_os_api/`，注册 `GET /pmflow-os/projects/{project_id}/truth-state` 与 `GET /pmflow-os/projects/{project_id}/execution-summary`，统一返回 `{code,message,data}`。
|
||
- 新增 `backend/app/services/pmflow_os_projection_service.py` 与 `backend/app/schemas/pmflow_os.py`，把 `ProjectTruthState` 投影接到真实后端对象：`Requirement / Decision / Risk / Release` 来自 `truth_nodes`，`Task` 来自 `tasks`，`Project Memory` 来自 `truth_nodes + semantic_facts`，`ExecutionContext` 来自 `dev-sync summary + prompt_packages + progress_events + repo/task code link`。
|
||
- `Thread / ChangeSet / ChangeItem / Approval / EvidenceLink` 本轮没有稳定表，不用 mock 冒充；接口返回空集合并通过 `projectionWarnings` 明确说明。
|
||
- 新增前端 API `frontend/src/api/pmflowOs.ts`，封装 `getPMFlowTruthState(projectId)` 与 `getPMFlowExecutionSummary(projectId)`。
|
||
- `frontend/src/features/pmflow-os/store.tsx` 现支持 `?projectId=<id>` 通过 React Query 读取真实 `truth-state`；只有显式 `?demo=1` 或 `?dataSource=demo` 才启用本地 mock 演示动作。真实 API 失败时显示错误/空态，不静默 fallback 成 mock 成功。
|
||
- `ProjectMemoryPage` 在真实模式下展示后端 `projectMemory.truthNodeFacts / semanticFacts`，不再把前端 mock 当作项目记忆来源。
|
||
|
||
涉及文件：
|
||
|
||
- `backend/app/api/pmflow_os_api/__init__.py`
|
||
- `backend/app/services/pmflow_os_projection_service.py`
|
||
- `backend/app/schemas/pmflow_os.py`
|
||
- `backend/app/api/router.py`
|
||
- `backend/tests/test_pmflow_os_projection_api.py`
|
||
- `frontend/src/api/pmflowOs.ts`
|
||
- `frontend/src/features/pmflow-os/store.tsx`
|
||
- `frontend/src/features/pmflow-os/components/PMFlowOsFrame.tsx`
|
||
- `frontend/src/features/pmflow-os/pages/CommandCenterPage.tsx`
|
||
- `frontend/src/features/pmflow-os/pages/ProjectMemoryPage.tsx`
|
||
- `docs/architecture/CODE_REFERENCE_INDEX.md`
|
||
- `docs/architecture/ARCHITECTURE_INVENTORY.md`
|
||
- `docs/PMFLOW_PRODUCT_DELIVERY_STANDARD.md`
|
||
- `CLAUDE.md`
|
||
|
||
验证：
|
||
|
||
- 静态路径检查完成。
|
||
- 后端：`python -m py_compile`（Python 3.12 runtime）通过。
|
||
- 后端：`pytest tests/test_pmflow_os_projection_api.py -q` 通过，覆盖空项目 truth-state、Project Memory projection、tasks projection、execution-summary 空态、tenant/project 权限边界。
|
||
- 后端 router import smoke：`from app.api.router import api_router` 通过。
|
||
- 前端：`npm run typecheck` 通过。
|
||
- 前端：`npm run build` 通过。
|
||
|
||
剩余缺口：
|
||
|
||
- 本轮不新增 migration，因此 `Thread / ChangeSet / ChangeItem / Approval / EvidenceLink` 仍为空集合或 warning；后续 Phase C 再补真实表与 mutation。
|
||
- `WorkGraph / ExecutionBridge / ReleaseGrowth` 仍有部分静态展示区，A3 只保证 truth store 与 Project Memory 真实读取入口，不做 UI 重画和完整页面数据替换。
|
||
- 后端代码已改，但当前是在本地开发工作区执行验证，未连接运行中的部署服务；热部署/重启需要在实际部署环境执行。
|
||
|
||
### 2026-04-25 / Phase B - Project Launch 真实创建链 / done
|
||
|
||
完成内容：
|
||
|
||
- 新增 Phase B 专用启动链表 migration `backend/alembic/versions/20260425_add_pmflow_launch_tables.py`，只创建 `pmflow_launch_drafts / pmflow_threads / pmflow_thread_messages`；本轮未创建 `pmflow_change_sets / pmflow_change_items / pmflow_approvals / pmflow_evidence_links`。
|
||
- 新增后端启动链入口 `backend/app/api/pmflow_launch_api/`，注册 `POST /pmflow-launch/drafts` 与 `POST /pmflow-launch/drafts/{draft_id}/confirm`，统一返回 `{code,message,data}`。
|
||
- 新增 `backend/app/services/pmflow_launch_service.py` 与 `backend/app/schemas/pmflow_launch.py`：草案生成调用 `llm_service.generate_structured_object(function_name="pmflow_launch_draft_v1")` 并显式传 `routing_meta`；结构化失败返回明确错误或 warnings，不用模板句冒充成功。
|
||
- confirm 在同一事务内锁定草案并创建 `Project / UserProject / PMFlowThread / PMFlowThreadMessage / truth_nodes / tasks / semantic_facts seed / OperationLog`，随后更新草案 `status=confirmed` 与 `confirmed_project_id`；重复 confirm 幂等返回同一 `project_id`，不重复写正式对象。
|
||
- `truth_nodes.content` 与任务 payload 写入 `launch_draft_id / thread_id / thread_message_id / source=pmflow_launch_confirmed_draft / confidence / evidence`，确保初始 Project Memory 与 Task 能追溯到启动草案和首条用户输入。
|
||
- A3 `truth-state` projection 已更新为优先读取 `pmflow_threads` 默认启动线程与 `pmflow_thread_messages`，Project Memory 仍只来自 `truth_nodes + semantic_facts`，不从 launch draft 直接拼。
|
||
- 新增前端 API `frontend/src/api/pmflowLaunch.ts`，封装 `createPMFlowLaunchDraft` 与 `confirmPMFlowLaunchDraft`。
|
||
- `frontend/src/features/project-launch/useProjectLaunchState.ts` 默认走真实 API；只有显式 `?demo=1` 或 `?dataSource=demo` 才启用本地演示状态机。draft/confirm 失败进入明确失败态，不静默跳 mock 成功态。
|
||
- 新增 `/pmflow-os` route alias，创建成功后使用后端返回的 `/pmflow-os?projectId=<id>` 进入 A3 真实读路径。
|
||
|
||
涉及文件：
|
||
|
||
- `backend/alembic/versions/20260425_add_pmflow_launch_tables.py`
|
||
- `backend/app/models/pmflow_launch.py`
|
||
- `backend/app/api/pmflow_launch_api/__init__.py`
|
||
- `backend/app/services/pmflow_launch_service.py`
|
||
- `backend/app/schemas/pmflow_launch.py`
|
||
- `backend/app/services/pmflow_os_projection_service.py`
|
||
- `backend/app/config/ai_prompts_catalog/part_scenes_06.py`
|
||
- `backend/app/services/llm_service/shared_part_01.py`
|
||
- `backend/tests/test_pmflow_launch_api.py`
|
||
- `backend/tests/test_pmflow_os_projection_api.py`
|
||
- `frontend/src/api/pmflowLaunch.ts`
|
||
- `frontend/src/features/project-launch/useProjectLaunchState.ts`
|
||
- `frontend/src/features/project-launch/useProjectLaunchState.test.ts`
|
||
- `frontend/src/router/index.tsx`
|
||
- `docs/architecture/CODE_REFERENCE_INDEX.md`
|
||
- `docs/architecture/ARCHITECTURE_INVENTORY.md`
|
||
- `docs/PMFLOW_PRODUCT_DELIVERY_STANDARD.md`
|
||
- `CLAUDE.md`
|
||
|
||
验证：
|
||
|
||
- 后端：`python -m py_compile` 新增后端模块、migration、router、prompt 聚合文件通过。
|
||
- 后端：`pytest tests/test_pmflow_launch_api.py tests/test_pmflow_os_projection_api.py -q` 通过，覆盖 draft 成功、结构化字段缺失、warnings、confirm 创建 Project/thread/message/truth_nodes/tasks、truth-state 回读、幂等、过期/跨 tenant/跨 user、rollback。
|
||
- Alembic：`alembic upgrade head` 在本地开发 PostgreSQL 成功从 `20260421_finalize_v1_productization` 升级到 `20260425_add_pmflow_launch_tables`。
|
||
- 前端：`npm run test -- src/features/project-launch/useProjectLaunchState.test.ts` 通过，覆盖真实 draft API、draft 失败、confirm 成功、confirm 失败不进成功态、显式 demo 分支。
|
||
- 前端：`npm run typecheck` 通过。
|
||
- 前端：`npm run build` 通过。
|
||
|
||
剩余缺口：
|
||
|
||
- Phase B 只覆盖首次 Project Launch 创建链；项目内后续 ChangeSet / ChangeItem / Approval / EvidenceLink 审查系统仍留给 Phase C。
|
||
- 初始 `semantic_facts` seed 仅写用户确认后的 project-level facts；完整异步抽取和治理仍复用既有 semantic facts 管线。
|
||
|
||
### 2026-04-26 / Phase C1 - PMFlow Change Review 数据底座与审查状态机 / done
|
||
|
||
完成内容：
|
||
|
||
- 新增 C1 review 表 migration `backend/alembic/versions/20260426_add_pmflow_change_review_tables.py`，只创建 `pmflow_change_sets / pmflow_change_items / pmflow_approvals / pmflow_evidence_links`；未新增 commit 或 Phase C2 表。
|
||
- 新增模型 `backend/app/models/pmflow_change_review.py`，所有表包含 `tenant_id`，并按 `tenant_id + project_id` 查询；`ChangeItem` 归属 `ChangeSet`，`Approval` 记录 `accept / edit / defer` 的 before/after，`EvidenceLink` 可引用 thread message。
|
||
- 新增服务 `backend/app/services/pmflow_change_review_service.py`，实现项目内消息、`proposed_items` extraction、ChangeSet detail、accept/edit/defer 审查状态机；老项目无真实线程时仅允许 `default` 或 `thread-project-{project_id}` 懒创建默认线程。
|
||
- 在 `backend/app/api/pmflow_os_api/` 扩展 `/pmflow-os` API：`POST /projects/{project_id}/threads/{thread_id}/messages`、`POST /projects/{project_id}/extractions`、`GET /projects/{project_id}/change-sets/{change_set_id}`、`POST /change-items/{change_item_id}/accept|edit|defer`，统一响应包络。
|
||
- `PMFlowOSProjectionService` 已投影 `changeSets / changeItems / evidence / approvals`，`activeChangeSetId` 取最近 open ChangeSet，`loopStage` 映射为 `command_idle / extraction_ready / review_open`；Project Memory 仍只来自 `truth_nodes + semantic_facts`。
|
||
- 前端 `frontend/src/api/pmflowOs.ts` 增加 Change Review API wrapper；`frontend/src/features/pmflow-os/store.tsx` 真实模式调用后端 message/extraction/accept/edit/defer，并在成功后 refetch truth-state。真实模式不再本地 promote accepted item，也不假装写入项目记忆；demo 模式仍需显式 `?demo=1` 或 `?dataSource=demo`。
|
||
|
||
涉及文件：
|
||
|
||
- `backend/alembic/versions/20260426_add_pmflow_change_review_tables.py`
|
||
- `backend/app/models/pmflow_change_review.py`
|
||
- `backend/app/services/pmflow_change_review_service.py`
|
||
- `backend/app/api/pmflow_os_api/__init__.py`
|
||
- `backend/app/schemas/pmflow_os.py`
|
||
- `backend/app/services/pmflow_os_projection_service.py`
|
||
- `backend/tests/test_pmflow_change_review_api.py`
|
||
- `backend/tests/test_pmflow_os_projection_api.py`
|
||
- `frontend/src/api/pmflowOs.ts`
|
||
- `frontend/src/features/pmflow-os/store.tsx`
|
||
- `frontend/src/features/pmflow-os/store.api.test.tsx`
|
||
- `frontend/src/features/pmflow-os/pages/ChangeReviewPage.tsx`
|
||
- `frontend/src/features/pmflow-os/components/ProjectStructuredLoop.tsx`
|
||
- `docs/architecture/CODE_REFERENCE_INDEX.md`
|
||
- `docs/architecture/ARCHITECTURE_INVENTORY.md`
|
||
- `docs/architecture/PMFLOW_OS_PRODUCT_CONTRACT.md`
|
||
- `docs/PMFLOW_PRODUCT_DELIVERY_STANDARD.md`
|
||
- `CLAUDE.md`
|
||
|
||
验证：
|
||
|
||
- 后端：`python -m py_compile` 新增后端模型、service、schema、router、migration 通过。
|
||
- 后端：`pytest tests/test_pmflow_change_review_api.py tests/test_pmflow_os_projection_api.py tests/test_pmflow_launch_api.py -q` 通过，覆盖 message 懒创建线程、extraction、change items、evidence link、detail、accept/edit/defer、reviewed 自动推进、权限边界、truth-state 投影，以及 accepted/edited 不进入 Project Memory。
|
||
- Alembic：`alembic heads` 返回 `20260426_add_pmflow_change_review_tables (head)`；`alembic upgrade head` 在本地开发 PostgreSQL 成功从 `20260425_add_pmflow_launch_tables` 升级到 `20260426_add_pmflow_change_review_tables`。
|
||
- 前端：`npm run test -- src/features/pmflow-os` 通过。
|
||
- 前端：`npm run typecheck` 通过。
|
||
- 前端：`npm run build` 通过；Vite 仍提示既有循环 chunk warning，但构建成功。
|
||
|
||
剩余缺口：
|
||
|
||
- C1 不实现 `/commit`，不写 `truth_nodes / tasks / semantic_facts`；accepted/edited 仅代表审查状态，不代表 confirmed Project Memory。
|
||
- `POST /extractions` 本轮只接收 `proposed_items`，不默认调用 LLM 结构化提取；AI extraction 主链留给后续阶段。
|
||
- 高风险 `risk_level=high` 本轮只记录风险等级和 approval，commit gate 留给 C2。
|
||
|
||
下一步建议：
|
||
|
||
- 执行 Phase C2：实现 ChangeSet commit，把 `accepted / edited` ChangeItem 按对象类型写入正式 `truth_nodes / tasks / semantic_facts`，并补齐高风险 approval gate 与部分失败回滚/明细返回。
|
||
|
||
### 2026-04-24 / Product Blueprint / done
|
||
|
||
完成内容：
|
||
|
||
- 整理并落盘 PMFlow 产品蓝图真源。
|
||
- 明确 PMFlow 是“对话驱动的 AI 产品执行操作系统”。
|
||
- 明确 `solo-first, team-ready`、项目真相层、ChangeSet 待确认、Execution Bridge、人机混编团队等不可偏离项。
|
||
|
||
涉及文件：
|
||
|
||
- `docs/PMFLOW_PRODUCT_BLUEPRINT.md`
|
||
- `USER.md`
|
||
- `CLAUDE.md`
|
||
- `docs/architecture/ARCHITECTURE_INVENTORY.md`
|
||
|
||
验证：
|
||
|
||
- 文档新增与引用检查完成。
|
||
- 无代码改动，未运行编译/测试。
|
||
|
||
下一步：
|
||
|
||
- 执行 Phase A：PMFlow OS 产品合同收口。
|
||
|
||
### 2026-04-24 / Delivery Standard / done
|
||
|
||
完成内容：
|
||
|
||
- 建立 PMFlow 产品推进执行标准。
|
||
- 记录当前推进状态、下一阶段方向、Phase A-F 推进顺序、单次任务范围标准和完成后进度回写标准。
|
||
- 明确新开线程必须先读蓝图、执行标准和代码索引，避免重做或漏做。
|
||
|
||
涉及文件：
|
||
|
||
- `docs/PMFLOW_PRODUCT_DELIVERY_STANDARD.md`
|
||
- `USER.md`
|
||
- `CLAUDE.md`
|
||
- `docs/architecture/ARCHITECTURE_INVENTORY.md`
|
||
|
||
验证：
|
||
|
||
- 文档新增与引用检查完成。
|
||
- 无代码改动，未运行编译/测试。
|
||
|
||
下一步：
|
||
|
||
- 从 A1 对象合同映射开始，把前端 `pmflow-os/types.ts` 与后端现有对象逐一对齐。
|