first

docs/static-data-audit-20260423.md

@@ -0,0 +1,226 @@
+# 安心验静态数据与展示映射审计
+
+审计时间：2026-04-23
+
+## 一、已确认的真实问题
+
+### 1. 后台订单详情页存在“接口有值但页面没展示完整”的问题
+
+- 文件：`admin-web/src/pages/orders/index.vue`
+- 现象：
+  - 接口已返回 `product_info.color`
+  - 接口已返回 `extra_info.condition_desc` / `remark`
+  - 页面原先只展示了 `size_spec` 和 `usage_status`
+  - 导致后台看到的内容与接口实际内容不一致，且卡片出现大面积空白
+- 本轮已修复：
+  - 商品信息区补充 `颜色 / 规格`
+  - 补充信息区补充 `补充说明`
+
+### 2. 鉴定作业台也存在同类字段遗漏
+
+- 文件：`admin-web/src/pages/appraisal-tasks/index.vue`
+- 现象：
+  - 页面已有 `product_info.color`
+  - 但工作区与上下文区未展示，导致检测侧看到的信息不完整
+- 本轮已修复：
+  - 商品与送检区补充 `颜色 / 规格`
+  - 工作台左侧上下文区补充 `颜色 / 规格`
+
+### 3. 用户端多个页面在接口失败时会静默回退到 mock 数据
+
+- 风险级别：高
+- 问题本质：
+  - 页面请求失败后，没有给用户明确错误态
+  - 而是继续显示 `src/mocks/app.ts` 中的示例数据
+  - 会造成“接口已经失败，但页面仍像有真实数据”的错觉
+- 这类问题比普通静态文案更危险，因为会直接影响业务判断
+
+## 二、前端仍在使用 mock / fallback 的页面
+
+### 1. 用户端高风险页面
+
+以下页面在请求失败时，会直接沿用 mock 或 fallback 数据：
+
+- `user-app/src/pages/home/index.vue`
+- `user-app/src/pages/address/index.vue`
+- `user-app/src/pages/message/index.vue`
+- `user-app/src/pages/mine/index.vue`
+- `user-app/src/pages/order/detail.vue`
+- `user-app/src/pages/order/shipping.vue`
+- `user-app/src/pages/report/detail.vue`
+- `user-app/src/pages/help/index.vue`
+- `user-app/src/pages/help/detail.vue`
+- `user-app/src/pages/settings/index.vue`
+- `user-app/src/pages/support/index.vue`
+- `user-app/src/pages/support/detail.vue`
+- `user-app/src/pages/support/create.vue`
+- `user-app/src/pages/verify/result.vue`
+
+统一来源：
+
+- `user-app/src/mocks/app.ts`
+
+### 2. 风险说明
+
+- 订单、报告、消息、地址、工单、验真都属于真实业务数据
+- 这些页面不适合在接口失败时展示示例数据
+- 正确策略应该是：
+  - 显示错误态
+  - 提供重试按钮
+  - 保留空态，但不能伪造业务内容
+
+## 三、后端接口本身仍是静态拼装的数据
+
+### 1. 首页接口
+
+- 文件：`server-api/app/controller/app/HomeController.php`
+- 当前静态内容：
+  - `banners`
+  - `service_entries`
+  - `quick_entries`
+  - `trust_metrics`
+  - `trust_points`
+  - `faqs`
+- 当前只有 `category_entries` 来自数据库
+
+补充说明：
+
+- `user-app/src/pages/home/index.vue` 原先没有消费 `banners`
+- 即使接口已经返回首页头图文案，前端页面也仍然使用写死标题
+- 本轮已修复为直接读取接口 `banners[0]`
+
+### 2. 帮助中心接口
+
+- 文件：`server-api/app/controller/app/HelpCenterController.php`
+- 当前问题：
+  - 帮助分类与文章内容全部写在控制器里
+  - 搜索和分类筛选只是对本地数组做过滤
+- 结论：
+  - 当前帮助中心已经“可用”，但本质仍是写死内容，不是后台可运营内容
+
+### 3. 设置页协议入口
+
+- 文件：`server-api/app/controller/app/SettingsController.php`
+- 当前静态内容：
+  - `legal_entries`
+  - 跳转的帮助中心关键词
+
+### 4. 下单预览协议文案
+
+- 文件：`server-api/app/controller/app/AppraisalController.php`
+- 当前静态内容：
+  - `preview()` 中的 `agreements`
+  - `service_agreement`
+  - `privacy_policy`
+  - `appraisal_notice`
+
+## 四、前端仍然硬编码的业务选项
+
+这些不一定是 bug，但如果要达到“后台可维护、线上可运营”的标准，后续建议逐步改成可配置或接口下发。
+
+### 1. 用户端
+
+- `user-app/src/pages/support/create.vue`
+  - 工单类型 `typeOptions`
+- `user-app/src/pages/support/index.vue`
+  - 常见问题快捷入口 `quickTypes`
+- `user-app/src/pages/appraisal/product.vue`
+  - 颜色建议 `colorSuggestions`
+  - 规格建议 `sizeSuggestions`
+- `user-app/src/pages/appraisal/extra.vue`
+  - 购买渠道
+  - 使用情况
+  - 附件情况
+
+### 2. 管理后台
+
+- `admin-web/src/pages/orders/index.vue`
+  - 服务筛选项
+  - 状态筛选项
+- `admin-web/src/pages/appraisal-tasks/index.vue`
+  - 阶段筛选项
+  - 状态筛选项
+  - 结果选项
+- `admin-web/src/pages/reports/index.vue`
+  - 服务筛选项
+  - 报告状态项
+  - 结果项
+- `admin-web/src/pages/tickets/index.vue`
+  - 工单类型与状态筛选
+
+说明：
+
+- 这类枚举型选项短期内可以先保留
+- 但工单类型、结果模板、服务文案如果未来需要运营调整，建议迁移为后台字典表或系统配置
+
+## 五、已发现的“假入口 / 假交互”
+
+- `user-app/src/pages/appraisal/upload.vue`
+  - `查看示例` 按钮无实际功能
+  - `查看拍摄示例` 入口无实际功能
+- `user-app/src/pages/home/index.vue`
+  - 未识别的快捷入口会落到“该功能正在完善中”
+- `user-app/src/pages/mine/index.vue`
+  - 未识别入口也会落到“该功能正在完善中”
+
+## 六、推荐开发顺序
+
+### P0：先清掉会误导真实业务判断的 fallback
+
+优先处理以下页面：
+
+- 订单详情
+- 报告详情
+- 消息中心
+- 地址管理
+- 工单列表 / 工单详情
+- 设置页
+- 验真页
+
+目标：
+
+- 失败时显示明确错误状态，不再显示 mock 业务数据
+
+### P1：把接口里已返回但页面没展示完整的字段补齐
+
+优先处理以下模块：
+
+- 后台订单详情
+- 鉴定作业台
+- 用户端订单详情
+- 报告详情页的商品摘要 / 估值摘要一致性
+
+目标：
+
+- 页面展示与接口字段保持一致
+- 同一份订单数据在用户端、后台、报告端口径一致
+
+### P2：把后端静态内容迁移为可维护内容
+
+优先处理：
+
+- 首页内容
+- 帮助中心
+- 设置页协议入口
+- 下单预览协议区
+
+推荐做法：
+
+- 新建内容配置表 / 帮助中心表 / 协议配置表
+- 后台增加内容维护入口
+- 用户端改为读取接口配置
+
+### P3：把前端硬编码枚举逐步改为字典化
+
+优先处理：
+
+- 工单类型
+- 鉴定结果模板
+- 用户端下单辅助枚举
+
+## 七、建议的下一步落地动作
+
+1. 先移除用户端业务页面对 `user-app/src/mocks/app.ts` 的依赖，改为错误态 + 重试。
+2. 统一订单 / 报告 / 鉴定任务三端字段口径，补齐 `color`、`condition_desc`、`remark`、`accessories` 等实际字段。
+3. 设计内容配置模型，把首页、帮助中心、协议说明迁到后台管理。
+4. 最后再做字典化，把工单类型、辅助选项、结果模板迁到接口配置。