# AGENTS.md — 爱伴·AI之旅 (train)

训练营系统，单 git 仓库（远程 `origin` = http://git.iwintrue.com/liaoxg/train.git，分支 `master`），三个子项目：

- `train-backend/` — Spring Boot 2.7.18 / Java 8 / MyBatis-Plus 3.5.3.1，端口 9083，JWT
- `train-frontend/` — uni-app Vue2 小程序（学员端）
- `train-web/` — Vue2 + Element UI 管理后台（vue-cli 5）

## 最容易猜错的核心事实

- **后端没有独立数据库**。train-backend 单数据源直连 cfc 同库 `zxyj`（`192.168.16.251:3306`，账号 `zxyj`，密码 `zxyj@123`，可用 `TRAIN_DB_URL/USERNAME/PASSWORD` 环境变量覆盖）。`train_*` 运营表与 cfc 表（`users`、`activities`、`user_platform_balance`、`tianpan_member_annual_energy`…）建在同一 schema。
- **JWT 密钥已与 cfc 对齐**（`cfc-prod-jwt-secret-2026-keep-it-safe!`），营员 token 与 cfc 体系互通。不要改回独立密钥。
- **`com.train.cfc` 包是跨库实体的"方言"**：`CfcUser`/`CfcActivity` + mapper 映射 cfc 的 `users`/`activities` 表。改字段必须与 cfc 侧表结构对齐（cfc 参考在 `E:\cfc`）。
- **`E:\cfc` 是只读参考**（cfc-backend 端口 9082，同库 zxyj）。绝不修改该目录任何文件。
- **微信登录 test-mode 默认 true**（`application.yml`），跳过真实微信 API，openid 为 `test_<code>`。

## 硬约束（用户明示，违反即返工）

- 前端**只允许 Vue2**：train-frontend 必须 uni-app Vue2（@dcloudio 2.x），train-web 必须 Vue2 + vue-cli + Element UI。**禁用 TypeScript、Vite、Vue 3。**
- 品牌名固定为「爱伴·AI之旅」（训练营总品牌），课程体系为 L0/L1/L2/L3/L4 五级。L0 课程名为「家立方-AI管家成长营」（首期课程名，保留为 L0 的 course name）。后续 L1-L4 课程待规划。品牌名勿回退为旧称。

## 命令与验证

- 后端编译验证：`mvn clean compile`（在 `train-backend/` 下）。**测试被 surefire `skipTests=true` 跳过**；`mvn clean compile` 成功即当前唯一可靠的验收门槛。
- 本机 MySQL 通常不可达，**无法做运行时端到端验证**——编译通过就提交，不要因连不上库而卡住。
- 前端：`npm run dev:h5` / `build:h5`（train-frontend H5 端）；`npm run dev` / `build`（train-web）。
- **train-frontend 小程序打包用 HBuilderX**（与 cfc 同工具链）：导入 `train-frontend/` → 运行到微信开发者工具，产物在 `unpackage/dist/dev/mp-weixin/`。`npm run build:mp-weixin` 的 `dist/` 产物不完整，勿依赖。改代码后必须在 HBuilderX 重新打包，否则白板。
- schema 由 `DatabaseInitializer` 启动时执行 `schema.sql`，逐条容错（失败仅 warn）。建表语句幂等；存量库补列的 `ALTER TABLE ADD COLUMN` 重复执行会报错但被吞掉，属预期。

## 后端规范（与 cfc 对齐）

- **接口统一 `@PostMapping`**，禁止 `@GetMapping/@PutMapping/@DeleteMapping`。
- **DI 用 `@Resource` 不用 `@Autowired`**，字段名 = 类名首字母小写（匹配默认 Bean Name）。
- **响应统一 `Result<T>`**（`com.train.common.Result`，code/message/data）。
- **分层 Controller → Service → Mapper**，禁止 Controller 直接操作 Mapper。
- **禁用类型绕过**：`as any`、`@ts-ignore` 不应出现。
- **数据库迁移幂等**：加列/建表/索引用 try-catch 忽略"已存在"，或参照 cfc 的 `ensureColumn()` 辅助方法；每次迁移后同步更新 `schema.sql` 的 `CREATE TABLE` 完整定义。
- **金额规范（重要）**：后端金额字段一律用**整数类型**（`int`/`Long`），单位**分**（对齐 cfc 的 `price`/`memberPrice`/`totalConsumption` 等字段）。禁止用 `double`/`float` 存金额。

## 前端金额显示规范（三端通用）

后端金额以"分"为单位的整数返回，前端显示时**除以 100 转成"元"**再展示，禁止把后端 int 值原样渲染成金额：

```js
// 分 → 元（保留两位小数）
function fenToYuan(fen) {
  return (fen / 100).toFixed(2)
}
```

## 时间显示规范（三端通用）

- 后端返回 ISO 8601（`2026-08-15T14:30:00`）。
- 展示时间：`yyyy-MM-dd HH:mm:ss`（截前 19 位 + T 替换空格）。
- 仅日期：`yyyy-MM-dd`（截前 10 位）。
- **禁止 `new Date(str).toLocaleString()` / `toLocaleTimeString()`**（iOS/浏览器输出不一致）。小程序侧用 `utils/format.js` 的 `parseDate()` 解析。

## 小程序限制（train-frontend 必守）

- 禁止可选链 `?.`（用 `&&` 替代）。
- 禁止 CSS Grid（用 flexbox）。
- 禁止 `:key` 带运算符表达式（如 `:key="item.id || item.circleId"`，改用方法调用 `:key="getItemKey(item)"`）。
- 禁止在 `:class` 绑定中调用方法。
- 禁止直接 `new Date(string)`（iOS 部分格式解析失败，用 `parseDate()`）。
- 禁止在 CSS 类名/选择器用中文。
- Vue 2 Options API，禁止 Composition API。

## 终端编码陷阱（Windows / PowerShell 5.1）

- PowerShell 把 UTF-8 当 GBK 解码，`git diff`/终端输出的中文会显示为乱码——**是假乱码**。判断文件编码/JSON 合法性用 Node 或 read/grep 工具，不要信 PowerShell 的显示。
- 中文 commit message 经 PowerShell 传参可能被截断（含引号时更甚）。失败时重试，用更简单的 message。

## 工作流约定

- 先 `git status`/`git diff` 确认改动范围，只 stage 意图内的文件；`.gitignore` 已排除 node_modules/dist/unpackage/target 等。
- 提交前用 `git diff --cached --stat` 检查 staged 内容是否仅含目标文件；`git checkout -- file` 会丢弃 staged 改动，慎用。
- commit message 用中文、conventional 风格（如 `Phase1: ...`），一次提交一个逻辑单元。
- 用户偏好：改动尽量小、贴合既有模式（对 `TrainUser` 等既有实体/控制器保持兼容，不推翻重写）。