# 鲸彩好运（lottery-mp）LLMs.txt — AI Agent 系统操作导航

> 面向对象：需要理解并操作本系统的 AI Agent（操作管理后台页面、调用 API、理解业务底层逻辑）。
> 内容基准：本文件与 llms/ 目录下的文档基于 2026-09-14 的 master 分支代码编写；文档与代码冲突时，以代码为准。
> 线上地址：本文件 https://mp.cdjchd.com/LLMs.txt（小写别名 /llms.txt）；详情文档 https://mp.cdjchd.com/docs/llms/<文件名>。本地开发将域名替换为 http://localhost:8080。
> 使用方式：先读下方「系统速览」与「任务路由」，确定目标功能后，抓取对应详情文档链接再动手操作。

====================================================================
一、系统速览
====================================================================

产品定位
- 鲸彩好运：微信小程序抽奖营销平台。核心玩法 = 多形态抽奖裂变获客 + 现金红包钱包留存 + 商城/广告变现。
- 平台侧角色：运营/财务/风控（管理后台，RBAC 分权）；用户侧角色：抽奖发起人与参与者（小程序）。

技术形态（Monorepo 三端）
- Go 后端：cmd/server/main.go 唯一入口（服务装配 + 后台任务启动）；Gin + GORM，SQLite/MySQL 双驱动，可选 Redis（计数/限流/分布式锁/Stream 队列）。代码在 internal/{config,logger,database,model,handler,middleware,router,service}。
- Vue 3 管理后台：web/（TypeScript + Vite + Pinia + Naive UI）。生产构建产物经 web/embed.go 用 go:embed 嵌入 Go 二进制，前后端单体部署。
- 微信小程序用户端：miniprogram/（原生小程序，无分包，68 个页面，见 miniprogram/app.json）。

访问地址
- 生产：https://mp.cdjchd.com/（后台页面与 API 同域，API 统一前缀 /api）
- 本地开发：后端 http://localhost:8080；后台 dev server http://localhost:5173（vite 代理 /api 与 /static 到 8080）；小程序用微信开发者工具打开 miniprogram/（release/trial/develop 环境 API 均指向生产域名，其余指向 127.0.0.1:8080）

账号与认证
- 管理后台超管：用户名 admin；初始密码优先取环境变量 ADMIN_INIT_PASSWORD，未设置则首次启动随机生成 16 位并在启动日志打印一次（cmd/server/main.go:125），之后不再显示。
- 小程序用户：wx.login → code2session 静默登录，无账密；JWT 默认 720h。
- 三套认证互不通用：admin JWT（Kind=admin + RBAC 权限码）、mp JWT（Kind=mp）、Open API（AK/SK + HMAC 签名）。

全局约定（操作前必须知道）
- 金额单位一律为「分」（fen）；前端展示时转元。积分（心愿值/好运币）为整数个。
- API 响应统一信封 {code, msg, data}；code=0 成功；业务错误 HTTP 恒为 200，靠 code 区分；HTTP 401 = 登录失效。
- 错误码分段：1xxx 通用；2001-2099 用户域；2100-2199 整段保留给抽奖域（2111-2125 门槛类、2130s 组团、2150s 签到、2160s 幸运、2170s 每日666、2180s 助力）；3xxx 支付订单；4xxx 安全（签名/OpenAPI）。命运盒子（drawbox）使用独立码空间（1001/1002/1004/5000），仅经其专属接口返回。
- 后台高敏操作（开奖、删除、标记已支付、退款、发货、提现审核、参数熔断配置等）均有二次确认弹窗；后台 admin 组所有请求自动写审计日志（OperationLog）。
- 后台前端不做菜单/按钮级权限过滤，权限收敛靠后端 RequirePerm 校验（无权限返回 403 语义 code=2004/1003）。

====================================================================
二、任务路由（我想做 X → 读哪份文档）
====================================================================

- 了解整体架构 / 启动构建 / 认证细节 / 错误码全表 / 配置体系 / 定时任务 / 限流风控加密 → 01
- 登录后台、后台通用操作习惯（弹窗/二次确认/跨页联动）、管理后台账号与 RBAC 角色权限 → 02
- 创建/编辑/审核/开奖一场普通抽奖；组团、阶段开奖、即抽即中、大转盘玩法、年会抽奖、测试抽奖、指定中奖、留言审核、抽奖统计 → 03
- 助力玩法（enable_assist）：任务面板、助力榜、限时翻倍、助力规则文案配置 → 04
- 题库与问卷管理；抽奖绑定问卷；用户填卷闭环 → 05
- 签到抽奖（心愿换红包，连签 N 天达标开奖）→ 06
- 幸运积分抽奖（消耗积分即抽、必中券、CPS 电商跳转）→ 07
- 命运盒子（免费次数+任务、L1-L4 奖池、成本预算熔断、试抽面板）→ 08
- 每日666（每日 20:00 定时开奖）→ 09
- 用户现金余额 / 提现审核 / 商家转账到零钱 / 对账 → 10
- 统一订单 / 微信支付 / 人工标记已支付 / 发货物流 / 退款 → 11
- 商城（商品、SKU、购物车、优惠券、评价、积分兑换、CPS 外部商品）→ 12
- 积分（心愿值）体系：签到规则、任务配置、手动调整、好运币充值 → 13
- 邀请裂变 / 分享归因 / 好运合伙人 / CPA 推广员 → 14
- 智能推广（CPC 广告投放与计费）/ 展示券（手气广场付费推广）→ 15
- 用户主页与动态 / 发起人档案 / 收货地址 / 站内通知 / 投诉 / FAQ / 联系客服 → 16
- 运营驾驶舱 / 财务对账 / 盈亏平衡看板 / CPS 佣金结算 / 风控中心 / 供应商 / 跑马灯公告 → 17
- A/B 实验（变量注册表、分桶定向、变体配置、显著性分析）→ 18
- 高级版订阅 / 玩法案例模板 / Open API 密钥 → 19

====================================================================
三、文档索引
====================================================================

全部详情文档为纯文本，每份按统一结构组织：功能概述 / 底层逻辑 / 后台操作 / 小程序端操作 / API 速查 / 注意事项。以下链接线上可直接抓取（源文件位于仓库 llms/ 目录）：

- https://mp.cdjchd.com/docs/llms/01-system-overview.txt     系统总览：三端架构、启动与构建、三套认证、错误码全表、静态配置与运行时 KV 配置、定时任务清单、限流/风控/加密/审计/监控横切机制
- https://mp.cdjchd.com/docs/llms/02-admin-console.txt       管理后台通用：登录与布局、完整菜单地图、后台用户/角色/权限页面操作、RBAC 保护不变量、通用交互约定
- https://mp.cdjchd.com/docs/llms/03-lottery-core.txt        普通抽奖核心：生命周期（发起→参与→门槛→开奖→发奖履约）、五种开奖方式、八种玩法模板、测试抽奖、组团/阶段/即抽即中、指定中奖、年会、留言与统计
- https://mp.cdjchd.com/docs/llms/04-assist.txt              助力系统：enable_assist 开关、任务类型与幂等、助力榜、限时翻倍、规则文案配置
- https://mp.cdjchd.com/docs/llms/05-questionnaire.txt       题库与问卷：双端归属规则、组卷、抽奖绑定校验、填卷提交闭环（2111/2125）
- https://mp.cdjchd.com/docs/llms/06-signin-lottery.txt      签到抽奖：连签资格、状态机、开奖与红包入账、后台管理页
- https://mp.cdjchd.com/docs/llms/07-lucky-lottery.txt       幸运积分抽奖：权重库存、必中券（A/S 级）、CPS 转化追踪、商城奖品结算
- https://mp.cdjchd.com/docs/llms/08-drawbox.txt             命运盒子：九宫格抽奖、任务赚次数、幸运值/保底/新人保护、成本三档熔断、四层并发防护、A/B 接入
- https://mp.cdjchd.com/docs/llms/09-daily666.txt            每日666：KV 配置驱动、20:00 定时开奖、红包余额累积入账
- https://mp.cdjchd.com/docs/llms/10-wallet-withdrawal.txt   现金钱包与提现：Ledger 幂等账本、提现全流程与资金安全不变量、商家转账、对账自愈
- https://mp.cdjchd.com/docs/llms/11-orders-payment.txt      统一订单与支付：11 种商品类型、支付回调分发、超时关单、标记已支付/发货/物流/退款操作
- https://mp.cdjchd.com/docs/llms/12-mall.txt                商城：分类/商品/SKU/购物车/结算、优惠券模板与批量发放、评价审核、积分兑换、CPS 商品
- https://mp.cdjchd.com/docs/llms/13-points.txt              积分（心愿值）：签到规则、任务配置、流水与排行、手动调整、好运币充值（100:1）
- https://mp.cdjchd.com/docs/llms/14-fission-growth.txt      裂变增长：邀请链路与归因、分享统计、必中券、好运合伙人等级、CPA 推广员
- https://mp.cdjchd.com/docs/llms/15-promotion.txt           推广变现：CPC 智能推广（投放/审核/计费/防刷）、展示券手气广场（套餐/审核/库存）
- https://mp.cdjchd.com/docs/llms/16-user-community.txt      用户与内容：用户主页/动态、发起人档案（引流）、地址加密、通知路由、投诉、三级 FAQ、客服配置
- https://mp.cdjchd.com/docs/llms/17-finance-risk.txt        经营与风控：运营驾驶舱、财务对账、盈亏平衡看板、佣金结算、风控中心（V8 引擎与阈值）、供应商、跑马灯公告
- https://mp.cdjchd.com/docs/llms/18-ab-experiment.txt       A/B 实验：变量注册表、四维分桶、新老用户/省份定向、变体可视化配置、显著性分析、小程序消费闭环
- https://mp.cdjchd.com/docs/llms/19-subscription-openapi.txt 高级版与开放能力：订阅套餐与特性码、玩法案例模板库、Open API AK/SK 与 HMAC 调用

====================================================================
四、常用命令速查
====================================================================

后端（仓库根目录）
- make build / make run / make test
- 本地起服务前先配置 configs/config.yaml（可加 config.local.yaml 覆盖）；jwt.secret 为空或默认值时拒绝启动

管理后台（web/）
- pnpm dev（开发，端口 5173，代理到 8080）
- pnpm build（vue-tsc 类型检查 + vite 构建，产物 dist/，会被 go:embed 嵌入后端）
- pnpm test（vitest）

小程序
- 微信开发者工具导入 miniprogram/；测试后端连通性时把 utils/env.ts 指向本地（默认非正式环境走 http://127.0.0.1:8080）

其他
- 仓库内（未对外发布）的深度设计文档：docs/redpacket-wallet/、docs/signin-lottery/、docs/ad/ 等目录下的 design.md，以及 docs/鲸彩好运V11.0-产品后台操作文档.md（面向人工运营，含截图，可作功能命名参照）。这些文件仅存在于代码仓库中，无线上地址，需读源码仓库获取。
