工具优先 · 契约驱动 · AI 原生交付

AI 编码时代的项目底座
规矩先立好，AI 自己写对

不塞给你一堆要读的代码，而是给 AI 立好护栏：
接口写进契约，对错交给自动检查，样板自动生成，流程固化成技能。

📐 读方法论 查看架构
Volo gRPC-rust Envoy transcoder PostgreSQL 一服务一库 React 19 + AntD 6 K8s + Istio Ambient Forgejo GitOps ClickHouse APM FDE 一键部署 refinery 迁移 cargo audit 门禁 AI Goal Workflow
8
领域微服务独立部署
219
RPC 契约 · 覆盖率审计 100%
3
层契约自动生成（proto→Rust/TS/Hooks）
全 PR
CI 门禁 + 分支保护（clippy/test/audit）
Inside the Foundation

AI 工作流贯穿每一层

不是又一个脚手架，而是一套跑通的工程实践：AI 工作流全程参与，CI 门禁和灰度发布都验证过
后台、PWA、App 共用一套后端

AI 原生交付工作流

一个想法拆成任务 → AI 并行开写 → 自动审查 → 灰度发布。 交付节奏从"周"变成"天"。

loop-it · review-it · ship-it

接口改一遍，前后端自动对齐

接口只写在 proto 里，Rust SDK、TS SDK、前端 hooks 全部自动生成。 改接口像改文档一样安全，前后端不会对不上。

proto → RS / TS SDK + hooks

后台该有的能力都现成

RBAC 权限、审计日志、MFA、OAuth、文件预签名、站内信、数据字典、任务调度、多语言、暗色模式——不用再自己搭一遍。

cargo build --workspace ✓

一条命令搭起整套环境

FDE 一条命令装好 Forgejo、8 个数据库、缓存、消息队列、对象存储和可观测组件，离线也能交付；数据库结构用版本化迁移管理。

./fde deploy · 8 容器 + 8 分库
The Method

工具要用在 AI 最容易出错的地方

样板代码、类型转换、CRUD，AI 顺手就写，不用再套一层生成器。
接口边界、一致性、验证这些 AI 容易翻车的地方，才该用工具管住。

接口只写一遍

proto 里写下接口和数据结构，Rust SDK、TS SDK、前端类型和 hooks 全部由它生成。不用手写，也就不会前后端对不上。

proto → RS / TS SDK + hooks

对错交给机器检查

把要求写成 CI 检查——契约校验、数据库迁移、回归测试、lint/audit。检查不过就合不进去，比靠人盯着靠谱。

clippy · test · audit · 分支保护

生成的东西能追回来源

生成分两种：SDK、类型、hooks 这类不用手改（文件头带 @generated，写明来源和怎么重新生成）；服务骨架、RPC 占位是留着让你填的（todo!），已经写好的实现绝不覆盖。出问题能顺着找到源头。

proto → stubs / 类型 / hooks

把流程固化成技能

把交付流程写成 AI 能照着做的技能（loop-it / review-it / ship-it），每一步都能查、能回滚、能重复用，不靠谁记性好。

prd → issues → loop → ship
真实命令 — 一切从 proto 开始
# ① 新建 / 补服务：生成骨架和 RPC 占位（签名对齐 proto，已写的实现不覆盖）
$ just new-service bffadmin port=8083    # 服务骨架：鉴权和日志中间件已接好
$ just gen-service bffadmin              # 按 proto 生成 RPC 占位（todo!），不覆盖已写实现
$ just gen-deploy bffadmin               # K8s 清单 + overlay 接线 + 服务注册

# ② 契约变更：三层 SDK 全部重新生成
$ buf lint && buf breaking --against main   # 契约校验 · 向后兼容
$ just gen-sdk && just gen-sdk-ts           # Rust SDK + TS SDK
$ pnpm generate:hooks                       # 前端 hooks（proto → TanStack Query）

✓ 服务骨架 + RPC 占位  ✓ 三层 SDK 生成（RS / TS / hooks）  ✓ 219 个 RPC 覆盖率审计

每个 RPC 一个独立文件（services/<svc>/src/service/<method>.rs），又小又独立。AI 可以并行改，不会互相踩文件。

真正省下的不是打字的时间，是读懂的成本：AI 要看的只有几千行契约和规则，而不是几十万行代码。

Architecture

清晰的分层架构

Web / PWA → Envoy 网关（HTTP/JSON 转码）· 原生 App → gRPC 直连领域服务
同一套后端，两种复用方式

Web / PWA · React 19 HTTP/JSON · :7788 原生 App gRPC 直连 · 同一套后端 Envoy 网关 · gRPC 转码 HTTP/JSON ↔ gRPC · 仅 Web/PWA 走这里 gRPC 直连 · 不经过转码 resource · :8001 API 资源 / 菜单 / 初始化上下文 audit · :8002 登录 / 操作 / API 审计日志 storage · :8004 文件元数据 / OSS 预签名 identity · :8005 用户 / 租户 / 登录 / MFA / OAuth permission · :8006 权限点 / 角色 / 策略评估 dict · :8007 数据字典 / 多语言 task · :8008 调度任务 internal_message · :8009 站内信 / 分类 / 收件箱 db_resource db_audit db_storage db_identity db_permission db_dict db_task db_message 一服务一库 · 不跨服务查表 · 服务间仅少量 gRPC 直连（identity→permission/audit, resource→permission）
Domain Services

8 个领域服务，覆盖后台全部核心能力

每个服务独立部署、独立演进，按需水平扩展

resource:8001
API 资源、菜单、前端路由与初始化上下文
resource_service.proto
audit:8002
登录 / 操作 / API / 数据访问 / 权限审计
audit_service.proto
storage:8004
文件元数据、传输、OSS 预签名
storage_service.proto
identity:8005
用户 / 组织 / 租户 / 登录 / MFA / OAuth
identity_service.proto
permission:8006
权限点 / 权限组 / 角色 / 策略评估
permission_service.proto
dict:8007
数据字典 / 条目 i18n / 语言
dict_service.proto
task:8008
调度任务
task_service.proto
internal_message:8009
站内信 / 分类 / 收件箱
internal_message_service.proto
AI Goal Workflow

AI 驱动的交付工作流

目标即需求：想法进来，生产代码出去。每一步可审查、可回滚

想法 / Goal

需求登记为任务卡片，AI 按依赖拓扑排序

任务拆解

拆成可并行执行的原子任务

AI 并行实现

隔离 worktree 并发开发 + 自动审查

代码审查

/review-it 并行测试与差异审查

GitOps 发布

分支驱动 CD，合入即部署到 K8s

循环执行 loop-it → review-it → ship-it，一个 Goal 闭环 = 一次可交付增量

Admin Console

企业级 React 后台，开箱即用

React 19 + Ant Design 6 + Vite 8，hooks 由 proto 自动生成，手写逻辑永不覆盖

细粒度 RBAC

菜单 / API 双层权限守卫，动态路由，权限码聚合

全量审计

登录 / 操作 / API / 数据访问审计可视化

MFA + OAuth

多因子认证、备份码、OAuth 提供商配置

国际化

i18next 命名空间 + 字典 i18n 管理

主题切换

AntD Token + UnoCSS，暗色 / 亮色一键切换

hooks 自动生成

proto → TanStack Query hooks，类型安全开箱即用

GitOps CD

分支即环境，合入即上线

  • git push 触发 CI：多级缓存构建 → 镜像 → manifest 渲染
  • cargo test/clippy/audit 全 PR 门禁，main 分支保护，红则无法合并
  • fj pr 创建 PR → 审查通过 → 合入目标分支
  • release 分支 灰度载体：受影响服务镜像构建 + 多账户染色灰度
  • gitops 分支被同步工具感知，自动同步到 K8s
  • kustomize overlay 管理环境差异（dev / staging / prod）
  • istio ambient 流量治理 + ns 级 waypoint + 灰度路由
deploy.sh — GitOps 分支部署
$ git push origin feat/goal-42
$ fj pr create --title "feat: internal_message inbox"
$ fj pr merge --squash --delete-branch
$ fj issue close 42

⏱ 检测到 gitops 分支更新
→ 渲染 kustomize overlay prod
→ 同步到 K8s 集群
✓ internal_message 滚动发布完成 :8009
Observability · ClickHouse APM

黄金三支柱，上线即有，不补课

自建 ClickHouse 调用链（零外部依赖），日志 / 指标 / 追踪一体
跨服务全链路还原，一条命令看调用树

调用链直写 ClickHouse

rust_ddd_logs.traces 直写（零 collector 依赖），trace_id 跨服务串连

envoy → identity → audit

一条命令还原调用树

just trace <trace_id> 一条命令还原调用树，排障直接贴进 issue

just trace 4f9a… → 调用树

日志-追踪关联

日志与 span 共用 trace_id / request_id，一键跳到链路，慢查询自动标记

log → trace → 泳道 dash

集群实时流量泳道

just topology 5 灰度 / main 双泳道实时拓扑，kubectl 实况渲染

just topology 5 · 每 5s 刷新
接入方式 — 零外部依赖
$ just trace 4f9a3c…   # 还原整条调用树
$ just topology 5     # 集群实时流量泳道（每 5s 刷新）

✓ 服务端 span（server）✓ 客户端 span（client）✓ 慢查询标记
✓ trace_id 跨服务串连 ✓ 灰度 / main 泳道实时拓扑
✓ ClickHouse 直写，无 collector
just topology 版本泳道 dash 🔍 just topology 泳道 dash · 点击放大
Comparison

这套底座覆盖的能力

同样的能力，从零搭建约 3 个月；方法沉淀下来，起步即 1 天

能力自己从零搭建RustSaaS
微服务拆分与 DDD 建模从架构评审开始8 领域直接可用
前后端接口契约手写 SDK + 文档 + 反复对齐proto 自动生成，永不失配
RBAC / 审计 / MFA / OAuth逐个实现，半年量开箱即用
后台前端选型 + 搭建 + 联调React 19 + AntD 6 就绪
持续交付自己搭 CI/CD + 环境GitOps 分支部署
可观测性（日志/指标/追踪）后期补课，选型+接入耗时ClickHouse 自建 APM + just trace
CI 质量门禁自己搭 lint/测试/漏洞扫描 + 分支保护全 PR 必跑，红则无法合并
数据库迁移手写 ALTER / 全量重建refinery 版本化迁移
功能开发流程手写 → 自测 → 提测AI Goal Workflow 自动闭环
上线时间3~6 个月1 天
How to Engage

两种参与方式

这是一套自用的项目底座，也是一份可展示的工程方法论。
不为它标价，只按结果合作。

自用 · 项目底座
持续演进
我自己的交付加速器：新项目从它起步，省下重复搭基建的时间
  • 8 领域服务 + 契约生成链路可复用
  • FDE 一键私有化部署（离线可交付）
  • CI 门禁 / GitOps / 可观测性开箱即用
  • goal-workflow 工作流固化
看架构
开放合作
合作 · 私有化交付 / 方法论落地
按结果商谈
适合要私有化 / 内网部署、或想把 AI 产研工作流落到自己团队的场景
  • 私有化部署（远程 / 上门内网）
  • AI 工作流落地 + 团队培训
  • 按你的领域定制一个服务
  • 长期工程方法咨询
聊聊你的场景

如果你也在做 AI 时代的工程工具，欢迎交流

这套底座用于我自己的交付；如果你的场景需要私有化落地、或想把 AI 产研工作流搬进团队，可以直接聊。

📧 邮件联系 再逛逛架构