待办清单

跨会话的知识库/接口文档后续工作,按优先级排列。完成一项从这里划掉,别留"已完成"记录——git log 就是完成记录。

0. 消息系统统一(删旧 Notify;闭环主体已完成)

方向已定(2026-07-18):user 服务的旧 Notify{Body,Target,Type} 体系删除,全系统消息统一走 public 的 hiapi-system-basic-message。

已完成(详见 domains/系统消息中心-实施进展.md 阶段2~5、domains/系统消息中心-使用指南.md):公告广播(MsgAnnouncement+已读游标)、事件接入修复(旧 @EventListener 收不到 MQ 的 bug)、user 旧 Notify 删除、channel/platform 公告发布面(platform→merchant/channel 全局广播)、hiapi-cloud-public-web 用户端消息 widget(message-entry/announcement-bar,顺带修复 message.vue 里一个请求前缀写错导致页面打不通的 bug)、channel→merchant 定向公告(渠道只广播给自己名下商户,MsgAnnouncement 加 channelId 维度,顺带修了 ChannelPlatformAnnouncementController 已读游标全渠道共享的 bug)。代码均编译通过,待部署验证(建表/队列/端到端)。

提现审核通知已登记到 hiapi-cloud-finance/docs/completion-plan.md §P3 第11项(跨服务事件,归属 finance 判断何时接,不在本仓库跟踪)。

0.5 AI 开放接口部署后:导 EOLINK

功能代码已完成(见 ADR-0006、对接指南),部署后再做:

1. 给 AI 管理类接口补 Javadoc:/cloud-api/{merchant|channel|platform}/ai/api-key/*(generate/rotate/revoke/toggle/scope/query)、/cloud-api/{...}/ai/assistant/*(authorize/revoke/status)、/cloud-{svc}/open-api/manifest。
2. 按 §1 流程导入 EOLINK(内联展开 schema,勿用 $ref),归入"开放(open-api)"分组。
3. 运行时接口清单本就由各服务 /open-api/manifest 自描述,EOLINK 只补管理类接口即可,不必手抄业务开放接口。

0.6 私有化部署:转向 nuwa 交付中心(2026-07-28 重新定调)

规模重估:独立部署客户从"3 个"改为每年 100~200 个(约每周 4 个上线)。据此推翻了若干按小规模做的决定,见 总览与架构。

已完成且保留:配置外部化(prod profile)、统一 CI、umbrella chart(自带 Nacos + 建库 Job + 依赖矩阵)、购机清单。

已废弃:hiapi-customers(git 仓库 + SOPS/age 加密客户配置)、Argo 拉模式、交付操作手册。手工建客户目录在 200/年的量级不成立,客户配置改由 nuwa 承载。age 主私钥备份的待办随之消失。

待办

开发顺序见 nuwa 交付中心 §六,这里只留跨会话要记住的点:

0. 进度:M0-2(chart RBAC)、M1(部署配置)、M2(服务端渲染下发)、M3(装机脚本)已完成,见 nuwa 交付中心 §六。下一步只剩 M0 —— M2/M3 都写完了但一次真机器都没跑过,而空转的原因始终是 ACR 里没有可拉取的镜像。M0 一通就该立刻连着 M0-3 把"空机器→两个脚本→后台可登录"验一遍,再谈 M4。 ⚠️ chart 的 ingress.className 默认已从 nginx 改成 traefik(与 k3s 自带的一致),部署配置里新增「Ingress class」字段并显式渲进 values。class 对不上的表现是域名 404 且没有任何日志指向它,不要再照旧文档 --disable=traefik。 ⚠️ 改了 hiapi-chart 必须跑 hiapi-cloud-nuwa/scripts/sync-chart.sh 并提交 —— nuwa 内嵌了一份 chart 副本,不同步的话依赖矩阵和渲染用的还是旧的。 ⚠️ 部署勾选清单 = apps 表里全部 ONLINE 应用,GET /v1/deploy/catalog 只返回 App 表的 字段。chart 里有但没登记成应用的服务(public/finance/socket 这些)一个字都不许出现在 返回里,包括依赖提示。新应用注册时 project 要等于 chart 里的服务名 (project=vem ↔ services.vem);对不上不影响勾选,但渲染时默认拒绝下发并点名(可确认后跳过)。
1. M0 是硬阻塞:Codeup 流水线没配、没打过 tag,ACR 里还没有任何可拉取的镜像。这一步不做,后面全是空转。 脚本与配置说明已就绪:hiapi-chart/ci/(build.sh + check-images.sh + README 里 9 条流水线的建法)。先手工推一个镜像证明路通,再配流水线。 ⚠️ 未决:ACR 仓库可见性。 公开仓谁都能拉,而 hiapi-cloud-public 绝不能公开(JNI 保护模块);走私有仓要 pull secret,而 nuwa 的部署配置里还没有 imagePullSecrets 字段。底座三个不含保护模块,可先用公开仓把 M0-3 验通。 ⚠️ socket 的源码是 hiapi-fast-frame/hiapi-socket-server 子目录,不是独立仓库(它是 vem 的硬依赖)。它的流水线工作目录不是仓库根。shop/store 仍然无构建方式 —— 没立项之前别在应用商店里把它们置为 ONLINE,否则客户勾了就是 ImagePullBackOff。
2. chart 补 ServiceAccount + RBAC 已完成(2026-07-28),见 Chart 指南。遗留:h5-prereqs.hiapi-cloud.yaml 里构建 Job 用的两个 PVC 写死 aliyun-nas 且需要 RWX,k3s 环境没有,收进 chart 前要先定私有化环境下 H5 构建产物怎么共享(NFS?还是构建完直接推 OSS 不落盘)。M0-3 真集群验证时一并解决。 ⚠️ 这条现在还卡着底座里的 web-ui —— H5 构建产物的静态站属于必装底座(2026-07-29 定),但 chart 里还没有这个服务,因为产物落在那个 RWX PVC 上。PVC 的事不解决,web-ui 就进不了 chart。 2.5 M2 前置:helm template 跑不了 M2 渲染与下发 都已完成(2026-07-30)。bitnami 三个依赖 vendored 进 hiapi-chart/charts/;镜像前缀从 global.imageRegistry(bitnami 保留键)挪到 image.registry;nuwa 用 helm v4 SDK 服务端渲染 + 一次性下载券,验收用例 TestRenderMatchesHelmCLI 与本机 helm template 逐字节一致。详见 nuwa 交付中心 §M2、nuwa 教程 §6.5。 遗留:chart 支持 global.imagePullSecrets,但 nuwa 的部署配置里没这个字段,私有镜像仓库的客户还装不了(归 §1 的 M0 镜像发布一起解决)。手工桥接脚本 hiapi-deploy/render-customer.sh 保留到 nuwa 部署验证完再删。 ⚠️ 加了 helm SDK 之后 nuwa 的 go.mod 要求 go ≥ 1.26,二进制从 20M 涨到 47M;升级 helm SDK 大版本时记得跑一遍上面那个一致性用例。
3. 最小闭环手动跑通一次不要跳过:已踩到两个"开发环境替我们兜住的前置条件"(Nacos 空配置、业务库不存在),只有真集群会暴露第三个。
4. Flyway 已决定推后,但它锁住了 M6(客户自助升级后端)—— ddl-auto: update 不可预演、不可回滚。
5. hiapi-customers 目录已废弃但未物理删除(有 commit 无远端)。(hiapi-chart 已推 Codeup,不再是待办)
6. 非阻塞:编译目标版本混用 17/18/21,建议随某次全量构建收敛到 21。
7. 未立项:shop/store 无 jib 无 Dockerfile,服务发现仍是 Eureka。

1. 其余服务的字段注释 + 接口文档

已完成:hiapi-cloud-vem(全量)、hiapi-cloud-public(全量)。

未开始:hiapi-cloud-user、hiapi-cloud-finance、hiapi-cloud-shop、hiapi-cloud-store、hiapi-cloud-nuwa 等。

流程参照(已验证可行):

1. 扫描服务下实体/VO/DTO/Query 类的无注释字段(vem 用过的 python 脚本思路:找 private/protected 字段,往上看有没有紧邻注释)
2. 逐个类补 Javadoc 字段注释(不改逻辑,只加注释)
3. 按 controller 分组,手写 OpenAPI(含 schema + 中文 description,不要用 $ref 引用——EOLINK 的 MCP 导入不解析 $ref,会导致请求体/返回内容显示为空,必须内联展开)
4. 通过 mcp__apikit-api-docs__import_api 导入,sync_unique_type: api_url_method 增量覆盖
5. mvn compile 验证注释改动没有语法错误

2. "同步接口文档" skill

现在全靠手动:改完接口 → 读代码 → 写 OpenAPI → 调 MCP 导入。应该抽成一个类似 report-public-module 的仓库级 skill,输入一个服务/controller,自动跑完整套流程。

3. EOLINK 孤儿接口清理

SaaS 项目(ndyVHaCb6c6a0841d6760843bb7ce245ac916b23f7402b6)里以下 4 条是历史遗留,代码里查无实现(实际路由已改成 /platform/app-store/{app-server}/install 这套,Platform 权限,非 public):

• /cloud-api/public/app/install
• /cloud-api/public/app/status
• /cloud-api/public/app/uninstall
• /cloud-api/public/app/upgrade

建议直接在 EOLINK 里删除,不需要再核实。

⚠️ 只能人工在网页上删(2026-07-31 核实):EOLINK 的 MCP 工具只有 import_api / update_api_details,没有删除接口的能力。import_api 的 is_removed 参数是"删掉导入文件里没有的所有接口",拿它来删这 4 条会顺手删掉一大片, 不能用。要么人工删,要么用 update_api_details 把状态改成 deprecated(2)。

4. 疑似代码 bug(需确认后再改)

EventFinanceAssetsReceipt 监听 finance.assets.change 但无发布方已定性(2026-07-31):保留,是缺发布方,不是废弃。

它是"跨进程给用户加钱"的既定通路,而需要它的调用方还没接上 —— hiapi-cloud-user 的 RegionalRewardTask 直接调 ICloudFinanceAssetsService.changeAssets, 那个 bean 在 user 进程里不存在(user 对 finance 零依赖、也没有 feign 适配器), 必然 NPE → 被 try/catch 吞 → 明细状态回滚 → 每轮重试,区域奖励永远发不出去。

这意味着治理规划 T1 里"走异步事件"那条路的消费侧已经建好了,只差 user 侧 把 changeAssets 换成发一条 AssetsChangeEvent。走哪条路要业主拍板(另一条是新开 /feign/finance/assets/change,等于把资金变动入口暴露成同步服务间 API)。 拍板之前不要删这个类 —— 删了等于替业主否掉成本最低的那条路。 详见类注释与 架构治理规划.md T1。

hiapi-cloud-vem/vem-models/vem-server/src/main/java/cn/hiapi/vem/vo/OrderVo.java:

/** 商品标题 */
private long titles;

注释说是"商品标题"但类型是 long,大概率应为 String。没有动它,先找当初写这段的人确认业务含义,再决定是改字段类型还是改注释。

5. modules/index.md 的 Owner 认领 已完成(2026-07-31)

整个平台目前由 AdinZ 一人维护,Owner 列已全部填上;顺带修正了两处过期条目 (hiapi-frame 整体废弃、hiapi-basic-feign 已归档),并补上漏掉的 hiapi-cloud-sy。

6. 找回密码/邮箱注册/发信服务(2026-07-23,详见 domains/登录注册体系.md §八、domains/发信服务(短信邮件)-架构与配置指南.md)

后端代码已完成且编译通过,hiapi-core-public 已 report-public-module 上报,但:

1. 未做端到端验证:没有可跑的部署环境,建议部署后手动跑一遍 POST /account/forget → POST /account/reset-pwd → 新密码登录。
2. 前端未接 admin-ts 已接(2026-07-31):登录页加了两步找回密码对话框 (views/login/forget-password.vue),中英文案齐全。 C 端其实早就有了(public-web 的 pages/auth/forgot-password.vue)。 uniapp 仍未接,而且短期也接不了:hiapi-cloud-uniapp 的 src/pages 目前是空的, pages.json 里那个 pages/index/index 文件都不存在 —— 整个仓还是脚手架状态, 没有登录页可以挂。
3. nuwa 上报了两次(混淆版 auto-20260723-121001 用户要求撤回,又传了未混淆版 auto-20260723-121216),没有验证 nuwa 是否真的会用最新版覆盖生效,还是两个版本都留着造成歧义——如果部署后发现线上还在跑混淆版,先查这个。
4. ForgetPwd/BasicLoginRequest 加了字段(senderToken/email),影响 /account/register、/account/forget 的请求体 schema,EOLINK 里这两个接口的文档需要同步更新(参照 §1 流程,先补 Javadoc 再导入)。
5. Merchant/Platform/Channel 三种账户类型的 forget()/resetPwd() 依然是空白已处理(2026-07-31):merchant / channel 已实现(它们是客户侧账户,实体上有 mobile); platform 明确为「有意不支持」 —— 平台账户跨所有租户、权限最高、本来就不支持注册, 开自助找回等于把"能收到某个手机号的短信"变成拿到最高权限的充分条件,理由已写进代码。 两个安全点:resetToken 的 redis 前缀按账户类型隔离(否则商户的 token 能重置 C 端用户密码)、 token 取出即删一次性核销。