📅 发布日期 2026-08-01
👥 适用团队 后端 · 前端 · 运维
🎯 目标 统一AI协作基线
📁 仓库位置 根目录 /BOUNDARIES.md + /CLAUDE.md
🔒 一、完整边界清单
以下硬性约束必须写入项目根目录 BOUNDARIES.md,所有开发(含AI生成)必须遵守。
1.1 基础设施边界
| 维度 | 强制约束 | 违规后果 |
| 数据库连接池 | MaxOpenConns=50, MaxIdleConns=20 | RDS连接耗尽,服务熔断 |
| 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 命名规范
- Go代码:遵循标准Go命名(驼峰,首字母大写公开,小写私有)。
- API路径:RESTful风格,如
POST /api/v1/cp/dramas,路径全部小写,单词用 - 分隔。
- 数据库表:小写+下划线,如
cp_accounts,主键 id,时间字段 created_at / updated_at。
- 环境变量:大写+下划线,如
DB_DSN, REDIS_ADDR。
3.3 Git工作流与Commit规范
- 分支模型:
main 为生产分支,develop 为集成分支(可选),所有开发从 main 拉 feature/xxx 分支,合并前需通过CI并至少一位同事Code Review。
- Commit格式:
<type>: <subject>,type可选 feat, fix, docs, style, refactor, test, chore。例如:feat: 添加CP上传短剧接口。
- 合并策略:使用 Squash merge,保持主分支历史整洁。
3.4 代码风格与质量
- Go代码必须通过
golangci-lint 检查(配置在 .golangci.yml)。
- 单元测试覆盖率目标 ≥70%,核心业务模块(资产、结算)≥85%。
- 所有外部调用(DB、Redis、HTTP)必须添加超时和重试(除幂等操作外)。
- 错误处理:使用
errors.Wrap 添加上下文,避免裸返回。
3.5 测试规范
- 单元测试:使用
testing 标准库 + testify 断言,Mock外部依赖(用 gomock 或 sqlmock)。
- 集成测试:使用
testcontainers 启动MySQL/Redis容器,测试真实交互。
- E2E测试:使用
go test 加 net/http/httptest 模拟完整调用链。
3.6 CI/CD 流水线(Gitea Actions)
- 每个 Pull Request 自动触发
ci.yaml,包含:Lint → Test → Build。
- 合并到
main 后自动构建 Docker 镜像并推送到阿里云ACR,并触发 staging 环境部署(蓝绿部署或滚动更新)。
- 设置质量门禁:测试覆盖率低于70%或lint有错误时,阻止合并。
3.7 文档与注释
- 所有公开函数、接口、结构体必须有 Godoc 风格的注释。
- API 文档由
openapi.yaml 生成,前端和后端共同维护。
- 复杂业务逻辑必须在代码中添加注释说明设计意图,便于AI理解。
3.8 依赖管理
- Go module 管理,定期运行
go mod tidy 和 go mod vendor(可选)。
- 第三方库升级前需评审,确保兼容性和安全性。
🛠️ 四、开发容器与工具链
🐳 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)存储镜像,并配置生命周期清理策略。
✅ 五、上线前检查清单
- 边界合规:所有代码已对照
BOUNDARIES.md 逐项检查。
- 安全扫描:使用
gosec 扫描代码漏洞,并修复所有中高危问题。
- 性能测试:使用
wrk 或 vegeta 对核心接口(如首页列表、金币发放)进行压力测试,确保在目标QPS下资源占用正常。
- 数据迁移验证:执行迁移脚本并核对数据一致性,准备回滚方案。
- 监控告警:接入阿里云ARMS或Prometheus,配置关键指标(错误率、延迟、队列积压)告警。
- 降级演练:模拟Lilishop、DeepSeek、MySQL等依赖故障,验证熔断和兜底机制生效。
🤝 六、团队协作约定
- 每日站会:同步进展,重点讨论AI生成代码的Review反馈。
- Code Review重点:检查边界合规、安全漏洞、业务逻辑正确性,并记录常见AI错误模式。
- 知识沉淀:将AI生成的高质量代码片段和常见陷阱整理成Wiki,持续优化提示词。
- 分支保护:
main 分支设置保护,仅允许通过CI和至少1人批准的PR合并。
🎉 以上所有条目均已评审通过,即日起作为柠檬剧场二期开发的强制性基线。