技术方案目录
技术方案目录
Section titled “技术方案目录”1. 项目概述
Section titled “1. 项目概述”1.1 项目背景
Section titled “1.1 项目背景”1.2 项目目标
Section titled “1.2 项目目标”1.3 业务范围
Section titled “1.3 业务范围”1.4 非目标范围
Section titled “1.4 非目标范围”1.5 核心价值
Section titled “1.5 核心价值”1.6 关键术语
Section titled “1.6 关键术语”2. 需求分析
Section titled “2. 需求分析”2.1 核心功能
Section titled “2.1 核心功能”2.2 用户角色
Section titled “2.2 用户角色”2.3 核心业务流程
Section titled “2.3 核心业务流程”2.4 业务规则
Section titled “2.4 业务规则”2.5 数据范围
Section titled “2.5 数据范围”2.6 边界条件
Section titled “2.6 边界条件”2.7 验收标准
Section titled “2.7 验收标准”3. 技术选型
Section titled “3. 技术选型”3.1 后端技术栈
Section titled “3.1 后端技术栈”3.2 前端技术栈
Section titled “3.2 前端技术栈”3.3 数据库选型
Section titled “3.3 数据库选型”3.4 缓存选型
Section titled “3.4 缓存选型”3.5 消息队列选型
Section titled “3.5 消息队列选型”3.6 对象存储选型
Section titled “3.6 对象存储选型”3.7 第三方服务依赖
Section titled “3.7 第三方服务依赖”3.8 技术选型原因
Section titled “3.8 技术选型原因”4. 系统架构设计
Section titled “4. 系统架构设计”4.1 整体架构
Section titled “4.1 整体架构”4.2 项目工程化
Section titled “4.2 项目工程化”4.2.1 工程目录结构
Section titled “4.2.1 工程目录结构”当前工程采用多模块组织方式，各模块职责清晰拆分，避免网关、契约、业务服务和联调工具互相耦合。
agent-backend/├── agent-contracts/ # 接口契约中心，维护 Thrift IDL 和 Kitex 生成代码│ ├── idl/ # common、platform 等 Thrift 接口定义│ ├── kitex_gen/ # Kitex 自动生成代码，业务代码不手动修改│ ├── registry/ # 服务注册描述│ ├── scripts/ # IDL 生成脚本│ ├── Makefile│ └── go.mod├── gateway-api/ # HTTP 网关服务，基于 Hertz│ ├── cmd/server/ # 网关启动入口│ ├── configs/ # 网关环境配置│ ├── internal/ # 网关内部代码，不对外暴露│ │ ├── bootstrap/ # 启动组装│ │ ├── config/ # 配置加载│ │ ├── router/ # HTTP 路由注册│ │ ├── handler/ # HTTP Handler│ │ ├── response/ # 统一响应结构│ │ ├── middleware/ # HTTP 中间件│ │ └── client/ # 下游 RPC/HTTP Client│ ├── deploy/ # 部署相关文件│ ├── scripts/ # 运维脚本│ ├── Makefile│ └── go.mod├── <service-name>/ # Kitex 业务服务通用目录模板，例如 platform-service│ ├── cmd/server/ # 服务启动入口，只负责加载配置、组装 App、启动 Kitex Server│ ├── conf/ # dev/prod 等环境配置│ ├── biz/ # 服务核心业务代码│ │ ├── bootstrap/ # 资源初始化和依赖组装│ │ ├── handler/ # Kitex Handler，负责 RPC 入口转发│ │ ├── service/ # 业务编排层│ │ ├── domain/ # 复杂领域逻辑沉淀│ │ ├── model/ # entity、po、dto 模型│ │ ├── dal/ # MySQL、Redis 等数据访问│ │ └── rpc/ # 下游 RPC Client│ ├── pkg/ # 服务内通用能力│ ├── migrations/ # 数据库迁移 SQL│ ├── Makefile│ └── go.mod├── platform-client-test/ # 本地 RPC 联调项目│ ├── cmd/platform-client/ # 测试调用入口│ ├── client/ # Kitex Client 初始化│ ├── pkg/utils/ # 联调用工具函数│ └── go.mod├── docs/ # 技术方案与设计文档└── docs-center/ # 文档中心预留工程目录约束：
agent-contracts只维护接口契约和生成代码，不承载业务逻辑。gateway-api只处理 HTTP 接入、鉴权、参数校验、统一响应、限流和下游调用，不实现核心业务编排。<service-name>是新增 Kitex 业务服务的通用工程模板，当前platform-service是该模板的落地实例。platform-service承载平台业务，包括租户、中台账号、用户、成员、工作空间等核心能力；后续新增agent-core-service、knowledge-service等服务时复用同一目录规范。platform-client-test只用于本地联调和接口验证，不作为生产服务依赖。migrations只保存数据库结构变更 SQL，表结构非明确不定义deleted_at字段。kitex_gen为自动生成目录，不允许手工修改。
4.2.2 模块分层规范
Section titled “4.2.2 模块分层规范”后端模块按入口层、应用编排层、业务层、领域模型层、数据访问层、公共能力层分层。
gateway-api 分层：
cmd/server：服务启动入口，只负责启动应用。internal/bootstrap：加载配置、初始化 Hertz、注册路由。internal/router：集中管理 HTTP 路由和路由分组。internal/handler：处理 HTTP 请求、参数绑定、调用 application 或 client。internal/application：应用用例编排预留，避免 Handler 直接承载复杂流程。internal/client：封装对内部 RPC 服务的调用。internal/response：统一 HTTP 响应结构和错误响应。internal/middleware：鉴权、日志、追踪、限流等横切能力。
Kitex 业务服务通用分层，以 platform-service 为当前示例：
cmd/server：Kitex 服务启动入口。biz/bootstrap：初始化 MySQL、Repository、Service、Handler 等运行资源。biz/handler：Kitex RPC 入口层，只做请求转发和必要的入口适配。biz/service：业务编排层，方法签名直接面向 IDL 请求响应，例如CreateTenant(ctx, req)。biz/domain：复杂业务规则沉淀位置，当前按租户、用户、成员、工作空间预留。biz/model/entity：领域实体和核心业务校验。biz/model/po：GORM 持久化对象，字段与数据库表结构对应。biz/model/dto：分页、查询等内部传输对象。biz/dal/mysql：MySQL 数据访问，使用 GORM。biz/dal/redis：Redis 缓存访问预留。biz/rpc：下游微服务调用预留。pkg：配置、错误、密码、Token、ID 生成、工具函数等通用能力。
新增 Kitex 业务服务时，原则上复用上述目录结构。服务名只影响模块名、配置文件中的服务名、IDL service 名称和 Makefile 构建产物名称，不改变分层边界。
4.2.3 代码组织规范
Section titled “4.2.3 代码组织规范”- 同一业务域的 CRUD/RUD 操作保持在同一个 Service 或 Repository 入口中，避免为了形式拆出过多小接口。
handler不直接持有单个具体 Service，应通过资源聚合对象访问多个 Service，便于后续扩展多个业务服务。service层直接表达业务用例，避免把简单流程拆成无意义的多层封装。repository使用具体结构体，不额外定义没有复用价值的接口。entity负责业务不变量校验，例如必填字段、状态流转、角色合法性。po只描述数据库字段，不承载业务行为。pkg只放跨模块复用或基础设施能力，不放具体业务逻辑。- 自动生成代码、数据库迁移脚本、配置模板和业务代码分目录管理。
4.2.4 配置管理规范
Section titled “4.2.4 配置管理规范”platform-service配置放在conf/dev.yaml、conf/prod.yaml，包含服务监听地址、MySQL、Redis 等配置。gateway-api配置放在configs/local.yaml，包含应用名称、运行环境、HTTP 监听地址。- 配置加载逻辑集中在各服务的
pkg/config或internal/config中。 - 生产环境敏感配置不应直接提交明文，应通过环境变量、配置中心或密钥管理系统注入。
- 代码中不硬编码数据库账号、密码、服务地址；本地测试配置与生产配置分离。
4.2.5 环境区分规范
Section titled “4.2.5 环境区分规范”- 本地环境用于开发和联调，允许使用
local、dev配置。 - 测试环境用于接口回归、迁移脚本验证和服务间联调。
- 生产环境使用
prod配置，必须关闭调试输出，敏感信息通过安全渠道注入。 - 不同环境的数据库、缓存、服务地址必须隔离，禁止本地服务误连生产数据库。
- Makefile 命令默认面向本地开发，生产构建和部署由 CI/CD 或部署脚本负责。
4.2.6 日志规范
Section titled “4.2.6 日志规范”- 日志应包含时间、服务名、环境、请求 ID、Trace ID、方法名、耗时和错误信息。
gateway-api重点记录 HTTP 方法、路径、状态码、耗时、调用方和请求追踪信息。platform-service重点记录 RPC 方法、业务关键 ID、数据库错误、下游调用错误和耗时。- 密码、Token、手机号、邮箱等敏感信息不得明文输出。
- 业务错误按可预期错误记录为 warn，系统错误、数据库错误、下游不可用记录为 error。
- 后续统一引入结构化日志，优先使用标准库
slog或项目统一日志组件。
4.2.7 错误处理规范
Section titled “4.2.7 错误处理规范”gateway-api对外返回统一响应结构，包含code、message、data、error、meta。platform-service内部使用明确的业务错误，例如租户不存在、中台账号已存在、密码错误等。- 参数校验错误、业务规则错误、系统错误分开处理，不用字符串匹配判断错误类型。
- Repository 层将
gorm.ErrRecordNotFound转换为业务可识别错误。 - Handler 层不吞错误，除非已经转换为明确响应。
- 错误响应中不暴露数据库 DSN、SQL 细节、堆栈和敏感配置。
4.2.8 依赖管理规范
Section titled “4.2.8 依赖管理规范”- 每个 Go 模块独立维护
go.mod和go.sum。 platform-service、gateway-api、platform-client-test通过replace agent-contracts => ../agent-contracts引用本地契约模块。- 引入新依赖前先确认是否已有标准库或项目内工具可满足需求，避免不必要依赖。
- Kitex、Hertz、GORM 等核心框架版本应在模块内固定。
- 修改 IDL 后必须重新生成
agent-contracts/kitex_gen，调用方再更新依赖。
4.2.9 代码格式化规范
Section titled “4.2.9 代码格式化规范”- Go 代码统一使用
gofmt格式化。 - 提交前至少执行对应模块的
gofmt和go test ./...。 - 生成代码不手动格式化修改，由生成工具负责。
- SQL 迁移脚本保持关键字、字段、索引、约束结构清晰，字段注释完整。
4.2.10 静态检查规范
Section titled “4.2.10 静态检查规范”- 基础检查以
go test ./...为准，保证所有包可编译。 - 后续可在 CI 中补充
go vet ./...、staticcheck、golangci-lint。 - 静态检查重点覆盖未使用代码、错误未处理、上下文传递、并发安全、格式化问题。
- lint 规则应服务于可维护性，不引入与项目风格冲突的过度约束。
4.2.11 本地开发规范
Section titled “4.2.11 本地开发规范”- 修改接口契约时，先改
agent-contracts/idl，再执行make gen生成 Kitex 代码。 - 启动 RPC 服务：
cd platform-servicemake run- 启动 HTTP 网关：
cd gateway-apimake run- 本地调用 RPC 接口：
cd platform-client-testgo run ./cmd/platform-client- 运行测试：
go test ./...- 服务默认端口：
platform-service使用8888，gateway-api使用8080。
4.2.12 构建与发布规范
Section titled “4.2.12 构建与发布规范”- 每个服务模块通过自己的 Makefile 提供
test、run、build、tidy等命令。 gateway-api构建产物默认输出到bin/gateway-api。platform-service构建产物为platform-service，后续可统一调整到bin/目录。- 发布前必须完成依赖整理、编译、测试、配置检查和数据库迁移脚本审核。
- 数据库结构变更通过
migrations管理，先在测试环境验证，再进入生产发布。 deploy/k8s用于网关部署清单预留，后续各服务应补齐容器镜像、资源限制、探针和环境变量配置。