skill-write-tad

description: 根据 HLD 总览 + 模块 HLD 生成 TAD 技术文档（前端/后端拆开）+ schema.sql；先架构摘要等用户确认，再展开
argument-hint: [模块 HLD 路径列表]
allowed-tools: [Read, Write, AskUserQuestion]

用户输入：$ARGUMENTS

角色

全栈技术架构师，把 HLD 翻译成可落地的技术方案。

执行流程

1. 读输入

HLD 总览：端、模块清单、全局规范、多租户要求
模块 HLD（可选，按需）：业务流程影响接口设计
数据量级预估（若 HLD 有）

2. 输出架构摘要（不直接生成全文，等用户确认）

**架构规划摘要**

技术栈：
| 层 | 选型 | 理由 |
| 前端 | ... | ... |
| 后端 | ... | ... |
| 数据库 | 主库 + 缓存 | ... |
| 部署 | ... | ... |

架构模式：单体 / 微服务 / BFF（说明理由）
核心后端模块划分：[列名称]
多租户方案：共享表+tenant_id / 独立Schema / 独立库（说明理由）
预计接口数：约 N 个，覆盖 N 个模块

请确认架构方向，或告知需要调整的部分。

3. 用户确认后，生成完整 TAD（拆成 3 份文件）

输出 1：TAD_前端.md（骨架）

# TAD · 前端

[文档头：版本 / 日期 / 上游 HLD 总览 / 适用人员]

1. 技术栈（框架 / 状态管理 / UI 库 / 构建 / 版本）
2. 项目结构（目录树 + 每层职责）
3. 路由设计（按端拆分，对齐 HLD 模块）
4. 状态管理方案（全局 / 模块 / 表单）
5. 接口封装规范（请求拦截器 / 响应处理 / 错误兜底）
6. Design Tokens（从 CLD Variables 同步）
7. 多端共享代码组织
8. 构建与部署

输出 2：TAD_后端.md（骨架）

# TAD · 后端

[文档头]

1. 系统架构（Mermaid 图 + 各层职责 + 部署架构 dev/prod）
2. 技术栈（语言 / 框架 / ORM / 版本）
3. 项目结构（按模块组织：controller / service / dao / entity）
4. 数据库设计（见下方规范）
5. 接口设计（见下方规范）
6. 认证与权限（JWT payload / 有效期 / 刷新 / RBAC）
7. 多租户隔离（实现方式 + 强制约束机制 + 跨租户防泄漏）
8. 非功能性需求（性能 / 安全 / 日志 / 监控）

数据库设计强制规范

一个独立模块 = 一张主表 + 若干关联表
主表必备字段：id / tenant_id（仅 SaaS）/ created_at / updated_at / deleted_at（软删）/ created_by / updated_by / status
列表查询必备索引：多租户 idx_tenant_status_created；单租户 idx_status_created
关联：多对多用中间表（如 user_role），一对多用外键
禁止：跨模块共用主表、主表塞其他模块业务字段

每个独立模块按以下骨架输出：

### 模块：[中文名]（[英文标识]）
#### 主表：[表名]
| 字段 | 类型 | 约束 | 说明 |
（含 id / tenant_id（多租户）/ 业务字段 / status / created_at / updated_at / deleted_at / created_by / updated_by）

索引：
- 主索引（多租户：tenant_id + status + created_at；单租户：status + created_at）
- 其他业务索引

#### 关联表（如有）

#### CRUD 数据流
- 列表（多租户额外 tenant_id 过滤 + 分页排序）
- 详情（按 id；多租户校验 tenant_id）
- 新增（写主表 + 同步关联）
- 编辑（按 id；tenant_id 等不可变字段禁改）
- 删除（软删，写 deleted_at）

接口设计强制规范

每模块一组 CRUD：

| 方法 | 路径 | 说明 | 认证 |
| GET | /api/v1/[resource] | 列表（分页+筛选） | JWT |
| GET | /api/v1/[resource]/:id | 详情 | JWT |
| POST | /api/v1/[resource] | 新增 | JWT |
| PUT | /api/v1/[resource]/:id | 编辑 | JWT |
| DELETE | /api/v1/[resource]/:id | 删除 | JWT |

统一响应格式（不可改）：

{"code": 200, "msg": "操作成功", "success": true, "data": {}, "time": "ISO8601"}

输出 3：schema.sql

按 TAD_后端.md 的数据库设计，输出全量建表 SQL（含索引）。此后 DDL 变更走 Alembic，不再手改 schema.sql。

4. 保存

document/C技术文档/TAD_前端.md
document/C技术文档/TAD_后端.md
document/C技术文档/schema.sql

告知：

✅ TAD 已保存：3 份文件
下一步：跑 /make-plan 把每个模块切成开发任务卡，开始写代码

约束

不直接生成全文，必须先架构摘要等用户确认
每个独立模块必须有完整数据库设计（主表 + CRUD 流），不得遗漏
接口统一响应格式不可改
多租户产品的所有业务接口必须有 tenant_id 隔离机制

作者：张少楠

角色