# 架构与资源边界

区分后端项目、Release Operation、Artifact、环境、部署、运行治理和数据库迁移。

后端应用的构建面与运行面相互独立：

| 资源                | Owner              | 职责                        | 是否可变       |
| ----------------- | ------------------ | ------------------------- | ---------- |
| Project           | Project Service    | 后端应用的唯一产品身份，保存源码和 Git 历史  | 可持续修改      |
| Release Operation | Rust Build Service | 从主线 HEAD 发布一个 Cargo 语义版本  | 完成后保留状态和日志 |
| Artifact          | Artifact Service   | 保存构建成功后登记的统一可部署制品元数据      | 不可变        |
| Environment       | Hosted Service     | 某个 Project 的开发、测试、生产等运行配置 | 可产生配置修订    |
| Deployment        | Hosted Service     | 把一个 Artifact 部署到一个环境      | 每次部署形成记录   |
| Endpoint          | Hosted Service     | 对调用方提供稳定访问地址              | 由部署和路由状态支撑 |

“Hosted Service”是平台提供的托管构建与运行能力，不是需要另行创建的产品资源。项目、环境、部署、
端点以及它们的历史都以真实 `projectId` 关联；不存在与 Project 并列的 `hostedServiceId`。

核心不变量是：

```text
同一主线 commit 的 Cargo package.version 发布一次
  -> 得到一个不可变 projectVersion
  -> 同一个 projectVersion 逐级部署到开发、测试和生产
```

Hosted Service 部署只接收 `projectId + projectVersion`，不会把 `releaseOperationId`、`buildJobId` 或
`artifactId` 当成部署版本，也不会在部署阶段隐式重新构建。发布成功时，构建服务把
`hosted_service_release` 登记到独立 Artifact Service；Hosted Service 在自己的边界内按项目版本解析该
不可变制品。Artifact 查询不改变后端所有权，也不是正常部署入口。

## 配置边界

- 源码和 Artifact 保存与环境无关的程序逻辑。
- 数据库、密钥、第三方 token 和环境差异配置在 Environment 或 Config Provider 中管理。
- `db-service` 负责数据库 Instance、Logical Database、Profile 和 Allocation；Hosted Service 能力只在
  Project Environment 中保存绑定，并在部署时解析连接配置。
- 数据库迁移是与运行 Artifact 同源提交构建出的不可变 Artifact，由 Hosted Service 能力在目标
  Environment 的数据库上、运行部署和流量切换之前执行。
- Endpoint 鉴权由环境级 consumer/token 或应用自身鉴权负责。
- 业务用户权限由后端应用自身或上游受信任身份上下文负责。

不要把生产配置打进 Artifact，也不要让构建脚本根据目标环境生成内容不同但版本相同的制品。

## 业务进程与运行治理边界

Hosted Service 后端必须按可以水平扩展为多个副本设计。Rust 业务进程不拥有实例数量、流量入口或跨副本
治理状态；增加、替换或回收副本不能改变业务合同，也不能要求业务代码增加部署环境分支。

| 层次                 | 负责                                                        | 不负责                                 |
| ------------------ | --------------------------------------------------------- | ----------------------------------- |
| Rust 业务进程          | 业务规则、业务授权、数据一致性、事务、幂等、业务配额，以及健康检查、优雅退出、请求取消和有界资源使用等单进程正确性 | 实例数量、扩缩容、入口负载均衡、通用请求限流、跨副本运行配额和发布调度 |
| Hosted Service 控制面 | Environment 的类型化运行治理配置、配置修订、Slot 绑定、Deployment 编排和治理策略下发  | 在业务进程内复制一套运行治理状态                    |
| Slot               | 当前可用的 CPU、内存和副本容量权益，以及运行载体约束                              | 业务规则或某个请求的业务授权                      |
| OpenResty 与运行载体    | Endpoint 路由与鉴权、通用速率和并发保护、负载均衡、进程放置、就绪摘挂流、重启和发布切换          | 依赖业务数据判断的配额、计费权益或领域不变量              |

实例数量、扩缩容策略、资源限制和通用流量策略应由目标 Environment 下的类型化、版本化治理配置统一管理，
并由 Hosted Service 根据 Slot 当前容量和产品目录校验后投影到运行载体。它们不是注入 Rust 进程的普通环境
变量，也不能通过约定任意配置键让业务代码自行解释。当前是否开放某项治理能力、可选值和限制，以工作区
当前 Runtime 方法定义与 Slot 目录为准；能力尚未开放时，普通 Environment 配置不能代替平台治理合同。

凡是需要在多个副本之间保持统一语义的通用运维能力，都必须由外部运行层或权威集中式服务执行。例如单个
OpenResty 实例可以完成本地过载保护，但跨副本的全局精确限流必须使用共享的权威计数能力，不能把每个 Rust
进程的本地计数相加后假装成全局配额。

这条边界不把业务责任移出 Rust 服务。像“某用户每天最多创建多少个业务对象”、积分余额、套餐权益、事务
冲突和上游调用幂等仍依赖业务身份与持久化状态，必须由对应业务 Owner 执行；它们不能被降格为 OpenResty
中的通用请求限流。

## 代码设计边界

运行资源边界清晰并不代表服务内部可以继续传递无类型数据。Rust 后端必须把 HTTP、消息、数据库 JSON
列和 Artifact 限制在适配器边界；JSON 进入服务后立即反序列化为有明确 Owner、版本和不变量的 Rust
类型，领域和应用逻辑只处理类型化对象。

Contract DTO、领域对象、应用 Command/Query、数据库 Record 和第三方 Payload 必须分开建模，业务转换
使用显式 `TryFrom`、`From`、编译器或应用服务完成。完整的目录、依赖方向、Serde、契约演进和测试门禁见
[Rust 服务设计约束](/development/backend-development/rust-service-design/)。