103 lines
6.1 KiB
Markdown
103 lines
6.1 KiB
Markdown
# 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 的主题切换功能
|