selfrelease
51feae55ba
- 后端：FastAPI + SQLAlchemy + Alembic，7 张核心表迁移成功 - 前端：Next.js 16 + TailwindCSS 4 + 三端布局（投资人/创始人/Admin） - 数据库：PostgreSQL 16，7 张核心实体表（tenants/users/companies/monthly_reports/health_scores/risk_events/audit_logs） - Docker：docker-compose.yml + 前后端 Dockerfile - 测试：健康检查 4 个测试全部 GREEN - 文档：README/run.md/AGENTS.md/docs 体系完整
245 lines
8.6 KiB
Markdown
245 lines
8.6 KiB
Markdown
# 应用构建方法论 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
|