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

- **接口:** 统一 `@PostMapping`，禁止 `@GetMapping/@PutMapping/@DeleteMapping`
- **ORM:** MyBatis-Plus `@TableName` + `@TableId(type = IdType.AUTO)`
- **响应:** 统一 `Result<T>` (code/message/data)
- **认证:** JWT Bearer Token，`Authorization` Header；`JwtInterceptor` 拦截 `/api/**`（8个公开路径除外）
- **DI:** `@Resource` 替代 `@Autowired`，字段名匹配默认 Bean Name
- **角色控制:** 控制器内手动检查 `@RequestAttribute("role")`
- **小程序限制:** 禁止可选链 `?.`（用 `&&` 替代）、禁止 CSS Grid（用 flexbox）、禁止 `:key` 表达式（用方法调用代替）、禁止直接 `new Date(string)`（用 `parseDate()`）
- **新增Controller/Service:** 检查类名是否与其他包重名（Spring Bean Name 冲突）
- **新增路由:** 运行 `grep -rn '@Mapping' cfc-backend/src/.../controller/ | grep -oP '@\w+Mapping\("\K[^"]*' | sort -u` 检查重复

## UNIQUE STYLES

- **双角色:** 家长端可切换查看孩子视角；直接登录的孩子端不能切换到家长端
- **成长规划师:** `role=teacher`，可登录规划师端，也可切换回家长视角
- **五维能量:** 身/心/智/行/富维度体系，能量按比例分配
- **测评订单:** 家长申请 → 选择规划师 → 孩子快照 → 支付 → 规划师录入结果
- **四级地址:** 省市区街道，区域回退匹配
- **多数据源:** cfc 主库 + sfms 只读源（`SfmsDataSourceConfig`）
- **环境自适应:** 小程序 `config.js` 通过 `uni.getAccountInfoSync()` 自动切换 develop/trial/release 的 API 地址
- **测试模式:** `wechat.test-mode: true` 跳过微信 API，使用模拟数据

## cfclub 新特性

- 家庭邀请二维码（小程序码+令牌+落地页）
- 健康报告 PDF 上传与解析
- 文章发布-审核系统
- 饮食推荐系统（前端+后端）
- 维度配置与知识库管理（Web管理端）
- 家庭关系图重设计
- 成长记录重构
- Dify AI 对话集成
- 家庭成员关系编辑（前端：RelationshipPicker + family-members 编辑弹窗）
- 关系类型 CRUD 管理（Web管理端 RelationshipTypes.vue）
- 联系人管理（ContactCard, ContactImport, contact-detail）

## 微信公众号文章发布

稳定发布脚本: `C:\code\cfc\publish_v11_stable.py`

**发布流程**:
1. `GET /cgi-bin/token` 获取 access_token
2. `POST /cgi-bin/material/add_material type=thumb` 上传封面 → thumb_media_id
3. `POST /cgi-bin/media/uploadimg` 上传内容图片 → URL
4. `POST /cgi-bin/draft/add` 创建草稿（content字段填完整HTML）

**API关键参数**:
| 字段 | 限制 |
|------|------|
| title | ≤32字符，建议≤30字节（约10个中文）|
| content | <1MB，<2万字符，HTML标签 |
| thumb_media_id | 必须来自 material/add_material type=thumb |
| content内图片URL | 必须来自 media/uploadimg，外部URL被过滤 |

**HTML注意事项**:
- 单引号属性: `<img src='url' style='width:100%' />`
- 不支持: JS, 复杂div/CSS, 双引号属性
- WeChat会用自己的样式渲染，基本CSS会被保留

**封面图片生成**:
- 模型: `agnes-image-2.0-flash`（通过 Agnes AI API: `https://apihub.agnes-ai.com/v1/images/generations`）
- 认证: Bearer token（见 `opencode.json` 配置）
- 尺寸: `1024x1024`
- 出图后下载至 `C:\Users\Administrator\Documents\双培强基工程\images\cover_33_v11_case_study.png`
- 封面风格要求: 温暖、简约、留白充足（右侧/下方供文字叠加）、无需文字、适合家庭教育主题
  - 示例 prompt: `"A warm summer scene with a mother and child silhouette sitting together on a bench under a tree, soft golden sunlight filtering through leaves, warm orange and gold tones, peaceful and emotional atmosphere. Minimalist composition with lots of negative space on the right and bottom for text overlay. Chinese parenting theme. No text in image. 1024x1024 pixels."`
- 调用方式: POST 请求，model=`agnes-image-2.0-flash`，返回 JSON 中含 `data[0].url`

**稳定脚本用法**:
```bash
python C:\code\cfc\publish_v11_stable.py
```

脚本会输出media_id，登录 `mp.weixin.qq.com` → 草稿箱查看和发布。

## 公众号内容编写规范（案例研究型内容）

### 核心观点：案例研究 > 纯干货

纯干货内容难以转化客户，因为缺乏说服力。**案例研究**通过"证明能力"大幅提升转化率：
- 基于**社会认同心理**：相似问题被解决 → 信任建立 → 成交
- 客户质量高、成交率高
- 代价：初始流量可能低于泛内容

### 常见误区（必须避免）

| 误区 | 问题 | 后果 |
|------|------|------|
| 用别人的案例（名人/网红） | 不是你的真实客户 | 无法证明你的能力 |
| 只写结果不写过程 | 缺乏"从零到一"的路径 | 读者无法复制 |
| 成功不是在你帮助下达成 | 无代入感 | 转化失败 |

### 三步法：高转化案例研究

**第一步：聚焦真实成果**
- 必须是你**亲自完成**或**在你的帮助下**客户取得的成果
- 禁止使用名人案例（只适合引流，不适合转化）
- 数据来源：报告、截图、真实反馈

**第二步：鲜明的前后对比**
- 合作前状态（如：自驱力评分 4.07/10）
- 合作后具体结果（如：自驱力提升至 5.30/10）
- 真实描述转变过程，避免夸大

**第三步：拆解问题解决过程**
按以下框架叙述：
1. **核心问题**：客户当时面临什么挑战？
2. **解决方案**：你采取了什么具体行动？
3. **经验提炼**：可供读者借鉴的教训或行动指南

### 文章结构模板

```
开头：描述一个典型场景/痛点（让读者代入）
↓
案例引入：用真实数据/截图展示结果
↓
问题分析：解释为什么这个问题值得解决
↓
解决方案：描述你的具体方法
↓
经验总结：提炼可复制的规律
↓
结尾：呼吁行动（咨询/购买/关注）
```

### 数据与截图要求

- **脱敏**：姓名→化名（如"小李"），日期→模糊（如"三个月前"），学校→不提及
- **截图**：报告中关键数据页面，敏感信息打码
- **截图标注**：截图上须用红色框/箭头/高亮标注主要内容区域，让读者一目了然
- **英文翻译**：截图中的英文标题/关键术语须在旁边添加中文翻译（如 `↑ CRP ↓` 标注"↑ C反应蛋白 ↓"）
- **数据引用**：注明来源（如"A2核心素养评估报告"）

### 案例库与素材库

- 案例库：`C:\Users\Administrator\Documents\双培强基工程\`
- 报告截图：`temp_images\{学生姓名}\desensitized\`
- 文章素材：`articles\v11_case_study.md`

### 禁忌清单

- ❌ 使用非客户案例（名人、竞争对手）
- ❌ 虚构或夸大成果数据
- ❌ 暴露客户隐私（姓名/学校/家庭住址）
- ❌ 缺少具体转变过程的描述

## COMMANDS

```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）
- 禁止 `:key` 表达式（如 `:key="item.id || item.circleId"`，微信小程序模板编译器不支持带运算符的 `:key` 绑定 → 改用方法调用 `:key="getItemKey(item)"`）
- 禁止直接 `new Date(string)` 解析日期字符串（部分 iOS 的 JavaScriptCore 不支持空格分隔格式如 `"2026-08-22 14:00"` → 统一用 `utils/format.js` 的 `parseDate()`）
- Vue 2 Options API，禁止 Composition API

## 子模块详细规范

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