yml2213
2a76d59a30
公告中心（前台公告列表/详情）此前完全没有站点概念，分站访客只能看到主站公告。 本次按「默认继承主站、站长可切仅本站」的口径支持分站自定义。 数据与口径： - 新增 announcements.distribution_site_id（0=主站），前台按站点隔离 - 新增 distribution_sites.announcement_mode：inherit（默认，主站+本站）/ own_only（仅本站） 后端： - 公告模块新增 ResolvePublicSiteScope：主站 [0]、inherit [0, siteID]、own_only [siteID]， 站点编码无效/已停用回落主站；列表与详情都按该范围过滤，详情不再允许跨站按 ID 读取 - 管理端公告列表支持按站点筛选（site_id：不传=全部，0=主站，>0=分站）并带出站点名 - 分销模块新增本站公告 CRUD（distribution/announcement.go）：强制 distribution_site_id=本站， 先过 ensureSiteAccess，跨站更新/删除/上下架一律 ErrAnnouncementNotFound - UpdateSiteBranding 支持 announcement_mode 切换（非法值报错，读侧非法历史值回落 inherit） - 新增权限 distribution:announcement_view|manage 并授予 super_admin/ops/finance， 站长开通时继承 ops 角色即自动获得 - 路由：站长侧 /api/distribution/announcements*，平台侧 /api/admin/distribution/announcements* 前端： - 分销后台新增「公告中心」页：来源开关（继承主站+本站 / 仅本站）、本站公告列表与 新建/编辑/发布/下架/归档/恢复/删除，空态按来源模式给出引导 - 平台后台公告页新增「站点」列与筛选，新建公告可选择归属站点（主站或指定分站代发） - 前台 PC/移动无需改动：请求已带 X-Distribution-Site-Code，后端按站点隔离，页面已有空态 测试： - 公告模块：主站/继承/仅本站三种可见范围、跨站详情拦截、无效站点回落、管理端站点筛选 - 分销模块：本站公告 CRUD 与跨站防护、公告来源开关校验与非法值容错
HFB Sys
哈夫币租号平台，面向《三角洲行动》账号租赁场景。
开发方式
- 后端：Go + Gin + GORM + MySQL + Redis
- 前端：Vue 3 + TypeScript + Vite + Element Plus
- 开发依赖：Docker Compose 启动 MySQL、Redis、MinIO
快速开始
一键启动开发版本：
./scripts/dev.sh
脚本会自动启动 MySQL、Redis、MinIO，首次初始化数据库结构，并同时启动后端、主站前后台、分销独立后台与分销专属前台。
- 主站前台地址：
http://localhost:5189 - 主站后台地址：
http://localhost:5189/admin/login（超级管理员默认admin/admin123456） - 分销管理后台：
http://localhost:5190（在主站后台“分销站点”开通站点并配置分销操作员登录） - 分销专属前台：
http://localhost:5191（独立端口隔离，支持 Host 域名与 X-Distribution-Site 头识别站点）
生产环境不使用上述端口：Caddy 按域名分流，分销管理后台固定为
https://distribution.<CADDY_DOMAIN>（见deploy/caddy/Caddyfile）。主站后台的「打开独立分销后台」与开通凭证通过构建期VITE_DISTRIBUTION_ADMIN_URL注入该地址；未配置时按当前主站域名推导。
如需拆分调试，可手动执行：
docker compose -f deploy/docker-compose.dev.yml up -d
cd backend
cp .env.example .env
go run github.com/pressly/goose/v3/cmd/goose@v3.27.1 \
-dir migrations \
mysql 'hfb:secret@tcp(127.0.0.1:13306)/hfb_sys?charset=utf8mb4&parseTime=True&loc=Local&multiStatements=true' \
up
go run ./cmd/api
cd ../frontend
npm ci
npm run dev
代码门禁
提交前或部署前在本地执行全量检查，覆盖后端 go vet / go build / go test 与前端 prettier / eslint / typecheck / vite build：
./scripts/check.sh
./scripts/deploy-prod.sh 在构建镜像前会自动调用 check.sh（本地有 go 和 npm 时）。检查未通过会中止部署；确需跳过用 --skip-check（不推荐）。check.sh 也支持 --skip-backend、--skip-frontend、--skip-tests 做局部调试。
本地门禁由 scripts/check.sh 统一执行；后端覆盖率基线由 scripts/check-backend-coverage.sh 维护。完整租赁与分销链路 e2e 已包含在 go test ./... 中，需本地 MySQL 可用。
服务探针：GET /health 仅表示进程存活；GET /health/ready 和 GET /api/health 会检查 MySQL、Redis，任一依赖不可用时返回 503。
数据库 SQL 约束、执行计划、慢查询观测、连接池和备份恢复要求见 docs/数据库SQL约束与运维.md。
需要在本地推送前自动执行同一套检查时，启用 Git hook：
bash scripts/install-git-hooks.sh
启用后，git push 会执行 scripts/check.sh；仅临时跳过时使用：
SKIP_CHECKS=1 git push
开发态短信与实名
- 后端日志使用单行可读文本。开发环境同时输出控制台和
backend/logs/app-YYYY-MM-DD.log，生产示例只输出文件以避免重复存储；可通过LOG_LEVEL=debug|info|warn|error调整级别。 - 短信验证码默认使用 mock 适配器，本地验证码会以 INFO 日志输出，手机号保持脱敏。生产环境强制使用
SMS_PROVIDER=aliyun。 - 阿里云短信需要配置
ALIYUN_ACCESS_KEY_ID、ALIYUN_ACCESS_KEY_SECRET、ALIYUN_SMS_SIGN_NAME和ALIYUN_SMS_LOGIN_TEMPLATE_CODE，模板变量名默认为code。 - 实名认证使用 mock 适配器，登录后请求
POST /api/realname/start，提交合法姓名和 18 位身份证号会直接通过。 - 实名状态可通过
GET /api/realname/status查询。 - 租号发布需要登录并完成实名认证；
POST /api/listings/{id}/submit-review会进入待审核，后台通过后才上架。 - 订单创建需要登录；开发态会直接锁定账号并进入待交接，暂不接真实支付和押金冻结。
- 账号交接已支持号主提交说明、租客确认收号，确认后订单进入租赁中。
- 归还流程已支持租客提交归还、号主确认归还，完成后账号重新上架。
- 后端已接入开发态订单超时扫描任务，会按系统配置处理交接超时、确认收号超时、逾期未归还和确认归还超时。
- 文件上传已接入 MinIO，发布账号资产截图和申诉证据可上传 JPG、PNG、WebP 或 PDF。
- MinIO 开发地址默认使用
http://localhost:19090，控制台默认使用http://localhost:19091。 - 钱包账务当前为开发态模拟流水，可通过
GET /api/wallet/balance和GET /api/wallet/ledger查看。 - 后台资金流水已接入，支持按用户、订单和业务类型查询。
- 站内信已支持订单关键节点自动写入，可通过
GET /api/notifications查看。 - 订单群聊已支持支付成功后自动创建，租客、号主和客服可在移动端消息页进入会话。
- 申诉仲裁已支持订单双方发起申诉、开发态后台落账处理。
- 系统配置已支持默认配置初始化和后台编辑，更新会写入审计日志。
- 后台已使用独立登录、图形验证码和独立管理 UI，页面入口由
VITE_ADMIN_BASE_PATH控制。 - 后台仪表盘已接入真实统计数据。
- 用户管理后台已接入，支持冻结和解冻用户。
- 订单管理后台已接入，支持查看全量订单和交接记录。
- 商品管理后台已接入，支持查看全量商品、商品详情、强制下架和标记异常。
- 订单详情后台已支持客服关闭和标记异常，相关操作会写入审计日志并通知双方。
- 商品审核后台已接入，审核员可查看账号资产截图后通过或拒绝。
- 审计日志后台已接入，支持查看高风险操作明细。
文档
分销独立测试库
启动 MySQL 后，可将当前开发库复制到独立测试库 hfb_sys_distribution_test，源库保持不变：
./scripts/clone-distribution-test-db.sh
脚本支持通过 SOURCE_MYSQL_* 和 TEST_MYSQL_* 环境变量指定源库、目标库连接。测试配置模板见 backend/.env.distribution-test.example。