# 数据库（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` 未声明唯一约束；若业务要求全局唯一，应在后续变更中补齐约束与迁移。