# 应用构建方法论 v3.0（融合 Superpowers）

> 基于 v2.5 + [obra/superpowers](https://github.com/obra/superpowers) 流程纪律，针对 AIPortPilot 项目优化。
> 核心理念：**结构化 > 自由发挥 / 快照 > 覆盖 / 演进 > 重写 / 先想再写 / 先测再码**

---

## 一、七步开发流程（强制执行）

每一步都是**必须执行的工作流**，不是建议。Agent 在任何任务前先检查当前处于哪一步。

### Step 1：Brainstorming（头脑风暴）

**触发**：用户提出新功能/新模块需求时
**动作**：
- 不急着写代码，先苏格拉底式提问
- 探索替代方案，权衡取舍
- 分段展示设计，每段短到用户能读完就消化
- 产出：`docs/1-prd.md`（产品设计文档）
**完成标志**：用户对 PRD 签字确认

### Step 2：Design Document（设计文档）

**触发**：PRD 签字后
**动作**：
- 技术架构设计（技术栈、数据模型、API 设计、UI/UX 方案）
- 产出：`docs/1-prd.md` 中的技术设计章节
**完成标志**：用户对技术方案签字确认

### Step 3：Writing Plans（任务拆解）

**触发**：设计批准后
**动作**：
- 将工作拆成 **2-5 分钟** 的小任务
- 每个任务有：精确文件路径、完整代码描述、验证步骤
- 任务之间无循环依赖，可并行标注
- 产出：`docs/2-task.md`（任务清单）
**完成标志**：用户对任务清单签字确认

### Step 4：Feature Branch（特性分支）

**触发**：任务清单批准后
**动作**：
- `git checkout -b feature/{module-name}`
- 确保干净测试基线
**完成标志**：分支创建成功

### Step 5：TDD Implementation（测试驱动实现）

**触发**：分支创建后
**动作**：
- **RED**：先写失败测试，运行确认失败
- **GREEN**：写最小代码让测试通过
- **REFACTOR**：重构，保持测试绿色
- **COMMIT**：每个 RED-GREEN 循环提交一次
- **禁止**：先写代码后补测试
**完成标志**：所有任务测试通过

### Step 6：Code Review（代码审查）

**触发**：每个任务完成后
**动作**：
- 对照计划检查规格符合度
- 检查代码质量（命名、结构、安全、性能）
- 严重问题阻断进度，必须修复后继续
**完成标志**：审查通过

### Step 7：Finishing Branch（收尾合并）

**触发**：所有任务完成且审查通过
**动作**：
- 运行全量测试
- 提供选项：合并到 master / 创建 PR / 保留分支 / 丢弃
- 合并后清理分支
**完成标志**：代码进入 master

---

## 二、三原则

1. **结构化 > 自由发挥**：先文档后代码，先设计后实现
2. **快照 > 覆盖**：用 `*_snapshot` JSON 保存历史，不删旧数据
3. **演进 > 重写**：版本号 + `is_current` 指针，增量演进

---

## 三、文档骨架（必有）

| 文件 | 内容 | 何时写 |
|---|---|---|
| `README.md` | 项目介绍、技术栈、快速启动 | Step 2 |
| `run.md` | 10 板块运维手册 | Step 2 |
| `AGENTS.md` | Agent 协作规则 | Step 2 |
| `docs/0-req.md` | 需求文档（从方案文档提炼） | Step 1 |
| `docs/1-prd.md` | PRD + 技术设计 | Step 1-2 |
| `docs/2-task.md` | 任务清单（2-5 min 粒度） | Step 3 |
| `docs/daily/` | 日报 | 每日 |

### run.md 十板块

技术栈 / 首次准备 / 基础设施启停 / 应用启停 / DB 命令 / 排错 / 端口表 / env / 部署备份 / FAQ

### 铁律

- 命令可复制粘贴
- 标注 `[Docker]` / `[Native]`
- 危险操作标红
- 版本号写死
- 过时即同步

---

## 四、数据 8 铁律

1. 快照隔离历史（`*_snapshot` JSON）
2. 版本号 + `is_current` 唯一指针，不删旧
3. 内部状态机与用户可见状态分离
4. 租户隔离走 `session.tenant_id`，不信任请求体
5. 配置粒度对齐"谁应该决定"（全局/租户/用户）
6. 字段演进：nullable + 默认值；枚举用字符串；时间戳 `*_at`
7. 审计字段：`created_by/updated_by/deleted_by + *_at`；关键操作落 `audit_logs` ≥ 6 月
8. UTC 存储；金额用 decimal/整数；禁止 float

---

## 五、安全与权限

- 密钥进 KMS/Vault，**绝不进 Git**，仅 commit `.env.example`
- 后端必须独立校验权限，前端隐藏 ≠ 后端放权
- PII 全链路脱敏（手机/身份证/邮箱），日志中用 `138****1234`
- 注入防御：SQL 参数化 / 命令 `shell=False` / XSS 自动转义 + CSP / CSRF 走 SameSite
- 限流熔断：登录 5次/min/IP，写接口按用户限流，429 带 `Retry-After`
- JWT 短 TTL（≤2h）+ refresh；Cookie 必 HttpOnly+Secure+SameSite
- **本项目特殊**：投后数据高度敏感，优先私有化部署，数据不出域

---

## 六、API 设计

- REST 资源命名（名词复数 + 层级），版本进 URL 不进 query
- HTTP 状态码语义化，禁全 200 塞 error
- 统一响应壳：`{code, message, data, trace_id, timestamp}`
- 分页 `?page&page_size&sort&filter[k]=v`，大数据集用 keyset 游标
- 写接口接受 `Idempotency-Key`，订单/支付**必须**
- `trace_id` 全链路（网关→后端→DB→前端 `X-Trace-Id`）
- OpenAPI 自动生成进 Git，废弃接口 `Deprecation` + `Sunset`

---

## 七、AI / 智能集成

- 接口抽象，业务面对自家"智能服务接口"
- 多源容灾 + 兜底降级（规则/缓存/默认），不拖垮主流程
- 强制 Structured Output / JSON Schema，禁编造
- 决策证据化：输出 `score / confidence / evidence / concerns / fallback_used`
- Prompt 进 Git，不只在 DB；可 diff、可回滚
- 单次/用户/租户分级成本预算；缓存优先；慢路径异步化
- 用户输入与系统 prompt **分离 role**，加分隔符 `<<<USER_INPUT>>>`，防注入
- LLM 输出代码绝不直接 exec/eval，必经语法检查 + 沙箱
- PII 进 LLM 前脱敏，响应再回填
- `confidence < 0.6` 显式提示人工核对

---

## 八、客户端 + 多端 UIUX

### 三端角色化

- **投资人端（B 端专业）**：主色 `gray-900`，左 Sidebar（`w-52 sticky`）+ 内容 `bg-[#f8f9fb]`，信息密集
- **创始人端（C 端温暖）**：主色 `indigo-600`，顶部 sticky Header（`h-14 bg-white/95 backdrop-blur`），渐变背景
- **Admin 端（警示）**：Header `bg-slate-950` + 主色 `amber-400`，内容 `bg-slate-100`，必带 ADMIN 徽章

### 共享 Token

- Geist 字体 / oklch 色彩 / `--radius: 0.625rem`，**禁硬编码 hex**
- shadcn + @base-ui + lucide + sonner + recharts，**禁多 UI 库混用**

### Layout 统一

- 容器 `container mx-auto max-w-7xl px-4`，Header 全应用 `h-14`

### 交互统一

- `<LoadingSpinner>` / `<EmptyState>` / sonner toast / `<Dialog>` 二次确认
- 状态色三件套：`emerald(success) / amber(warning) / rose(destructive)`

### 响应式

- sm/md/lg/xl/2xl 五断点
- Sidebar < md 折叠为抽屉/下拉，不丢功能入口

### a11y

- 键盘可达 / 对比度 ≥ 4.5:1 / 语义化标签 / aria-label，**禁 `<div onClick>`**

### 其他

- i18n：文案进 JSON，用 `Intl.*` 格式化
- 报告页强制 `@media print`
- 流式输出 RAF 批量刷新，禁每 token 触发 React 重渲染
- **禁 `alert()/confirm()`、禁多 UI 库、禁硬编码主色 hex、禁三端共用 Header**

---

## 九、五防一兜底

1. 防异步穿越（AbortController / 引用保存）
2. 防外部单点（超时+重试+熔断+多源）
3. 防资源缺失（启动校验字体/翻译/配置）
4. 防 API 弃用（季度内替换 + 灰度升级）
5. 防数据丢失（事务 / 幂等键 / 持久化队列 / beforeunload）
6. 一兜底：最差体验是"功能受限可用"，不是白屏

---

## 十、部署运维

- 部署脚本"只清自己"，禁 `pm2 delete all`、禁 `redis-cli FLUSHALL`、禁 `rm -rf /`
- 跨子域 cookie 名独立 + `domain=.example.com`
- DB migrate 走 CI/CD 自动应用
- 备份：每天 2 次 + 滚动 7 天 + 双副本（本机 + 异地）+ 每月恢复演练
- 监控 4 金指标：Latency / Traffic / Errors / Saturation
- 灰度 1% → 10% → 50% → 100%，每档观察 ≥ 30 分钟
- 回滚 SOP 必备，回滚比修复快

---

## 十一、测试纪律

- **70/20/10**：单元/集成/E2E
- **TDD 强制**：RED-GREEN-REFACTOR，先写失败测试再写代码
- 关键路径必覆盖（登录/支付/导出/权限/AI 主流程）
- 集成测试用 testcontainers 跑真实 DB，禁 mock DB
- 修 bug 必先写复现测试，禁删测试、禁 `@skip/it.only` 进 PR

---

## 十二、协作纪律

- 每步完成后更新 `docs/2-task.md` 状态
- 日报写 `docs/daily/YYYY-MM-DD.md`
- 重大决策记 `docs/decisions/`（ADR 格式）
- 代码审查问题按严重度分级：Critical（阻断）/ Major（必须修）/ Minor（建议）
- 提交信息格式：`type(scope): description`，type ∈ feat/fix/refactor/test/docs/chore