# 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 |