提示：AI 结果必须带引用；若证据不足会提示“未找到可靠证据”。

    下载 Markdown

    提示词资产化系统技术架构文档（v1.0）

    1. 文档目标

    本文档用于定义提示词资产化系统的技术架构、模块边界、技术栈约束与落地规范，作为后续研发、测试与运维的统一基线。

    2. 强制约束

    1. 后端服务技术栈固定为 Golang。
    2. 前端服务技术栈固定为 React + Vite + Ant Design。
    3. 所有持久化存储访问必须通过 /Users/Zhuanz/work-space/cloud-data-proxy 提供的代理能力完成，禁止业务服务直连数据库。
    4. React 开发采用事件驱动模型，非必要情况禁止使用 useEffect。

    3. 总体架构

    flowchart LR U["用户"] --> FE["前端应用<br/>React + Vite + Ant Design"] FE --> BE["后端 API 服务<br/>Go"] BE --> PXY["cloud-data-proxy<br/>HTTP 接口"] PXY --> DB["MySQL/元数据存储"] BE --> OBS["日志/指标/审计"]

    架构说明：

    1. 前端仅访问后端业务 API，不直接访问数据库代理。
    2. 后端是唯一业务入口，负责鉴权、业务编排、规则校验、审计与错误模型统一。
    3. 后端通过 proxy 的 /v1/query、/v1/exec、/v1/ddl 完成读写与结构变更。

    4. 技术栈规定

    4.1 后端（Go）

    建议基线：

    1. 语言版本：Go 1.22+
    2. Web 框架：Gin（或 Chi，二选一并在项目内保持唯一）
    3. 配置管理：Viper 或自研轻量配置加载
    4. 日志：zap（JSON 结构化日志）
    5. 指标：Prometheus + /metrics
    6. API 文档：OpenAPI 3
    7. 测试：testing + testify

    核心原则：

    1. 不引入数据库驱动到业务仓储层，仓储层只依赖 proxy client 接口。
    2. 所有 SQL 均由后端生成并经 proxy 执行，统一参数化，禁止字符串拼接注入风险。

    4.2 前端（React + Vite + Ant Design）

    建议基线：

    1. React 18+
    2. Vite 5+
    3. TypeScript 5+
    4. Ant Design 5+
    5. 路由：React Router
    6. 状态管理：Zustand 或 Redux Toolkit（推荐事件 action 驱动）
    7. 测试：Vitest + React Testing Library

    核心原则：

    1. 页面状态由事件驱动更新，不通过 useEffect 做默认数据流编排。
    2. 请求触发来自显式用户动作（点击、提交、切换）或路由 loader，不使用 “组件加载后自动 effect 拉取” 作为默认模式。

    5. 后端逻辑架构分层

    API Layer (HTTP Handler)
  -> Application Layer (UseCase / Service)
    -> Domain Layer (Entity / Rule)
      -> Infrastructure Layer (Proxy Client / Cache / Logger)

    5.1 API Layer

    职责：

    1. 参数校验、鉴权、错误码映射、响应序列化。
    2. 注入 request_id 并传递到下游。

    5.2 Application Layer

    职责：

    1. 编排提示词资产的业务流程（创建、拆解、模板化、评估、发布）。
    2. 保证幂等与状态流转合法性。

    5.3 Domain Layer

    职责：

    1. 定义核心实体与聚合：PromptAsset、PromptTemplate、PromptModule、PromptEvaluation。
    2. 承载规则：模板发布门槛、评分合格线、版本不可回退条件等。

    5.4 Infrastructure Layer

    职责：

    1. 实现 cloud-data-proxy client。
    2. 提供审计写入、缓存、重试与熔断能力。
    3. 统一封装 query/exec/ddl 调用协议。

    6. 存储访问架构（通过 cloud-data-proxy）

    6.1 接口映射

    1. 读：POST /v1/query
    2. DML 写：POST /v1/exec
    3. DDL：POST /v1/ddl
    4. 管理动作（可选）：/admin/apps、/admin/apps/{app_id}/rotate-key

    6.2 访问策略

    1. 每次请求必须带 Authorization: Bearer <api_key>。
    2. 每次调用必须记录 proxy 返回的 request_id。
    3. DDL 请求必须强制 ddl_ack=true 且提供 change_reason。
    4. 不允许出现任何后门直连开关（例如 DIRECT_DB_DSN）。

    6.3 重试与失败处理

    1. 查询与幂等读请求可有限重试（如指数退避，最多 2 次）。
    2. 写请求默认不自动重试，避免重复写；通过业务幂等键控制重放。
    3. proxy 不可用时快速失败并返回统一错误码（如 PROXY_UNAVAILABLE）。

    7. 核心业务模块设计

    7.1 资产管理模块

    能力：

    1. 原始提示词录入、编辑、归档。
    2. 标签与分类管理。
    3. 资产检索与分页查询。

    7.2 结构拆解模块

    能力：

    1. 将提示词拆解成 role/goal/context/constraints/output_schema 等标准块。
    2. 对拆解结果进行字段完整度校验。

    7.3 模板与实例模块

    能力：

    1. 公共模块抽取与模板组装。
    2. 模板参数定义与渲染。
    3. 场景化实例生成与版本追踪。

    7.4 评估治理模块

    能力：

    1. 多维评分（准确性、稳定性、安全性、效率）。
    2. 审核与发布状态流转。
    3. 变更审计与回溯。

    8. API 设计（业务服务）

    建议接口（示例）：

    1. POST /api/v1/assets：创建资产
    2. GET /api/v1/assets：资产检索
    3. POST /api/v1/assets/{id}/decompose：结构拆解
    4. POST /api/v1/templates：创建模板
    5. POST /api/v1/templates/{id}/render：渲染实例
    6. POST /api/v1/evaluations：提交评估
    7. POST /api/v1/templates/{id}/publish：发布模板

    统一响应规范：

    1. 返回体必须包含 request_id。
    2. 错误响应统一结构：code、message、details。

    9. 前端架构设计（事件驱动）

    9.1 目录建议

    src/
  app/                # 应用入口与路由
  pages/              # 页面
  features/           # 领域模块（assets/templates/evaluations）
  components/         # 通用组件（基于 Antd）
  store/              # 状态与 action
  services/           # API 调用封装
  utils/              # 工具与常量

    9.2 事件驱动数据流

    sequenceDiagram participant UI as 页面组件 participant ACT as Action participant API as Service API participant ST as Store UI->>ACT: 用户事件(点击/提交) ACT->>API: 发起请求 API-->>ACT: 返回结果 ACT->>ST: 更新状态 ST-->>UI: 触发渲染

    执行规范：

    1. 数据请求由事件触发（按钮点击、表单提交、路由 loader）。
    2. 组件避免在 useEffect 中发请求、做状态镜像、衍生状态计算。
    3. 衍生数据使用 useMemo 或 selector，不创建冗余 state。

    10. 安全设计

    1. 前后端均不打印明文 token/api_key。
    2. 后端对输入参数做白名单校验与长度限制。
    3. 关键操作（发布、DDL 相关）保留操作人和时间戳。
    4. 全链路 request_id 贯通日志与审计。

    11. 可观测性设计

    1. 日志：结构化字段包含 request_id、operator、action、duration_ms、error_code。
    2. 指标：请求总量、成功率、P95 延迟、proxy 调用失败率、模板发布成功率。
    3. 告警：proxy 连续错误、发布失败率异常、写入失败突增。

    12. 部署架构

    建议部署单元：

    1. 前端：静态资源部署（Nginx 或 CDN）。
    2. 后端：Go 二进制或容器部署。
    3. 代理：复用现有 cloud-data-proxy 服务。

    环境分层：

    1. dev：本地联调环境
    2. staging：预发布验证环境
    3. prod：生产环境

    配置策略：

    1. 环境变量注入地址与密钥。
    2. 严禁在代码仓库存储生产密钥。

    13. 测试策略

    1. 后端单元测试：领域规则、参数校验、错误映射。
    2. 后端集成测试：mock proxy 成功/失败路径、幂等逻辑。
    3. 前端组件测试：表单与列表交互、事件驱动 action 触发。
    4. 前端端到端测试：关键流程（创建资产 -> 拆解 -> 模板化 -> 发布）。

    14. 研发规范与质量门禁

    1. 新功能必须附带最小测试。
    2. PR 必须说明是否新增 useEffect，如新增需写明不可替代原因。
    3. 任何引入数据库直连依赖的改动一律拒绝合并。
    4. 所有写路径必须记录审计信息。

    15. 分阶段落地计划

    1. Phase 1：骨架搭建（Go API + React 基础框架 + proxy client）。
    2. Phase 2：资产管理与结构拆解。
    3. Phase 3：模板/实例与评估治理。
    4. Phase 4：观测、审计、性能优化与发布流程固化。