字段来源与默认值约定

概述

本章中的“默认值/必填”用于表达业务口径与字段期望，不等价于 MySQL 的列默认值。

实现时必须明确：默认值由哪一层填充，避免字段含义混淆或数据口径不一致。

可选填充层包括：

微信侧
服务端
前端兜底

字段来源分层约定

1. 微信侧来源字段

由微信能力或用户授权提供。

包括：

openId / unionId
微信昵称 / 头像
手机号授权 code（由服务端解密后落库）

说明：

微信侧提供的是原始授权数据或标识。
涉及用户身份与授权的信息，应以微信能力返回结果为准。

2. 服务端填充字段

服务端为权威来源。

包括：

各对象 createdAt / updatedAt
status
各类业务状态字段，如：
- orderStatus
- refundStatus
幂等键
审计字段

说明：

与业务流程、状态流转、审计追踪相关的字段，必须由服务端统一生成或维护。
服务端字段应作为业务判断与数据落库的最终依据。

3. 前端展示兜底

仅用于 UI 展示降级，不落库，或不作为业务判断依据。

包括：

默认头像
空态文案
占位图

说明：

当服务端字段缺失时，前端可以进行降级展示。
不得将前端兜底值反向写入为真实业务值。

实施原则

默认值语义与数据库默认值分离
- PRD 中的“默认值”表示业务期望，不代表数据库 schema 中必须配置默认值。
明确字段责任归属
- 每个字段在设计与实现时，应明确由微信侧、服务端或前端哪一层负责提供或兜底。
服务端字段为业务权威
- 涉及状态、审计、幂等、时间戳等关键字段，必须由服务端控制。
前端兜底仅限展示
- 前端可提升用户体验，但不得污染业务数据，也不得参与真实业务状态判定。

典型风险

将 PRD 默认值误理解为 MySQL 列默认值，导致数据语义错位
前端将展示占位值写回数据库，造成脏数据
服务端未统一维护状态字段，导致业务判断口径不一致
微信授权字段未按正确流程处理，例如手机号 code 未经服务端解密即直接使用

推荐实践

在接口文档中标注每个字段的来源层级与填充责任方
对服务端权威字段设置统一生成与更新机制
前端对兜底展示字段进行明确隔离，避免与真实业务字段混用
对授权类字段建立完整链路说明：获取、解密、落库、使用