Skip to content

公众号管理 PRD ​

文档信息 ​

项目内容
文档编号PRD-10-01
文档名称公众号管理
产品名称PMForge 项目管理平台
所属模块微信公众号(pmforge-module-mp)
文档版本v2.2
最后更新2026-11-18
文档状态已更新
实施状态预留(已编译,未接入运行时)
优先级P1

1. 功能概述 ​

1.1 功能定位 ​

公众号管理是平台面向「微信生态运营」的底座模块:把公众号账号、菜单、素材、图文草稿与发布、自动回复、粉丝消息、模板消息、粉丝与标签、运营数据集中到一个后台,让运营同学不必在微信公众平台与业务系统之间来回切换。

它解决的是**「内容和粉丝在哪、发过什么、谁在跟进」三件事无法沉淀**的问题:微信公众平台只提供操作界面,不提供与企业内部账号、权限、审计、文件存储的打通;本模块把这层打通,并保留与微信开放接口的完整对应关系。

1.2 目标用户与核心诉求 ​

角色核心诉求典型动作
公众号管理员账号接入安全、菜单可控、异常可查新增账号、配置菜单、清空配额重试
内容运营写稿—预览—发布一条链路建草稿、传素材、提交发布、看发布记录
客服/社群运营及时回复、按标签触达查粉丝消息、发模板消息、给粉丝打标签
数据分析粉丝涨跌、消息触达效果看粉丝增减、累计、消息概况、接口调用量
系统管理员权限与审计分配 mp:* 权限点、查操作日志与 API 日志

1.3 业务价值 ​

  1. 账号集中:一套后台管理多个公众号,避免多人共用微信后台账号。
  2. 内容留痕:草稿、发布、素材都在库中,可按账号/时间检索与复用。
  3. 触达闭环:粉丝—标签—模板消息串起来,运营动作可复盘。
  4. 可观测:微信接口失败原因透传为业务错误码,配额与调用量可见。

1.4 功能范围 ​

本期包含

  • 公众号账号接入、二维码、API 配额重置;
  • 自定义菜单配置与同步;
  • 素材(临时/永久/图文内图片)上传、查询、删除;
  • 图文草稿增删改查与发布、发布记录查询与删除;
  • 关注回复、消息类型回复、关键词回复;
  • 粉丝消息查询与主动发送;
  • 模板消息同步、查询、删除、发送;
  • 粉丝列表/详情/更新/同步,标签增删改查与同步、粉丝打标签;
  • 运营数据:粉丝增减、粉丝累计、消息发送概况、接口调用概况;
  • 微信服务器回调入口(GET 校验 + POST 事件接收)。

本期不包含

  • 小程序、企业微信、视频号;
  • 微信支付、卡券、广告投放;
  • 图文内容的富文本编辑器实现(由前端提供,本模块只存结构化字段);
  • 多租户下的公众号「共享池」策略(当前按租户隔离账号)。

2. 用户场景 ​

2.1 用户角色 ​

  • 公众号管理员:负责账号接入与菜单,权限 mp:account:*、mp:menu:*。
  • 内容运营:负责素材、草稿、发布,权限 mp:material:*、mp:draft:*、mp:free-publish:*。
  • 客服运营:负责会话与触达,权限 mp:message:*、mp:message-template:*、mp:user:*、mp:tag:*。
  • 数据分析:只读统计,权限 mp:statistics:query。

2.2 核心使用场景 ​

编号场景触发期望结果
S-01新公众号接入运营拿到 appId/appSecret账号创建成功,能生成二维码、能拉取粉丝
S-02菜单改版市场活动需要三个一级菜单保存后微信侧菜单生效,粉丝端可见
S-03活动图文发布内容同学写好稿草稿保存 → 提交发布 → 发布记录可查
S-04关键词自动回复用户回复「报价」命中关键词规则,返回配置的图文/文本
S-05订单提醒触达业务系统触发模板消息按 openid 发送成功,失败原因可查
S-06粉丝分层运营按来源打标签标签同步到微信,粉丝可按标签筛选
S-07周报复盘每周一看数据粉丝增减、累计、消息概况可导出/截图

2.3 用户故事与验收标准 ​

编号用户故事优先级验收标准
US-01作为公众号管理员,我希望接入一个公众号账号,以便统一管理P0① 必填:名称、appId、appSecret;② appId 全局唯一;③ appSecret 加密存储,接口不回显明文;④ 接入后能成功获取 access_token;⑤ 失败时返回微信原始错误原因
US-02作为管理员,我希望看到账号列表并生成二维码P0① 分页支持名称/appId 模糊搜索;② 精简列表供下拉选择;③ 生成二维码返回图片地址;④ 生成失败提示原因
US-03作为管理员,我希望清空账号的 API 配额P1① 仅测试/运维用途;② 清空后配额计数归零;③ 失败返回原因
US-04作为管理员,我希望配置自定义菜单P0① 一级最多 3 个、二级最多 5 个;② 支持跳转网页、小程序、图文素材、点击事件;③ 保存即同步微信;④ 同步失败保留本地配置并提示
US-05作为内容运营,我希望上传素材P0① 支持临时素材与永久素材;② 支持图文消息内图片上传;③ 返回 mediaId 与 url;④ 单文件大小与格式按微信限制校验
US-06作为内容运营,我希望管理图文草稿P0① 草稿含多篇图文(标题、作者、摘要、正文、封面、原文链接);② 支持新建/更新/删除/分页;③ 正文长度按微信限制校验;④ 草稿与账号绑定,跨账号不可见
US-07作为内容运营,我希望把草稿发布出去P0① 提交发布需选择草稿;② 发布结果异步,需可轮询/查列表;③ 发布记录可删除;④ 失败返回微信错误码
US-08作为客服运营,我希望配置自动回复P0① 关注回复每个账号唯一;② 按消息类型回复每种类型唯一;③ 关键词回复同一关键字唯一;④ 支持全匹配/半匹配
US-09作为客服运营,我希望查看并回复粉丝消息P1① 按账号/粉丝/时间分页;② 支持发送文本、图片、图文、音乐等类型;③ 发送失败返回原因
US-10作为客服运营,我希望用模板消息触达P1① 可从微信同步模板;② 可查询/删除本地模板;③ 发送时传 openid + 参数;④ 失败原因透传
US-11作为运营,我希望管理粉丝与标签P1① 粉丝列表按昵称/标签筛选;② 支持从微信同步粉丝;③ 标签增删改查并同步;④ 支持给粉丝批量打标签
US-12作为数据分析,我希望看运营数据P2① 粉丝增减按日期区间;② 粉丝累计;③ 消息发送概况;④ 接口调用概况;⑤ 数据来自微信接口,缓存 5 分钟
US-13作为系统管理员,我希望接收微信事件回调P0① GET 校验签名通过才返回 echostr;② 支持明文/密文/兼容模式;③ 关注/取关/消息/菜单点击事件落库;④ 异常不阻塞返回

3. 功能需求 ​

3.1 账号管理 ​

功能说明权限点接口
创建账号名称、appId、appSecret、token、aesKey 接入mp:account:createPOST /admin-api/mp/account/create
更新账号名称、密钥轮换mp:account:updatePUT /admin-api/mp/account/update
删除账号逻辑删除,关联数据保留mp:account:deleteDELETE /admin-api/mp/account/delete
账号详情不返回 appSecret 明文mp:account:queryGET /admin-api/mp/account/get
账号分页名称/appId 搜索mp:account:queryGET /admin-api/mp/account/page
精简列表下拉选择mp:account:queryGET /admin-api/mp/account/list-all-simple
生成二维码返回带参数二维码图片mp:account:qr-codePUT /admin-api/mp/account/generate-qr-code
清空配额重置当日调用计数mp:account:clear-quotaPUT /admin-api/mp/account/clear-quota

规则:appId 唯一;appSecret 使用平台加密器存储;删除前校验是否仍有关联草稿/菜单(存在则提示先清理)。

3.2 菜单管理 ​

功能说明权限点接口
保存菜单全量覆盖式保存,保存后同步微信mp:menu:savePOST /admin-api/mp/menu/save
删除菜单删除微信侧菜单mp:menu:deleteDELETE /admin-api/mp/menu/delete
菜单列表返回树形结构mp:menu:queryGET /admin-api/mp/menu/list

规则:一级 3 个、二级 5 个;叶子节点才允许配置动作;动作类型包含跳转网页、小程序、图文素材、点击推事件;保存失败时本地记录保留,供修正后重试。

3.3 素材管理 ​

功能说明权限点接口
上传临时素材有效期 3 天mp:material:upload-temporaryPOST /admin-api/mp/material/upload-temporary
上传永久素材图文/图片/语音/视频mp:material:upload-permanentPOST /admin-api/mp/material/upload-permanent
上传图文内图片不占用永久素材配额mp:material:upload-news-imagePOST /admin-api/mp/material/upload-news-image
删除永久素材按 mediaId 删除mp:material:deleteDELETE /admin-api/mp/material/delete-permanent
素材分页按类型/永久性筛选mp:material:queryGET /admin-api/mp/material/page

3.4 草稿与发布 ​

功能说明权限点接口
草稿分页按账号、标题筛选mp:draft:queryGET /admin-api/mp/draft/page
新建草稿多篇图文,封面用永久素材 mediaIdmp:draft:createPOST /admin-api/mp/draft/create
更新草稿全量替换图文列表mp:draft:updatePUT /admin-api/mp/draft/update
删除草稿同步删除微信草稿mp:draft:deleteDELETE /admin-api/mp/draft/delete
发布草稿提交后由微信异步处理mp:free-publish:submitPOST /admin-api/mp/free-publish/submit
发布记录查询已发布图文mp:free-publish:queryGET /admin-api/mp/free-publish/page
删除发布删除已发布记录mp:free-publish:deleteDELETE /admin-api/mp/free-publish/delete

3.5 自动回复 ​

功能说明权限点接口
自动回复分页按类型/关键字筛选mp:auto-reply:queryGET /admin-api/mp/auto-reply/page
自动回复详情—mp:auto-reply:queryGET /admin-api/mp/auto-reply/get
新建关注/消息/关键词三类mp:auto-reply:createPOST /admin-api/mp/auto-reply/create
更新修改回复内容与匹配方式mp:auto-reply:updatePUT /admin-api/mp/auto-reply/update
删除—mp:auto-reply:deleteDELETE /admin-api/mp/auto-reply/delete

唯一性规则:关注每个账号 1 条;消息类型每个账号每种类型 1 条;关键词每个账号每个关键字 1 条(重复返回「已存在该关键字的回复」)。

3.6 消息与模板消息 ​

功能说明权限点接口
消息分页按粉丝/账号/时间mp:message:queryGET /admin-api/mp/message/page
发送消息文本/图片/图文/音乐mp:message:sendPOST /admin-api/mp/message/send
模板同步从微信拉取模板列表mp:message-template:syncPOST /admin-api/mp/message-template/sync
模板列表—mp:message-template:queryGET /admin-api/mp/message-template/list
模板详情—mp:message-template:queryGET /admin-api/mp/message-template/get
删除模板—mp:message-template:deleteDELETE /admin-api/mp/message-template/delete
发送模板消息openid + datamp:message-template:sendPOST /admin-api/mp/message-template/send

3.7 粉丝与标签 ​

功能说明权限点接口
粉丝分页昵称/标签/关注状态筛选mp:user:queryGET /admin-api/mp/user/page
粉丝详情—mp:user:queryGET /admin-api/mp/user/get
更新粉丝备注、标签mp:user:updatePUT /admin-api/mp/user/update
同步粉丝从微信全量/增量同步mp:user:syncPOST /admin-api/mp/user/sync
标签分页—mp:tag:queryGET /admin-api/mp/tag/page
标签详情—mp:tag:queryGET /admin-api/mp/tag/get
标签精简列表下拉选择mp:account:queryGET /admin-api/mp/tag/list-all-simple
创建标签同步到微信mp:tag:createPOST /admin-api/mp/tag/create
更新标签—mp:tag:updatePUT /admin-api/mp/tag/update
删除标签粉丝上的该标签同步移除mp:tag:deleteDELETE /admin-api/mp/tag/delete
同步标签拉取微信标签mp:tag:syncPOST /admin-api/mp/tag/sync

3.8 数据统计 ​

功能说明权限点接口
粉丝增减按日期区间,最多 30 天mp:statistics:queryGET /admin-api/mp/statistics/user-summary
粉丝累计按日期区间mp:statistics:queryGET /admin-api/mp/statistics/user-cumulate
消息发送概况按日期区间mp:statistics:queryGET /admin-api/mp/statistics/upstream-message
接口调用概况按日期区间mp:statistics:queryGET /admin-api/mp/statistics/interface-summary

3.9 开放回调 ​

功能说明权限点接口
回调校验(GET)校验 signature/timestamp/nonce,返回 echostr公开(签名校验)GET /admin-api/mp/open/{appId}
事件接收(POST)关注/取关/文本/图片/菜单点击等事件公开(签名校验)POST /admin-api/mp/open/{appId}

规则:回调必须校验签名;支持明文、密文、兼容三种模式;处理异常要吞掉并返回 success,避免微信重试风暴;事件消息落 mp_message 表供后台查询。

4. 非功能需求 ​

4.1 性能要求 ​

  • 后台列表接口 P95 < 500ms(单账号 10 万粉丝以内)。
  • 微信接口调用单独超时(连接 3s、读取 5s),失败快速返回,不阻塞页面。
  • 粉丝同步按分页批量写入,单次 1 万粉丝不超过 60s。

4.2 安全要求 ​

  • appSecret 使用平台 encryptor 加密存储,接口与日志均不回显明文。
  • access_token 集中缓存于 Redis(key 按 appId 隔离),过期前 5 分钟刷新,避免并发刷新击穿。
  • 所有写操作记录操作日志(@LogRecord),所有接口调用记录 API 日志(@ApiAccessLog)。
  • 回调入口校验签名,并限制请求体大小。

4.3 兼容性要求 ​

  • 支持 MySQL / PostgreSQL / Oracle / SQL Server / 达梦 / Kingbase / openGauss / HighGo 八套脚本。
  • 微信接口版本以公众平台当前稳定版为准,字段新增按「忽略未知字段」处理。

4.4 可用性要求 ​

  • 微信侧限流/配额耗尽时返回明确错误码与原因,页面提示「稍后重试或清空配额」。
  • 单账号故障不影响其它账号;同步类操作可重试且幂等。

5. 数据设计 ​

5.1 数据表概览 ​

表名说明关键字段
mp_account公众号账号app_id、app_secret、token、aes_key
mp_menu自定义菜单account_id、parent_id、type、menu_key
mp_material素材account_id、media_id、type、permanent
mp_draft 关联的图文存储于 mp_material/草稿结构草稿图文标题、作者、摘要、封面 media_id
mp_auto_reply自动回复account_id、type、request_keyword、request_match
mp_message粉丝消息与事件account_id、openid、type、send_from、event
mp_message_template模板消息account_id、template_id、title、content
mp_user粉丝app_id、openid、tag_ids、subscribe_status
mp_tag标签account_id、tag_id、name

说明:草稿与发布记录由微信侧持有 media_id,本地保存结构化字段(标题/作者/摘要/正文/封面/原文链接),发布时以 media_id 与微信交互。

5.2 关键约束 ​

  • mp_account.app_id 唯一;mp_user(app_id, openid) 唯一;mp_tag(account_id, tag_id) 唯一。
  • mp_auto_reply 按 type 做业务唯一(关注 1 条、每消息类型 1 条、每关键字 1 条),由服务层校验。
  • 所有表带 tenant_id(租户隔离)、creator/create_time/updater/update_time、deleted 逻辑删除。

5.3 缓存设计 ​

缓存KeyTTL说明
access_tokenmp:access_token:{appId}7000s提前 5 分钟刷新
API 配额mp:quota:{appId}:{date}当日调用前自增,超限拒绝
统计结果mp:statistics:{appId}:{type}:{range}300s降低微信调用次数

6. 跨模块联动 ​

关联模块联动点说明
system用户、租户、字典、权限、操作日志权限点 mp:* 归属菜单;操作日志记录关键动作
infra文件存储、API 日志、定时任务素材与封面存文件服务;回调与页面调用记 API 日志;粉丝/模板同步可由定时任务触发
im/通知运营提醒发布失败、配额告警可走站内信(规划)

7. 附录 ​

7.1 权限标识汇总 ​

mp:account:{create,update,delete,query,qr-code,clear-quota}、mp:menu:{save,delete,query}、mp:material:{upload-temporary,upload-permanent,upload-news-image,delete,query}、mp:draft:{create,update,delete,query}、mp:free-publish:{submit,query,delete}、mp:auto-reply:{create,update,delete,query}、mp:message:{query,send}、mp:message-template:{sync,query,delete,send}、mp:user:{query,update,sync}、mp:tag:{create,update,delete,query,sync}、mp:statistics:query。

7.2 接口汇总 ​

见文末「代码对齐(自动生成)」章节的接口对照表与 docs/code/api/mp.md。

7.3 错误码定义 ​

错误码说明
1_006_000_000公众号账号不存在
1_006_000_001生成公众号二维码失败,原因:{}
1_006_000_002清空公众号的 API 配额失败,原因:{}
1_006_001_000获取粉丝增减数据失败,原因:{}
1_006_001_001获得粉丝累计数据失败,原因:{}
1_006_001_002获得消息发送概况数据失败,原因:{}
1_006_001_003获得接口分析数据失败,原因:{}
1_006_002_000标签不存在
1_006_002_001创建标签失败,原因:{}
1_006_003_000粉丝不存在
1_006_003_001更新粉丝标签失败,原因:{}
1_006_004_000素材不存在
1_006_004_001上传素材失败,原因:{}
1_006_005_000发送消息失败,原因:{}
1_006_006_001提交发布失败,原因:{}
1_006_007_001创建草稿失败,原因:{}
1_006_008_000创建菜单失败,原因:{}
1_006_009_000自动回复不存在
1_006_009_001操作失败,原因:已存在关注时的回复
1_006_009_003操作失败,原因:已存在该关键字的回复
1_006_010_000模版消息不存在
1_006_010_003同步模版消息失败,原因:{}
1_006_010_004发送模版消息失败,原因:{}

7.4 名词解释 ​

名词说明
appId / appSecret公众号唯一标识与密钥
access_token调用微信接口的凭证,7200s 有效
mediaId微信素材标识,临时素材 3 天有效
openid粉丝在单个公众号内的唯一标识
unionId同一微信开放平台账号下的跨应用唯一标识
模板消息微信服务号下发通知的模板能力

代码对齐(自动生成) ​

本节由 tools/docs/prd-align.mjs 从源码与 SQL 解析生成,请勿手工编辑;重跑 npm run prd:align 会整体替换。

1. 模块规模 ​

控制器接口权限点数据表
1251408

2. 控制器清单 ​

控制器基础路径接口数权限点数代码位置
MpAccountController/mp/account86modules/mp/src/main/java/com/pmforge/module/mp/controller/admin/account/MpAccountController.java
MpAutoReplyController/mp/auto-reply54modules/mp/src/main/java/com/pmforge/module/mp/controller/admin/message/MpAutoReplyController.java
MpDraftController/mp/draft44modules/mp/src/main/java/com/pmforge/module/mp/controller/admin/news/MpDraftController.java
MpFreePublishController/mp/free-publish33modules/mp/src/main/java/com/pmforge/module/mp/controller/admin/news/MpFreePublishController.java
MpMaterialController/mp/material55modules/mp/src/main/java/com/pmforge/module/mp/controller/admin/material/MpMaterialController.java
MpMenuController/mp/menu33modules/mp/src/main/java/com/pmforge/module/mp/controller/admin/menu/MpMenuController.java
MpMessageController/mp/message22modules/mp/src/main/java/com/pmforge/module/mp/controller/admin/message/MpMessageController.java
MpMessageTemplateController/mp/message-template54modules/mp/src/main/java/com/pmforge/module/mp/controller/admin/message/MpMessageTemplateController.java
MpOpenController/mp/open20modules/mp/src/main/java/com/pmforge/module/mp/controller/admin/open/MpOpenController.java
MpStatisticsController/mp/statistics41modules/mp/src/main/java/com/pmforge/module/mp/controller/admin/statistics/MpStatisticsController.java
MpTagController/mp/tag76modules/mp/src/main/java/com/pmforge/module/mp/controller/admin/tag/MpTagController.java
MpUserController/mp/user43modules/mp/src/main/java/com/pmforge/module/mp/controller/admin/user/MpUserController.java

3. 接口对照 ​

本文引用 51 个接口,代码中存在 51 个(命中率 100%)。

本文接口代码中对应真实接口
/mp/account/create✅
/mp/account/update✅
/mp/account/delete✅
/mp/account/get✅
/mp/account/page✅
/mp/account/list-all-simple✅
/mp/account/generate-qr-code✅
/mp/account/clear-quota✅
/mp/menu/save✅
/mp/menu/delete✅
/mp/menu/list✅
/mp/material/upload-temporary✅
/mp/material/upload-permanent✅
/mp/material/upload-news-image✅
/mp/material/delete-permanent✅
/mp/material/page✅
/mp/draft/page✅
/mp/draft/create✅
/mp/draft/update✅
/mp/draft/delete✅
/mp/free-publish/submit✅
/mp/free-publish/page✅
/mp/free-publish/delete✅
/mp/auto-reply/page✅
/mp/auto-reply/get✅
/mp/auto-reply/create✅
/mp/auto-reply/update✅
/mp/auto-reply/delete✅
/mp/message/page✅
/mp/message/send✅
/mp/message-template/sync✅
/mp/message-template/list✅
/mp/message-template/get✅
/mp/message-template/delete✅
/mp/message-template/send✅
/mp/user/page✅
/mp/user/get✅
/mp/user/update✅
/mp/user/sync✅
/mp/tag/page✅
/mp/tag/get✅
/mp/tag/list-all-simple✅
/mp/tag/create✅
/mp/tag/update✅
/mp/tag/delete✅
/mp/tag/sync✅
/mp/statistics/user-summary✅
/mp/statistics/user-cumulate✅
/mp/statistics/upstream-message✅
/mp/statistics/interface-summary✅
/mp/open/{id}✅

4. 数据表 ​

表名说明
mp_accountMpAccountDO
mp_auto_replyMpAutoReplyDO
mp_materialMpMaterialDO
mp_menuMpMenuDO
mp_messageArticle
mp_message_templateMpMessageTemplateDO
mp_tagMpTagDO
mp_userMpUserDO

5. 说明 ​

  • 模块码:mp(微信公众号);PRD 编号:10-01。
  • 「接口对照」只统计本文用反引号显式写出的 /admin-api/... 路径;未写接口的章节不代表没有实现。
  • 代码位置为相对仓库根的路径,行号可在功能卡或 docs/code/api/ 中查到。

文档变更记录 ​

版本日期变更说明作者
v2.22026-11-18补齐公众号模块 PRD:13 条用户故事、9 组功能需求、8 张表、42 个权限点、52 个接口,按代码现状撰写产品