architecture-designer

Skill: Architecture Designer

在逐场景的技术实现之前，建立项目的技术全局视图：系统架构、技术选型、部署约束和非功能性约束。完整部署方案由 deployment-designer Skill 在 Phase 3 Step 3 产出。

触发条件

用户要求设计技术架构、做技术选型或规划系统架构
用户提到 "Phase 3 Step 0"、"架构设计"、"技术方案"
Phase 2 产品设计文档已完成，需要开始 Phase 3
用户想要确定技术栈或部署约束

核心能力

读取 Phase 1 需求文档和 Phase 2 产品设计文档，理解产品全貌
基于产品复杂度和场景特征，推荐适合的系统架构
为每项技术选型提供选型理由和替代方案对比
绘制系统架构图（Mermaid）和部署约束图
明确部署方案的输入边界：运行环境、依赖服务、部署目标、外部服务测试策略
更新 logos-project.yaml 的 tech_stack 字段

与 Phase 1/2 的衔接

架构设计是 Phase 2（产品设计）到 Phase 3（技术实现）的桥梁。它的输入来自 Phase 1/2，输出影响 Phase 3 所有后续步骤：

输入（来自 Phase 1/2）	输出（影响 Phase 3 后续步骤）
场景清单和复杂度	系统边界划分 → 时序图的参与方
非功能性需求（性能、安全）	技术选型约束 → API 设计决策
产品交互方式（Web/Mobile/API）	前端技术栈 → 原型实现方式
数据量和访问模式	数据库选型 → DB 设计
第三方服务依赖（支付、邮件等）	集成方式 → 时序图中的外部参与方

执行步骤

Step 1: 理解产品全貌

读取以下文档，建立对项目的整体认知：

需求文档（Phase 1）：产品定位、核心场景、约束与边界
产品设计文档（Phase 2）：信息架构、页面结构、交互复杂度
已有的 logos-project.yaml：当前 tech_stack 中是否已有初始选型

重点提取：

核心场景数量和复杂度
是否有实时性需求（WebSocket、SSE）
是否有后台任务（定时任务、消息队列）
第三方服务依赖清单
用户规模预期

Step 2: 确定系统架构

根据产品复杂度选择架构模式：

简单项目（个人 SaaS、工具类产品）：

单体架构 + 单数据库
架构概要可以用一段文字 + 一张简图

中等项目（团队 SaaS、多角色系统）：

前后端分离 + 单体后端 + 单数据库
可能需要对象存储、缓存等辅助服务

复杂项目（多服务、高并发、多端）：

微服务 / 模块化单体
需要详细的架构决策记录（ADR）

⚠️ Mermaid flowchart / graph 语法安全（强制）：

节点标签默认使用 ID["标签文本"]，尤其是标签包含 /、(、)、<、>、:、#、{}、[]、空格、中文、API 路径、端口、技术栈组合或 <br/> 时。
正确：PROXY["/voice/api 代理"]、API["API Server<br/>Node.js"]、DB["PostgreSQL :5432"]。
错误：PROXY[/voice/api 代理]，因为 [/ 会被 Mermaid 解析为平行四边形形状语法，标签内再出现 / 时容易导致解析失败。
多行标签使用 <br/>，整段文本仍放在同一对双引号内：API["HTTP API<br/>/voice/api"]。
子图名称含空格、中文或特殊字符时必须加引号：subgraph "Voice Service"。
只有明确需要 Mermaid 形状语义时才使用 ID[(Database)]、ID[/Input/] 等形状语法；普通说明文本不要借用形状语法。

用 Mermaid 绘制系统架构图：

graph TB
    subgraph "Frontend"
        Web["Web App - Next.js"]
    end
    subgraph "Backend"
        API["API Server - Node.js"]
        Worker["Background Worker"]
    end
    subgraph "Data"
        DB["PostgreSQL"]
        Cache["Redis"]
        S3["Object Storage"]
    end
    subgraph "External"
        Auth["Supabase Auth"]
        Email["SendGrid"]
    end

    Web -->|REST API| API
    API --> DB
    API --> Cache
    API --> S3
    API --> Auth
    Worker --> DB
    Worker --> Email

Step 3: 技术选型

为每个技术维度给出选型和理由：

| 维度 | 选型 | 理由 | 备选方案 |
|------|------|------|---------|
| 语言 | TypeScript | 前后端统一、类型安全 | Go（性能优先时） |
| 前端框架 | Next.js 15 | SSR + RSC、生态成熟 | Astro（内容站）、Nuxt（Vue 生态） |
| 后端框架 | Hono | 轻量、边缘优先、TS 原生 | Express（生态）、Fastify（性能） |
| 数据库 | PostgreSQL | 功能丰富、JSONB、RLS | MySQL（简单场景） |
| 认证 | Supabase Auth | 开箱即用、RLS 集成 | NextAuth（自托管） |
| 部署约束 | Vercel + Supabase | 零运维、自动扩容 | AWS（自主控制） |

注意：本步骤只定义部署约束和部署目标，不写完整发布步骤。完整部署方案必须由 deployment-designer 输出到 logos/resources/prd/3-technical-plan/3-deployment/。

选型原则：

优先选择团队已熟悉的技术
在无明显差异时，选择社区更大的方案
选型理由必须关联到具体的产品需求或约束

Step 4: 非功能性约束

明确关键的非功能性要求：

性能目标：核心 API 响应时间、页面加载时间
安全要求：认证方式、数据加密、CORS 策略
可扩展性：预期用户规模、数据增长估算
可观测性：日志、监控、告警方案
开发体验：本地开发环境、CI/CD 流程

Step 5: 外部依赖与测试策略

梳理项目的所有外部服务依赖，为每个依赖确定编排测试阶段的隔离策略。此步骤的产出直接影响 Phase 3 Step 3（编排测试）能否顺利执行。

从架构图和时序图参与方中识别外部依赖（邮件、短信、验证码、支付、OAuth 等）
与用户确认每个依赖的测试策略

可选的测试策略：

策略	说明	典型场景
`test-api`	测试环境提供后门 API	邮件/短信验证码
`fixed-value`	特定测试数据使用固定值	测试手机号固定验证码
`env-disable`	环境变量关闭该功能	图形验证码、滑块
`mock-callback`	编排中主动调用模拟回调	支付回调、Webhook
`mock-service`	本地 mock 服务替代	OAuth Provider

如果项目没有外部服务依赖（如纯 CLI 工具），可跳过此步骤。

Step 6: 更新 logos-project.yaml

将确认的技术选型写入 logos-project.yaml 的 tech_stack 字段，将外部依赖和测试策略写入 external_dependencies 字段，确保后续所有 Skill 和 AI 工具都能读取到统一的技术栈和测试约定。

external_dependencies:
  - name: "邮件服务"
    provider: "SendGrid"
    used_in: ["S01-用户注册", "S03-忘记密码"]
    test_strategy: "test-api"
    test_config: "GET /api/test/latest-email?to={email}"

同时根据技术选型填写 skip_phases，告知 phase 检测逻辑跳过本模块不需要的阶段：

项目类型	建议 skip_phases
标准 Web / API 项目	不填（全走）
有本地数据库、无 HTTP API（SQLite 桌面应用、Electron）	`[api, scenario]`
无数据库、无 HTTP API（CLI 工具、前端库、纯计算工具）	`[api, database, scenario]`
有 HTTP API、无数据库（无状态代理服务）	`[database]`

modules:
  - id: core
    name: 核心功能
    lifecycle: initial
    skip_phases: [api, scenario]   # 根据实际技术选型填写，无需跳过时删除此行

判断依据：

无 HTTP API → skip api 和 scenario（API 编排测试依赖 HTTP API）
无任何数据库 → skip database
有 SQLite / 本地数据库 → 保留 database（仍需设计 schema）

Step 7: 交接部署方案设计

架构设计完成后，必须向后续 deployment-designer Skill 交接以下信息：

技术栈：语言、框架、数据库、运行时、包管理器
部署目标：本地、测试、预发、生产中的哪些环境需要覆盖
运行依赖：数据库、缓存、对象存储、第三方服务、消息队列
配置与密钥来源：环境变量、密钥管理方式、不可提交配置
数据迁移方式：迁移工具、初始化数据、回滚要求
健康检查入口：页面、API、CLI 命令或进程检查方式
smoke 设计输入：部署后必须验证的最小核心链路

交接完成后，建议下一步提示：

继续进入 Phase 3 Step 3：使用 deployment-designer 输出部署方案和 smoke 测试方案。

输出规范

架构概要文档：logos/resources/prd/3-technical-plan/1-architecture/core-01-architecture-overview.md（架构文件全局唯一，后续修改始终在此文件上更新，不新建文件）
架构图使用 Mermaid 格式
技术选型使用表格格式，每项必须有理由
更新 logos-project.yaml 的 tech_stack 和 external_dependencies 字段
如项目确定无需部署，必须在架构文档中说明原因，并建议在 logos-project.yaml 中设置对应模块的 deployment_required: false
简单项目允许精简输出（不强制所有章节）

实践经验

不要过度设计：独立开发者做 SaaS，单体 + PostgreSQL + Vercel 够用就行，不要上来就微服务
选型理由比选型本身重要：写清楚"为什么选 X"比"选了 X"更有价值，因为项目演进时需要重新评估
架构图是时序图的前提：架构图中的系统组件就是后续时序图的参与方，两者必须一致
tech_stack 是 AI 的锚：后续 AI 生成代码时会读取 logos-project.yaml 的 tech_stack，选型不准确会导致生成的代码无法使用
非功能性约束宁可先宽后紧：初期不要定太严格的性能目标，随着实际数据再收紧
测试策略必须在架构阶段决定：验证码、支付等外部依赖的测试方案如果等到编排测试时才想，往往发现没有预留后门 API，导致编排测试无法全自动执行

⚠️ 收尾步骤（强制）：更新 resource_index

完成本 Skill 的所有文档产出后，必须：

将架构文档追加写入 logos/logos-project.yaml 的 resource_index：

resource_index:
  # ...已有条目...
  - path: logos/resources/prd/3-technical-plan/1-architecture/<文件名>.md
    desc: 系统架构概要。涉及技术栈选型、系统组件划分、非功能性约束时必读。

同步更新 logos/logos-project.yaml 的 tech_stack 和 external_dependencies 字段（这是本 Skill 的核心产出之一）。
（强制）梳理并预写入场景清单：

根据架构文档、需求文档和产品设计文档，整理出本项目的完整核心业务场景列表，向用户逐一确认后，将其写入 logos/logos-project.yaml 的 scenarios 字段：
```
scenarios:
  - id: S01
    name: <场景名称>
  - id: S02
    name: <场景名称>
  # ...
```
确认要点：
- 场景清单是否覆盖了所有核心用户旅程？
- 是否有遗漏的边界场景或管理后台场景？
- 场景编号是否按业务优先级排序？
此步骤产出的 scenarios 字段将作为 scenario-architect Skill 的输入基础，直接影响后续阶段的完成判断。若此步骤跳过，scenario-architect Skill 开始时将强制要求补填。

不执行收尾步骤将导致后续 AI 在场景建模和代码生成时无法读取架构决策，产生技术栈不一致的代码。

Authority Closure 与 Authority Registry

规范源

执行本节前完整读取 spec/authority-closure.md。本 Skill 只定义 architecture-designer 的 producer 职责，不复制 AC-01～AC-08；冲突时根规范优先。

强制步骤：共享事实盘点

在技术选型前，从需求/场景提取跨组件、进程或仓库共享的业务事实和完成谓词，并盘点 cache/index/marker/receipt/view 等投影及 owner/writer/recovery/cutover 变化。适用 fact 必须进入架构 Authority Registry。

每行填写 fact_id、semantic scope、authority owner、canonical state、sole writer、mutation entry、decision/read API、projection consumer、freshness proof、rebuild rule、recovery source、forbidden shadow sources 和 cutover exit。fact_id 以业务语义命名，不绑定文件或类。

Fail-closed

两个组件均可直接 write/decide：拆分 fact 或选择唯一 owner，不交付“共同权威”。
projection 无 freshness/rebuild：降为 advisory 或移除，不能参与业务决策。
旧 writer 无法关闭或切换无终点：保持未决，不进入部署设计。
不得用“最后写入胜出”“读取时择新”“双方最终一致”替代 Authority Closure。

交接 scenario-architect、deployment-designer、test-writer 和 code-reviewer 时只传 fact_id 引用与适用范围；项目 Registry 保持唯一实例源。

02 资源文件 1

03 SKILL.md 正文