Wx_WxCheck_Prod/openspec/specs/backend-api/spec.md

后端 API（WxCheckMvc）规范

Purpose

本能力描述 WxCheckMvc 暴露给微信小程序与管理侧的 HTTP API：登录/注册、会话记录的增删改查、文件上传、地址补全，以及 Redis Stream 的消息读取。

路由约定：统一为 /api/{Controller}/{Action}。

Requirements

Requirement: 小程序登录（基于微信 code）

系统 SHALL 提供登录接口，用 wx.login() 获取的 code 向微信换取 openid，并以 openid 作为系统内部 UserKey。

接口：POST /api/Login/Login

请求：

• Code: string

响应（成功）：

• success: true
• data: 用户对象（包含 UserKey/openid 与 Token）

行为：

• 若 xcx_users 不存在该 UserKey，系统 SHALL 自动插入一条用户记录（资料可为空）。
• 若用户 IsDisabled = 1，系统 SHALL 返回 success: false。
• 若 xcx_users 中已经存在该 UserKey，系统 SHALL 在登录流程中更新该记录的 UpdateTime 为当前服务器时间（用于“最近登录/活跃”判断）。

Scenario: 首次登录自动建档

• WHEN 提交的 code 能换取有效 openid
• AND 数据库中不存在该 openid
• THEN 系统创建用户记录并返回 Token

Scenario: 禁用用户登录

• WHEN 用户 IsDisabled = 1
• THEN 系统返回 success: false 且提示用户已禁用

Requirement: 小程序注册/完善资料

系统 SHALL 提供接口用于完善用户资料（用户名、微信名、手机号、头像链接）。

接口：POST /api/Login/Register

请求：

• UserKey: string（openid）
• UserName: string
• WeChatName: string
• PhoneNumber: string
• AvatarUrl: string

校验：

• UserKey 必填
• PhoneNumber SHALL 清洗为纯数字后满足 ^1\d{10}$
• UserName SHALL 去除标点/符号/空白后仍非空

响应（成功）：

• success: true
• data: 更新后的用户对象（包含 Token）

Scenario: 正常完善资料

• WHEN 提交合法的用户名与手机号
• AND UserKey 对应用户存在
• THEN 系统更新用户资料并返回新 Token

Scenario: 用户不存在

• WHEN UserKey 对应用户不存在
• THEN 系统返回 404

Requirement: 上传文件并可更新头像

系统 SHALL 提供文件上传接口，保存到后端 wwwroot/{rootPathType} 下，并返回可访问 URL。

接口：POST /api/Check/UploadFile（multipart/form-data）

表单字段：

• file: 上传文件
• rootPathType: string（可选；默认 Avatar，仅允许字母/数字/下划线）
• userKey: string（可选；若提供则更新 xcx_users.AvatarUrl）

响应：

• success: true/false
• url: 公开访问 URL
• path: 相对路径

Scenario: 上传头像并更新用户表

• WHEN 上传文件并提供 userKey
• THEN 系统保存文件并更新该用户 AvatarUrl

Requirement: 新增会话记录

系统 SHALL 提供接口新增会话记录（软实时写入数据库），并尝试将消息投递到 Redis Stream。

接口：POST /api/Check/AddConversation

请求（核心字段）：

• UserKey: string
• ConversationContent: string
• SendMethod: string
• UserLocation: string（当前实现中会尝试解析 lat,lng）
• MessageType: int（默认 1）
• Guid?: string（可选；缺省则服务端生成）
• SpeakingTime?: int

行为：

• 系统 SHALL 写入 xcx_conversation，并生成/使用 Guid。
• 系统 MAY 将会话与用户信息写入 Redis Stream（key: xcx_msg，group: xcx_group）。

Scenario: 新增会话并返回 guid

• WHEN 提交包含 UserKey 与 ConversationContent 的请求
• THEN 系统创建会话记录并返回 conversationGuid

Requirement: 查询会话记录（按用户）

系统 SHALL 提供按 UserKey 查询会话记录的接口，默认只返回未删除记录。

接口：POST /api/Check/GetConversations

请求：

• UserKey: string
• MessageType: int（0 不过滤；1 公有；2 私有；当前实现仅在 MessageType == 1 时追加过滤）

Scenario: 查询用户所有未删除会话

• WHEN 提交 UserKey
• THEN 系统返回该用户 IsDeleted = 0 的会话记录

Requirement: 分页查询会话记录

系统 SHALL 提供分页接口。

接口：POST /api/Check/GetConversationsByPage

请求：

• UserKey: string
• Page: int（<1 视为 1）
• PageSize: int（1..100，否则默认 10）
• MessageType: int（当前实现仅在 MessageType == 1 时追加过滤）

响应：

• data.conversations
• data.totalCount / page / pageSize / totalPages

Scenario: PageSize 超限

• WHEN PageSize > 100
• THEN 系统按默认值 10 处理

Requirement: 更新会话记录

系统 SHALL 提供接口按 Guid + UserKey 更新会话内容与发送方式。

接口：POST /api/Check/UpdateConversation

请求：

• Guid: string
• UserKey: string
• ConversationContent: string
• SendMethod: string
• MessageType: int

Scenario: 非本人更新

• WHEN Guid 存在但 UserKey 不匹配
• THEN 系统返回 404（记录不存在或无权限修改）

Requirement: 删除会话记录（软删除）

系统 SHALL 提供接口按 Guid + UserKey 软删除会话。

接口：POST /api/Check/DeleteConversation

请求：

• Guid: string
• UserKey: string

Scenario: 删除已删除记录

• WHEN 记录已被删除
• THEN 系统返回 404

Requirement: 按 Guid 查询会话（不受软删除影响）

系统 SHALL 提供接口按 Guid 查询单条会话记录，不过滤 IsDeleted。

接口：POST /api/Check/GetConversationByGuid

Scenario: 查询已删除会话

• WHEN Guid 对应记录存在但 IsDeleted = 1
• THEN 系统仍返回该记录

Requirement: 地址补全（经纬度→地址）

系统 SHALL 提供接口按 Guid 查找会话记录经纬度，并使用高德逆地理编码生成地址写回 UserLocation。

接口：POST /api/Check/CheckAddress

Scenario: 记录不存在

• WHEN Guid 对应记录不存在或已删除
• THEN 系统返回 404

Requirement: Redis Stream 读取消息

系统 SHALL 提供接口从 Redis Stream 读取消息。

接口：POST /api/Check/ReadMessageFromRedis

请求：

• GroupName?: string（默认 xcx_group）
• ConsumerName?: string（默认 consumer_{ticks}）
• Count?: int（默认 1）

Scenario: 无新消息

• WHEN Stream 中无可读消息
• THEN 返回 success: true 且数据为空

Requirement: 管理端统计接口（QueryStats）

系统 SHALL 提供聚合统计接口 GET /api/Admin/QueryStats，返回单行 JSON，data 对象字段如下：

• ActiveUsers (number)：最近 7 天内 UpdateTime >= DATE_SUB(NOW(), INTERVAL 7 DAY) 且 UserKey 和 PhoneNumber 都不为空的用户数
• TotalConversations (number)：xcx_conversation 的总记录数
• TodayNewConversations (number)：xcx_conversation 中 CreateTime >= CURDATE() AND CreateTime < DATE_ADD(CURDATE(), INTERVAL 1 DAY) 的记录数
• TotalUsers (number)：xcx_users 中 UserKey 和 PhoneNumber 都不为空的用户总数

响应（成功）：

• success: true
• data: { ActiveUsers, TotalConversations, TodayNewConversations, TotalUsers }

行为/安全：

• 当前实现为匿名访问，建议在后续迭代中加上管理员鉴权（例如 [Authorize(Roles = "Admin")] 或策略）。
• 为保证查询性能，建议为 xcx_users.UpdateTime 和 xcx_conversation.CreateTime 建立适当索引（若数据量很大）。

Known Limitations

• 当前 JWT 配置存在，但认证中间件与授权标注未启用；接口默认可匿名访问。
• MessageType 的过滤条件存在实现差异：部分接口仅在 MessageType == 1 时追加过滤（不覆盖 2）。
• 文件上传未实现内容类型/大小的强制限制。