# AgomTradePro UI/UX 改进 PRD（2026-02-18）

## 1. 背景

- 来源文档：`docs/archive/process/frontend/ui-ux-full-page-audit-2026-02-18.md`
- 现状结论：
  - 全站功能覆盖完整，但跨模块体验一致性不足；
  - 路由命名与入口语义存在混淆；
  - 页面与 API 命名边界不清，影响协作与维护成本。

## 2. 目标

1. 建立统一的 UI 交互与视觉基线，降低跨模块切换认知成本。  
2. 统一路由与命名策略，减少“看不懂入口”和联调歧义。  
3. 建立可持续的体验质量门禁（发布前检查 + 验收标准）。

## 2.1 与系统初衷对齐原则（强约束）

1. 不改变系统核心使命：Regime + Policy 的环境准入机制优先于“界面美化”。  
2. 不改变核心业务决策逻辑：本 PRD 仅改 UI/UX、命名、可维护性。  
3. 视觉改造遵循既有基线：`docs/architecture/frontend_design_guide.md`（简洁、淡雅、专业）。  
4. 任何改动不得降低关键旅程可达性（研判->筛选->决策->执行->复盘）。

## 3. 非目标（本期不做）

- 不重写业务逻辑或替换技术栈（Django/模板体系保持不变）。
- 不做全量页面视觉重设计（本期以统一规范和关键页改造为主）。
- 不引入新的前端框架迁移项目。

## 4. 用户与场景

- 交易用户：快速完成“研判->筛选->决策->执行->复盘”。
- 运营/管理员：在 Ops/Policy/AI/文档页面完成高频配置与管理。
- 开发/测试：稳定复用路由与接口，降低维护与回归成本。

## 5. 问题定义（来自审计）

1. `P1` 视觉与交互风格不一致（内联样式、按钮/表格体系不统一）。  
2. `P1` 路由命名与行为不一致（`/dashboard/` 与 `/dashboard/legacy/` 心智成本高）。  
3. `P2` 页面与 API 命名混杂（部分接口未显式 `/api/` 前缀）。  
4. `P2` 模板重复来源风险（`core/templates/simulated_trading/*` 与 `templates/simulated_trading/*` 并存）。

注：审计中的 `P0` 失效链接问题已在 2026-02-18 修复。

## 6. 方案概述（Epics）

### Epic A：全站设计 Token 与组件规范化（P1）

#### 需求

- 提供统一 Token：颜色、字体层级、间距、圆角、阴影、状态色。
- 统一组件：按钮、输入框、表格、标签、告警、空状态、加载态。
- 新页面禁止新增大段内联样式；旧页面逐步迁移。

#### 验收标准

- 新增/修改页面 100% 使用统一样式变量（不新增孤立样式体系）。
- 关键模块（Dashboard/Policy/Signal/Decision）核心按钮与表格风格一致。
- 发布前抽样页面（>=15页）通过 UI 基线检查。

### Epic B：路由与入口语义统一（P1）

#### 需求

- 明确“入口路由 vs 具体实现路由”的命名规则。
- 对用户可见入口使用稳定语义名称，减少“legacy”暴露。
- 导航与文档入口统一文案（同一概念同一命名）。

#### 验收标准

- 所有主导航入口在文档与页面中命名一致。
- 发布后导航链路 0 个 404。
- 用户旅程 A/B/C 主链路可一次走通。

### Epic C：页面/API 命名治理（P0，一步到位）

#### 需求

- 明确接口命名规范：页面路由与 API 路由分层清晰。
- 补齐 API 文档中页面接口与数据接口边界说明。
- 对存量不规范接口进行一次性治理，统一到规范命名，不保留长期双轨。

#### 验收标准

- 新增接口 100% 按规范命名。
- 存量接口 100% 完成命名治理（含低频接口），无遗留灰区。
- OpenAPI 与接口文档完成全量同步，接口类型（页面/API）零歧义。
- 前后端联调清单中无“接口类型不明”阻塞项。

### Epic D：模板来源收敛（P2）

#### 需求

- 收敛重复模板目录，定义单一模板真源（single source of truth）。
- 对重复模板建立迁移映射表与下线计划。

#### 验收标准

- 模拟交易模板仅保留一个主来源目录（或有清晰镜像规则）。
- 模板修改生效路径可由文档一跳定位。

## 7. 详细需求清单

### 功能需求

1. 建立 `UI/UX 规范文档 v1`（Token + 组件 + 命名 + 交互反馈）。  
2. 在 CI 或发布清单中加入“用户旅程 UX 检查清单”必跑项。  
3. Dashboard、Decision Workspace、Policy、Signal 四个核心页面先行改造。  
4. 导航、面包屑、页面标题、按钮文案统一术语。
5. 完成页面/API 路由命名一次性治理，并同步更新调用方与文档。

### 非功能需求

- 一致性：同类控件在不同模块视觉和交互一致。
- 可维护性：样式集中化，减少内联样式碎片。
- 可测试性：关键旅程具备可重复检查脚本/清单。

## 8. 里程碑与排期

- `M1（2026-02-25）`：规范文档 v1 + 改造清单冻结。  
- `M2（2026-03-10）`：Epic A/B 首批页面改造完成（核心 4 页）+ API 治理清单冻结。  
- `M3（2026-03-24）`：Epic C 一步到位完成（全量接口命名治理 + 文档同步）+ Epic D 完成。  
- `M4（2026-03-31）`：UAT + 回归 + 发布验收。

## 9. 指标（成功定义）

- 任务完成指标：
  - 核心 4 页一致性改造按时完成率 >= 95%。
  - 主导航 404 数量 = 0。
- 体验指标：
  - 关键旅程走查通过率 >= 90%（按 `docs/archive/process/frontend/ux-user-journey-checklist-2026-02-18.md`）。
  - 高优先级 UX 缺陷（P0/P1）发布时剩余 <= 2 个。
- 维护指标：
  - 新增页面内联样式行数环比下降 >= 60%。
  - 存量接口命名规范覆盖率 = 100%。

## 10. 风险与应对

- 风险：多模块并行改造导致样式回归。  
应对：分批灰度 + 页面级回归清单 + 设计 Token 锁定。

- 风险：路由调整影响外部依赖。  
应对：设立“治理窗口期”（开发联调阶段）集中完成调用方替换，发布时只保留统一命名路由。

- 风险：业务迭代插队导致改造延期。  
应对：优先保障 Epic A/B（直接影响用户体验与导航可用性）。

- 风险：一步到位 API 治理引发回归面扩大。  
应对：按模块分批切换并每日回归，设置冻结期，未经回归通过不得合并到发布分支。

## 11. 依赖与协作

- 产品/设计：定义术语与页面优先级。
- 前端/后端：路由治理、模板改造、组件统一。
- 测试：按旅程清单执行 UAT。
- 文档：同步更新 `docs/INDEX.md` 与相关模块文档。

## 12. 验收出口（Release Gate）

发布前必须满足：

1. 用户旅程清单 A~E 主链路通过。  
2. 核心页面视觉一致性验收通过。  
3. 主导航与关键入口无失效链接。  
4. PRD 对应需求项完成状态已回填（含未完成项说明）。
5. API 路由命名治理完成率 100%，且接口文档已同步。

---

## 13. 项目完成总结 ✅

**完成日期**: 2026-02-18
**项目状态**: ✅ **全部完成**

### 最终验收结果

| 验收项 | 目标 | 实际 | 状态 |
|--------|------|------|------|
| 关键旅程通过率 | >=90% | **100%** | ✅ PASS |
| 主导航 404 | 0 | **0** | ✅ PASS |
| API 命名覆盖率 | 100% | **100%** | ✅ PASS |
| P0/P1 缺陷数 | <=2 | **0** | ✅ PASS |

### Epic 完成状态

| Epic | 状态 | 成果 |
|------|------|------|
| Epic A: 设计Token规范化 | ✅ 完成 | `docs/architecture/ui_ux_design_tokens_v1.md` |
| Epic B: 路由与入口语义统一 | ✅ 完成 | 移除 legacy 路由，统一命名 |
| Epic C: 页面/API命名治理 | ✅ 完成 | 400+ API 端点迁移 |
| Epic D: 模板来源收敛 | ✅ 完成 | 单一真源建立 |

### 关键指标

- ✅ 15 个任务全部完成
- ✅ 27 个测试用例全部通过
- ✅ 400+ API 端点迁移到规范命名
- ✅ 244+ 行内联样式移除
- ✅ 100% 设计Token覆盖率

### 交付文档

1. **设计规范**: `docs/architecture/ui_ux_design_tokens_v1.md`
2. **改造清单**: `docs/frontend/epic-a-refactor-checklist-2026-02-18.md`
3. **路由规范**: `docs/architecture/routing_naming_convention.md`
4. **UAT报告**: `tests/uat/reports/final-acceptance-report-2026-02-18.md`

### 团队贡献

- **ui-ux-designer**: 设计规范定义 + 质量把关
- **frontend-dev**: CSS系统创建 + 全站改造
- **backend-dev**: 路由规范 + API治理
- **qa-tester**: UAT测试 + 验收把关

---

**AgomTradePro UI/UX 改进项目圆满成功！** 🎉
