# 02 管理后台通用操作与 RBAC（for AI Agents）

> 关联代码：web/src/layouts/AdminLayout.vue（菜单）、web/src/router/index.ts（路由）、web/src/views/system/（RBAC 页面）、web/src/api/http.ts（请求层）、web/src/stores/auth.ts（登录态）
> 后台技术栈：Vue 3 + TypeScript + Naive UI；组件库积木为 n-card / n-data-table / n-modal / n-form / n-tag / n-popconfirm。

====================================================================
1. 功能概述
====================================================================

管理后台（生产 https://mp.cdjchd.com/，本地 dev http://localhost:5173）是运营/财务/风控/超管的统一操作端。本档说明：登录与布局、完整菜单地图、后台账号与角色权限（RBAC）管理、全局交互约定。各业务页面的具体操作见对应功能文档。

====================================================================
2. 底层逻辑
====================================================================

2.1 登录态
- 登录：POST /api/admin/auth/login → token 存 Pinia + localStorage（key = lottery_admin_token）；请求拦截器统一加 Authorization: Bearer <token>。
- 路由守卫：进入受保护路由时调 GET /api/admin/auth/me 拉取用户信息与权限码数组（store.can(code) = permissions.includes）。
- 任何接口返回 HTTP 401 → 自动清 token 跳 /login。token 有效期默认 24h；后端每请求回查账号状态，禁用即时失效。

2.2 RBAC 模型（后端 internal/service/rbac/、middleware/rbac.go）
- User（后台账号，多角色多对多）— Role — Permission（权限码，全量声明在 internal/service/rbac/permissions.go，95 个，分 system/business/common 组）。
- 中间件链：admin 组 = JWT(kind=admin) + Audit（异步写 OperationLog 审计日志）+ RequirePerm(db, "权限码")。
- 预置角色（启动一次性种子，configs 表标记 rbac.preset_roles_seeded；删了不复活）：admin（超管，全量权限）/ operations（运营）/ finance（财务）/ risk（风控）。
- 超管保护不变量（后端强制，前端同步锁定）：
  - code=admin 的超管角色：权限与关联用户锁定，不可编辑、不可删除
  - 不可删除/降停最后一个可登录的超管用户（删/停/降角色均拒绝）
  - 用户被删时自动解绑角色（防孤儿关联），角色被删时自动解绑用户
- 前端权限现状（重要）：侧边栏菜单不按权限过滤、无按钮级权限指令；无权限的操作点了会被后端拒绝（code 2004/1003）。Agent 模拟后台操作前应先调 /api/admin/auth/me 确认权限。

2.3 通用交互约定（Agent 用浏览器操作后台时按此预期）
- 列表页统一模式：顶部筛选区（n-select/n-input + 查询/重置）→ n-data-table 远程分页 → 行操作按钮列；部分页面带「导出 CSV」（GET blob 下载）。
- 新建/编辑统一为 n-modal 弹窗表单（useModalForm 状态机），底部「确定/取消」。
- 高敏操作（开奖、删除活动、标记已支付、退款、发货、提现审核、用户禁用、drawbox 参数保存等）均有 dialog.warning 二次确认或 n-popconfirm。
- 跨页联动：小程序用户列表「更多」下拉通过路由 query（user_id/mp_user_id）跳转订单、地址、余额、发起人档案、命运盒子记录等页面并自动预筛选；多数列表页支持 URL query 预筛选。
- 列表接口统一返回 {list,total}（个别 items，前端 hook 兼容）；金额后端为分，前端 API 层统一做 fen↔yuan 转换（响应÷100、请求×100），页面交互一律元。

====================================================================
3. 后台操作
====================================================================

3.1 登录
- 访问 /login，输入用户名/密码 → 登录成功跳 /（仪表盘）。仪表盘仅显示昵称与权限数。

3.2 菜单地图（侧边栏硬编码在 AdminLayout.vue；路由定义 web/src/router/index.ts，全部懒加载）
- 仪表盘：/ 
- 驾驶舱：运营驾驶舱 /sprint6/cockpit；财务对账 /sprint6/finance；盈亏平衡看板 /finance/breakeven；A/B 实验 /sprint6/ab；供应商 /sprint6/suppliers；跑马灯公告 /sprint6/announcements；风控中心 /sprint6/risk
- 系统管理：用户 /system/users；角色 /system/roles；权限 /system/permissions
- 裂变运营：邀请排行 /fission/leaderboard；转化漏斗 /fission/funnel；风控日志 /fission/risk；用户裂变详情 /fission/users/:id
- 积分管理：签到规则 /points/checkin；任务配置 /points/tasks；用户积分 /points/users；积分流水 /points/transactions；积分排行 /points/leaderboard
- 配置管理：
  - 功能开关总览 /config/feature-switches：按分组（内容与社区/钱包与资金/抽奖活动/营销与推广/商城）展示全局开关注册表，NSwitch 直切，关闭需二次确认弹窗。营销与推广组含「智能推广」开关（ad.smart_promo_enabled）：关闭后小程序隐藏投放入口（个人中心九宫格、抽奖详情页推广区块），已投放广告照常展示与计费。商城组含「商城购买」开关（mall.purchase_enabled）：关闭后小程序隐藏现金购买与购物车结算入口、后端拒绝新购买订单，积分兑换不受影响（见 12）。
  - 助力规则 /config/assist-rules：KV 规则表（key/标题/正文摘要/更新时间/操作）+ 新增/编辑/删除弹窗。
  - 今日奖品 /config/today-prize：标题(≤50)/描述(≤200)/关联抽奖活动/自定义封面图/自定义展示标题(≤50)。
  - 官方大奖 /config/featured-lottery：标题(≤50)。
  - 签到卡片文案 /config/checkin-card：左卡片标题(≤50)/消耗文案前缀(≤20)/消耗文案后缀(≤20)/右卡片标题(≤100)。
  - 充值配置 /config/recharge：充值入口开关 + 档位列表（金额元/好运币数），赠送按基准汇率自动计算。
  - 免责说明 /config/disclaimer：富文本编辑器。
  - 另有不在菜单的可直达页：联系客服 /config/contact-info（标题/描述/二维码上传）、天天抽奖 /config/daily-lottery（标题/描述）、动态功能设置 /config/dynamic。
- 订单管理：/orders
- 资金管理：提现设置 /config/wallet；提现规则配置 /config/withdraw-disclaimer；提现审核 /wallet/withdrawals；红包发放记录 /wallet/payouts；用户余额 /wallet/users；余额流水 /wallet/transactions
- 抽奖管理：普通抽奖 /lotteries（+/create、/:id、/:id/edit）；签到抽奖 /signin-lottery（+/:id、/:id/records、/:id/winners）；幸运抽奖 /lucky-lottery（+/:id）；年会抽奖 /annual（+/:id）；投诉管理 /complaints
- 用户与档案：小程序用户 /mp/users；发起人档案 /organizer-profiles（+/:id）；地址管理 /addresses
- 展示券管理：套餐管理 /promo-slot/products；全局配置 /promo-slot/config；手气广场审核 /promo-slot/reviews
- 高级版订阅：订阅套餐 /subscription/plans；玩法案例模板 /play-template-cases
- 问卷管理：题库管理 /questionnaire/questions；问卷管理 /questionnaire/questionnaires
- 商城管理：商品管理 /mall/products；商品分类 /mall/categories；优惠券模板 /mall/coupons；评价审核 /mall/reviews
- 命运盒子：奖池管理 /drawbox/prizes；库存看板 /drawbox/stock；试抽面板 /drawbox/trial；参数配置 /drawbox/config；中奖记录 /drawbox/records
- 智能推广：/ads
- 常见问题：模块 /faq/modules；分类 /faq/categories；条目 /faq/items

3.3 后台用户管理（/system/users，views/system/UserList.vue）
- 表格列：ID/用户名/昵称/状态/角色/操作。
- 行操作：编辑、删除。
- 「新建用户」弹窗：用户名 + 密码 + 昵称 + 多选角色。
- 「编辑」弹窗：昵称、状态（启用/停用）、重置密码、多选角色。
- 「删除」：需保留至少一个可登录超管（后端强制拒绝）。
- API：/api/admin/users CRUD，权限码 user:list/create/update/delete。

3.4 角色管理（/system/roles，views/system/RoleList.vue）
- 表格列：ID/代码/名称/内置/权限数/用户数/操作。
- 行操作：编辑、删除。
- 「新建角色」：名称 + code + 描述 + 按分组多选权限 + 多选关联用户。
- 「编辑」：同上；内置角色（IsBuiltin）可改名改权限可删除（一次性种子），但 code=admin 超管角色锁定不可改不可删。
- 「删除」：自动解绑该角色下的用户；拒绝影响最后超管的删除。
- 语义约定：role_ids/user_ids 传 null=不改、[]=清空、非空=替换。
- API：/api/admin/roles CRUD、GET /api/admin/permissions；权限码 role:*、permission:list。

3.5 权限列表（/system/permissions）
- 只读表格（ID/代码/名称/分组）。查「某操作需要哪个权限码」用这张表或直接读 internal/service/rbac/permissions.go。

====================================================================
4. 小程序端操作
====================================================================

无。RBAC 仅作用于管理后台。

====================================================================
5. API 速查
====================================================================

POST /api/admin/auth/login              登录（公开）
GET  /api/admin/auth/me                 当前用户 + 权限码数组
GET|POST /api/admin/users               用户列表 / 新建（user:list/create）
PUT|DELETE /api/admin/users/:id         更新 / 删除（user:update/delete）
GET|POST /api/admin/roles               角色列表 / 新建（role:list/create）
PUT|DELETE /api/admin/roles/:id         更新 / 删除（role:update/delete）
GET  /api/admin/permissions             权限码全量（permission:list）
POST /api/admin/upload                  文件上传（upload:file；有大小/类型限制）
GET  /api/admin/config/feature-switches 功能开关总览（config:read）
PUT  /api/admin/config/feature-switches/:key 切换功能开关（config:write）
GET|PUT /api/admin/config/recharge      充值配置（config:read/write）

====================================================================
6. 注意事项
====================================================================

- 前端零环境变量：API 地址完全依赖同源/代理；本地 dev 由 vite 代理 /api 与 /static 到 http://localhost:8080。
- 忘记超管密码：无自助找回；需直接改库（users.password_hash 为 bcrypt）或设 ADMIN_INIT_PASSWORD 后初始化新环境。
- 「标记已支付」「退款」「手动开奖」等高敏操作会进审计日志（OperationLog），操作前确认业务正当性。
- 侧边栏菜单项无权限过滤：菜单可见 ≠ 可操作，以后端 403 为准。
- 上传接口返回相对 URL（/static/uploads/...），富文本/封面引用时直接使用该 URL。
- 后台前端所有金额字段统一为「元」：API 层自动与后端「分」互转（响应÷100、请求×100 Math.round），Agent 操作后台表单时按元输入即可。
