tankwar_proj/.codebuddy/plan/content-security/requirements.md

需求文档 — 用户生成内容（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 个基础违规词汇作为兜底