name	aim-attachment-domain
description	AIM 的附件域。涉及 `app/attachment`、AttachmentService gRPC、上传/下载授权、SeaweedFS/S3 签名、附件元数据、`aim.attachment.uploaded` 事件时使用。

aim-attachment-domain

边界

attachment 是内部 gRPC 服务，不向客户端/公网暴露 REST/WS。
客户端附件能力只能经 gateway 的 /api/attachments/* REST 入口访问；gateway 通过 AttachmentRpc 调用 attachment.rpc。
core 校验附件消息引用只能通过 AttachmentService.ValidateReference gRPC，不再调用内部 HTTP。
attachment 可直接访问 SeaweedFS/S3 与 PostgreSQL；媒体附件（image/video/audio）上传完成后发布 aim.attachment.uploaded，普通文件（file）上传完成后直接置为解析完成，不进入 data_parsing。
不要恢复 internal/httpx、http.Server、/v1/attachments/* 等模块间 HTTP 接口。

关键位置

app/attachment/attachment.go：服务入口，启动 go-zero zrpc 并由 zrpc.MustNewServer 自动注册到 etcd（Etcd.Key: attachment.rpc）。
app/attachment/rpc/attachment.proto：AttachmentService 协议源。
app/attachment/rpc/pb/：protoc 生成代码，除重新生成外不要手改。
app/attachment/internal/server/：gRPC server 适配层，负责 pb 与业务 service DTO 转换、错误映射。
app/attachment/internal/service/：附件核心业务、SeaweedFS/S3 预签名与对象校验。
app/attachment/model/migrations/：附件表结构。
app/attachment/rpc/etc/attachment.yaml：本地 go run / 单服务调试默认配置；Docker Compose 部署挂载 deploy/config/<env>/attachment.yaml 到 /app/etc/attachment.yaml。

变更规则

RPC 变更必须先改 app/attachment/rpc/attachment.proto，再在 app/attachment/rpc 下执行： protoc --go_out=. --go-grpc_out=. attachment.proto。
新增字段只追加字段号，不复用旧字段号；保持 gateway/core 调用兼容。
对外 REST 字段转换在 gateway 完成；attachment 只暴露内部 pb 类型。
gRPC 业务错误使用 errorx.NewCodeError 映射：参数错误 CodeBadInput，无记录 CodeNotFound，权限/引用不匹配 CodeForbidden，基础设施错误对外清洗为 internal error。
SeaweedFS/S3 HTTP 调用是对象存储协议，不是 AIM 模块间 API；必须用 context-aware request 并保留 tracing。
媒体上传完成事件使用 aim.attachment.uploaded，key 使用 file_id，payload 要携带 trace context；file 普通附件不得发布给 data_parsing。

常用验证

go test ./app/attachment/...
go test ./app/gateway/api/internal/handler/attachments/... ./app/core/rpc/internal/logic/...
go build ./app/attachment/... ./app/gateway/api/... ./app/core/rpc/...

Más de este repositorio

mismo repositorio

aim-shared-domain

hellopoisonx/aim

aim 的进程内共享包域。对应 `app/shared` 模块。

2026-06-055

aim-database-migration

hellopoisonx/aim

AIM 数据库迁移规范与 Docker Compose 集成。当修改 migration SQL 文件、新增迁移、修改 docker-compose.yaml 的 migrate 服务、或排查迁移失败时使用。

2026-06-045

aim-auth-domain

hellopoisonx/aim

aim 的认证域。对应 `auth` 模块。

2026-06-035

aim-core-domain

hellopoisonx/aim

aim 的核心域。对应 `core` 模块。

2026-06-035

aim-dev-tool

hellopoisonx/aim

AIM 开发测试工具（dev-tool）。Python CLI，覆盖 gateway 全部 REST 端点与 WebSocket 帧协议，支持多 profile 多用户并行测试、并发压测。当需要调试 REST/WS 接口、运行集成测试、压力测试、或新增命令时使用。

2026-06-035

aim-gateway-domain

hellopoisonx/aim

aim 的网关域。对应 `gateway` 模块。

2026-06-035

aim-attachment-domain

边界

attachment 是内部 gRPC 服务，不向客户端/公网暴露 REST/WS。

客户端附件能力只能经 gateway 的 /api/attachments/* REST 入口访问；gateway 通过 AttachmentRpc 调用 attachment.rpc。

core 校验附件消息引用只能通过 AttachmentService.ValidateReference gRPC，不再调用内部 HTTP。

attachment 可直接访问 SeaweedFS/S3 与 PostgreSQL；媒体附件（image/video/audio）上传完成后发布 aim.attachment.uploaded，普通文件（file）上传完成后直接置为解析完成，不进入 data_parsing。

不要恢复 internal/httpx、http.Server、/v1/attachments/* 等模块间 HTTP 接口。

关键位置

app/attachment/attachment.go：服务入口，启动 go-zero zrpc 并由 zrpc.MustNewServer 自动注册到 etcd（Etcd.Key: attachment.rpc）。

app/attachment/rpc/attachment.proto：AttachmentService 协议源。

app/attachment/rpc/pb/：protoc 生成代码，除重新生成外不要手改。

app/attachment/internal/server/：gRPC server 适配层，负责 pb 与业务 service DTO 转换、错误映射。

app/attachment/internal/service/：附件核心业务、SeaweedFS/S3 预签名与对象校验。

app/attachment/model/migrations/：附件表结构。

app/attachment/rpc/etc/attachment.yaml：本地 go run / 单服务调试默认配置；Docker Compose 部署挂载 deploy/config/<env>/attachment.yaml 到 /app/etc/attachment.yaml。

变更规则

RPC 变更必须先改 app/attachment/rpc/attachment.proto，再在 app/attachment/rpc 下执行： protoc --go_out=. --go-grpc_out=. attachment.proto。

新增字段只追加字段号，不复用旧字段号；保持 gateway/core 调用兼容。

对外 REST 字段转换在 gateway 完成；attachment 只暴露内部 pb 类型。

gRPC 业务错误使用 errorx.NewCodeError 映射：参数错误 CodeBadInput，无记录 CodeNotFound，权限/引用不匹配 CodeForbidden，基础设施错误对外清洗为 internal error。

SeaweedFS/S3 HTTP 调用是对象存储协议，不是 AIM 模块间 API；必须用 context-aware request 并保留 tracing。

媒体上传完成事件使用 aim.attachment.uploaded，key 使用 file_id，payload 要携带 trace context；file 普通附件不得发布给 data_parsing。

常用验证

go test ./app/attachment/... go test ./app/gateway/api/internal/handler/attachments/... ./app/core/rpc/internal/logic/... go build ./app/attachment/... ./app/gateway/api/... ./app/core/rpc/...