Wx_WxCheck_Prod/openspec/specs/database/spec.md

数据库（wx_xcx_check）规范

Purpose

本能力描述 MariaDB/MySQL schema wx_xcx_check 的表结构与核心业务语义，用于约束后端 API 的持久化行为。

参考文件：

• 根目录 wx_xcx_check.sql
• WxCheckMvc/wx_xcx_check.sql

Requirements

Requirement: 用户表 xcx_users

系统 SHALL 存储小程序用户档案，主业务键为 UserKey（微信 openid）。

字段语义（核心）：

• UserKey：唯一键（UNIQUE）
• UserName：用户姓名（可空，注册/完善资料后写入）
• WeChatName：微信昵称（可空）
• PhoneNumber：手机号（可空，注册/完善资料后写入）
• AvatarUrl：头像 URL（可空，上传后写入）
• Department：部门（可空，用于管理端筛选）
• IsDisabled：0 启用 / 1 禁用
• FirstLoginTime：首次登录时间
• CreateTime/UpdateTime

Scenario: 首次登录建档

• WHEN 后端检测到 UserKey 不存在
• THEN 插入一条用户记录，至少包含 UserKey/FirstLoginTime/IsDisabled

Requirement: 会话表 xcx_conversation

系统 SHALL 存储会话记录，并支持软删除。

字段语义（核心）：

• UserKey：关联用户（逻辑关联；当前 schema 未声明外键）
• ConversationContent：会话内容
• SendMethod：发送方式（文本/语音等，由业务侧约定字符串）
• MessageType：1 公有 / 2 私有
• Guid：会话唯一标识（业务约定；schema 未声明 UNIQUE）
• Latitude/Longitude：经纬度（字符串存储）
• UserLocation：地址文本（可由高德逆地理编码写入）
• RecordTime：记录时间
• RecordTimeUTCStamp：毫秒级 UTC 时间戳（用于排序/分页）
• SpeakingTime：对话时长（可空）
• IsDeleted：0 正常 / 1 删除

索引：

• idx_userkey、idx_utcstamp、idx_deleted、idx_messagetype、idx_guid

Scenario: 软删除

• WHEN 用户删除会话
• THEN 将 IsDeleted 置为 1
• AND 默认查询不返回 IsDeleted = 1 的记录

Requirement: 操作日志表 xcx_log

系统 MAY 记录操作日志，用于审计与问题排查。

字段语义（核心）：

• UserKey：操作者
• OperationContent：操作内容
• Impact：影响描述
• RecordTime：记录时间

Scenario: 记录操作日志

• WHEN 发生需要审计的关键操作
• THEN 系统写入 xcx_log

Known Limitations

• xcx_conversation.UserKey 与 xcx_users.UserKey 当前为“逻辑关联”，未声明外键；数据一致性需由应用层保障。
• Guid 未声明唯一约束；若业务要求全局唯一，应在后续变更中补齐约束与迁移。