PRD-20261014-fmode-app-v2.md 11 KB
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)
「功能所有都测试完成」
具体化为:
- 7 个功能模块 + 5 项通用能力全部通过测试
- 单测全绿(
npm test) - 双端全路由冒烟断言通过
- 规范断言通过(零硬编码色值 / 零
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 |
九、未验证项披露(诚实声明)
- 云函数 5 个契约的字段定义未核对 —— ER 图为逆向推测
AgentTask等三张表的 21/13/14 字段清单未获取- 线上云函数是否已支持 kanban 未知(核对的可能是旧副本)
kanban-report.py是否已部署到容器未知- 多任务真实并行频率未知(样本仅 15 任务)
- 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