前端对接清单 — 项目资料 + 内容生产
面向前端同学：按「前端页面 → 后端接口 → 请求/响应参数 → 当前是否可对接」逐页对照，覆盖两个大模块。
- 模块 A · 内容生产（内容 / 审核 / 发布 / 分析与建议）：接口契约
docs/api/content-production.openapi.yaml，路由app/api/route/content.php（下文 §0–§6）- 模块 B · 项目资料（来源 / 知识 / 执行约束 / 图片素材 / 治理）：接口契约
docs/api/project-materials.openapi.yaml，路由app/api/route/material.php（下文 §M0–§M5） 生成基线：2026-08-14 代码状态 + 当前.env配置。可用性符号：🟢 可直接对接 · 🟡 依赖未验证的外部 AI/存储 · 🔴 开关关闭或接口未实现。
0. 全局约定（对接前必读）
| 项 | 约定 |
|---|---|
| 基础路径 | 所有接口前缀 /api，即 https://<host>/api/front/content/... |
| 认证 | Authorization: Bearer <JWT>（复用既有用户模块登录拿到的 token；与项目资料模块同一套） |
| 响应封套 | 统一 { "code": 0, "msg": "success", "data": {...} }；code = 0 表示成功，非 0 为错误 |
| 业务错误 | 内容模块业务错误在 data.error_code 上返回 CONTENT_* 枚举（见 OpenAPI ErrorData），如 CONTENT_REVISION_CONFLICT、CONTENT_LEASE_CONFLICT、CONTENT_CAPABILITY_UNAVAILABLE、CONTENT_SHARE_EXPIRED 等 |
| 分页 | 列表统一 page（默认 1）、limit（默认 20，最大 100） |
| 幂等 | 所有写操作须带请求头 Idempotency-Key（ASCII 1–64 字符，见 BaseController::idempotencyKey()）。生产 IDEMPOTENCY_REQUIRED=true 强制；当前测试环境 IDEMPOTENCY_REQUIRED=false，缺省头会自动生成一次性键（幂等退化为单次），前端仍建议主动传 |
| 乐观锁 | 计划/单元/文章写操作需带 expected_revision / expected_plan_revision（上次读到的版本号）；不匹配返回 CONTENT_REVISION_CONFLICT，前端刷新后重试 |
| 编辑租约 | 文章正文编辑先 acquire 拿 lease_token（64 位 hex，TTL 300s），保存正文须回传该 token；过期/被他人占用返回 CONTENT_LEASE_CONFLICT |
| 可用性符号 | 🟢 可直接对接 · 🟡 接口存在但依赖未开启的 AI/外部能力 · 🔴 开关关闭或接口未实现，前端应冻结/隐藏 |
1. 可用性总览
| 功能域 | 前端页面 | 后端接口 | 当前状态 |
|---|---|---|---|
| 工作流开关 | L01（项目设置-协作） | GET/POST /workflow |
🟢 |
| 我的内容 | C01 | GET /articles/mine |
🟢 |
| 新建内容（手工/粘贴） | C02 | POST /articles（manual_editing） |
🟢 |
| 新建内容（AI / Agent） | C02 | POST /articles（AI 执行器） |
🔴 AI 关闭 + Agent 未配置 |
| 文章编辑器 | C03 | edit-session/*、content、context、versions |
🟢 |
| 文章/版本只读 | C03R | GET /articles/:id、versions、article-versions/:id |
🟢 |
| 完成前检查（状态机） | C04 | checks/* |
🟢 |
| 完成前检查（AI 结果项） | C04 | （检查项由 AI 生成） | 🔴 CONTENT_AI_ENABLED=false |
| 计划与排期（手工） | C05 / C05N / C05E | plans/*、units |
🟢 |
| 计划智能生成 | C05N | plans/:id/generation/* |
🔴 CONTENT_PLAN_GENERATION_ENABLED 未开启 |
| 计划交接写作 | C05H | POST /plans/:id/handoff |
🟢 |
| 计划客户确认（外链） | C05E + X01 | confirmations/* + share/plan/* |
🟢 |
| 写作 Agent | C06 / C06D | — | 🔴 后端接口未实现 |
| 审核中心 | R01 | GET /reviews |
🟢 |
| 内部审核 | R02 | reviews/* |
🟢 |
| 定稿 | R04 | finalization/* |
🔴 CONTENT_FINALIZATION_ENABLED=false |
| 发布中心 / 新建 / 配置 / 详情 | R05–R08 | publishing、publish-drafts、publish-attempts |
🔴 CONTENT_PUBLISHING_ENABLED=false |
| 外部稿件（DOC/DOCX） | R06 备选入口 | external-manuscripts/* |
🔴 CONTENT_MANUSCRIPT_ENABLED=false |
| 客户外链-计划确认 | X01 | share/plan/* |
🟢 |
| 客户外链-文章审核 | X02 | share/review/* |
🟢 |
| 分析与建议-规则段（gap 诊断） | A01 | POST/GET /analysis、GET /analysis/:id |
🔴 CONTENT_ANALYSIS_ENABLED 未开启 |
| 分析与建议-LLM 段（L2/L3 建议） | A01 | （规则产出基础上由 LLM 生成） | 🔴 LLM transport 未接 |
| 建议确认 / 落地为文章 | A01 | analysis-recommendations/:id/confirm、/link |
🔴（依赖分析开启 + 有建议记录） |
一句话结论：绿链（工作流 → 计划 → 手工写作 → 检查状态机 → 审核 → 客户外链分享）可立即对接；AI 生成 / 定稿 / 发布 / 外部稿件 / Agent / 分析与建议全部处于关闭或未实现，前端先冻结这些入口。
2. 逐页对照
C01 我的内容 — /projects/:projectId/content/mine
权限：project.view（新建/继续另需 content.manage）
| 接口 | 用途 | 请求 | 响应 | 状态 |
|---|---|---|---|---|
GET /api/front/content/articles/mine |
我的文章列表 | query：project_id（必填）、page、limit |
data = Article[]（含 id/title/owner_id/creation_status/review_status/publish_status/current_version_no 等） |
🟢 |
GET /api/front/content/workflow |
项目工作流开关（审核/发布阶段是否启用） | query：project_id |
data = ProjectWorkflow（internal_review_enabled/customer_review_enabled/publish_enabled/revision/version_no） |
🟢 |
工作流开关的后端读写归 L01（项目设置-协作 tab）。
publish_enabled=false时应隐藏发布入口。
C02 新建内容 — /projects/:projectId/content/new
权限：content.manage
| 接口 | 用途 | 请求 | 响应 | 状态 |
|---|---|---|---|---|
POST /api/front/content/articles |
创建文章（四类业务来源汇入） | body ArticleCreate：project_id、source_type、executor_type、title、owner_id、topic 必填；可选 original_body（粘贴正文）、project_questions/keywords/reference_materials、audience/tone/length_requirement/content_form/image_requirements、workflow（三项开关）、workflow_change_reason |
data = Article |
🟢（仅 manual_editing） |
字段枚举（关键）：
source_type：direct_requirement（直接需求）/content_plan（来自计划）/analysis_recommendation（分析推荐）/existing_article（已有文章）executor_type：manual_editing（手工，✅ 当前可用）/configured_system_writer（系统写作器，🔴 未配置）/explicit_agent（显式 Agent，🔴 未配置 + AI 关闭）
⚠️ 当前
CONTENT_SYSTEM_WRITER_ID、content.explicit_agents均为空，AI 关闭。前端「AI 生成 / 指定 Agent」两种新建模式须冻结，只保留手工编辑 + 粘贴original_body。
C03 文章编辑器 — /projects/:projectId/content/articles/:articleId/edit
权限：content.manage
| 接口 | 用途 | 请求 | 响应 | 状态 |
|---|---|---|---|---|
POST /api/front/content/articles/:id/edit-session/acquire |
获取编辑租约 | body LeaseAcquire：project_id（可选 lease_token 续期） |
data：lease_token、editable_by_me、lease_expires_at |
🟢 |
GET /api/front/content/articles/:id/content |
读工作副本正文 | query：project_id |
data = MutableWorkCopy（title/body/image_refs/revision/editable_by_me/lease_expires_at/base_version_id） |
🟢 |
POST /api/front/content/articles/:id/content |
保存正文 | body WorkCopyUpdate：project_id、title、body（≤1MB）、image_refs、expected_revision、lease_token |
data = 更新后的 MutableWorkCopy |
🟢 |
POST /api/front/content/articles/:id/edit-session/release |
释放租约 | body LeaseRelease：project_id、lease_token |
data = 空 |
🟢 |
GET /api/front/content/articles/:id/context |
读写作上下文 | query：project_id |
data = ArticleContext（topic/project_questions/keywords/reference_materials/executor_type 等） |
🟢 |
POST /api/front/content/articles/:id/context |
更新上下文 | body ContextUpdate：project_id、expected_revision + 上下文字段 |
data = ArticleContext |
🟢 |
POST /api/front/content/articles/:id/start-manual |
转手工编辑 | body：project_id |
data = Article |
🟢 |
GET /api/front/content/articles/:id/versions |
版本列表 | query：project_id |
data = ArticleVersion[] |
🟢 |
POST /api/front/content/articles/:id/versions |
保存（固定）版本 | body：project_id、lease_token |
data = ArticleVersion（含 version_no/creation_reason） |
🟢 |
POST /api/front/content/articles/:id/cancel |
取消 | body：project_id |
data = Article |
🟢 |
POST /api/front/content/articles/:id/archive |
归档 | body：project_id |
data = Article |
🟢 |
GET /api/front/content/articles/:id |
文章详情 | query：project_id |
data = Article |
🟢 |
编辑器内的「AI 续写 / AI 优化 / 本地改写建议」按钮对应
ai-jobs、proposals接口，当前 🔴（见下「AI 能力」）。
C03R 文章 / 固定版本只读 — /content/articles/:articleId/view、/content/articles/:articleId/versions/:versionId
权限：project.view / content.review / publish.view
| 接口 | 用途 | 请求 | 响应 | 状态 |
|---|---|---|---|---|
GET /api/front/content/articles/:id |
文章记录只读 | query：project_id |
data = Article |
🟢 |
GET /api/front/content/articles/:id/versions |
版本列表 | query：project_id |
data = ArticleVersion[] |
🟢 |
GET /api/front/content/article-versions/:versionId |
固定版本详情（含绑定资料快照） | query：project_id + path versionId |
data = ArticleVersion（含 context_snapshot、source_snapshot） |
🟢 |
C04 完成前检查 — /projects/:projectId/content/articles/:articleId/check
权限：content.manage
| 接口 | 用途 | 请求 | 响应 | 状态 |
|---|---|---|---|---|
POST /api/front/content/articles/:id/checks |
发起检查 | body CheckCreate：project_id、allow_context_gaps，version_id 或 lease_token 二选一 |
data = 检查任务（check_id） |
🟢 |
GET /api/front/content/checks/:checkId |
检查详情 | query：project_id |
data = 检查（含 items[]，每项 category/severity/blocking/range/finding/evidence/source_refs/remediation） |
🟢 |
POST /api/front/content/check-items/:itemId/acknowledge |
确认/处理检查项 | body CheckAcknowledge：project_id、acknowledgement |
data = 空 |
🟢 |
POST /api/front/content/checks/:checkId/cancel |
取消检查 | body：project_id |
data = 空 |
🟢 |
⚠️ 状态机（提交/查询/确认/取消）可对接 🟢，但检查项本身由 AI 生成（
AiCheckResult）。当前CONTENT_AI_ENABLED=false，真实检查项不会产出 → 前端「检查结果」区域应显示「AI 能力未启用」占位，不要等待结果。
C05 / C05N / C05E 计划与排期 — /content/plans、/content/plans/new、/content/plans/:planId/edit
权限：查看 project.view；新建/编辑/确认/交接另需 content.coordinate
| 接口 | 用途 | 请求 | 响应 | 状态 |
|---|---|---|---|---|
GET /api/front/content/plans |
计划列表 | query：project_id、status、owner_id、page、limit |
data = ContentPlan[] |
🟢 |
POST /api/front/content/plans |
新建计划 | body PlanCreate：project_id、name、start_at（YYYY-MM-DD）、due_at、creation_mode（manual/intelligent）；不接受 owner_id/units |
data = ContentPlan |
🟢（manual）；🟡 intelligent 只建不生成 |
GET /api/front/content/plans/:id |
计划详情 | query：project_id |
data = ContentPlan（含 units[]、generation、status） |
🟢 |
POST /api/front/content/plans/:id |
更新计划 | body PlanUpdate：project_id、expected_revision + name/owner_id/start_at/due_at 至少一项 |
data = ContentPlan |
🟢 |
POST /api/front/content/plans/:id/units |
新增规划单元 | body UnitWrite：project_id、topic、planned_count、expected_plan_revision + 可选 publish_target/channels/monitoring_keyword_id/keyword/direction/constraints |
data = PlanningUnit |
🟢 |
POST /api/front/content/plans/:id/units/:unitId |
更新单元 | body UnitUpdate：project_id、expected_revision、expected_plan_revision + 补丁字段 |
data = PlanningUnit |
🟢 |
POST /api/front/content/plans/:id/units/:unitId/delete |
删除单元 | body UnitDelete：project_id、expected_revision、expected_plan_revision |
data = 空 |
🟢 |
POST /api/front/content/plans/:id/cancel |
取消计划 | body：project_id、expected_revision |
data = ContentPlan |
🟢 |
POST /api/front/content/plans/:id/archive |
归档计划 | body：project_id、expected_revision |
data = ContentPlan |
🟢 |
POST /api/front/content/plans/:id/delete |
删除计划 | body：project_id、expected_revision |
data = 空 |
🟢 |
POST /api/front/content/plans/:id/confirmations |
发起客户确认 | body PlanConfirmationRequest：project_id、expected_revision、ttl? |
data = 确认轮次（含外链 token） |
🟢 |
GET /api/front/content/plans/:id/confirmations |
确认历史 | query：project_id |
data = PlanConfirmationRound[] |
🟢 |
POST /api/front/content/plans/:id/confirmation/cancel |
取消确认 | body PlanConfirmationCancel：project_id、expected_revision |
data = PlanConfirmationCancellation |
🟢 |
计划状态枚举（status）：draft / confirmation_pending / confirmed / changes_requested / handed_off / cancelled / archived。
C05H 计划交接写作 — /content/plans/:planId/handoff
权限：content.coordinate
| 接口 | 用途 | 请求 | 响应 | 状态 |
|---|---|---|---|---|
POST /api/front/content/plans/:id/handoff |
按计划批量创建文章并冻结计划 | body PlanHandoffCommand：project_id、owner_id（团队成员）、due_at?、expected_revision |
data = 交接结果（新文章列表） |
🟢 |
C06 / C06D 写作 Agent — /content/agents、/content/agents/:agentId
权限：查看 project.view；写作另需 content.manage
🔴 后端无 Agent 接口：
app/api/route/content.php中无/agents路由；ContentAgentGateway明确「Python Agent registry 尚未实现」，config/content.php的explicit_agents = []、系统写作器 ID/版本均为空。前端此两页冻结，Agent 列表/详情/使用记录待后端补齐。
A01 分析与建议 — /projects/:projectId/content/analysis
权限：写 content.manage；读 project.view
| 接口 | 用途 | 请求 | 响应 | 状态 |
|---|---|---|---|---|
POST /api/front/content/analysis |
创建一次分析运行（规则段同步） | body AnalysisRunCreate：project_id（必填）、trigger_type（manual/scheduled，默认 manual）、window{start,end}（可选） |
data = 分析版本（id/version_no/status/coverage_rate/insufficient_data/findings[]） |
🔴 |
GET /api/front/content/analysis |
运行版本列表 | query：project_id、page、limit |
data = 版本列表 |
🔴 |
GET /api/front/content/analysis/:id |
运行详情（含发现+建议） | query：project_id |
data = 版本详情（findings[]、recommendations[]） |
🔴 |
POST /api/front/content/analysis-recommendations/:id/confirm |
确认建议（draft→confirmed，幂等） | query project_id + 头 Idempotency-Key，空 body |
data = {id,status} |
🔴 |
POST /api/front/content/analysis-recommendations/:id/link |
落地为文章（幂等） | query project_id + 头 Idempotency-Key + body AnalysisLinkCommand（owner_id?、due_at?） |
data = 交接结果（含 article_id） |
🔴 |
🔴 当前整体关闭：
.env未配置CONTENT_ANALYSIS_ENABLED（默认 false）。开启后分两段：
- 规则段（L1 监测发现 + gap 诊断）🟢 可直接对接；
coverage_rate < 80%（CONTENT_ANALYSIS_COVERAGE_THRESHOLD）时版本判insufficient_data、零发现零建议。- LLM 段（L2/L3 方向建议）仍 🔴：
CONTENT_ANALYSIS_LLM_ENABLED=false且真实 transport 未联签，不会产出建议。 前置数据：项目须配dl_project_target目标 + 监测关键词采集数据（dl_project_result/dl_project_result_reference_site），否则覆盖率 0 直接insufficient_data。
3. 审核与发布
R01 审核中心 — /projects/:projectId/review
权限：content.review / publish.execute / publish.view / project.view（只读）
| 接口 | 用途 | 请求 | 响应 | 状态 |
|---|---|---|---|---|
GET /api/front/content/reviews |
审核任务列表 | query：project_id、分页 |
data = 审核轮次列表 |
🟢 |
R02 内部审核 — /projects/:projectId/review/articles/:articleId/internal
权限：content.review
| 接口 | 用途 | 请求 | 响应 | 状态 |
|---|---|---|---|---|
POST /api/front/content/articles/:id/reviews |
提交审核（绑定版本 + 检查） | body ReviewSubmit：project_id、version_id、check_id |
data = 审核轮次（roundId） |
🟢 |
GET /api/front/content/reviews/:roundId |
审核详情 | query：project_id |
data = 审核轮次（含评论/决策/状态） |
🟢 |
POST /api/front/content/reviews/:roundId/comments |
提交评论/建议 | body ReviewComment：project_id、message_type（comment/suggestion）、content、required + 可选 thread_id/suggested_text/range |
data = 评论消息 |
🟢 |
POST /api/front/content/reviews/:roundId/decision |
审核决策 | body ReviewDecision：project_id、decision（approved/returned）、summary? |
data = 审核轮次 |
🟢 |
POST /api/front/content/review-messages/:messageId/resolve |
解决反馈 | body FeedbackResolution：project_id、resolution（applied/manual_fixed/rejected_with_reason）、reason? |
data = 空 |
🟢 |
POST /api/front/content/reviews/:roundId/share |
生成客户审核外链 | body ShareIssue：project_id、ttl? |
data = 分享凭证（token） |
🟢 |
R03 作者反馈修订 — /content/.../revise
权限：content.manage。→ 重定向到文章编辑器（C03），无独立后端接口。
R04 定稿 — /projects/:projectId/review/articles/:articleId/finalize
权限：content.review
| 接口 | 用途 | 请求 | 响应 | 状态 |
|---|---|---|---|---|
POST /api/front/content/articles/:id/finalization/preflight |
定稿预检 | body FinalizationRequest：project_id、version_id、check_id、review_round_id? |
data = 预检结果 |
🔴 |
POST /api/front/content/articles/:id/finalization |
生成定稿版本 | 同上 | data = 定稿结果（finalized_version_id） |
🔴 |
GET /api/front/content/articles/:id/finalization |
定稿详情 | query：project_id |
data = 定稿 |
🔴 |
🔴
CONTENT_FINALIZATION_ENABLED=false，前端冻结「定稿」入口。
R05–R08 发布中心 / 新建 / 配置 / 详情 — /publish、/publish/new、/publish/:id/configure、/publish/:id
权限：查看 publish.view/project.view；执行 publish.execute
| 接口 | 用途 | 状态 |
|---|---|---|
GET /api/front/content/publishing |
发布中心列表 | 🔴 |
GET /api/front/content/publishing/channels |
可用渠道目录 | 🔴 |
POST /api/front/content/publish-drafts |
新建发布稿（PublishDraftCreate：project_id、source_type、source_version_id） |
🔴 |
GET /api/front/content/publish-drafts/:id |
发布稿详情 | 🔴 |
POST /api/front/content/publish-drafts/:id/channels |
配置渠道（PublishChannels：channel_ids、expected_revision） |
🔴 |
POST /api/front/content/publish-drafts/:id/preflight |
发布预检 | 🔴 |
POST /api/front/content/publish-drafts/:id/submit |
提交发布（PublishSubmit） |
🔴 |
POST /api/front/content/publish-drafts/:id/cancel |
取消 | 🔴 |
GET /api/front/content/publish-drafts/:id/attempts |
尝试列表 | 🔴 |
GET /api/front/content/publish-attempts/:id |
尝试详情 | 🔴 |
POST /api/front/content/publish-attempts/:id/sync / cancel / retry |
同步/取消/重投 | 🔴 |
🔴
CONTENT_PUBLISHING_ENABLED=false，且CONTENT_PUBLISHING_PROVIDER_ENABLED/BILLING均 false（无真实发布渠道/计费）。前端冻结整个发布中心。 外部稿件（DOC/DOCX 上传）GET/POST /external-manuscripts亦 🔴（CONTENT_MANUSCRIPT_ENABLED=false）。
4. 客户外链（免登录，凭 token）
认证方式：高熵 token（免 JWT）。作用域仅从 token 对应的服务端冻结事实读取，不访问项目资料。 ⚠️ 路径命名差异：前端注册表用
/share/plans/:token与/share/articles/:token，后端实际是/share/plan/:token与/share/review/:token，对接时以后端路径为准。
X01 内容计划确认
| 接口 | 用途 | 请求 | 状态 |
|---|---|---|---|
GET /api/front/content/share/plan/:token |
客户查看计划快照 | path token |
🟢 |
POST /api/front/content/share/plan/:token/decision |
客户确认/提修改 | body PlanCustomerDecision：decision（confirm/request_changes）、overall_comment?、unit_feedback? |
🟢 |
响应 PublicPlanConfirmation：{round_id, status, plan{id,snapshot_no,name,start_at,due_at}, units[]}。token 格式 ^[A-Za-z0-9_-]{43}$。
X02 文章审核
| 接口 | 用途 | 请求 | 状态 |
|---|---|---|---|
GET /api/front/content/share/review/:token |
客户查看审核文章 | path token |
🟢 |
POST /api/front/content/share/review/:token/comments |
客户提交评论 | body PublicReviewComment：message_type、content、required + 可选 customer_name/thread_id/suggested_text/range |
🟢 |
POST /api/front/content/share/review/:token/decision |
客户审核决策 | body PublicReviewDecision：decision（approved/returned）、summary?、customer_name? |
🟢 |
5. AI 能力（全部 🔴，前端冻结）
| 接口 | 用途 | 状态 |
|---|---|---|
POST /api/front/content/articles/:id/ai-jobs |
发起 AI 任务（AiJobCreate：capability = content.generate_full/optimize_full/propose_local_edit） |
🔴 CONTENT_AI_ENABLED=false |
GET /api/front/content/ai-jobs/:jobId |
AI 任务详情 | 🔴 |
POST /api/front/content/ai-jobs/:jobId/retry / cancel |
重试/取消 | 🔴 |
GET /api/front/content/articles/:id/proposals |
本地改写建议列表 | 🔴 |
POST /api/front/content/proposals/:proposalId/apply / reject |
采纳/拒绝建议 | 🔴 |
POST /api/front/content/plans/:id/generation/retry / cancel |
计划智能生成重试/取消 | 🔴 CONTENT_PLAN_GENERATION_ENABLED 未开启 |
6. 前端冻结清单（当前环境建议隐藏/禁用的 UI）
- 新建内容：AI 生成模式、指定 Agent 模式（只留手工编辑 + 粘贴）。
- 文章编辑器：AI 续写 / AI 优化 / 本地改写建议按钮。
- 完成前检查：可发起与查看状态，但「检查结果项」显示「AI 能力未启用」占位，不等待结果。
- 计划：智能生成（
creation_mode= intelligent只建不生成，可建但提示 AI 未启用）。 - 写作 Agent：整个页面（后端无接口）。
- 定稿：整个入口。
- 发布中心：新建/配置/详情/渠道/费用全部。
- 外部稿件：DOC/DOCX 上传入口。
- 分析与建议：整个入口（
CONTENT_ANALYSIS_ENABLED未开启；开启后也只开放规则段，LLM 建议区仍需占位）。
模块 B · 项目资料（material）
M0. 全局约定
| 项 | 约定 |
|---|---|
| 基础路径 | /api/front/materials/*；跨项目平台库 /api/front/library/materials |
| 认证 | Authorization: Bearer <JWT>（与内容模块同一套用户登录） |
| 能力 | 读 material.view；写 material.manage；确认授权管理 project.member.manage（仅超管/管理员） |
| 租户 | 所有读写按 team_id + project_id 强制作用域；跨对象聚合禁止 N+1 |
| 幂等 | 治理写操作走 GovernanceCommand 幂等（Idempotency-Key 头，SHA-256 payload：同 key 同 hash 幂等、异 hash 409）；资产写额外 expected_version_no 乐观并发 |
| AI 回调 | POST /materials/callbacks/processing 用 body 内 HMAC-SHA256 签名认证，非 JWT，前端不直接调用 |
M1. 可用性总览
| 功能域 | 前端页面 | 后端接口 | 状态 |
|---|---|---|---|
| 资料首页（四菜单摘要） | 首页 | GET /materials/home |
🟢 |
| 跨项目资料库 | 平台库 | GET /library/materials |
🟢 |
| 搜索 / 待处理 | 搜索 / 待办 | GET /materials/search、/pending |
🟢 |
| 原始资料/反馈（来源） | 来源列表/详情 | GET /materials/sources、/sources/:id |
🟢 |
| 资料录入（文件/URL/手动） | 录入 | POST /materials/sources/capture |
🟢 |
| 来源新版本上传 | 来源详情 | POST /materials/sources/:id/versions |
🟢 |
| 知识列表/详情 | 知识 | GET /materials/knowledge、/knowledge/:id |
🟢 |
| 知识治理（确认/撤回/修订/停用/归并） | 知识治理 | POST /materials/knowledge/:id/* |
🟢 |
| 执行约束列表/详情 | 约束 | GET /materials/rules、/rules/:id |
🟢 |
| 约束治理（激活/修订/终止/重确认） | 约束治理 | POST /materials/rules/:id/* |
🟢 |
| 图片素材列表/详情/Picker/预览 | 素材 | GET /materials/assets、/assets/:id、/picker、/preview |
🟢 |
| 素材上传/确认/停用 | 素材治理 | POST /materials/assets、/assets/:id/confirm、/disable |
🟢 |
| 确认授权 | 成员授权 | GET/POST /materials/confirmation-grants、/:id/revoke |
🟢 |
| 冲突详情/裁决 | 冲突 | GET /materials/conflicts/:id、/resolve |
🟢 |
| 变更/缺口/处理任务详情 | 详情页 | GET /materials/changes/:id、/demands/:id、/processing-jobs/:id |
🟢 |
| AI 处理结果（解析/抽取知识） | 录入后自动 | POST /materials/processing-jobs/:id/retry、回调 |
🟡 依赖编排服务 8100 在线 |
一句话结论：项目资料模块整体 🟢 可直接对接；唯一 🟡 是「AI 解析/知识抽取」的结果产出依赖 MATERIAL_AI_ENDPOINT=http://127.0.0.1:8100 的 Python 编排服务在线（配置已就绪，运行时可用性需确认）。
M2. 逐页对照（按功能域）
M2.1 资料首页 / 搜索 / 待处理
| 接口 | 用途 | 请求 | 响应 | 状态 |
|---|---|---|---|---|
GET /api/front/materials/home |
首页四菜单摘要（近期输入/待处理/风险） | query：project_id |
汇总计数与近期条目 | 🟢 |
GET /api/front/materials/search |
项目内跨对象当前版本搜索 | query：project_id + 搜索条件 |
source/knowledge/rule/asset 命中 | 🟢 |
GET /api/front/materials/pending |
待处理投影 | query：project_id + filters |
待处理列表 | 🟢 |
M2.2 原始资料 / 反馈（来源）
| 接口 | 用途 | 请求 | 响应 | 状态 |
|---|---|---|---|---|
GET /api/front/materials/sources |
来源列表 | query：project_id、分页/筛选 |
Source[]（含 current_version 摘要、knowledge_count/constraint_count/pending_constraint_count/usage_count） |
🟢 |
GET /api/front/materials/sources/:id |
来源详情 | query：project_id |
详情（含 preview/extraction/manual_kind；manual 正文 original_content） |
🟢 |
POST /api/front/materials/sources/capture |
统一录入（文件/URL/手动） | 头 Idempotency-Key + body items[]（item_key、type、name、attachment_id|text|url、manual_kind、feedback_source） |
采集请求（同 hash 幂等；异 hash 409） | 🟢 |
POST /api/front/materials/sources/:id/versions |
上传新原件版本 | 头 Idempotency-Key + expected_version_no |
新 SourceVersion | 🟢 |
type枚举document|web|manual（ai_discovery历史兼容、列表默认排除）；manual_kind=pasted_content|feedback，feedback需feedback_source=customer_communication|customer_review|internal_review|execution_review|other。
M2.3 知识（Knowledge）
| 接口 | 用途 | 状态 |
|---|---|---|
GET /api/front/materials/knowledge / /knowledge/:id |
列表 / 详情（fact_content 正文、summary/conditions/boundaries/tags） |
🟢 |
POST /api/front/materials/knowledge/:id/confirm |
确认（source/pending→confirmed，需 material.manage + active grant） |
🟢 |
POST /api/front/materials/knowledge/:id/withdraw |
撤回确认（仅未使用知识） | 🟢 |
POST /api/front/materials/knowledge/:id/versions |
创建修订版本 | 🟢 |
POST /api/front/materials/knowledge/:id/disable |
停用 | 🟢 |
POST /api/front/materials/knowledge/:id/merge |
归并同义知识到目标新版本 | 🟢 |
M2.4 执行约束（Constraint，物理表 rule）
| 接口 | 用途 | 状态 |
|---|---|---|
GET /api/front/materials/rules / /rules/:id |
列表 / 详情（constraint_type/content/scope/severity；兼容别名 rule_type） |
🟢 |
POST /api/front/materials/rules/:id/activate |
激活（pending→active） |
🟢 |
POST /api/front/materials/rules/:id/reconfirm |
重确认（pending→active） |
🟢 |
POST /api/front/materials/rules/:id/versions |
修订（active/terminated→pending） |
🟢 |
POST /api/front/materials/rules/:id/terminate |
终止（active→terminated） |
🟢 |
M2.5 图片素材（Asset）
| 接口 | 用途 | 请求/响应 | 状态 |
|---|---|---|---|
GET /api/front/materials/assets |
素材列表（current-MVP 仅 image） | query：project_id、分页 |
🟢 |
GET /api/front/materials/assets/picker |
素材 Picker（仅 available，list/count 同谓词，limit 1–50） | query：project_id |
🟢 |
GET /api/front/materials/assets/:id/preview |
预览签名 URL（300s TTL） | query：project_id（可选历史版本） |
🟢 |
GET /api/front/materials/assets/:id |
素材详情 | query：project_id |
🟢 |
POST /api/front/materials/assets |
直接上传图片（内容寻址去重） | 头 Idempotency-Key + multipart；响应含 was_duplicate |
🟢 |
POST /api/front/materials/assets/:id/confirm |
确认（需 verified Confirmation + grant 回溯） | 头 Idempotency-Key + expected_version_no |
🟢 |
POST /api/front/materials/assets/:id/disable |
停用（available/recheck/candidate→disabled） |
头 Idempotency-Key + expected_version_no |
🟢 |
图片边界：JPEG/PNG/WebP/GIF，≤10 MiB，最长边 ≤12000px，总像素 ≤40MP。
copyright/copyright_status保留历史兼容默认，不再要求版权证据即可 available。
M2.6 治理：授权 / 冲突 / 变更 / 任务
| 接口 | 用途 | 状态 |
|---|---|---|
GET /api/front/materials/confirmation-grants |
确认授权列表 | 🟢 |
POST /api/front/materials/confirmation-grants |
创建授权（需 project.member.manage） |
🟢 |
POST /api/front/materials/confirmation-grants/:id/revoke |
撤销授权 | 🟢 |
GET /api/front/materials/conflicts/:id |
冲突详情（双方版本/证据/裁决历史） | 🟢 |
POST /api/front/materials/conflicts/:id/resolve |
原子裁决（需 material.manage + active grant） |
🟢 |
GET /api/front/materials/changes/:id |
来源变更与受影响对象 | 🟢 |
GET /api/front/materials/demands/:id |
资料缺口详情 | 🟢 |
GET /api/front/materials/processing-jobs/:id |
AI 处理任务状态 | 🟢 |
POST /api/front/materials/processing-jobs/:id/retry |
手动重试终态任务 | 🟡（结果依赖 AI 服务） |
M3. 状态机枚举（前端展示用）
| 对象 | 状态 |
|---|---|
| 来源 Source | 类型 document|web|manual|ai_discovery；版本抽取 pending|processing|completed|no_result|unsupported|failed；解析 ready|processing|needs_review|disabled |
| 知识 Knowledge | source|confirmed|pending|disabled |
| 执行约束 Constraint | pending|active|terminated|disabled |
| 图片素材 Asset | candidate|available|recheck|disabled |
| 确认授权 Grant | active|revoked |
来源预览（SourceVersion）六类：
document_pages\|table\|image\|web_snapshot\|text\|unavailable（unavailable携带preview_error_code/message/recovery）。
M4. AI 采集处理流（capture → processing → callback）
POST /sources/capture（+ Idempotency-Key）
→ 新建 Source + 投递处理任务（ThinkPHP 队列）
→ Python 编排服务（MATERIAL_AI_ENDPOINT=127.0.0.1:8100）解析/抽取
→ POST /materials/callbacks/processing（body 内 HMAC 签名，非 JWT）回写知识/约束候选
- 前端无需直接调 callback；只需关注
processing-jobs/:id状态与sources的extraction状态。 - 🟡 若编排服务 8100 未在线，capture 仍成功但
extraction停在processing、知识/约束候选不产出——前端按processing给出「处理中/需重试」提示，并提供retry入口。
M5. 前端冻结清单（项目资料）
ai_discovery来源：列表/搜索/首页/待处理均默认排除，前端无需展示该类型入口。- AI 回调接口：前端不调用，仅服务端与编排服务交互。
- （其余无冻结项——项目资料模块整体可用。）