# PRD-20261014-fmode-app-v2

| 字段 | 值 |
|---|---|
| 文档编号 | PRD-20261014-fmode-app-v2 |
| 版本号 | v1.1 |
| 最后更新日期 | 2026-10-14 |
| 状态 | **草案 · 待评审** |
| 本次变更原因 | v1.1:第1轮评审修复(S1 模块清点统一口径 / T8 关联文档补齐) |
| 上游文档 | 《访谈-20261014-现状调研汇总.md》《访谈-20261014-第二轮裁决记录.md》《访谈-20261014-第三轮裁决记录.md》《SPEC-20261014-fmode-app-v2-草案.md》 |
| 规格细节 | FR/AC 明细见 SPEC,**本文档不重复 AC,只定盘子** |

---

## 一、背景与问题

### 1.1 产品现状
`fmode-app`(存量,Angular 19)是一套**能跑通**的双端客户端:用户通过 IM 式会话与「数字生命」(AI Agent)交互,并查看其运行状态与交付成果。六大功能模块齐备,用户动线完整。

### 1.2 但它有三个结构性问题

| 问题 | 量化证据 |
|---|---|
| **① 文档业务逻辑不清晰** | PRD 无 FR/AC 编号,不可验收;PRD 写"金色飞马主题"而代码是蓝紫渐变,**背离且无人察觉**;3 次"视觉重设计"只交任务清单,零设计规范;`docs/README.md` 与 `04-quality/` 实际内容自相矛盾 |
| **② 组件样式未按规范** | ui-kit 采用率 **1.3%**(149 个组件仅用 2 个);组件内联硬编码色值 **321 处**;令牌前缀 **3 套并存**;全局样式 **2079 行** |
| **③ UI 从未经过设计** | 布局尺寸 236/318/340/420px 全硬编码,无从设计推导;视觉方向漂移 3 次(金色飞马 → 微信克隆 → 蓝紫)**从未定稿**;桌面端无媒体查询降级 |

**单一根因:从未产出设计规范,就开始写 UI。**

### 1.3 为什么必须重建而非修补
每修一处 UI 都要对抗 321 处硬编码与 3 套令牌,补丁式修改**无法收敛**。
在「新工程 + 规范底座 + 先设计后编码」的前提下重建,成本低于继续修补。

---

## 二、目标

### 2.1 总目标
把 fmode-app 重建为一套**规范原生**的双端客户端:文档可追溯、界面有设计、代码无脏债。

### 2.2 三个支柱(对应三个问题)

| 支柱 | 做法 | 验证 |
|---|---|---|
| **规范原生工程** | Angular 20.3 + ui-kit 整目录接入 + 单一令牌体系 + Tailwind preflight 正常启用 | ui-kit `ng build` 一次通过(✅ 已验证) |
| **先设计后编码** | 新增**阶段②设计系统**环节:设计令牌定稿 / 组件规范 / 关键页面原型 / 双端布局规范 | 设计规范未定稿**不得进入编码** |
| **文档与代码同步** | 按 rules/11 建立 `docs/` 全链,四向追溯矩阵从第一天维护 | 每条 FR 有 AC 才进开发;"完成"包含文档同步 |

### 2.3 成功标准(用户裁决 7)
> **「功能所有都测试完成」**

具体化为:
1. 7 个功能模块 + **5 项**通用能力**全部通过测试**
2. 单测全绿(`npm test`)
3. 双端全路由冒烟断言通过
4. 规范断言通过(零硬编码色值 / 零 `console.log` / 触达区 ≥44px / 无障碍基线)

---

## 三、范围

### 3.1 范围内

> **口径(评审 S1 修复)**:「7 个功能模块」**不含登录**。登录属跨端通用能力,与"用户可见的业务功能面"不同层。
> 「7 个模块全部通过测试」指下表 7 个;**通用能力另有各自 AC,同样必须通过**。

#### A. 7 个功能模块

| # | 模块 | 桌面路由 | 移动路由 | 主要画像 |
|---|---|---|---|---|
| 1 | 通讯录 | `/desktop/contacts` | `/mobile/contacts` | P1/P2 |
| 2 | 会话 | `/desktop/chat/:id` | `/mobile/chat/:id` | **P1 核心** |
| 3 | 项目 | `/desktop/projects` | `/mobile/projects` | P2 |
| 4 | 事件 | `/desktop/events` | `/mobile/events` | P2/P3 |
| 5 | 工作台 | `/desktop/workbench` | `/mobile/workbench` | **P2/P3 核心** |
| 6 | **任务看板(新增)** | `/desktop/tasks` | `/mobile/tasks` | **P2/P3 核心** |
| 7 | 成果 | `/desktop/deliverables` | `/mobile/deliverables` | **P1 核心** |

#### B. 通用能力(跨模块,不计入 7 模块)

| # | 能力 | 路由 | 说明 |
|---|---|---|---|
| 1 | 入口分流 | `/` | UA + 视口一次性判定 |
| 2 | **登录** | `/login` | 同页双形态;验证码 / Token / 自动 |
| 3 | **移动聚合首页** | `/mobile/home` | 移动落地页(评审 G1 补登) |
| 4 | 数字生命详情 | `/desktop/agent/:id` `/mobile/agent/:id` | |
| 5 | 我的(含端切换) | `/desktop/mine` `/mobile/mine` | |

### 3.2 范围外

- 语音通话(**裁决:暂不实现,作增项保留**)
- 工作群组 / 多人群聊 / 消息线程(**排除**,只做"人-数字生命"一对一会话)
- 自建后端(全部走 fmode 平台云函数)
- 响应式单套布局(延续双端双套)
- 非 Web 端

### 3.3 范围冻结(FR-18)
任何新增功能须走**变更请求**由用户决策。**AI 禁止以"顺手做了"为由增加页面/接口。**

---

## 四、工作方式与交付

### 4.1 阶段顺序(用户裁决 6)
```
阶段① 需求挖掘  →  阶段② 设计系统  →  阶段③ 制作编码  →  阶段④ 交付验收
   文档做好做完         UI 设计            功能完善
```
**阶段门禁不可跳过。**

### 4.2 交付粒度(用户裁决 8)
**逐模块交付验证**:每个模块独立走完「实现 → 测试 → 冒烟 → 交付验证」,在用户处过一遍再进下一个。
**最终 7 个功能模块 + 5 项通用能力全部交付**,不以 MVP 为由砍模块。

**交付顺序**(依据依赖与画像优先级):
```
0 基础设施 → 1 登录 → 2 通讯录 → 3 会话 → 4 成果 → 5 工作台
→ 6 任务看板 → 7 项目 → 8 事件 → 9 详情/我的 → 10 迁移兼容
```
> 任务看板(序 6)有外部依赖:云函数接收端未实现。不可用时**先落空态,禁止伪造数据**,报告阻塞后跳序 7,待就绪回补。

### 4.2.1 设计评审门禁(用户裁决 11)
**阶段② 分两步交付,设计初版必须先给用户看:**
```
②A 设计方向确认  →  用户查看  →  ②B 组件规范细化
   令牌 + 视觉方向 + 关键页面草案
```
- **G-D1 硬门禁**:关键页面原型未确认**不得进入编码**
- **提问授权**:设计中的业务语义 / 视觉方向 / 交互取舍问题**可直接问用户**
- **参考授权**:允许参考同类产品(IM / 数字员工管理 / 任务看板类),但需说明**借鉴点与改造点**并留痕
- **原型形态**:可交互 HTML,不进生产包,不污染 `src/`

### 4.3 验收环境(用户裁决 10)
**本地优先**。验收 = `npm start`(http://localhost:4200)。**不做部署动作**(OBS 上传 / CDN 刷新 / 线上路径)。
> 「替换旧版」的**上线动作**暂缓;**FR-16 迁移需求仍要做**(纯前端实现,与是否上线无关)。

---

## 五、用户画像(摘要)

| 画像 | 端 | 核心诉求 | 对应模块 |
|---|---|---|---|
| **P1 业务同事** | 手机为主 | 看进展、收成果、发指令 | 会话、成果 |
| **P2 管理者/超管** | 桌面为主 | 统览全局、盯有没有卡住 | 工作台、任务看板 |
| **P3 运维/交付方** | 双端 | 盯指标、查技术信号 | 工作台、任务看板、详情 |

> 详见 `docs/01-requirements/personas/用户画像.md`
> **设计含义**:桌面走高密度(多栏对比),移动走高可达(单列、大触达区、沉浸)。

---

## 六、关键业务规则

| # | 规则 | 来源 |
|---|---|---|
| R1 | 端分流**一次性判定**,窗口缩放/旋转不改变端 | 存量特性,保留 |
| R2 | 未接入 FMODE 的数字生命,点行进**详情页**而非会话页;该判定**服务层单点实现** | 存量 5 处重复,须收敛 |
| R3 | **单一事实源**:每个数据域一个 owner 服务,视图只消费 | 存量 4 个轮询器重叠 |
| R4 | 租户归属校正由**服务端权威**判定 | 存量客户端 PUT 自改 |
| R5 | 任务看板**一期只读** | 写操作待 RBAC |
| R6 | 所有业务表带 `company` 指针;删除用软删 | 黄金规则 6 |

---

## 七、非功能要求

| 类别 | 要求 |
|---|---|
| **规范符合** | 零硬编码色值 / 单一令牌前缀 / 字号 ≤8 档 / 圆角 ≤4 档 / 业务样式全部进组件 |
| **无障碍** | aria 完整、键盘可达、focus 可见、触达区 ≥44px、支持 `prefers-reduced-motion` |
| **安全** | 前端零服务端密钥(`masterKey` 铁律);v2 新写代码不得复制存量硬编码模式 |
| **性能** | 路由懒加载;Matrix SDK 独立 chunk 不进主包 |
| **可测** | 单测 + 双端全路由冒烟 + 规范断言脚本 |
| **可追踪** | 全链文档:PRD → SPEC → ER → API → 测试 → 留痕 |

---

## 八、风险

| # | 风险 | 影响 | 应对 |
|---|---|---|---|
| R1 | 云函数字段定义**未经核对** | 数据层返工 | 阶段② 优先核对;ER 图 ❓ 标记 |
| R2 | **任务看板依赖云函数改造**(未实现) | 序 6 模块阻塞 | 先落空态,报告后跳序 7 |
| R2b | **租户归属权威判定依赖云函数 `zl4yU8PAEB` 改造**(与 R2 同级阻塞) | 登录后的归属校正逻辑 | 同 R2 处理:先落现状行为,报告中标注待改造 |
| R3 | `AgentTask` 21 字段清单未知 | 映射不确定 | 待 Agent 核实(16 问清单) |
| R4 | ui-kit 596 文件,可能引入未用代码 | 体积/维护性 | 阶段② 做组件盘点与按需评估 |
| R5 | 存量 `deploy.sh` 明文凭证 | **已裁决不处理**(自有服务器) | NFR-03 已注明适用范围 |
| R6 | 多任务"并行度"未经实测 | UI 可能按错误假设设计 | 待 Agent 实证(16 问第 4 组) |
| R7 | **任务评论/附件需新增两张表**(`AgentTaskComment`/`AgentTaskAttachment`) | 影响 AC-07b.2 可实施性 | 随云函数改造一并建;若审批受阻则降级为 `AgentTask.extra` JSON |

---

## 九、未验证项披露(诚实声明)

1. **云函数 5 个契约的字段定义未核对** —— ER 图为逆向推测
2. **`AgentTask` 等三张表的 21/13/14 字段清单未获取**
3. **线上云函数是否已支持 kanban 未知**(核对的可能是旧副本)
4. **`kanban-report.py` 是否已部署到容器未知**
5. **多任务真实并行频率未知**(样本仅 15 任务)
6. **ui-kit 组件盘点已出结果**(见 `docs/02-design/design-system/ui-kit底座盘点.md`),发现 8 项组件缺口 + 10 项令牌缺口

---

## 十、关联文档

- SPEC(FR/AC 明细):`docs/01-requirements/prd/SPEC-20261014-fmode-app-v2-草案.md`
- 用户画像:`docs/01-requirements/personas/用户画像.md`
- RACI:`docs/01-requirements/raci/RACI.md`
- 业务流程图:`docs/02-design/architecture/业务流程图.md`
- ER 图:`docs/02-design/database/ER-图-草案.md`
- 重建方案:`docs/02-design/plans/2026-10-14-v2重建方案.md`
- 多任务调研:`docs/02-design/plans/调研-20261014-多任务并行可行性.md`
- 裁决记录:`docs/01-requirements/stories/访谈-20261014-{第二轮,第三轮}裁决记录.md`
- 现状调研汇总:`docs/01-requirements/stories/访谈-20261014-现状调研汇总.md`
- 访谈问卷:`docs/01-requirements/stories/访谈问卷-20261014-v2需求挖掘.md`
- 交接文档:`docs/01-requirements/交接文档-阶段1至2.md`
- 第1轮评审报告:`docs/04-quality/review/2026-10-14-SPEC-ER评审-第1轮.md`