From 2e72ae84e11d3d4abc8a45045f910edebfea93da Mon Sep 17 00:00:00 2001 From: zpc Date: Wed, 1 Apr 2026 20:38:35 +0800 Subject: [PATCH] =?UTF-8?q?=E4=BA=A4=E6=8E=A5=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- 交接文档.md | 216 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 216 insertions(+) create mode 100644 交接文档.md diff --git a/交接文档.md b/交接文档.md new file mode 100644 index 0000000..5987505 --- /dev/null +++ b/交接文档.md @@ -0,0 +1,216 @@ +# LiveForum 项目交接文档 + +## 一、项目概述 + +LiveForum（论坛社区）是一个直播机构的粉丝社区平台，面向中文用户，主要通过微信小程序提供服务。核心功能包括论坛发帖/评论/点赞、主播档案与送花排行、CDK 激活码、手机号登录与实名认证、身份权限管理、防沉迷系统等。 + +当前版本：v1.2.0（已完成） + +## 二、技术栈总览 + +| 模块 | 技术 | +|------|------| +| 小程序 API | .NET 8、FreeSql（SQL Server）、Redis、Hangfire、AgileConfig、Serilog、JWT、Autofac | +| 后台管理 API | .NET 8、SqlSugar、Mapster、NLog | +| 后台管理前端 | Vue 3 + Vite + Element Plus + Pinia | +| 微信小程序 | uni-app（Vue 3）、uview-plus、dayjs | +| 数据库 | SQL Server（主库）、Redis（缓存/消息队列/JWT Token 存储） | +| 文件存储 | 腾讯云 COS | +| 配置中心 | AgileConfig（支持热更新） | +| 微信 SDK | SKIT.FlurlHttpClient.Wechat.Api | +| 爬虫 | Python + Playwright | +| 压测 | k6 | + +## 三、项目结构 + +``` +├── server/ +│ ├── webapi/LiveForum/ # 小程序 API（主业务） +│ │ ├── LiveForum.WebApi/ # 入口、Controllers、BackgroundServices +│ │ ├── LiveForum.Service/ # 业务逻辑（按领域分文件夹） +│ │ ├── LiveForum.IService/ # 服务接口 +│ │ ├── LiveForum.Model/ # DTO、实体（T_ 前缀）、枚举、领域事件 +│ │ ├── LiveForum.Code/ # 基础设施（JWT、Redis、中间件、缓存、工具类） +│ │ ├── LiveForum.Repository/ # 数据访问（FreeSql） +│ │ ├── LiveForum.Tests/ # 单元测试（xUnit + FsCheck + Moq） +│ │ └── DatabaseScripts/ # SQL 迁移脚本 +│ ├── admin/ZrAdminNetCore/ # 后台管理 +│ │ ├── ZR.Admin.WebApi/ # 后台 API 入口 +│ │ ├── ZR.Service/Liveforum/ # 后台业务逻辑 +│ │ ├── ZR.LiveForum.Model/ # 后台论坛模型 +│ │ └── ZR.Vue/ # 后台前端 +│ ├── crawler/ # Python 爬虫（commerce / entertainment） +│ └── k6/ # 压测脚本 +├── 前端/live-forum/ # 微信小程序 +├── docs/ # 需求文档（按版本） +└── mcp/ # 开发工具（MCP 数据库服务器） +``` + +## 四、核心业务模块 + +| 模块 | 路径（Service 层） | 说明 | +|------|-------------------|------| +| 登录认证 | Auth/ | 微信登录、手机号登录、JWT Token 管理（Redis 存储） | +| 帖子 | Posts/ | 发帖、评论、点赞、分类、回复权限控制 | +| 主播 | Streamers/ | 主播档案、数据来源为爬虫 | +| 送花 | Flowers/ | 送花（礼物）、排行榜、每日重置（Hangfire） | +| CDK | Cdk/ | CDK 激活码系统，激活后才能互动 | +| 实名认证 | RealName/ | 首次互动前需实名验证 | +| 身份权限 | Permission/ | 身份组 + SK 认证等级，控制发帖/回复/送花/点赞/删帖权限 | +| 防沉迷 | （Admin 配置） | 按时间段限制发帖、回复、送花 | +| 消息推送 | Messages/ | 点赞、回复、自定义消息通知 | +| 敏感词 | SensitiveWord/ | 内容过滤引擎 | +| 首页 | Home/ | Banner 管理、弹窗配置 | +| 用户 | Users/ | 用户资料、关注关系、认证信息 | +| 文件上传 | Others/ | 腾讯 COS 上传 | + +## 五、关键架构设计 + +### 5.1 DI 容器 +- 使用 Autofac，通过程序集扫描自动注册 `LiveForum.Service` 中的服务 +- 单例服务在 `Program.cs` 中手动注册 + +### 5.2 异步处理 +- 领域事件驱动：点赞、浏览、送花、消息等通过 `LiveForum.Model/Events/` 定义事件 +- Redis 消费者 + 批量同步服务（BackgroundServices/）处理异步写入 +- Hangfire 处理定时任务（如每日送花重置） + +### 5.3 缓存策略 +- Redis 用于 JWT Token 管理、消息队列、批量同步缓冲 +- SystemCache/ 提供字段级和系统级缓存层 + +### 5.4 中间件 +- 异常处理中间件、执行时间中间件、签名验证中间件、响应缓存中间件 + +## 六、数据库 + +### 6.1 SQL Server +- 实体类使用 `T_` 前缀（如 `T_Users`、`T_Posts`、`T_IdentityGroups`） +- WebAPI 使用 FreeSql ORM +- Admin 使用 SqlSugar ORM +- 迁移脚本位于： + - `server/webapi/LiveForum/DatabaseScripts/` + - `server/webapi/数据库脚本/`（v1.2.0 升级脚本） + +### 6.2 Redis +- 缓存、消息队列、批量同步缓冲、JWT Token 存储 +- 使用 StackExchange.Redis + +## 七、CI/CD 部署 + +### 7.1 流水线 +``` +代码推送 (master) → Drone CI → 构建 Docker 镜像 → 推送 Harbor → SSH 部署 +``` + +### 7.2 关键地址 + +| 组件 | 地址 | +|------|------| +| Drone CI | `192.168.195.25:13080` | +| Harbor 镜像仓库 | `192.168.195.25:19900`（HTTP） | +| 部署服务器 | `192.168.195.15` | +| 部署目录 | `/disk/docker-compose/live-forum-new` | + +### 7.3 构建镜像 + +| 镜像 | 说明 | +|------|------| +| `live-forum/webapi` | 小程序 API | +| `live-forum/admin-api` | 后台管理 API | +| `live-forum/admin-web` | 后台管理前端（Nginx） | + +每个镜像打两个标签：`latest` + commit SHA 前 8 位（用于回滚）。 + +### 7.4 Drone Secrets + +| Secret | 说明 | +|--------|------| +| `harbor_username` | Harbor 用户名 | +| `harbor_password` | Harbor 密码 | +| `ssh_username` | 部署服务器 SSH 用户名 | +| `ssh_password` | 部署服务器 SSH 密码 | + +### 7.5 回滚方式 +```bash +# 在部署服务器上修改 docker-compose.yml 中镜像标签为指定 commit SHA +cd /disk/docker-compose/live-forum-new +# 修改镜像标签，例如 :latest → :a1b2c3d4 +docker compose up -d +``` + +## 八、本地开发 + +### 小程序 API +```bash +cd server/webapi/LiveForum +dotnet restore LiveForum.sln +dotnet build LiveForum.sln +dotnet run --project LiveForum.WebApi +# Swagger: http://localhost:{port}/swagger +``` + +### 后台管理 API +```bash +cd server/admin/ZrAdminNetCore +dotnet restore ZRAdmin.sln +dotnet run --project ZR.Admin.WebApi +``` + +### 后台管理前端 +```bash +cd server/admin/ZrAdminNetCore/ZR.Vue +npm install +npm run dev +``` + +### 运行测试 +```bash +cd server/webapi/LiveForum +dotnet test LiveForum.Tests +``` + +### 爬虫 +```bash +cd server/crawler/commerce # 或 entertainment +pip install -r requirements.txt +playwright install chromium +python main.py login # 手动浏览器登录 +python main.py daemon # 定时爬取 +``` + +## 九、外部依赖与账号 + +| 服务 | 说明 | +|------|------| +| AgileConfig | 远程配置中心，支持热更新，连接信息在 `appsettings.json` | +| 腾讯云 COS | 文件存储，密钥在配置中心 | +| 微信小程序 | AppId/AppSecret 在配置中心 | +| SQL Server | 连接字符串在 `appsettings.json` / AgileConfig | +| Redis | 连接字符串在 `appsettings.json` / AgileConfig | + +## 十、配置文件位置 + +| 文件 | 说明 | +|------|------| +| `server/webapi/LiveForum/LiveForum.WebApi/appsettings.json` | WebAPI 配置（含 AgileConfig 连接） | +| `server/admin/ZrAdminNetCore/ZR.Admin.WebApi/appsettings.json` | Admin API 配置 | +| `server/admin/ZrAdminNetCore/ZR.Vue/.env.production` | Admin 前端生产环境变量 | +| `server/admin/ZrAdminNetCore/ZR.Vue/nginx.conf` | Admin 前端 Nginx 配置 | +| `.drone.yml` | CI/CD 流水线配置 | + +## 十一、需求文档 + +- `docs/1.0.1/需求文档.md` — v1.0.1 基础功能需求 +- `docs/1.2.0/需求文档.md` — v1.2.0 需求（CDK、手机号登录、实名认证、权限等） +- `docs/1.2.0/bug.md` — v1.2.0 已知问题 + +## 十二、注意事项 + +1. 数据库实体类统一使用 `T_` 前缀 +2. Autofac 自动扫描注册服务，新增 Service 无需手动注册（单例除外） +3. 基础镜像已迁移到内网 Harbor，更新基础镜像需手动 pull → tag → push +4. 部署服务器 Docker 需配置 `insecure-registries` 信任 Harbor +5. 配置中心 AgileConfig 支持热更新，敏感配置不要写在代码仓库中 +6. SQL 迁移脚本需手动执行，注意区分业务库和管理库 +7. 爬虫需要先手动登录获取 Cookie，再启动 daemon 模式