6.1 KiB
6.1 KiB
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
- API Controllers：
- 后台管理网站：
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
- 微信小程序（JavaScript + WXML/WXSS），依赖
- 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
- 小程序端通过
wx.login()获取code，调用后端登录接口换取用户信息与 Token（当前 token 主要用于前端保存/展示）。 - 小程序端对话发送/修改/删除通过后端 API 写入数据库（表
xcx_conversation）。 - 后端在新增会话时（AddConversation）会将会话与用户信息写入 Redis Stream（key:
xcx_msg，group:xcx_group），用于异步消费（例如外部系统订阅）。 - 后端管理查询（AdminController）提供查询用户与会话的接口。
- 后台管理网站：
- 使用 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。 - 分页接口限制
PageSize1..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>语法 - 组件模块化：每个组件职责单一，可复用
- 组件命名：PascalCase（如
- 样式：
- 使用 CSS Modules 或 Scoped CSS
- 响应式设计：优先适配手机宽度（<768px），其次适配桌面
- 深色/浅色模式：使用 Element Plus 的主题切换功能