صفحهٔ اصلی گشت‌و‌گذار راهنما
ثبت نام ورود
liaoxg
/
cfc
1
1
انشعاب 0
پرونده‌ها مشکلات 0 درخواست واکشی 0 ویکی
درخت: 3e0011babc
شاخه‌ها تگ‌ها
cfc
/
AGENTS.md

AGENTS.md 14 KB
تاريخچه خام

浠艾福 (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
cfc-langgraph/ Python FastAPI + LangGraph + ChromaDB RAG（AI 服务） 9000
  • 接口: 统一 @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")
  • AI 服务统一走 LangGraph: 所有 AI 能力（对话/问卷/画像/推荐/解析）基于 cfc-langgraph Python 服务（FastAPI + LangGraph + ChromaDB RAG，端口 9000，生产 ai.etotem.com.cn）；Java 侧通过 AiGateway 调用（熔断 + 超时 + Fallback），禁止绕过 AiGateway 直接对接第三方 LLM；新增 AI 功能优先以 LangGraph graph 形式实现
  • 小程序限制: 禁止可选链 ?.（用 && 替代）、禁止 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

稳定脚本用法:

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

禁忌清单

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

公众号数据驱动优化指南（基于后台分析）

数据来源：https://mp.weixin.qq.com/misc/appmsganalysis?action=report&type=daily_v2 内容分析页面

流量构成（近30天）

渠道 占比 含义
朋友圈 ~33% 文章有转发价值，主动传播能力
搜一搜 ~30% 标题关键词SEO匹配度
公众号消息 ~16% 粉丝主动打开率
聊天会话 ~11% 点对点分享
公众号主页 ~10% 关注后/查看主页
推荐 ~4% 微信推荐系统曝光
其它 ~2%

关键判断：公众号流量严重依赖朋友圈分享和搜一搜SEO，粉丝主动打开率低（16%），推荐系统几乎不推荐。

标题公式（基于高阅读文章验证）

✅ 高阅读标题特征（30天TOP5）

文章 阅读 特征
几十亿人看他跳舞，但他23年没刷过一道题 91 数字+冲突+反差
妈妈，我不想上学：38.6%的孩子在替家长喊疼 50 数字+痛点+数据
61.7%孩子用AI，20.5%正在变笨 40 双数字+颠覆认知
AI时代，还要让孩子背诵吗？ 36 争议性反问
当孩子在说「没意思」——四无时代 31 痛点+概念包装

标题模板

[数字] + [冲突/反差] + [悬念/痛点]   →  "61.7%孩子用AI，20.5%正在变笨"
[场景] + [反转] + [结论]              →  "几十亿人看他跳舞，但他23年没刷过一道题"
[数据] + [痛点] + [解决方案暗示]       →  "38.6%的孩子在替家长喊疼"

❌ 低阅读标题教训

  • 标题过长（>25字）：#53「女儿超常发挥50分，妈妈却偷改了她的志愿」32字，仅18阅读
  • 标题偏平无冲突：「好无聊」「溺水是无声的」— 缺乏转发动力
  • 无关键词：标题不含"孩子""家长""教育"等高频搜索词，搜一搜匹配差

标题检查清单

  • 标题 ≤25字符（建议20字以内）
  • 含数字（百分比/次数/分数等）
  • 含冲突/反差/反转（"你以为...其实..."）
  • 前12字有吸引力（微信推荐展示前12字）
  • 含高频搜索词（孩子/家长/教育/青春期/暑假等）
  • 不含"愿每个X"式收束

内容类型策略

类型 建议占比 最佳案例 特点
案例故事型 40% 身体如何塑造心智（91阅读） 人物+反差，朋友圈传播力最强
数据热点型 30% 61.7%孩子用AI（40阅读） 数据+热点话题，搜一搜匹配高
干货实操型 20% 是什么决定学习力（16阅读） 稳定基本盘，粉丝粘性
产品推广型 10% 公益讲座/测评推广 控制在≤15%

写作前必查（补充）

除现有自检清单外，额外检查：

  • 标题是否含数字？不含 → 加数字再发布
  • 标题是否含"孩子""家长"关键词？不含 → 调整标题
  • 前12字是否足够吸引人？太平淡 → 前移冲突点
  • 文章是否有"转发价值"？（读了想分享给朋友/家人？）

发布后追踪

  • 发布后7天，登录 数据分析 → 内容分析 查看阅读量
  • 阅读<30 → 标题/选题有问题，下次避免同类
  • 阅读30-60 → 正常水平
  • 阅读>60 → 好标题/好选题，总结可复用的点
  • 关注"推荐"渠道占比：若持续<5%，说明标题缺乏爆点

COMMANDS

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