# Project Context

## Purpose
本仓库实现"微信小程序通信记录管理系统"：小程序端采集/展示对话与用户信息；后端提供登录、会话记录的增删改查、文件上传与管理查询能力；数据存储在 MariaDB/MySQL。后台管理网站提供管理员操作界面，用于系统配置、数据管理和监控。

## Repository Layout (Source of Truth)
- 小程序端：`CommunicationRecords/`
  - 页面：`pages/chat`（聊天与会话列表）、`pages/logs`（登录/注册/隐私协议）等
  - 公共：`utils/config.js`（环境与 API 根地址）
- 后端：`WxCheckMvc/`（ASP.NET Core 8，MVC + Web API Controller）
  - API Controllers：`Controllers/LoginController.cs`、`Controllers/CheckController.cs`、`Controllers/AdminController.cs`
  - 配置：`appsettings.json`
- 后台管理网站：`admin-web/`（Vue 3.x + Element Plus + Vite）
  - 页面：登录页、会话记录管理页、用户管理页等
  - 路由：`src/router/index.js`（vue-router配置）
  - 组件：`src/components/`（模块化组件）
  - 状态管理：`src/store/`（深色/浅色模式状态）
  - 样式：`src/styles/`（响应式样式、主题样式）
- 数据库：`wx_xcx_check.sql`（根目录）与 `WxCheckMvc/wx_xcx_check.sql`（均为 MariaDB/MySQL 导出）

## Tech Stack
- Client:
  - 微信小程序（JavaScript + WXML/WXSS），依赖 `WechatSI` 插件（语音识别/录音管理器）
  - 后台管理网站：Vue 3.x + Element Plus + Vite
    - 路由管理：vue-router
    - 状态管理：Pinia（用于深色/浅色模式切换）
    - HTTP客户端：axios
    - 构建工具：Vite
    - 开发环境：Node.js
- Server: ASP.NET Core 8（`ControllersWithViews` + API Controller），数据库访问使用 `MySql.Data`
- DB: MariaDB/MySQL（schema: `wx_xcx_check`）
- Cache/Stream: Redis（通过 `CSRedis`；用于 Redis Stream 推送与读取消息）
- External APIs:
  - 微信：`https://api.weixin.qq.com/sns/jscode2session`（用 `code` 换取 `openid`）
  - 高德地图：逆地理编码（经纬度 → 地址）

## High-Level Architecture
1) 小程序端通过 `wx.login()` 获取 `code`，调用后端登录接口换取用户信息与 Token（当前 token 主要用于前端保存/展示）。
2) 小程序端对话发送/修改/删除通过后端 API 写入数据库（表 `xcx_conversation`）。
3) 后端在新增会话时（AddConversation）会将会话与用户信息写入 Redis Stream（key: `xcx_msg`，group: `xcx_group`），用于异步消费（例如外部系统订阅）。
4) 后端管理查询（AdminController）提供查询用户与会话的接口。
5) 后台管理网站：
   - 使用 Vue 3.x + Element Plus + Vite 构建
   - 通过 vue-router 管理多页面路由
   - 使用 Pinia 管理深色/浅色模式状态
   - 通过 axios 调用后端 AdminController 提供的 API
   - 响应式设计：优先适配手机宽度，电脑其次
   - 前端验证：固定账号密码均为 Admin
   - 模块化设计：所有页面和组件采用模块化思路

## Core Domain Model
- 用户（`xcx_users`）
  - `UserKey`：用户唯一标识（实际为微信 `openid`）
  - 可补全资料：`UserName`、`WeChatName`、`PhoneNumber`、`AvatarUrl`、`Department`
  - 状态：`IsDisabled`（禁用）
- 会话记录（`xcx_conversation`）
  - `Guid`：会话唯一标识（由后端生成或前端传入）
  - `MessageType`：1 公有 / 2 私有
  - `IsDeleted`：软删除标记
  - `RecordTimeUTCStamp`：用于排序与分页

## API Surface (Entry Points)
后端 API 统一路由前缀：`/api/{Controller}/{Action}`。

- 登录与用户：`/api/Login/Login`、`/api/Login/Register`
- 会话与文件：`/api/Check/AddConversation`、`GetConversations`、`GetConversationsByPage`、`UpdateConversation`、`DeleteConversation`、`GetConversationByGuid`、`UploadFile`、`CheckAddress`、`ReadMessageFromRedis`
- 管理查询：`/api/Admin/QueryUsers`、`/api/Admin/QueryConversations`

## Business Rules (High Impact)
- 登录
  - 使用 `code` 向微信换取 `openid`，以 `openid` 作为 `UserKey`。
  - 若 `xcx_users` 中不存在该 `UserKey`，后端会插入一条“未完善资料”的用户记录（仅含 `UserKey/FirstLoginTime` 等）。
- 注册/资料完善
  - 仅允许更新已存在的用户（若不存在返回 NotFound）。
  - `PhoneNumber` 会被清洗为纯数字并校验为 `^1\d{10}$`。
  - `UserName` 会去除标点/符号/空白后校验不为空。
- 会话
  - 删除为软删除（`IsDeleted = 1`）。
  - 查询默认过滤 `IsDeleted = 0`。
  - 分页接口限制 `PageSize` 1..100。

## Known Limitations / Risks
- 鉴权“已配置但未启用”：后端配置了 JWT Bearer，但当前请求管线未启用 `UseAuthentication()`，且控制器/Action 未使用 `[Authorize]`；因此 API 当前等同于“无强制鉴权”。
- 配置敏感信息明文：`WxCheckMvc/appsettings.json` 中包含数据库密码、微信 AppSecret、JWT SecretKey 等，存在泄露风险。
- 环境选择被强制：小程序端 `CommunicationRecords/utils/config.js` 固定返回 `release`，导致无法按 `envVersion` 自动切换。
- 小程序存在硬编码域名：部分页面直接写死 `https://wx-xcx-check.blv-oa.com:4433`，未统一走 `config.baseUrl`。
- Redis 连接固定为 `127.0.0.1:6800` 且无密码（见 `CSRedisCacheHelper`），生产部署需额外约束网络与权限。
- 文件上传缺少类型/大小白名单：`UploadFile` 仅校验目录名字符集，未对扩展名、内容类型、大小做进一步限制。

## Conventions
- C#：PascalCase（类型/方法），配置键区分大小写但项目内存在 `JwT`/`JWT` 混用历史；以 `appsettings.json` 的 `JwT:*` 为准。
- JS：camelCase；小程序请求优先使用 `config.baseUrl`。
- Vue 3.x：
  - 组件命名：PascalCase（如 `ConversationList.vue`）
  - 变量/方法：camelCase
  - 常量：UPPER_SNAKE_CASE
  - 使用 Composition API 和 `<script setup>` 语法
  - 组件模块化：每个组件职责单一，可复用
- 样式：
  - 使用 CSS Modules 或 Scoped CSS
  - 响应式设计：优先适配手机宽度（<768px），其次适配桌面
  - 深色/浅色模式：使用 Element Plus 的主题切换功能