2026-10-23-project-master-plan.md 19 KB

CFC 项目整体修改 / 完善 / 开发计划 v1.0

生成时间:2026-10-23 依据:docs/PROJECT-OVERVIEW.md(v2.21,权威口径)+ docs/superpowers/specs/(130 份规格)+ docs/superpowers/plans/(125 份计划)+ 各智能体会话执行记录 + 工作区实际代码核对 执行方式:本计划中的工作包通过 E:\cfc\tools\xaf_agent_hub\hub.py 派发到 6 个 opencode 智能体实例执行


一、调研结论(现状盘点)

1.1 代码结构

模块 技术栈 职责
cfc-backend Java 8 / Spring Boot 2.7 / MyBatis-Plus 全部业务后端、微信生态对接、支付与履约
cfc-frontend uni-app / Vue 2.7 微信小程序端
cfc-web Vue 2.6 / Element UI 管理后台(admin / teacher / orchestration)
cfc-langgraph Python 智能体编排(报告解读 / 健康规划)

1.2 文档资产

  • 规格 docs/superpowers/specs/:约 130 份;计划 docs/superpowers/plans/:约 125 份
  • 设计先行已成体系:本轮派发的工作包中,绝大多数已有现成设计规格,智能体应严格按规格落地,不要自行发挥

近期关键规格(本轮直接相关):

  • 2026-10-13-homepage-family-task-count-design.md —— 首页家庭任务数
  • 2026-10-22-fulfillment-multi-mode-design.md —— 履约多渠道
  • 2026-10-22-planner-learning-assessment-gate-design.md —— 规划师培训认证闸门(v2:多类别 + 线下打卡)
  • 2026-10-22-org-admin-management-design.md —— 机构管理员管理
  • 2026-10-22-activity-registration-roster.md —— 活动报名名册
  • 2026-10-22-activity-poster-redesign.md —— 活动海报重设计

1.3 版本与工作区状态

  • 分支:cfclub
  • 已修改未提交:12 个文件,全部在 cfc-web/(AGENTS.md、SliderCaptcha.vue、ActivityRegistrationReview.vue、EnergyRuleManagement.vue、IndicatorCorrelations.vue、IndicatorMappings.vue、LangGraphAdmin.vue、ReportCollectorTrainer.vue、VirtualTeamDetail.vue、dimension/index.vue、FlowEditor.vue、TeacherFamilies.vue)
  • 未跟踪临时文件:_oc_scan.json、_oc_scan_new.json、cfc-web/dist_verify/、cfc-web/docs/、cfc-web/public/CHANGELOG-v$(node.undefined.md(畸形文件名)、知识库参考资料 2 份

1.4 本轮已完成

  • 小程序首页应用库改名(已提交并推送到 origin/cfclub)
    • cfc-frontend/utils/app-library.js:应用名统一压缩至 ≤3 汉字(健康报告→报告、文章中心→文章、饮食推荐→饮食、成长记录→成长、会员中心→会员;AI管家 等本就 ≤3 字保持不变)
    • cfc-frontend/pages/index-home/index.vue:defaultKeys 中 'task' → 'diet',默认快捷 6 项变为 饮食🥗 → 天盘🏠 → 成员👨👩👧👦 → 圈子🤝 → 购物车🧺 → 商城🛒
  • 管理后台 admin 内联样式清理(C-14 / C-15 / C-16 三个批次已提交)

1.5 半途停下 / 未完成的会话(已核对执行记录)

实例 会话 结论
lan-204 小程序活动管理 ✅ 已完成(4 次提交,工作区干净)
lan-189 规划师认证 ⚠️ 只提交了设计规格,实现未落地 → 本计划 W3
pub-iwintrue 首页家庭任务数 ⚠️ 只提交积分修复,"首页家庭任务数"未做 → 本计划 W6
lan-248 — 🔶 提交后卡在 git rebase --continue(编辑器冲突),已恢复

二、本次变更需求汇总

  1. 资金与名额安全:活动报名名额并发超卖、取消/退款不回滚名额
  2. 签到审核形同虚设:签到无真实记录,审核无对象
  3. 履约链路不完整:多渠道履约缺失;微信发货同步接口 URL 错误
  4. 规划师培训认证闸门:设计已完成,代码零实现
  5. 机构管理员管理:设计已完成,16 项任务待落地
  6. 首页家庭任务数:设计已完成,未实现
  7. 通知渠道空实现:Email / 公众号 / 电话 / 短信 / 微信 5 个通道全是 TODO 占位
  8. 技术债:guide_activities / activity_provisions 两个空壳子系统待删除(需先依赖审计);pom.xml 全局 skipTests=true;仓库卫生

三、工作包与优先级

🔴 P0 —— 资金 / 数据正确性风险

编号 工作包 落点 说明
W1 活动报名名额原子校验 + 退款/取消回滚名额 cfc-backend/.../service/ActivityRegistrationService.java、entity/ActivityRegistration.java、mapper/ActivityRegistrationMapper.java 报名写入前用数据库层原子扣减(UPDATE ... SET remaining = remaining - 1 WHERE id=? AND remaining > 0),避免并发超卖;取消/退款必须回滚名额,与退款事务同生共死
W2 微信发货同步 URL 缺 /wxa 前缀(已确认的线上 Bug) cfc-backend/src/main/java/com/etotem/cfc/service/WechatService.java 第 709 行 现为 https://api.weixin.qq.com/sec/order/upload_shipping_info,正确应为 https://api.weixin.qq.com/wxa/sec/order/upload_shipping_info。同文件 441/510/552 行均带 /wxa,唯独此处漏了 → 发货信息永远同步不到微信
W3 规划师培训认证闸门落地(设计已有) docs/superpowers/specs/2026-10-22-planner-learning-assessment-gate-design.md 9 张表:planner_cert_categories / planner_courses / planner_course_progress / planner_offline_course_map / activity_checkins / planner_certifications(每用户每类别一行) / planner_exam_papers / planner_exam_questions / planner_exam_attempts。线下课复用主 activities 模块(不建独立课程表、不复用空壳 guide_activities),通过 planner_offline_course_map(activity_id, category_id, duration_hours) 桥接;线上课时走小鹅通;接单闸门改为类别感知 PlannerCertificationGuard.assertCertified(userId, categoryCode);ServiceRoleApplicationServiceImpl.approve() planner 分支由直接置 active 改为建 Guide(pending_cert) + 逐类别认证
W4 真实签到落地(修"签到审核形同虚设") activity_checkins(通用签到表)、cfc-web 签到审核页 复用 activities 报名/海报/二维码,扫码签到为主、admin 手动补录兜底;GPS 校验 v1 不启用

🟠 P1 —— 设计与产品已定、待补实现

编号 工作包 落点 说明
W5 履约多渠道 cfc-backend fulfillment 相关 + 2026-10-22-fulfillment-multi-mode-design.md 按规格补齐多模式履约;与 W2 同源,可一并处理
W6 首页家庭任务数 cfc-frontend 首页 + 2026-10-13-homepage-family-task-count-design.md 按规格实现家庭维度任务数;此前只做了积分修复
W7 机构管理员管理(16 项) cfc-web + 2026-10-22-org-admin-management-design.md 按规格逐项落地
W8 通知通道实现 cfc-backend/.../service/notification/ InApp / Webhook 已实现;Email / Gzh / Phone / Sms / Wechat 5 个通道的 send() 全是 // TODO + log.warn 占位,需接入或明确降级为"不支持并回退站内"

🟡 P2 —— 技术债与工程卫生(建议排在 P0/P1 之后)

编号 工作包 落点 说明
W9 删除空壳子系统 entity/ActivityProvision.java、entity/GuideActivity.java、mapper/GuideActivityMapper.java、config/DatabaseInitializer.java、resources/schema_assessment.sql 先做依赖审计再删:确认无 Controller/Service/前端引用后删除表、实体、Mapper、建表脚本;target/classes 下同名文件属构建产物,不要手改
W10 恢复单元测试 cfc-backend/pom.xml 第 28 行 <skipTests>true</skipTests> 改回 false,并让现有 src/test/java/com/etotem/cfc/unit/ 下的用例通过(含 ActivityRegistrationListTest / ActivityRegistrationRejectTest)
W11 仓库卫生 仓库根 / cfc-web/ 清理 _oc_scan.json、_oc_scan_new.json、cfc-web/dist_verify/、cfc-web/public/CHANGELOG-v$(node.undefined.md(畸形文件名);补齐 .gitignore;cfc-web/docs/ 与知识库参考资料确认是否入库

四、分配方案(智能体 × 工作包)

并发硬约束:每实例同时最多 2 个 CFC 会话。本轮首发 5 个工作包,每实例各 1 个,为中断巡检与续做各留 1 个空位。

工作包 实例 理由 主要落点(互不重叠,降低冲突)
W1 名额原子校验 + 退款回滚 lan-248 后端主力,ActivityRegistration* 相关 cfc-backend 活动报名 service/entity/mapper
W2 + W5 发货 URL 修复 + 履约多渠道 lan-204 刚完成小程序侧改动,熟悉前端与微信链路 WechatService.java + fulfillment 包
W3 + W4 规划师认证闸门 + 真实签到 lan-189 该会话已提交本项设计规格,上下文连续 新增 planner_* 表与代码 + activity_checkins
W7 机构管理员管理 16 项 pub-iwintrue 管理后台前端为主,该实例负载低 cfc-web/src/views/admin/**(新增为主)
W8 通知通道实现 local-45278 本地实例,便于调试外部网关凭据 cfc-backend/.../service/notification/**

第二批(首批有空位后依次派发):W6 首页家庭任务数 → pub-iwintrue;W9 空壳子系统删除 → lan-248;W10 恢复测试 → lan-189;W11 仓库卫生 → local-45278。

生产实例 prod-etotem 本轮不派发(默认只读,需 --allow-prod 才写)。


五、执行约束(所有智能体必须遵守)

  1. 按规格落地:优先读 docs/superpowers/specs/ 对应规格;规格与现状冲突时,先汇报冲突再动手,不要擅自改设计。
  2. 只动自己负责的文件:跨工作包的文件(如 DatabaseInitializer.java、schema_assessment.sql)如需改动,先说明并等待协调。
  3. 提交纪律:
    • 提交前 git pull --rebase --autostash;
    • 只 git add 自己负责的文件,禁止 git add .;
    • push 失败则 rebase 后重试;不要长时间卡在 git rebase --continue(lan-248 已踩过一次),需要人工裁决时直接停止并汇报;
    • 提交信息用 feat/fix/refactor(模块): 简述。
  4. 不得改动构建产物(target/)与自动生成文件。
  5. 完成后简要汇报:改了哪些文件、是否提交、是否推送、遗留问题。
  6. 免费额度兜底:若会话报 Free usage limit reached...,巡检进程会自动把该会话切到 axonhub/deepseek 并投递续做指令(工具:tools/xaf_agent_hub/fix_free_limit.py)。

六、模型策略(2026-10-23 用户定稿,唯一口径)

  1. 优先沿用会话原模型:复用已有会话时默认不换模型,只有显式 --model 才切;
  2. 只有 429/限流才自动切换,切换目标按实例取一个(config.json 的 fallback_model,缺省 axonhub/deepseek);
  3. 不级联切换其他模型:该实例连自己的兜底模型都没有时,宁可跳过也不换 nvidia / sensenova / etotem / axon 等其他模型(实测 axon/deepseek 会持续 rps exhausted 429,级联只会把好会话改坏)。

不同实例接入的 provider 不一致,axonhub/deepseek 并非处处可用,故兜底模型按实例配置(2026-10-23 用户拍板:pub-iwintrue 就用 etotem):

实例 兜底模型 fallback_model 说明
local-45278 axonhub/deepseek 默认免费模型 opencode/flint-40b-free 会 503,须显式指定
lan-248 axonhub/deepseek 模型池最全(168 个)
lan-204 axonhub/deepseek
lan-189 sensenova/deepseek-v4.1-flash 无 axonhub、无 etotem;选它是因为此前手工定到该模型且能跑,axon/deepseek 会持续 429
pub-iwintrue etotem/deepseek 用户指定:该实例无 axonhub provider,用自家 etotem
prod-etotem axonhub/deepseek manual_only(2026-10-23 用户定稿):只在用户明确下指令时才执行,fix_free_limit / check_agents / fill_slots 三条自动化路径无条件硬跳过(--allow-prod 也不放行补位);确要操作用 hub.py dispatch --instance prod-etotem … --allow-prod 显式定向

工具支撑:

  • hub.py dispatch --model providerID/modelID 指定模型;新建会话时若目标模型不可达,会按候选链兜底(否则会话一创建就 failed),恢复链路不使用候选链。
  • fix_free_limit.py / fill_slots.py 均从 config.json 读该实例的 fallback_model,不再共用全局常量;运行日志里按 实例=模型 记录实际取值。
  • POST /api/session/:id/model + {"model": {"id": modelID, "providerID": …, "modelID": …}} 是切模型的唯一有效方式(id 只填 modelID);在 prompt body 里带 model 无效。

七、巡检与自愈(每 10 分钟,常驻进程)

loop_resume.py 每 tick 依次执行三段(顺序有意义:先恢复已有会话占位,再补新任务):

  1. fix_free_limit.py —— 额度自愈:命中限流/不可用特征、且错误所属轮次模型 == 会话当前模型的会话 → 切到 axonhub/deepseek 并投递续做指令(按第六节模型策略,无 axonhub 的实例整体跳过);
  2. check_agents.py —— 检查 + 恢复:
    • 报告:每实例 运行中CFC / 近期完成 / 失败 / 待恢复;运行中明细(模型、多久前更新、末条消息在干什么);
    • 恢复:outcome=interrupted(明确中断)、outcome=failed(失败)、succeeded/空但末条判为半途停下的会话 → 投递续做指令;
    • 保护:只处理 CFC 会话;生产实例默认跳过(--allow-prod 放行);同一会话冷却 --cooldown-minutes(默认 20 分钟,状态写 out/resume_state.json);每实例最多恢复到并发上限;只看最近 --recent-hours(默认 12 小时)有活动的会话。
  3. fill_slots.py —— 并发位补齐:保证每个智能体都有「并发上限」个 CFC 会话在跑。
    • 有空闲位时,从任务池 tools/xaf_agent_hub/tasks_backlog.json 按 priority 取 status=pending 的任务派发过去;
    • 任务池按项目进度编排(12 个任务:T01 首页家庭任务数 / T02 删除空壳子系统 / T03 活动报名名册 / T04 活动海报重设计 / T05 限时特价 / T06 知识库统一 / T07 恢复单元测试 / T08 仓库卫生 / T09 审核中心统一详情 / T10 综合健康问卷 / T11 健康计划删除 / T12 活动签到审核页),每个任务带规格路径、落点与提交纪律;
    • 派发后写 session_id / dispatched_at / model,同一任务不会重复派发;会话结束且 succeeded 时近似回填 done(最终以智能体汇报为准);
    • 任务池空了就停手(不刷屏);生产实例默认不补位。

日志:心跳 out/resume_loop.log;分别行为 out/free_limit_runs.log、out/agent_check.log、out/fill_slots.log。 进度查看:python tools/xaf_agent_hub/check_agents.py(谁在跑什么)、编辑 tasks_backlog.json 增删任务、hub.py watch。

7.1 三层保活(防止巡检挂掉没人管,12:08 起为 V2 口径)

层级 角色 载体 失活后由谁拉起
L1 loop_resume.py 巡检本体 后台常驻进程 L2 看门狗
L2 watchdog.py --loop 看门狗 由 L3 计划任务直接承载(任务常驻 Running),每 5 分钟检查 L1 L3:进程死了下个 10 分钟触发点重开任务
L3 Windows 计划任务「xaf_hub_watchdog」 OS 调度,动作 = watchdog.py --loop,ExecutionTimeLimit=PT0S(不限时) 自身:Running 期间 IgnoreNew 去重;死后按触发点重启

V2 变更(12:08 实测教训):旧 L3 的动作是单次 watchdog.py(查一次就退出),它拉起的看门狗/巡检会在任务结束时被整树回收(11:38–11:55 全链静默死亡的根因)。现改为计划任务直接跑 --loop:任务永不结束 → 子进程不被回收;看门狗若死,下个触发点自动重启任务。锁 out/watchdog.lock 仍兜底防重复。

watchdog.py 判定"活着"的两个条件(任一不满足即重启):pid 文件里的进程存在且命令行确实是 loop_resume.py(防 pid 复用误判);心跳日志距今不超过 --max-stale-minutes(默认 25 分钟,进程在但卡死也算挂)。重启时先杀旧进程,再用绝对路径解释器以 DETACHED_PROCESS 方式拉起。

多个看门狗并发检查时用 out/watchdog.lock(O_CREAT|O_EXCL 原子锁 + 300 秒残留抢占)互斥,避免同时拉起两个巡检进程。

L3 注册命令(当前生效版本):

$py = "C:\Users\liaoxg.DESKTOP-DGLN79N\.workbuddy\binaries\python\versions\3.13.12\python.exe"
$script = "E:\cfc\tools\xaf_agent_hub\watchdog.py"
$action  = New-ScheduledTaskAction -Execute $py -Argument "`"$script`" --loop --loop-interval-minutes 5" -WorkingDirectory "E:\cfc\tools\xaf_agent_hub"
$trigger = New-ScheduledTaskTrigger -Once -At (Get-Date).AddMinutes(1) `
             -RepetitionInterval (New-TimeSpan -Minutes 10) -RepetitionDuration (New-TimeSpan -Days 3650)
$settings = New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries `
             -StartWhenAvailable -MultipleInstances IgnoreNew -ExecutionTimeLimit ([TimeSpan]::Zero)
Register-ScheduledTask -TaskName "xaf_hub_watchdog" -Action $action -Trigger $trigger `
             -Settings $settings -Force

⚠️ 不要用 schtasks.exe:它被本机沙箱的程序黑名单拦截(该黑名单属 WorkBuddy 客户端安全设置,不是 Windows 安全中心)。改用上面的 Register-ScheduledTask cmdlet 即可,实测注册成功、LastTaskResult=0、每 10 分钟触发。

⚠️ 本机实例 local-45278 = opencode 官方后台服务(12:18 起):v2.0.32+ 的 opencode web 子命令已取消(用 serve),单独 serve 起的进程认证对不上。已用 opencode service set port 45278 把官方后台服务固定在 45278(重启验证通过),~/.config/opencode/service.json 即其密码。不要再用 serve 手工起端口——后台服务自己就监听 45278,服务挂了用 opencode service restart。

常用命令:

# 看状态(不动手)
python tools/xaf_agent_hub/watchdog.py --dry-run
# 巡检挂了就修
python tools/xaf_agent_hub/watchdog.py
# 起/停常驻看门狗
python tools/xaf_agent_hub/watchdog.py --loop --loop-interval-minutes 5
python tools/xaf_agent_hub/watchdog.py --stop-loop
# 查看计划任务
powershell -Command "Get-ScheduledTaskInfo -TaskName xaf_hub_watchdog"

八、验收与巡检

  • 逐个工作包验收依据:规格文档中的验收标准 + 对应模块编译通过 +(W10 之后)单元测试通过。