cfc/AGENTS.md

浠艾福 (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

常用命令

# 后端
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	分层测试策略