workpod/dev-envs/flux/norms.md

Flux 项目开发规范

本文件供 Claude Code / AI 助手阅读，统一开发规范认知

---

Git 提交规范

<类型>: <简述>

类型: 新增 | 修复 | 优化 | 重构

禁止:

• 英文提交信息
• Co-Authored-By 尾巴
• 提及工具名称（如 "generated by Claude"）

示例:

新增: 渠道价格匹配规则引擎
修复: 下游进件超时未回调处理
优化: SQL 慢查询添加联合索引
重构: UpstreamService 抽象三方对接接口

技术栈与启动命令

模块	技术	目录	启动命令
flux-api	Java 17 + Redkale + Maven	flux-api/	cmd /c bin\restart.bat 或 mvn clean package 后运行
flux-admin	Vue 3 + Arco Design Pro + Vite + bun	flux-admin/	bun install && bun run dev
flux-uniapp	UniApp (H5) + Vite	flux-uniapp/	npm install && npm run dev:h5
flux-mock	Go (模拟三方)	flux-mock/	go run *.go
flux-test	Go (业务链测试)	flux-test/	go run test_quick.go {channel}
file-server	Go (文件上传)	file-server/	go run *.go
flux-wechat-api	微信服务	flux-wechat-api/	—

核心架构

上游渠道 (10个) → UpstreamService → 下游对接 (美信/小薇/易贷通/CryptoApi) → 三方机构

• 上游: 小爱、速贷、趣来借、臻品借、微融花、腰贷钱包、演示、放心借、龙享花、可贷
• 下游: 美信钱包、美信B、小薇钱包、易贷通、有鑫钱包、源融花、闪融花、Mock
• 加密: AES-CBC/ECB, CBC模式, 部分Base64密钥

代码审查要点

Redkale 框架 (flux-api)

• FilterNode 使用规范 → 见 /root/.kms/Redkale使用易错点.md
• JSON 字段映射用 @ConvertColumn，注意命名转换
• 数据库连接通过 @Resource(name="lake") 注入
• 自定义 Render 用 cn.casehub.base.TplRender

前端 (flux-admin)

• 组件库: Arco Design Pro
• 状态管理: Pinia
• 路由: Vue Router 4

Go 服务

• 交叉编译: $env:GOOS="linux"; $env:GOARCH="amd64"; go build
• 配置文件: 各模块独立 config.json

命名规范

{业务域}-{类型}-{名称}

前缀	含义
flux	Flux 架构核心项目

后缀	含义
-api	后端 API 服务
-admin	管理后台前端
-web	用户端 Web
-mp	小程序
-task	定时任务
-kit	工具库/SDK

高危操作检查清单

• 改 Docker/系统配置 → 先备份，验证语法，再重启
• 删数据库/容器 → 确认备份和影响范围
• 生产环境操作 → 必须先在测试环境验证
• 发版部署 → 通知相关人，准备回滚方案
• 数据库 DML → 先 SELECT 预览，确认 WHERE 条件

模型选择参考

场景	推荐模型
关键决策/技术选型	glm-5 / deepseek-r1
复杂推理	deepseek-r1
图片理解	kimi-k2.5 / qwen-max
日常开发操作	kimi-k2.5 / deepseek-v3
简单任务	glm-4.7-flash / qwen-turbo