交接文档

2026-04-01 20:38:35 +08:00 · 2026-04-01 20:38:35 +08:00 · 2e72ae84e1
commit 2e72ae84e1
parent 283bfec765
1 changed files with 216 additions and 0 deletions
--- a/交接文档.md
+++ 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 模式