平台运营批次 · 契约核对结论（25 SC · 防假 RED）
归属：契约补建计划 P0「平台运营（Web 管理端 / 运营治理）」· 核对时间 2026-11-07（EVD-11）
开工包：docs/tdd/orchestration/admin-ops-kickoff-20261107.md（origin/cfclub @ 802cbbce4）
核对对象：origin/cfclub cfc-backend controller 源码（工作树 HEAD = origin/cfclub）
核对方法：类级 @RequestMapping + 方法级 @PostMapping 逐一比对（grep -rn '@RequestMapping|@PostMapping' cfc-backend/src/main/java/com/etotem/cfc/controller/ 实测定位，不假定包路径），逐端点记录存在性；对字面路径缺失者定位等价实现（防假 RED：契约声明的接口范围必须能在真实源码中找到实现）
0. 结论摘要
- 25 个 SC 中 21 个存在可用 HTTP 端点载体（其中 16 个端点齐全、5 个端点存在但控制器归属/路径与开工包初核不同，已完成实测回填）。
- 4 个 SC 无完整 HTTP 端点载体：SC-A-04（关系类型 CRUD，
relationship_types 表已废弃，无独立 admin 端点）、SC-A-14（系统监控/告警，仅 /api/system/health 状态探活，无告警管理端点）、SC-A-19（账号注销/数据导出工单处理，仅用户侧 /api/user/deactivate、/api/user/data-export，无运营工单处理端点）、SC-A-20（限流/熔断配置，RateLimitInterceptor 为代码内置，无 HTTP 配置端点）。以上 4 个按 O-7 标注「无端点载体，需产品侧确认验收方式」。
- 端点核对范围内 无「假 RED」：凡开工包标注 ⚠ 待核实的 9 项（A-05/A-08/A-10/A-14/A-15/A-19/A-20/A-21/A-22），逐一实测回填，其中 5 项确认端点存在（A-05/A-08/A-10/A-15/A-22），4 项无完整载体（A-14/A-19/A-20/A-21 部分）。
- 无新增 DB 迁移、未改动业务代码与测试文件（本批次仅新增本核对文档 + API_REFERENCE 增补段落）。
1. 端点存在性核对（按 SC 清单，25 个）
列：SC → 开工包候选载体 → 实测源码端点（@RequestMapping 类级 + @PostMapping 方法级）→ 结论。
1.1 SC-A-01 管理端登录 + 全局统计
| 开工包候选 |
实测端点 |
结论 |
AdminAuthController /api/admin/auth/* |
实际类级前缀 /api/admin-auth（非 /api/admin/auth）：POST /api/admin-auth/login、/login-by-password、/send-code、/info、/change-password、/reset-password、/update-info、/account-roles、/wechat-scan-qr、/wechat-scan-poll |
✅ 端点齐全（1 处前缀差异见 §3） |
StatsController /api/stats/* |
/api/stats：dashboard、overview、trend、revenue、traffic、membership、family/summary、child/overview、child-completion、family-completion、points/ranking、product-view |
✅ 端点齐全 |
1.2 SC-A-02 报告解析中台（类型/聚类）
| 开工包候选 |
实测端点 |
结论 |
AdminReportParseController /api/admin/report-parse/* |
实际类名 ReportParseAdminController：/api/admin/report-parse：list、types、types/save、types/delete、types/toggle、unknown-clusters、unknown-uploads、generate-type、fingerprints/list、fingerprints/save、fingerprints/delete、imports、imports/import、imports/approve、imports/reject、retry、dan/reparse、backfill-food |
✅ 端点齐全（类名差异，非能力缺口） |
1.3 SC-A-03 文章发布-审核
| 开工包候选 |
实测端点 |
结论 |
AdminArticleController /api/admin/articles/* |
/api/admin/articles：list、detail、create、update、delete、publish、{id}/publish、submit-review、audit、withdraw、re-draft、move、toggle-featured、backfill-tags、categories/list、categories/create、categories/update、categories/delete、comments/list、reading-records、upload/image、upload/video |
✅ 端点齐全 |
1.4 SC-A-04 关系类型 CRUD ⚠
| 开工包候选 |
实测结论 |
结论 |
AdminRelationshipTypeController /api/admin/relationship-types/* |
无此 Controller、无 /api/admin/relationship-types 路由。relationship_types 表已在迁移中 DROP（DatabaseInitializer 迁移 169），关系语义改由 family_relationships 表（迁移 41）承载，成员关系编辑走 FamilyMembersController /api/family/member/{add,update} + FamilyRelationshipService，无独立运营 CRUD 端点 |
⚠ 无端点载体，需产品侧确认验收方式（member add/update 可承载关系写入，但无类型字典 CRUD） |
1.5 SC-A-05 勋章配置 CRUD ⚠（回填：已存在）
| 开工包候选 |
实测端点 |
结论 |
| 「勋章/成就 admin 端点（须实测定位）」 |
BadgeController /api/badges：create、update、delete、all、list、detail、member/list、ranking/family、grant、favorite、statistics/member；AdminChallengeScoreConfigController /api/admin/challenge-score-config：list、update |
✅ 确认存在（勋章 CRUD + 挑战分配置，与任务-激励批 SC-A-05 核验一致） |
1.6 SC-A-06 供应商管理
| 开工包候选 |
实测端点 |
结论 |
AdminSupplyManageController；/api/admin/supply-hierarchy/* |
SupplyManageController /api/admin/supply-manage：list、detail、create、update、delete、add-role、remove-role、adjust-tier；SupplyHierarchyController /api/admin/supply-hierarchy：tree、my、parent、parent-chain、direct-children、all-children、set、remove、change/apply、change-requests、change/review；另 AdminSupplierController /api/admin/supplier：list、save、update、delete |
✅ 端点齐全 |
1.7 SC-A-07 活动配置
| 开工包候选 |
实测端点 |
结论 |
活动 admin 端点；/api/admin/activity-checkins |
AdminActivityController /api/admin/activity：list、detail、audit、review、submit-review、withdraw、re-draft、backfill-tags；AdminActivityCheckinController /api/admin/activity-checkins：list、add、review、export |
✅ 端点齐全 |
1.8 SC-A-08 知识库管理 ⚠（回填：已存在，控制器名不同）
| 开工包候选 |
实测端点 |
结论 |
AdminKnowledgeController（维度知识库） |
无 AdminKnowledgeController；实际载体：KnowledgeBaseController /api/admin/knowledge-base（list、get、save、delete、upload-file、fetch-url、backfill-tags、bind-tags、bind-dimensions）+ KnowledgeBaseVectorController /api/admin/knowledge-base/vector（documents、stats、sync、delete-source、update-document）+ KnowledgeTagController /api/admin/knowledge-tag（list、save、delete）+ AdminUnifiedKnowledgeController /api/admin/knowledge-base/unified（overview、section、update、reset） |
✅ 确认存在（载体为 KnowledgeBaseController 系，非开工包猜测类名） |
1.9 SC-A-09 维度配置与知识库管理
| 开工包候选 |
实测端点 |
结论 |
DimensionAdminController /api/admin/dimension/*；DimensionRegistryController /api/dimension-registry/* |
DimensionAdminController /api/admin/dimension：data-source/list、data-source/save、data-source/delete、data-source/detail、norm/list、norm/save、norm/delete；DimensionRegistryController /api/dimension-registry：注册表查询；DimensionConfigController /api/admin/dimension-config：list、get、save、delete、tree |
✅ 端点齐全 |
1.10 SC-A-10 数据迁移 / 参数校验 ⚠（回填：已存在）
| 开工包候选 |
实测端点 |
结论 |
迁移类端点 + DatabaseInitializer（非 HTTP，判载体） |
DataMigrationController /api/migration：run；MigrationController /api：migrate/guide-packages、migrate/knowledge-base-to-articles；参数校验/动态配置载体 SysConfigController /api/admin/config：list、update、all |
✅ 确认存在（HTTP 载体 = 两个迁移 Controller + SysConfig；DatabaseInitializer 为启动期自动迁移，非 HTTP，作为补充载体） |
1.11 SC-A-11 用户/家庭查询治理
| 开工包候选 |
实测端点 |
结论 |
AdminFamilyOverviewController；/api/admin/org/member/* |
AdminFamilyOverviewController（类级 /api/admin）：families/{id}/overview、families/{id}/tasks；AdminOrgMemberController /api/admin/org/member：list、add、remove、change-type；AdminController /api/admin：users、users/create、user/search、users/{id}、users/{id}/update、users/{id}/delete、users/{id}/reset-password、families、families/{id}、families/{id}/update、families/{id}/delete、families/{id}/members、families/{id}/members/set-admin、children、children/{id}、children/{id}/update、children/{id}/adjust-points、guide/applications 等 |
✅ 端点齐全 |
1.12 SC-A-12 订单/退款人工处理
| 开工包候选 |
实测端点 |
结论 |
AdminProductOrderController /api/admin/product/order/* |
/api/admin/product/order：list、detail、ship、update-express、refund/approve、refund/reject、close |
✅ 端点齐全 |
1.13 SC-A-13 内容安全审核
| 开工包候选 |
实测端点 |
结论 |
AdminReviewCenterController /api/admin/review-center/* |
实际类名 ReviewCenterController：/api/admin/review-center/summary（聚合待审计数：article/product/guide/vendor/butler/package/activity/registration/withdraw/refund/hierarchyChange/nutritionist/knowledge）；文章审核走 AdminArticleController.audit + comments/list；活动审核走 AdminActivityController.audit |
✅ 端点齐全（类名差异，非能力缺口） |
1.14 SC-A-14 系统监控/告警 ⚠
| 开工包候选 |
实测端点 |
结论 |
| 监控端点（可能无 HTTP 载体 → 记缺口） |
唯一相关端点 AdminSystemController /api/system/health：JVM uptime / 内存 / CPU / OS 运行状态探活。无告警规则管理、无监控大盘查询端点 |
⚠ 端点载体不完整：仅状态探活（health），缺「告警配置/告警记录」类端点，需产品侧确认验收方式（是否以 health + 运维侧监控替代） |
1.15 SC-A-15 操作审计日志 ⚠（回填：已存在，控制器为两个）
| 开工包候选 |
实测端点 |
结论 |
| 审计端点（须实测） |
OperationLogController /api/admin/logs：operations（分页查询操作日志）、recent；AdminAuditController /api/admin/audit：list |
✅ 确认存在 |
1.16 SC-A-16 报告解析自学习/未知类型标注
| 开工包候选 |
实测端点 |
结论 |
AdminReportParseController（标注/学习链） |
ReportParseAdminController /api/admin/report-parse：types、types/save、types/delete、types/toggle、unknown-clusters、unknown-uploads、generate-type、fingerprints/list、fingerprints/save、fingerprints/delete、imports/import、imports/approve、imports/reject、retry、backfill-food、dan/reparse |
✅ 端点齐全 |
1.17 SC-A-17 优惠券/活动配置管理
| 开工包候选 |
实测端点 |
结论 |
AdminCouponController /api/admin/coupon/* |
/api/admin/coupon：list、create、update、delete、toggle-status、issue、issue-family、grant-log、grant-user、family-coupons、family-coupon-usage、gift-transfers |
✅ 端点齐全 |
1.18 SC-A-18 内容安全审核队列
| 开工包候选 |
实测端点 |
结论 |
AdminReviewCenterController（队列） |
ReviewCenterController /api/admin/review-center/summary：待审计数队列（13 类待审聚合）；具体队列列表由各业务 admin list 端点提供（articles/list、activity/list、product/order/list、coupon/list 等） |
✅ 端点齐全（队列计数 + 业务列表） |
1.19 SC-A-19 账号注销/数据导出工单处理 ⚠
| 开工包候选 |
实测端点 |
结论 |
| 工单端点（可能缺 → 记缺口） |
无运营工单处理端点。仅有用户侧自助端点：UserController：/api/user/deactivate（注销账号，AccountCleanupService.deactivateAccount）、/api/user/data-export（数据导出，AccountCleanupService.exportUserData）。无 admin 侧工单受理/审批/处理队列端点 |
⚠ 无端点载体，需产品侧确认验收方式（用户自助注销/导出已实现，运营受理工单端点缺） |
1.20 SC-A-20 限流/熔断配置 ⚠
| 开工包候选 |
实测端点 |
结论 |
| 配置类端点（须实测） |
无 HTTP 配置端点。限流为代码内置：RateLimitInterceptor（Redis 滑动窗口，高频 10 次/秒、验证码 1 次/60 秒）+ WebConfig 注册；熔断内置于 AiGateway（超时 + Fallback）。阈值不可通过管理端配置 |
⚠ 无端点载体，需产品侧确认验收方式（限流/熔断已实现为代码内置，运营侧无可配置端点） |
1.21 SC-A-21 舌诊/情绪模型管理 ⚠
| 开工包候选 |
实测端点 |
结论 |
AdminInnatePortraitConfigController；舌诊模型 admin |
InnatePortraitConfigController /api/admin/innate-portrait-config：list、update、invalidate（先天画像来源权重配置）；情绪模型 EmotionRecognitionController /api/mind/emotion：analyze、analyze-url（情绪识别，C 端调用）；舌诊 TongueDiagnosisService 挂在 HealthReportController（/api/health/report/* 报告上传链内），无独立舌诊模型管理端点 |
⚠ 端点载体部分存在：先天画像配置/情绪识别端点有，但「舌诊模型管理」无独立 admin 端点（模型配置内联在报告解析链路），需产品侧确认验收方式（是否以 innate-portrait-config + 报告链替代） |
1.22 SC-A-22 精准营养知识库管理 ⚠（回填：已存在，控制器归属不同）
| 开工包候选 |
实测端点 |
结论 |
| 营养知识库 admin 端点 |
知识库数据载体 HealthKnowledgeBaseController /api/health/knowledge（非 admin 前缀，含 C 端查询 + 管理方法）：add、update、delete、list、import、unified/*（overview、section、bacteria/query、bacteria/batch-query、food/query、indicator/query、indicator/category、nutrient/query、nutrient-standard/get、species-info/query、species-desc/query、genus-food-mapping/list、health-score/get、unified/import）、v3/*；管理侧补充 AdminFoodController /api/admin/foods：list、create、update、delete、detail、saveMonths |
✅ 确认存在（知识库本体 + 食物管理双载体；注意知识库写入端点未挂在 /api/admin 下，权限粒度需测试侧核验） |
1.23 SC-A-25 维度/权重/每日上限配置 CRUD 与生效
| 开工包候选 |
实测端点 |
结论 |
DimensionWeightController /api/admin/dimension-weight/*；AdminEnergyConfigController /api/admin/energy-config/* |
DimensionWeightController /api/admin/dimension-weight：list、save；AdminEnergyConfigController /api/admin/energy-config：overview、daily-limits、daily-limit-save、source-list、source-save、source-delete |
✅ 端点齐全 |
1.26 SC-A-26 能量来源比例与归因权重治理
| 开工包候选 |
实测端点 |
结论 |
AdminEnergyConfigController /source-*；AdminEnergyRuleController /api/admin/energy-rule/* |
AdminEnergyConfigController /api/admin/energy-config：source-list、source-save、source-delete、overview、daily-limits、daily-limit-save；AdminEnergyRuleController /api/admin/energy-rule：list、dimensions、create、update、delete、toggle |
✅ 端点齐全 |
1.27 SC-A-27 后台维护睡眠选项并同步小程序端（状态机内，仅登记映射）
| 开工包候选 |
实测端点 |
结论 |
sleep.config.tags（YELLOW，实现已在 origin/cfclub） |
配置载体 SysConfigController /api/admin/config：list、update、all（管理端维护 sleep.config.tags）；分发载体 PublicConfigController /api/config/public/value（小程序端拉取 sleep.quality.tags）；HealthSleepController /api/health/sleep：list、create |
✅ 已在状态机（YELLOW），本批只登记 SC↔键映射，不新建任务 |
2. 建议能力键映射（SC → 能力键，按 O-2 方案 A）
| SC |
场景标题 |
建议能力键 |
端点核验结论 |
备注 |
| SC-A-01 |
管理端登录 + 全局统计 |
admin.auth.login |
✅ 端点存在 |
登记映射，不新建任务（已在状态机） |
| SC-A-02 |
报告解析中台（类型/聚类） |
admin.reportParse.manage |
✅ 端点存在 |
类名 ReportParseAdminController |
| SC-A-03 |
文章发布-审核 |
admin.article.review |
✅ 端点存在 |
|
| SC-A-04 |
关系类型 CRUD |
admin.relationshipType.crud |
⚠ 无端点载体 |
需产品侧确认验收方式 |
| SC-A-05 |
勋章配置 CRUD |
admin.medal.config |
✅ 端点存在 |
勋章 CRUD + 挑战分配置 |
| SC-A-06 |
供应商管理 |
admin.supplier.manage |
✅ 端点存在 |
三 Controller 载体 |
| SC-A-07 |
活动配置 |
admin.activity.config |
✅ 端点存在 |
|
| SC-A-08 |
知识库管理 |
admin.knowledge.manage |
✅ 端点存在 |
载体 KnowledgeBaseController 系 |
| SC-A-09 |
维度配置与知识库管理 |
admin.dimension.config |
✅ 端点存在 |
|
| SC-A-10 |
数据迁移 / 参数校验 |
admin.data.migrate |
✅ 端点存在 |
迁移 + SysConfig 双载体 |
| SC-A-11 |
用户/家庭查询治理 |
admin.userGovernance |
✅ 端点存在 |
|
| SC-A-12 |
订单/退款人工处理 |
admin.order.manual |
✅ 端点存在 |
|
| SC-A-13 |
内容安全审核 |
admin.content.audit |
✅ 端点存在 |
ReviewCenter + 业务 audit |
| SC-A-14 |
系统监控/告警 |
admin.monitor.alarm |
⚠ 端点载体不完整 |
仅 health 探活，无告警管理端点 |
| SC-A-15 |
操作审计日志 |
admin.auditLog.view |
✅ 端点存在 |
logs/operations + audit/list |
| SC-A-16 |
报告解析自学习/未知类型标注 |
admin.parse.label |
✅ 端点存在 |
|
| SC-A-17 |
优惠券/活动配置管理 |
admin.coupon.config |
✅ 端点存在 |
|
| SC-A-18 |
内容安全审核队列 |
admin.content.audit（复用 A-13 键） |
✅ 端点存在 |
建议与 A-13 同键或建 admin.content.auditQueue，定稿时取舍 |
| SC-A-19 |
账号注销/数据导出工单处理 |
admin.ticket.handle |
⚠ 无端点载体 |
用户侧端点存在，运营工单端点缺 |
| SC-A-20 |
限流/熔断配置 |
admin.ratelimit.config |
⚠ 无端点载体 |
代码内置拦截器 |
| SC-A-21 |
舌诊/情绪模型管理 |
admin.mind.model |
⚠ 端点载体部分存在 |
先天画像配置/js识别有，舌诊模型独立端点缺 |
| SC-A-22 |
精准营养知识库管理 |
admin.nutrition.kb |
✅ 端点存在 |
知识库 + Foods 双载体 |
| SC-A-25 |
维度/权重/每日上限配置 CRUD 与生效 |
energy.viewConfig |
✅ 端点存在 |
同键勿重复（与 EVD-5 五维能量批同键） |
| SC-A-26 |
能量来源比例与归因权重治理 |
energy.viewConfig（或 energy.ruleConfig，定稿时取舍） |
✅ 端点存在 |
与 A-25 同源配置面 |
| SC-A-27 |
后台维护睡眠选项并同步小程序端 |
sleep.config.tags |
✅ 已在状态机 |
登记映射，不新建任务（已在状态机 YELLOW） |
⚠ 键去重提示：admin.auth.login、sleep.config.tags 已在状态机，本批只登记映射不新建任务；admin.content.audit 若 A-13/A-18 合并用一键，则只建一个任务（建议 A-18 复用 A-13 键，审核队列为同一能力的视图）。
3. 字面路径/控制器归属差异清单（非能力缺口，实操对齐项）
| # |
开工包声明 |
实际实现 |
影响 SC |
处置建议 |
| 1 |
AdminAuthController /api/admin/auth/* |
类级前缀 /api/admin-auth/*（AdminAuthController） |
SC-A-01 |
契约接口范围改用 /api/admin-auth/*（前端已按此调用，勿按开工包路径断言） |
| 2 |
AdminReportParseController |
实际类名 ReportParseAdminController（/api/admin/report-parse） |
SC-A-02/A-16 |
--design 标注真实类名 |
| 3 |
AdminKnowledgeController |
不存在；实际 KnowledgeBaseController + KnowledgeBaseVectorController + KnowledgeTagController + AdminUnifiedKnowledgeController |
SC-A-08 |
契约接口范围对齐到 /api/admin/knowledge-base/** |
| 4 |
AdminReviewCenterController |
实际类名 ReviewCenterController |
SC-A-13/A-18 |
--design 标注真实类名 |
| 5 |
营养知识库「admin 端点」 |
知识库本体在 /api/health/knowledge（非 admin 前缀）；admin 侧仅 AdminFoodController /api/admin/foods |
SC-A-22 |
契约接口范围明确双载体；知识库写入端点的权限粒度留待测试侧补权限流核验 |
4. 实现缺口清单（无端点载体 / 载体不完整，需产品侧确认）
| # |
SC |
场景标题 |
建议能力键 |
缺口描述 |
处置建议 |
| 1 |
SC-A-04 |
关系类型 CRUD |
admin.relationshipType.crud |
relationship_types 表已废弃 DROP；无独立字典 CRUD 端点；关系语义由 family_relationships + FamilyMembersController.update/add 承载 |
无端点载体，需产品侧确认验收方式：若需字典管理，新增 AdminRelationshipTypeController（先产品确认）；或改以成员关系编辑验证 |
| 2 |
SC-A-14 |
系统监控/告警 |
admin.monitor.alarm |
仅 /api/system/health（JVM/内存/CPU 探活），无告警规则/告警记录/监控大盘端点 |
无端点载体，需产品侧确认验收方式：若仅需探活，health 可验收；若需告警治理，待实现 |
| 3 |
SC-A-19 |
账号注销/数据导出工单处理 |
admin.ticket.handle |
用户侧自助注销/导出已有（/api/user/deactivate、/api/user/data-export），但无运营工单受理/审批/处理队列 admin 端点 |
无端点载体，需产品侧确认验收方式：先产品确认工单流程是否必须，若必须则新增 admin 工单端点 |
| 4 |
SC-A-20 |
限流/熔断配置 |
admin.ratelimit.config |
限流为代码内置 RateLimitInterceptor（常量阈值），熔断内置于 AiGateway，均无可配置端点 |
无端点载体，需产品侧确认验收方式：若阈值可接受硬编码则测试侧以现状验收；若需运营可调，待实现配置端点 |
| 5 |
SC-A-21 |
舌诊/情绪模型管理 |
admin.mind.model |
先天画像配置 /api/admin/innate-portrait-config（list/update/invalidate）存在；情绪识别 /api/mind/emotion 存在；舌诊模型无独立 admin 管理端点（模型配置内联在报告解析链） |
端点载体部分存在：产品侧确认验收方式——以先天画像配置 + 报告链验收，或补舌诊模型管理端点 |
缺口统计：5 个（完整无载体 3 个：A-04/A-19/A-20；载体不完整 2 个：A-14/A-21；A-21 部分载体可议）。
5. 核对结论与后续动作
- 防假 RED 结论：25 个 SC 中 21 个端点存在（16 齐全 + 5 归属/路径差异已回填），4 个无完整端点载体（A-04/A-14/A-19/A-20；A-21 部分）。全部 ⚠ 待核实项已实测回填，无假定包路径结论。
- 定稿前置：§3 的 5 处归属/路径差异，契约编写时直接采用真实端点；§4 的 5 个缺口按 O-7 标注「无端点载体，需产品侧确认验收方式」，不先行补实现。
- 能力键映射：25 个 SC 建议键见 §2；
admin.auth.login、sleep.config.tags 已在状态机，本批仅登记映射不新建任务；energy.viewConfig 与 EVD-5 批同键不重复；admin.content.audit A-13/A-18 建议同键合一。
- 台账回填：本契约核对文档 + API_REFERENCE 增补段落合入 origin/cfclub 后，研发负责人登记 TR-13 转测试侧（补 admin 端点 MockMvc 契约 JUnit + 非 admin token → 403 权限流）。
核对依据：origin/cfclub @ 802cbbce4（开工包 admin-ops-kickoff-20261107.md）+ 各 Controller 源码 @ 同 sha；核对人：TDD 契约核对会话 EVD-11（OpenCode）。本批仅新增契约文档（spec + API_REFERENCE 增补），未修改业务代码、测试文件、DB 迁移。
