games-org/tankwar_proj
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge feature/add_skin into master: resolve all conflicts

Browse Source 
- GameGlobal.js: keep upstream SERVER_URL with /ws suffix
- en.js/zh.js: merge both settings.nickname and settings.profile keys
- SettingsScene.js: keep both nickname row and profile button
- server/index.js: merge express app + content security proxy with
  noServer WebSocket mode and path validation
- Add .gitignore for node_modules and .codebuddy
This commit is contained in:
jakciehan
2026-05-12 07:05:20 +08:00
parent 38294c040c
commit d263c7bf48
48 changed files with 10480 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.codebuddy/plan/content-security/requirements.md
+166
View File
@@ -0,0 +1,166 @@
# 需求文档 — 用户生成内容（UGC）安全审核系统
## 引言
坦克大战小游戏当前在用户自定义昵称、聊天消息、个人资料签名、个人空间描述等场景中，未具备过滤政治有害、色情、赌博违法等不当信息的机制。根据微信平台规范及中国相关法律法规要求，小游戏必须对用户产生内容（UGC）进行内容安全审核，确保上线内容合法合规。
本需求旨在接入微信公众平台内容安全 API（`msgSecCheck`、`imgSecCheck`），并结合客户端本地敏感词过滤、服务器端二次校验、违规记录与处罚机制，构建一套完整的内容安全审核体系，覆盖所有用户可输入文本和上传图片的场景。
### 适用场景
| 场景 | 内容类型 | 审核方式 |
|------|---------|---------|
| 用户自定义昵称 | 文本 | 本地过滤 + 服务器端 msgSecCheck |
| 聊天室消息 | 文本 | 本地过滤 + 服务器端 msgSecCheck |
| 个人资料签名 | 文本 | 本地过滤 + 服务器端 msgSecCheck |
| 个人空间描述 | 文本 | 本地过滤 + 服务器端 msgSecCheck |
| 用户头像上传 | 图片 | 服务器端 imgSecCheck |
| 用户分享卡片文案 | 文本 | 本地过滤 + 服务器端 msgSecCheck |
---
## 需求
### 需求 1：客户端本地敏感词过滤
**用户故事：** 作为一名玩家，我希望在输入内容时能够即时收到不当内容的提示，以便我能够及时修改而不必等待服务器审核结果。
#### 验收标准
1. WHEN 用户在任意文本输入框中输入内容 AND 输入内容包含本地敏感词库中的违规词汇 THEN 系统 SHALL 立即在输入框下方显示"内容包含违规信息，请修改"的提示信息
2. WHEN 用户输入的内容通过本地敏感词过滤 AND 用户提交内容 THEN 系统 SHALL 将内容发送至服务器端进行二次审核
3. IF 本地敏感词库匹配到违规内容 THEN 系统 SHALL 阻止该内容的提交，提交按钮置灰或点击后提示违规
4. WHEN 系统初始化时 THEN 系统 SHALL 从服务器拉取最新的敏感词库并缓存到本地，缓存有效期不超过 24 小时
5. WHEN 本地敏感词库缓存过期或拉取失败 THEN 系统 SHALL 使用内置的兜底敏感词列表（硬编码的基础违规词库）继续工作
### 需求 2：服务器端文本内容安全审核（msgSecCheck）
**用户故事：** 作为一名游戏运营者，我希望所有用户提交的文本内容都经过微信官方内容安全 API 审核，以便确保内容审核的准确性和合规性。
#### 验收标准
1. WHEN 服务器接收到用户提交的文本内容（昵称、聊天消息、签名、描述等） THEN 系统 SHALL 在将内容存储或转发之前，调用微信 `msgSecCheck` API 进行审核
2. IF `msgSecCheck` 返回结果为内容违规 THEN 系统 SHALL 拒绝该内容的存储/转发，并向客户端返回错误码和"内容违规，请修改"的提示
3. IF `msgSecCheck` 返回结果为内容安全 THEN 系统 SHALL 允许该内容正常存储/转发
4. IF `msgSecCheck` API 调用失败（网络超时、服务不可用等） THEN 系统 SHALL 拒绝该内容的提交，返回"审核服务暂时不可用，请稍后再试"，并记录错误日志
5. WHEN 调用 `msgSecCheck` API THEN 系统 SHALL 传递用户的 `openid` 和 `scene` 值（昵称场景=1，聊天场景=2，签名场景=3，描述场景=4），以便微信进行精准审核
6. WHEN 服务器调用 `msgSecCheck` THEN 系统 SHALL 在 3 秒内完成审核并返回结果，超时则按审核失败处理
### 需求 3：服务器端图片内容安全审核（imgSecCheck）
**用户故事：** 作为一名游戏运营者，我希望用户上传的图片（如头像）经过微信官方图片安全 API 审核，以便防止违规图片传播。
#### 验收标准
1. WHEN 服务器接收到用户上传的图片（头像等） THEN 系统 SHALL 在将图片存储或展示之前，调用微信 `imgSecCheck` API 进行审核
2. IF `imgSecCheck` 返回结果为图片违规 THEN 系统 SHALL 拒绝该图片的存储/展示，并向客户端返回"图片内容违规，请更换"的提示
3. IF `imgSecCheck` 返回结果为图片安全 THEN 系统 SHALL 允许该图片正常存储/展示
4. IF `imgSecCheck` API 调用失败 THEN 系统 SHALL 拒绝该图片的上传，返回"审核服务暂时不可用，请稍后再试"
5. IF 用户上传的图片大小超过 1MB THEN 系统 SHALL 在调用审核前拒绝并提示"图片大小不能超过1MB"
### 需求 4：聊天室消息实时审核
**用户故事：** 作为一名玩家，我希望聊天室中的消息都是安全的，以便我能在良好的环境中与其他玩家交流。
#### 验收标准
1. WHEN 用户在聊天室发送消息 THEN 客户端 SHALL 先进行本地敏感词过滤，通过后再发送至服务器
2. WHEN 服务器接收到聊天消息 THEN 系统 SHALL 先调用 `msgSecCheck` 审核，审核通过后再将消息广播给同房间/队伍的其他玩家
3. IF 聊天消息审核未通过 THEN 系统 SHALL 仅向发送者返回"消息发送失败：内容违规"提示，不广播该消息
4. WHEN 聊天消息正在服务器审核中 THEN 系统 SHALL 在客户端显示"发送中..."状态，审核通过后显示为已发送
5. IF 聊天消息审核耗时超过 3 秒 THEN 系统 SHALL 显示"发送超时"并允许用户重试
### 需求 5：昵称设置与修改审核
**用户故事：** 作为一名玩家，我希望设置一个合规的昵称，以便其他玩家能看到我的身份标识。
#### 验收标准
1. WHEN 用户首次设置或修改昵称 THEN 客户端 SHALL 先进行本地敏感词过滤，通过后提交至服务器
2. WHEN 服务器接收到昵称修改请求 THEN 系统 SHALL 调用 `msgSecCheck`（scene=1）进行审核
3. IF 昵称审核通过 THEN 系统 SHALL 更新用户昵称并返回成功
4. IF 昵称审核未通过 THEN 系统 SHALL 返回错误，客户端提示"昵称包含违规内容，请重新输入"
5. IF 用户昵称长度超过 20 个字符 THEN 系统 SHALL 在客户端直接拒绝并提示"昵称长度不能超过20个字符"
6. IF 用户昵称长度少于 2 个字符 THEN 系统 SHALL 在客户端直接拒绝并提示"昵称长度不能少于2个字符"
### 需求 6：个人资料签名与空间描述审核
**用户故事：** 作为一名玩家，我希望在个人资料中表达自己，同时确保内容合规，以便不影响其他玩家的体验。
#### 验收标准
1. WHEN 用户设置或修改个人资料签名 THEN 系统 SHALL 经本地过滤 + `msgSecCheck`（scene=3）双重审核
2. WHEN 用户设置或修改个人空间描述 THEN 系统 SHALL 经本地过滤 + `msgSecCheck`（scene=4）双重审核
3. IF 签名或描述审核未通过 THEN 系统 SHALL 返回错误并提示"内容包含违规信息，请修改"
4. IF 个人资料签名长度超过 50 个字符 THEN 系统 SHALL 在客户端直接拒绝
5. IF 个人空间描述长度超过 200 个字符 THEN 系统 SHALL 在客户端直接拒绝
### 需求 7：违规记录与处罚机制
**用户故事：** 作为一名游戏运营者，我希望对多次违规的用户进行处罚，以便维护游戏环境的健康。
#### 验收标准
1. WHEN 用户的提交内容被审核判定为违规 THEN 系统 SHALL 记录违规日志，包含用户ID、违规内容、违规类型、时间戳
2. IF 用户累计违规次数达到 3 次 THEN 系统 SHALL 对该用户实施 24 小时禁言处罚
3. IF 用户累计违规次数达到 5 次 THEN 系统 SHALL 对该用户实施 7 天禁言处罚
4. IF 用户累计违规次数达到 10 次 THEN 系统 SHALL 对该用户实施永久禁言处罚
5. WHEN 用户处于禁言状态 AND 尝试发送聊天消息 THEN 系统 SHALL 提示"您已被禁言，剩余时间：X小时X分钟"
6. WHEN 用户处于禁言状态 AND 尝试修改昵称/签名/描述 THEN 系统 SHALL 提示"由于违规行为，您暂无法修改个人信息"
7. WHEN 禁言期满 THEN 系统 SHALL 自动解除禁言状态，并重置当前处罚级别的计数
### 需求 8：已有违规内容的清理与举报
**用户故事：** 作为一名玩家，我希望能够举报看到的不当内容，以便运营团队及时处理。
#### 验收标准
1. WHEN 玩家点击某条聊天消息或个人资料旁的举报按钮 THEN 系统 SHALL 弹出举报原因选择界面（政治有害/色情低俗/赌博诈骗/其他）
2. WHEN 玩家提交举报 THEN 系统 SHALL 将举报信息发送至服务器，包含被举报内容、举报原因、举报人信息
3. IF 同一条内容被 3 名以上不同用户举报 THEN 系统 SHALL 自动对该内容进行下线处理（隐藏），并标记待人工复核
4. WHEN 运营人员在后台对举报内容确认违规 THEN 系统 SHALL 对内容发布者按需求 7 的规则累计违规次数
5. WHEN 内容被自动下线或人工删除 THEN 系统 SHALL 将该用户的该字段内容重置为默认值（昵称恢复为"玩家+随机数"，签名/描述清空）
### 需求 9：服务器端审核服务架构
**用户故事：** 作为一名开发者，我希望服务器端的内容审核服务有清晰的架构和可靠的接口，以便各业务模块能够方便地接入审核能力。
#### 验收标准
1. WHEN 服务器启动时 THEN 系统 SHALL 初始化微信 Access Token 管理器，自动获取和刷新 token（有效期 2 小时，提前 5 分钟刷新）
2. WHEN 业务模块需要审核文本内容 THEN 系统 SHALL 提供统一的 `checkTextContent(openid, content, scene)` 异步方法
3. WHEN 业务模块需要审核图片内容 THEN 系统 SHALL 提供统一的 `checkImageContent(imageBuffer)` 异步方法
4. IF 微信 API 调用频率超过限制（msgSecCheck: 5000次/分钟） THEN 系统 SHALL 实施请求排队机制，避免超出频率限制
5. WHEN 服务器接收到审核请求 THEN 系统 SHALL 记录审核日志（请求时间、用户ID、内容摘要、审核结果），日志保留至少 180 天
6. IF Access Token 获取失败 THEN 系统 SHALL 重试最多 3 次，每次间隔递增（2s, 4s, 8s），全部失败后标记审核服务不可用
### 需求 10：客户端 ContentSecurityManager 集成
**用户故事：** 作为一名开发者，我希望客户端有一个统一的内容安全管理器，以便各场景能方便地调用内容审核功能。
#### 验收标准
1. WHEN 游戏初始化时 THEN 系统 SHALL 创建 `ContentSecurityManager` 实例并挂载到 `GameGlobal`
2. WHEN 任意场景需要验证用户文本输入 THEN 该场景 SHALL 调用 `GameGlobal.contentSecurityManager.checkLocalText(content)` 进行本地校验
3. IF 本地校验通过 THEN 该场景 SHALL 将内容提交至服务器进行二次审核
4. IF 本地校验未通过 THEN 该场景 SHALL 显示具体的违规提示，不向服务器发送请求
5. WHEN `ContentSecurityManager` 初始化时 THEN 系统 SHALL 从服务器拉取最新敏感词库，拉取失败时使用内置兜底词库
6. WHEN 敏感词库更新接口被调用 THEN 系统 SHALL 增量更新本地缓存，不影响正在进行的审核操作
---
## 非功能性需求
### 性能要求
- 本地敏感词过滤应在 50ms 内完成
- 服务器端审核接口响应时间应 ≤ 3 秒（含微信 API 调用时间）
- 敏感词库拉取不应阻塞游戏主线程
### 安全要求
- 违规日志中的用户内容应脱敏存储（仅保留前3个和后3个字符，中间用***替代）
- Access Token 不得在日志中明文记录
- 举报人信息应对被举报者保密
### 可用性要求
- 审核服务不可用时，系统应拒绝所有UGC提交（安全优先于可用性）
- 本地敏感词库应内置至少 500 个基础违规词汇作为兜底
.codebuddy/plan/content-security/task-item.md
+67
View File
@@ -0,0 +1,67 @@
# 实施计划 — 用户生成内容（UGC）安全审核系统
- [ ] 1. 搭建服务器端审核服务核心架构
- 创建 `server/services/wechatTokenManager.js`：实现微信 Access Token 自动获取与刷新（2小时有效期，提前5分钟刷新），获取失败时指数退避重试（2s/4s/8s），全部失败标记服务不可用
- 创建 `server/services/contentSecurityService.js`：实现统一审核方法 `checkTextContent(openid, content, scene)` 和 `checkImageContent(imageBuffer)`，封装 `msgSecCheck` 和 `imgSecCheck` API 调用，3秒超时处理，频率限制排队（5000次/分钟）
- 创建 `server/services/auditLogger.js`：实现审核日志记录（请求时间、用户ID、内容脱敏摘要、审核结果），日志保留180天，Access Token 不得明文记录
- _需求：9.1、9.2、9.3、9.4、9.5、9.6_
- [ ] 2. 实现服务器端 HTTP API 与敏感词库接口
- 在 `server/index.js` 中新增 HTTP 服务（Express），提供内容审核相关 API 路由：`POST /api/content/check-text`、`POST /api/content/check-image`、`GET /api/content/sensitive-words`
- 实现敏感词库拉取接口，从服务端返回最新敏感词列表供客户端缓存
- 各审核 API 内部调用 `contentSecurityService` 进行审核，审核不可用时拒绝请求并返回明确错误码
- _需求：2.1、2.4、3.1、3.4、1.4_
- [ ] 3. 实现违规记录与处罚机制
- 创建 `server/services/violationService.js`：实现违规日志记录（用户ID、违规内容、违规类型、时间戳），累计违规次数统计
- 实现禁言处罚逻辑：3次→24小时禁言，5次→7天禁言，10次→永久禁言；禁言期满自动解除并重置当前处罚级别计数
- 在审核 API 中集成违规记录：`msgSecCheck`/`imgSecCheck` 违规时自动调用 violationService 记录并触发处罚
- 添加禁言状态查询接口 `GET /api/user/mute-status`，返回是否禁言及剩余时间
- _需求：7.1、7.2、7.3、7.4、7.5、7.6、7.7_
- [ ] 4. 实现举报功能与违规内容自动下线
- 创建 `server/services/reportService.js`：实现举报提交（被举报内容、举报原因、举报人信息），举报人信息保密存储
- 实现自动下线逻辑：同一条内容被3名以上不同用户举报时自动隐藏，标记待人工复核
- 实现内容重置逻辑：内容被下线或删除时，昵称恢复为"玩家+随机数"，签名/描述清空
- 添加举报 API：`POST /api/content/report`，举报原因枚举（政治有害/色情低俗/赌博诈骗/其他）
- _需求：8.1、8.2、8.3、8.4、8.5_
- [ ] 5. 实现客户端 ContentSecurityManager
- 创建 `js/managers/ContentSecurityManager.js`：实现本地敏感词过滤方法 `checkLocalText(content)`，50ms 内完成匹配
- 实现敏感词库远程拉取与本地缓存（24小时有效期），拉取失败使用内置兜底词库（硬编码基础违规词汇）
- 实现增量词库更新方法，不阻塞正在进行的审核操作
- 在 `GameGlobal.js` 中初始化并挂载 `contentSecurityManager` 实例
- _需求：1.1、1.2、1.3、1.4、1.5、10.1、10.2、10.3、10.4、10.5、10.6_
- [ ] 6. 集成昵称设置与修改审核流程
- 在昵称设置/修改 UI 中添加本地敏感词实时校验，违规时输入框下方提示"内容包含违规信息，请修改"，提交按钮置灰
- 添加昵称长度前端校验：2~20字符，不满足时即时提示
- 昵称提交时调用服务器 `POST /api/content/check-text`（scene=1），审核未通过提示"昵称包含违规内容，请重新输入"
- 禁言状态下尝试修改昵称时提示"由于违规行为，您暂无法修改个人信息"
- _需求：5.1、5.2、5.3、5.4、5.5、5.6、7.6_
- [ ] 7. 集成聊天室消息实时审核流程
- 在聊天发送流程中添加本地敏感词校验，违规时阻止发送并提示
- 聊天消息提交至服务器后，服务器先调用 `msgSecCheck`（scene=2）审核，通过后再广播；未通过仅向发送者返回"消息发送失败：内容违规"
- 客户端实现"发送中..."状态显示，审核通过后切换为已发送；超时3秒显示"发送超时"并允许重试
- 禁言用户发送消息时提示"您已被禁言，剩余时间：X小时X分钟"
- _需求：4.1、4.2、4.3、4.4、4.5、7.5_
- [ ] 8. 集成个人资料签名与空间描述审核流程
- 在签名/描述编辑 UI 中添加本地敏感词实时校验与长度限制（签名≤50字符，描述≤200字符）
- 签名提交调用 `msgSecCheck`（scene=3），描述提交调用 `msgSecCheck`（scene=4），审核未通过提示"内容包含违规信息，请修改"
- 禁言状态下尝试修改签名/描述时提示"由于违规行为，您暂无法修改个人信息"
- _需求：6.1、6.2、6.3、6.4、6.5、7.6_
- [ ] 9. 集成头像上传图片审核与举报 UI
- 实现头像上传流程：客户端选择图片后先校验大小（≤1MB），上传至服务器调用 `imgSecCheck` 审核，违规提示"图片内容违规，请更换"
- 实现举报 UI：聊天消息和个人资料旁添加举报按钮，点击弹出举报原因选择界面（政治有害/色情低俗/赌博诈骗/其他）
- 举报提交调用 `POST /api/content/report`，成功后提示"举报已提交"
- _需求：3.1、3.2、3.3、3.4、3.5、8.1、8.2_
- [ ] 10. 端到端集成测试与日志验证
- 编写服务器端审核服务单元测试：Token管理、msgSecCheck/imgSecCheck 调用与超时、频率限制、违规记录与禁言处罚
- 编写客户端 ContentSecurityManager 单元测试：本地敏感词过滤、词库缓存与更新、兜底词库降级
- 端到端测试：昵称修改→聊天消息→签名修改→头像上传→举报→自动下线→禁言处罚全流程验证
- 验证审核日志脱敏存储（仅保留前3后3字符）和日志保留策略
- _需求：9.5、7.1、1.1、2.1、3.1、8.3_