技术设计：<产品名>¶

版本：v0.1 日期：作者：<架构师 / Agent> 状态：draft / review / frozen 关联：spec.md、user-story.csv、feature-implementation.md、openapi.yaml、schema.sql

1. 背景与目标¶

1.1 背景¶

<简述业务目标和约束。>

1.2 设计目标¶

支撑 P0/P1 用户故事；
3 周内上线；
可并行开发；
可回滚；
可观测。

1.3 非目标¶

<不在本期范围的技术能力>

2. 架构总览¶

┌─────────────────────────────────────────────┐
│  Browser (Vue SPA)                          │
└───────────────────┬─────────────────────────┘
                    │ HTTPS
                    ▼
┌─────────────────────────────────────────────┐
│  CDN / Static Hosting                       │
└───────────────────┬─────────────────────────┘
                    │ /api/v1/*
                    ▼
┌─────────────────────────────────────────────┐
│  API Gateway / Load Balancer                │
└───────────────────┬─────────────────────────┘
                    ▼
┌─────────────────────────────────────────────┐
│  API Service (Go)                           │
│  Router → Middleware → Handler → Usecase    │
│           → Repository                      │
└───────────┬─────────────────────┬───────────┘
            ▼                     ▼
┌───────────────────────┐  ┌──────────────────┐
│ PostgreSQL            │  │ Redis (optional) │
└───────────────────────┘  └──────────────────┘

2.1 组件与职责¶

组件	职责	不负责
前端 SPA	页面、交互、状态、前端校验	权限最终判断
API 服务	业务逻辑、鉴权、校验、审计	静态资源托管
PostgreSQL	持久化、约束、事务	业务规则（尽量用约束兜底）
Redis	会话、幂等、限流、缓存	唯一数据源
对象存储	附件/导出	公开可写
监控	日志、指标、告警	业务逻辑

3. 关键数据流¶

3.1 <核心流程，例如：创建任务>¶

1. 用户在页面提交
2. 前端校验
3. POST /api/v1/tasks + Idempotency-Key
4. Middleware: RequestID → Auth → RateLimit
5. Handler: 解析 + 校验
6. Usecase:
   a. 校验项目/成员/负责人
   b. 开启事务
   c. 插入任务
   d. 写审计
   e. 写 outbox
   f. 提交
7. 返回 201
8. 前端乐观更新

3.2 异步流程¶

outbox → worker → 发送通知 / 调用第三方

要求：

幂等；
重试上限；
死信队列；
可观测。

4. API 设计规范¶

4.1 基础¶

Base path：/api/v1
资源复数：/projects, /tasks
版本：路径版本
认证：Bearer token / httpOnly cookie
时间：ISO 8601 UTC
分页：page, page_size（默认 20，最大 100）
排序：sort=-due_date
幂等：Idempotency-Key

4.2 响应格式¶

成功：

{ "data": { ... } }

列表：

{
  "data": [...],
  "pagination": { "page": 1, "page_size": 20, "total": 137, "total_pages": 7 }
}

错误：

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "标题不能为空",
    "request_id": "01J...",
    "details": { "field": "title" }
  }
}

4.3 错误码¶

错误码	HTTP	含义
VALIDATION_ERROR	400	参数校验失败
UNAUTHORIZED	401	未认证
FORBIDDEN	403	无权限
NOT_FOUND	404	资源不存在
CONFLICT	409	冲突
RATE_LIMITED	429	限流
INTERNAL_ERROR	500	内部错误
SERVICE_UNAVAILABLE	503	依赖不可用

4.4 OpenAPI¶

文件：docs/01-design/api/openapi.yaml
规范：OpenAPI 3.1
所有 operation 有 operationId
所有响应有 schema
通过 redocly/spectral lint

5. 数据库设计¶

5.1 实体¶

表	说明	关键字段
users	用户	id, email, password_hash, status
projects	项目	id, tenant_id, name, status
project_members	项目成员	project_id, user_id, role
tasks	任务	id, project_id, title, status, version
audit_logs	审计	id, tenant_id, actor_id, action, request_id

5.2 约束与索引¶

主键：UUID；
外键：显式声明；
唯一约束：users.email、projects(tenant_id, short_code)；
软删除：deleted_at；
审计：只追加；
索引：高频查询组合 + 部分索引。

5.3 迁移¶

migrations/
├── 00001_init.sql
├── 00002_add_projects.sql
└── 00003_add_tasks.sql

规则：

已上线迁移不可修改；
生产迁移前备份；
expand-contract；
大表用 CONCURRENTLY / 分批；
回滚脚本单独准备。

6. 鉴权与权限¶

6.1 认证¶

access token 15 分钟；
refresh token 7 天，可撤销；
或 httpOnly cookie + CSRF；
不在 localStorage 存长期令牌。

6.2 授权¶

租户级隔离；
项目级角色（admin/member/viewer）；
对象级校验；
后端必须校验，前端隐藏只是体验。

6.3 权限矩阵¶

操作	admin	member	viewer
查看项目	✅	✅	✅
创建任务	✅	✅	❌
编辑任务	✅	✅	❌
删除任务	✅	❌	❌
管理成员	✅	❌	❌

7. 错误处理¶

统一 AppError；
Handler 集中映射 HTTP 状态码；
错误响应不泄露堆栈/SQL；
所有错误带 request_id；
日志记录内部细节，响应只给安全信息。

8. 并发与请求隔离¶

8.1 规则¶

禁止包级可变状态；
依赖启动时注入，运行期只读；
每请求独立 context.Context + 超时；
用户/租户从 context 取；
每写请求一个事务；
连接池有上限；
幂等 key；
panic recover；
优雅关闭；
缓存 key 带租户维度。

8.2 事务边界¶

创建任务：
  校验 → [插入任务 + 审计 + outbox] → 提交
  通知在事务外

8.3 并发控制¶

更新任务用乐观锁 version；
唯一约束兜底重复创建；
幂等表/Redis 防重复提交。

9. 性能与容量¶

指标	目标
API P95	< 500ms
页面首屏	< 2s
并发	50-100
数据量	1 万任务/年
可用性	≥ 99.5%

优化顺序：

正确的索引；
避免 N+1；
分页；
缓存（可选）；
异步化。

10. 安全与隐私¶

11. 可观测性¶

11.1 日志¶

{
  "time": "...",
  "level": "INFO",
  "msg": "task created",
  "request_id": "...",
  "user_id": "...",
  "tenant_id": "...",
  "duration_ms": 12
}

11.2 指标¶

http_requests_total{method,path,status}
http_request_duration_seconds
db_pool_connections
业务指标

11.3 健康检查¶

/healthz：进程存活
/readyz：依赖就绪

12. 部署拓扑¶

环境	用途	数据库	访问
local	开发	Docker	开发者
dev	联调	独立	团队
staging	预发	独立	团队
prod	生产	独立	受限

前端：S3 + CloudFront；
后端：ECS Fargate；
数据库：RDS PostgreSQL；
密钥：Secrets Manager；
CI/CD：GitHub Actions；
回滚：镜像/任务定义版本。

13. 测试策略¶

类型	范围	工具	门禁
单元	domain/usecase	go test	覆盖率
集成	repo + DB	testcontainers	全绿
API	handler	httptest	全绿
契约	OpenAPI	lint + schema	全绿
E2E	用户流程	Chrome MCP	全绿 + 截图

14. 风险与缓解¶

风险	概率	影响	缓解
<...>	中	高	<...>

15. 里程碑与并行计划¶

M1 契约冻结
  ↓
第 1 批：US-001, US-002
  ↓
第 2 批：US-003, US-004
  ↓
第 3 批：US-005 + 联调
  ↓
E2E → 部署 → 线上验证

文件所有权见 file-ownership.md。

16. 未决问题¶

编号	问题	负责人	截止	状态
Q-001	<...>	<...>	<...>	open

17. 变更记录¶

版本	日期	变更	作者
v0.1	<...>	初稿	<...>