🍋 柠檬剧场 · 二期

边界清单 AI编程规范 CLAUDE.md Go + Gin
v1.0 · 开发基线
📅 发布日期 2026-08-01 👥 适用团队 后端 · 前端 · 运维 🎯 目标 统一AI协作基线 📁 仓库位置 根目录 /BOUNDARIES.md + /CLAUDE.md

🔒 一、完整边界清单

以下硬性约束必须写入项目根目录 BOUNDARIES.md,所有开发(含AI生成)必须遵守。

1.1 基础设施边界

维度强制约束违规后果
数据库连接池MaxOpenConns=50, MaxIdleConns=20RDS连接耗尽,服务熔断
HTTP超时调用 Lilishop/一期PHP: 3s;调用 DeepSeek: 5s超时中断,强制返回兜底
Redis缓存首页剧集列表缓存 10min;用户进度缓存 30min(写回MySQL)缓存失效时查库必须限流
分布式锁所有余额/库存变动必须使用 Redis Redlock,锁超时 ≤2s并发超卖/超兑
消息队列使用 Redis Streams / Kafka,必须配置消费者重试(指数退避)任务丢失或重复消费

1.2 安全边界

维度强制约束违规后果
接口鉴权除登录/注册外,所有接口必须校验 JWT,并验证用户/CP身份越权访问
SQL注入防护必须使用 ORM 参数化查询,禁止字符串拼接数据泄露/删库
敏感数据数据库密码、API Key、微信密钥 只走环境变量,禁止硬编码密钥泄露
防重放攻击所有回调接口(如广告/支付)必须验证 nonce + timestamp + sign资金被刷
日志脱敏日志中不得打印手机号、身份证、密码等明文隐私合规风险

1.3 业务边界

维度强制约束违规后果
CP内容上架短剧 status 必须为 approved 才可被用户端检索未审核剧集展示,触发合规红线
商品绑定校验绑定的SKU必须属于该CP在Lilishop的卖家ID绑定其他卖家商品,引发财务纠纷
结算锁定CP结算账单生成后,该周期内订单数据 禁止物理删除对账不平,法律风险
CP权限隔离CP管理员只能查询/修改 cp_id 等于自己的数据越权查看其他CP敏感商业信息
弹幕/评论审核采用“先发后审”模式,异步送广电审核,违规后撤回并通知合规风险
金币发放单设备/单用户 日上限20元,必须实时风控校验营销成本失控

1.4 限流与降级边界

维度强制约束违规后果
DeepSeek限流单用户 1次/5s;全局限流 Flash 2500并发超出返回429,提示稍后再试
OpenIM消息单群 20条/s;单用户 5条/s超出丢弃并记录,防垃圾轰炸
广电审核异步队列积压超过 10,000条 触发报警人工介入扩容消费者
熔断降级调用外部依赖(Lilishop/PHP)失败率 >50% 时,自动熔断并返回兜底级联故障
AI排队超时DeepSeek 排队超过 5s 直接返回预置兜底话术,不计费用户体验下降

1.5 数据一致性边界

维度强制约束违规后果
跨端进度同步播放进度通过 UnionID 关联,iOS/Android 实时同步用户体验割裂
订单与结算一致性订单支付成功后,结算明细必须 事务写入,不得丢失财务差错
历史数据迁移一期数据迁移需提供 回滚脚本,并验证数据完整性数据丢失

🤖 二、AI编程启动提示词(多场景)

以下提示词应复制到与AI(Cursor、Copilot、DeepSeek等)对话的开头,强制执行边界。

🔹 通用基础提示词(适用于所有模块)
你是柠檬剧场二期Go服务的开发助手。硬性约束: - HTTP调用超时:Lilishop/一期PHP ≤3s,DeepSeek ≤5s。 - 数据库连接池:MaxOpenConns=50,MaxIdleConns=20。 - 分布式锁:所有余额/库存变动必须用Redis Redlock。 - 缓存:首页列表缓存10min,用户进度缓存30min(写回MySQL)。 - 日志:禁止打印敏感信息,使用结构化日志(logrus/zap)。 - 错误处理:所有error必须上抛或记录,禁止空白catch。 - 环境变量:所有密钥从环境变量读取,禁止硬编码。 - 每次生成代码前,先对照BOUNDARIES.md检查合规性。
🔸 CP模块专用(内容/审核服务)
在基础约束之上,CP模块强制: - 短剧status字段必须为“pending / approved / rejected”,只有approved才可被用户端查询。 - CP上传短剧时,视频文件必须转存OSS,且记录oss_key。 - 审核流采用异步任务,调用广电审核接口(Mock或真实),审核结果通过系统消息通知CP。 - CP注册时需上传资质文件,审核通过后才可创建Lilishop卖家账号(若自动化不可用则人工同步)。
🔸 电商模块专用(购物车/下单/分账)
在基础约束之上,电商模块强制: - 本地购物车表 cart_items 存储于MySQL,加购时不锁库存。 - 下单时调用Lilishop扣库存API,必须处理超时和重试(最多2次)。 - 下单成功后,立即写入结算明细表(状态=冻结),待用户确认收货后转为待结算。 - 商品绑定必须校验SKU所属卖家与当前CP一致,否则拒绝绑定。
🔸 AI对话模块专用(DeepSeek)
在基础约束之上,AI模块强制: - 使用DeepSeek Flash模型,全局限流2500并发,单用户限流1次/5秒。 - 请求先入Redis队列,设置5秒超时,超时则返回预置兜底话术(从Redis话术库读取)。 - 缓存策略:相同用户+剧集+小时级的请求直接返回缓存,减少调用。
🔸 社交模块专用(OpenIM/弹幕/评论)
在基础约束之上,社交模块强制: - 弹幕/评论采用“先发后审”,发布时status=active,异步送广电审核。 - 审核违规的,通过OpenIM系统消息通知用户,并软删除内容。 - OpenIM用户创建采用异步方式(登录成功后发消息队列),指数退避重试,不阻塞登录。 - 剧群创建归属CP,CP管理员有禁言/删除权限,但操作需留日志。

📘 三、项目规范(CLAUDE.md)

此部分内容应存入项目根目录 CLAUDE.md,供AI和团队成员共同遵守。

3.1 目录结构

柠檬剧场二期采用 Monorepo 结构: . ├── apps/ # 各微服务 │ ├── gateway/ # Go Gin 网关 │ ├── user-service/ # 用户/登录/UnionID │ ├── content-service/ # 短剧/CP/审核 │ ├── asset-service/ # 金币/余额 │ ├── settlement-service/ # 结算分账 │ ├── social-service/ # 弹幕/评论/OpenIM │ ├── ai-service/ # DeepSeek对话 │ └── ecom-service/ # 购物车/电商 ├── api/ # OpenAPI 定义 (openapi.yaml) ├── pkg/ # 公共库 │ ├── db/ # 数据库连接池 │ ├── redis/ # 分布式锁/缓存 │ ├── httpclient/ # 带超时/熔断的HTTP客户端 │ ├── logger/ # 结构化日志 │ └── utils/ # 工具函数 ├── migrations/ # 数据库迁移脚本 (*.up.sql / *.down.sql) ├── deployments/ # Docker/K8s 部署文件 ├── scripts/ # 构建/测试/迁移脚本 ├── .gitea/workflows/ # CI/CD流水线 ├── BOUNDARIES.md # 边界清单(本报告第一部分) └── CLAUDE.md # 项目规范(本文件)

3.2 命名规范

3.3 Git工作流与Commit规范

3.4 代码风格与质量

3.5 测试规范

3.6 CI/CD 流水线(Gitea Actions)

3.7 文档与注释

3.8 依赖管理

🛠️ 四、开发容器与工具链

🐳 DevContainer
已配置 Go 1.22 + MySQL 8 + Redis 7 + OpenIM(轻量) + Lilishop(Mock模式),使用docker-compose一键启动。
🔁 Gitea CI/CD
已搭建Actions流水线,支持并行Lint/Test/Build,自动推送镜像到阿里云ACR。
🧪 Mock服务
DeepSeek、广电审核、微信支付等外部依赖均有Mock端点,可在 /mock 包中配置开关。
📦 制品管理
使用阿里云容器镜像服务(ACR)存储镜像,并配置生命周期清理策略。

✅ 五、上线前检查清单

🤝 六、团队协作约定

🎉 以上所有条目均已评审通过,即日起作为柠檬剧场二期开发的强制性基线。