# 浠艾福 (XAF) - Agent 工作指南

## 重要工作流（易错点）

### 数据库迁移（`Unknown column` 错误处理流程）

```
错误日志 → 查 entity 类 → 查 schema.sql → DatabaseInitializer 加迁移 → 同步 schema.sql → mvn compile
```

- **唯一入口**: `DatabaseInitializer.runMigrations()` — 所有 DDL 迁移写在这里
- **首选**: `ensureColumn(table, column, definition)` — 自动忽略"列已存在"异常
- **必须同步 schema.sql**: 每次迁移后 schema.sql 的 `CREATE TABLE` 也必须同步更新
- **迁移编号**: 搜索 `// 迁移` 找最新编号，递增
- **幂等**: 所有迁移可重复执行

### Git 工作流（易踩坑）

- `git checkout -- file` 会丢弃**工作区和已 staged** 的改动（不可恢复）
- `git stash pop` 会将 stash 内容合并到工作区，可能带入不相关的改动
- 多模块同时修改时：用 `git add -p` 或分次 `git add` 精确控制 staged 范围
- 提交前：`git diff --cached --stat` 检查 staged 内容是否仅包含目标文件

### 新增 Controller/Service 前必做

1. `mvn clean compile` — 验证无编译冲突
2. 检查路由重复：`grep -rn '@Mapping' cfc-backend/src/.../controller/ | grep -oP '@\w+Mapping\("\K[^"]*' | sort -u`
3. 检查 Bean 命名冲突：Spring 默认 Bean Name 为类名首字母小写，不同包的同名类会冲突

## 项目结构

| 模块 | 技术栈 | 端口 |
|------|--------|------|
| `cfc-backend/` | Spring Boot 2.7.18 + MyBatis-Plus + Java 8 | 9082 |
| `cfc-frontend/` | uni-app 微信小程序 (Vue 2, Options API) | — |
| `cfc-web/` | Vue 2 + Element UI 管理端 | 8082 |
| `dan/danshop/` | 独立商城 Spring Boot | 8888 |

## 常用命令

```bash
# 后端
cd cfc-backend && mvn clean compile   # 唯一验证方式
mvn spring-boot:run                    # 启动 (localhost:9082)

# Web管理端
cd cfc-web && npm run serve            # 开发 (localhost:8082)
npm run build                          # 生产构建 → rsync 到 192.168.16.251:/var/www/cfc-admin/

# 小程序：npm install 后用微信开发者工具导入根目录
# 管理端部署服务器脚本: bash /home/iwt/cfc-auto-deploy.sh

# 数据迁移 (sfms → zxyj)
curl -X POST http://localhost:9082/api/migration/run
```

## 数据库

- 地址：`192.168.16.251:3306/zxyj`（账号 `zxyj / zxyj@123`）
- 只读源库：`bianwoyou.mysql.rds.aliyuncs.com:3305/sfms`（`SfmsDataSourceConfig` 配置）
- 建表定义：`cfc-backend/src/main/resources/schema.sql`（完整快照）
- 迁移入口：`cfc-backend/src/main/java/com/etotem/cfc/config/DatabaseInitializer.java`

## 核心框架约定

- **接口**: 统一 `@PostMapping`，禁止 `@GetMapping/@PutMapping/@DeleteMapping`
- **ORM**: MyBatis-Plus `@TableName` + `@TableId(type = IdType.AUTO)`
- **响应**: `Result<T>` (code/message/data)
- **认证**: JWT Bearer Token，`JwtInterceptor` 拦截 `/api/**`（8个公开路径除外）
- **DI**: `@Resource`，字段名必须与类型默认 Bean Name 一致
- **角色控制**: 控制器内手动检查 `@RequestAttribute("role")`

## 小程序限制

- 禁止可选链 `?.`（用 `&&` 替代）
- 禁止 CSS Grid（用 flexbox）
- Vue 2 Options API，禁止 Composition API

## 子模块详细规范

| 文件 | 内容 |
|------|------|
| `cfc-backend/AGENTS.md` | 后端详细规范 + 数据库迁移工作流 |
| `cfc-frontend/AGENTS.md` | 小程序前端规范 |
| `cfc-web/AGENTS.md` | Web管理端规范 |
| `tests/AGENTS.md` | 分层测试策略 |