Главная Обзор Помощь
Регистрация Вход
liaoxg
/
cfc
1
1
Ответвить 0
Файлы Задачи 0 Запросы на слияние 0 Вики
Дерево: bdfb0add15
Ветки Метки
cfc
/
AGENTS.md

AGENTS.md 22 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 内容是否仅包含目标文件

本地健康报告采集：AI 必须自动拉起依赖

用户说「启动本地」「测报告上传/解析」「启动 opencode / LangGraph」或让 AI 拉起本地环境时： 先探活，缺什么起什么，不要只口述命令。

服务 端口 探活 未在听则执行
cfc-backend 9082 http://127.0.0.1:9082 不要擅自重启 IDE 里已在跑的后端；仅在确认没进程时再 mvn spring-boot:run
LangGraph 报告解析（本地最小服务） 9000 http://127.0.0.1:9000/health → {"status":"ok"} 见下方启动命令
opencode（采集兜底） 4090 http://127.0.0.1:4090 见下方启动命令
pdftotext — pdftotext -v 已装过则不用启动；缺失则 winget install --id oschwartz10612.Poppler -e

本机 Windows 启动命令（PowerShell，后台跑、不要占用对话）：

# 1) LangGraph 报告解析（Python 3.14 装不齐完整栈，本地只用最小服务）
cd d:\Java_code\CFC\cfc-langgraph
.\.venv\Scripts\python.exe -m uvicorn local_report_app:app --host 0.0.0.0 --port 9000

# 2) opencode
$env:OPENCODE_ADMIN_PASSWORD = "IwinTrue@123"
opencode web --port 4090 --hostname 127.0.0.1
  • 只测登录/家庭/商城：不必开 9000/4090。
  • 测健康报告上传、异步采集、解析入库：9000 必须开，4090 建议开（LangGraph 解析为空时回退）。
  • 指纹脚本是文件不是服务：docs/scripts/fingerprint_engine.py（及 docs/scripts/parsers/ 副本）。application.yml 的 python.executable 必须是 python，禁止走微软商店空壳 python3。
  • 完整 app.main:app（对话/RAG/whisper）本机默认不启；生产走 ai.etotem.com.cn。

新增 Controller/Service 前必做

  1. 查阅接口文档：先看 docs/superpowers/api/API_REFERENCE.md，确认是否已有可复用或可修改的接口
  2. mvn clean compile — 验证无编译冲突
  3. 检查路由重复：grep -rn '@Mapping' cfc-backend/src/.../controller/ | grep -oP '@\w+Mapping\("\K[^"]*' | sort -u
  4. 检查 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")
  • 新增接口前: 必须先查阅 docs/superpowers/api/API_REFERENCE.md，确认无重复/相似接口才新增
  • 废弃接口: 标记 410 Gone 并注释说明，不直接删除；清理时机确认无前端调用后
  • 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，使用模拟数据

用户模型统一口径

  • 能登录用户：family_members.userId 非空且关联 User 有 openid（VO 层 memberType=login）
  • 不能登录用户（历史称"孩子"）：family_members.userId 为空或关联 User 无 openid（VO 层 memberType=local），由同家庭能登录用户代管其数据（任务/健康/DOA 等）
  • 新功能禁止再引入"孩子"概念，统一用"能登录用户/不能登录用户"表述

cfclub 新特性

  • 家庭邀请二维码（小程序码+令牌+落地页）
  • 健康报告 PDF 上传与解析
  • 文章发布-审核系统
  • 饮食推荐系统（前端+后端）
  • 维度配置与知识库管理（Web管理端）
  • 家庭关系图重设计
  • 成长记录重构
  • LangGraph 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会被保留

封面图片生成（统一使用 imagefree_gen.py 脚本，禁止再手写内联调用第三方 LLM 出图）:

  • 脚本: C:\code\cfc\imagefree_gen.py（ImageFree.net 文生图，阻塞式提交+轮询，生成完自动保存）
  • 用法: python imagefree_gen.py "提示词" --ratio 16:9 --out "C:\Users\Administrator\Documents\双培强基工程\images\cover_57_phone.png"
  • 宽高比: 封面用 16:9；文章插图用 4:3
  • 提示词可写入 .txt/.json 文件，用 -i prompt.txt 传入（JSON 需含 prompt 字段）
  • 出图保存至 C:\Users\Administrator\Documents\双培强基工程\images\cover_{编号}_{主题}.png
  • 辅助参数: --timeout <毫秒> 总超时；--preview 生成后打开预览；--json 输出 JSON 结果
  • 封面风格要求: 温暖、简约、留白充足（右侧/下方供文字叠加）、无需文字、适合家庭教育主题
    • 示例 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."
  • 依赖: pip install requests（PIL 可选，用于转格式）

稳定脚本用法:

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

禁忌清单

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

发布前人味检查（zh-writing-humanizer，必做）

文章写完、截图配齐后，发布草稿前必须调用 zh-writing-humanizer 技能对全文做一次 AI 腔检查与改写。

检查重点（公众号文章高频 AI 腔）：

类型 典型信号 处理
意义拔高 标志着、彰显了、深远影响、开启新篇章 改为具体事实：谁做了什么、变了什么
官腔套话 高度重视、持续推进、不断完善、赋能 删掉或换成具体动作
机械对比 不是…而是… 全文超过 2 次 保留 1-2 处最有力的，其余改直陈
三连排比 三个抽象名词并列（焦虑、控制、内耗式堆叠） 减到 2 个或改成具体场景
口号式结尾 愿每个X、未来可期、让我们拭目以待 结尾落在最后一个具体事实上
假坦白开头 说实话、讲真、不得不说 删掉钩子直接说事
空洞积极 不可否认、毋庸置疑、众所周知 删掉，或补上具体依据

改写原则：

  • 只改表达，不改事实：数据、分数、百分位、报告名称、化名、来源引用一律原样保留
  • 不新增细节：原文没有的场景、对话、数据不得为了"生动"而编造
  • 保留本号风格：短句节奏、加粗强调、口语化表达是人设的一部分，单处出现不算 AI 腔，堆叠才是问题
  • 改完后重跑一遍「写作前必查」和「禁忌清单」确认未被改坏

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

数据来源：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

# 本地健康报告采集依赖（AI 按「重要工作流」探活后按缺启动）
cd cfc-langgraph && .venv/Scripts/python.exe -m uvicorn local_report_app:app --host 0.0.0.0 --port 9000
# opencode: $env:OPENCODE_ADMIN_PASSWORD="IwinTrue@123"; opencode web --port 4090 --hostname 127.0.0.1

数据库

⚠️ 环境区分（重要）：192.168.16.251:3306 是测试库，不是生产库。任何针对它的 DDL 迁移、调试、数据改动都只能用于测试验证，不能代表生产环境实际状态。生产数据库连接信息（主机/库名/账号）不在此处，需向运维确认后再填写到下方，禁止把测试库当成生产库来判断线上问题。

  • 测试库：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

一线原则：判断"生产缺列 / Unknown column"等线上问题时，必须以生产库为准；测试库（192.168.16.251）的库表结构不代表生产，schema.sql 也只是同步镜像，最终以生产确认结果为准。

⚠️ children 表标注冲突：schema.sql 将 children 标为"已废除/并入 family_members"，但 Child 实体、ChildMapper、多个 Service（AccountCleanupService、TaskStatsService、GrowthTaskService 等）仍活跃使用，且生产库存在真实的 children 表。生产 children 表缺 phone/id_card 两列（AccountCleanupService.exportUserData 全字段 SELECT 会报 Unknown column 'phone'），用户已决定不迁移，保持现状。处理 children 相关需求时勿据此表已废弃而误删实体/迁移，也不要重复加 phone/id_card 迁移。

核心框架约定

  • 接口: 统一 @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")

时间显示规范

所有页面展示时间必须统一以下两种格式，禁止使用 toLocaleString()、toLocaleTimeString() 等浏览器差异化输出：

使用场景 格式 示例
时间（显示年月日+时分秒） yyyy-MM-dd HH:mm:ss 2026-08-15 14:30:00
仅日期（去掉后面的时间） yyyy-MM-dd 2026-08-15

后端统一返回 ISO 8601 格式（2026-08-15T14:30:00），前端按场景格式化：

  • 需展示时间的场景（订单时间、支付时间、创建时间、打卡时间等）：截取前19位 + 将 T 替换为空格 → yyyy-MM-dd HH:mm:ss
  • 仅需日期的场景（日期筛选、日报等）：截取前10位 → yyyy-MM-dd

禁止直接使用 new Date(str).toLocaleString('zh-CN')（输出格式因浏览器而异）。

小程序限制

  • 禁止可选链 ?.（用 && 替代）
  • 禁止 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 分层测试策略

本地采集 / AI 服务自动启动

用户要求启动本地、测报告解析、或启动 opencode / LangGraph 时，按上文「本地健康报告采集：AI 必须自动拉起依赖」执行：先探活 9082 / 9000 / 4090，缺哪个起哪个。

cd d:\Java_code\CFC\cfc-langgraph
.\.venv\Scripts\python.exe -m uvicorn local_report_app:app --host 0.0.0.0 --port 9000

$env:OPENCODE_ADMIN_PASSWORD = "IwinTrue@123"
opencode web --port 4090 --hostname 127.0.0.1