# miko-backend

**Repository Path**: oldauntu/miko-backend

## Basic Information

- **Project Name**: miko-backend
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-01
- **Last Updated**: 2026-10-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# miko-admin · 后端

> **把成熟后台系统里被反复验证过的治理范式，在「安全默认更严、资源占用更低」的前提下，用 Rust 重写一遍。**

![Rust](https://img.shields.io/badge/Rust-1.88%2B-orange)
![Axum](https://img.shields.io/badge/Axum-0.8-blue)
![SeaORM](https://img.shields.io/badge/SeaORM-2.0-blue)
![Tests](https://img.shields.io/badge/tests-1127%20passed-brightgreen)
![OpenAPI](https://img.shields.io/badge/OpenAPI-228%20operations-blueviolet)
![Clippy](https://img.shields.io/badge/clippy-D%20warnings%200-brightgreen)

前端仓库：[**miko-frontend**](https://gitee.com/oldauntu/miko-frontend) · 开发手册：[`docs/`](./docs/README.md) ·
进度与工程决策：[`docs/20-开发任务清单.md`](./docs/20-开发任务清单.md)

---

## 1. 这是什么

一套**可以直接拿去做生产内部系统的 Rust 后台管理框架**。

一个企业后台里"必须要有"的东西——RBAC 权限治理、数据权限、账号安全、审计追溯、
文件管理、定时任务、工作流、代码生成——在这里被逐项重新实现了一遍，而且在**安全默认值上比常见做法更严**。

它不是把别的生态的后台框架照搬过来，而是**按 Rust 的模块语义重新组织分层**：纯规则做成零 IO 的能力层
（可以单测到全覆盖），IO 与编排单独一层，装配收在 `miko-boot`。

| | |
|---|---|
| 语言 / 运行时 | Rust（edition 2024），Tokio，**无 JVM / 无 GC** |
| Web | Axum 0.8 + Tower + utoipa（OpenAPI 3.1） |
| 持久层 | SeaORM 2.0 + SeaORM Migration（35 个迁移） |
| 规模 | 20 个 crate · 273 个 `.rs` · 约 9.8 万行 Rust |
| 接口 | 190 条路径 / 228 个操作 / 135 个 schema / 24 个业务域 |
| 测试 | **1127 个用例 / 51 个套件全绿**；`clippy --workspace --all-targets -D warnings` 零告警 |
| 文档 | 20 篇开发手册 + **160 条工程决策记录（D1–D167）** |

> **非目标**（避免误解）：不追求功能广度上的军备竞赛；不做产品化 / 计费 / SaaS 运营；不承担具体业务定制。
> 一期只做框架本身与示例 Demo。

---

## 2. 相较其他框架，优势在哪

### 2.1 安全默认更严——而且是"控制失效时拒绝服务"的那种严

后台框架的普遍现状是：**HTTPS 到网关就算安全做完了**，应用层剩下的交给"别写错"。
本项目在应用层又补了一整套，并且在每个安全控制的失败分支上都选了**吵闹地停**，而不是**安静地放**。

| 能力 | 常见做法 | 本项目 | 关键差别 |
|---|---|---|---|
| 接口传输加密 | TLS 到网关即止 | 应用层信封：RSA-2048 OAEP + AES-256-GCM，AAD 绑 nonce | 时间窗**双向**校验（只查"太旧"= 录下的报文可无限重放）；nonce `SET NX` **失败即拒绝**（缓存挂了无法证明"第一次见"，放行等于防重放在最需要它的时刻静默失效） |
| 字段加密 | 能加解密就行 | 密文 + **HMAC 检索摘要成对产出**，写入只有一个入口 | 检索不解密（走摘要列）；摘要输入带列名做域分离；KEK/DEK 信封，**在线轮换 + 分批重加密且不动摘要列** |
| 数据脱敏 | 按请求属性判断 | `(viewer, owner)` **二元判据** + task-local | 上下文缺失 = **全脱敏**（多看几个星号是安全侧错误，明文是泄漏侧错误）；同部门只放开姓名 |
| 敏感操作二验 | 弹窗 + 再输一次密码 | 票据 **HMAC 绑定参数摘要** | 把"删除用户 A"的票拿去删 B → 403（不是 422：能拿到别人票据还能改参数，这本身就是要审计的攻击行为）；消费用条件 UPDATE 原子落定，并发重放只有一个成功 |
| 黑名单拦截 | 挂在鉴权之内 | 中间件挂在**鉴权之外** | 爆破流量本来就没有令牌，挂鉴权之内根本拦不到；被拦请求不写审计表（否则爆破流量能写满 `log_operate`） |
| 口令 | bcrypt / MD5 加盐 | **Argon2id** + 历史防重 + 弱口令字典 | 历史防重靠 PHC 串自带参数逐条 verify，不建彩虹表；**账号不存在时也跑一次哑散列**保持恒定耗时（防账号枚举） |
| 登录锁定 | 全局计数 | 三维度 principal + 三档梯度，缓存快速层 + DB 兜底 | 只有**凭据错**才计数（停用 / 客户端停用与爆破无关）；拿不到真实 IP 时**只锁账号维度**——退化成占位 IP 会让一个人输错把全部直连用户锁死 |

### 2.2 编译器当门禁，而不是靠 code review

这是 Rust 在这类系统上最被低估的收益。项目里有几处刻意设计，让"忘了一件事"变成**编译不过**：

```rust
// 敏感列的密文与摘要必须成对产出：写入路径把 vault 设成必填参数
// → 「改了 phone 忘了改 phone_hash」在编译期就不可能，而不是靠 review 发现
repo::insert_user(db, new_user, vault).await?;

// 数据权限靠函数签名强制传作用域：漏加条件 = 编译不过
// → 而不是"某个 handler 忘了注入 WHERE 就静默越权"
repo::list_users(db, &scope, req).await?;
```

另外两处结构性收益：

- **能力层刻意不依赖 `miko-core`**（如 `miko-excel` 的错误只在 `ie::to_app_error` 一处映射成 `AppError`）——
  纯规则层没有 IO、没有框架，可以单独拿出来给别的项目用，也保证单测覆盖能真正做到全量。
- **零反射**：定时任务的 `invoke_target`、代码生成器的目标都是显式注册表，且**没注册的 key 在创建时就拒绝**——
  不会出现"任务建好了、界面一切正常、但永远跑不起来"。

### 2.3 没有 JVM：单二进制、秒级冷启动、低内存

| 指标 | 本项目 | 典型 JVM 后台 |
|---|---|---|
| 部署产物 | 单个二进制，无运行时依赖 | 需要 JRE + 一堆 jar，或打胖包 |
| 冷启动 | M0 实测 **360 ms** 到 `/readyz` 可服务（目标 < 1.5 s） | 常见 10 s 以上（容器启动 + 上下文扫描 + 连接池预热） |
| 常驻内存 | 目标 **RSS < 200 MB** | 常见 300–500 MB 起步 |
| 延迟抖动 | 无 GC 停顿 | 受 GC 影响，P99 抖动大 |
| 依赖合规 | `cargo deny` + `cargo audit`，依赖树可静态审计；无反射、无运行时代理、无 XML | 传递依赖复杂，漏洞面大 |

### 2.4 160 条工程决策记录——这才是最难复制的部分

[`docs/20-开发任务清单.md`](./docs/20-开发任务清单.md) 里有 **160 条 D 编号决策**，每条写清「**现象 → 根因 → 取舍**」。
它们绝大多数**不是设计出来的，是跑出来的**——只有连上真库、真 Redis、真浏览器才会暴露：

- **雪花 ID 的 JS 精度坑**：`i64` ID 以 JSON 数字出网，浏览器读成 `Number`，`...149504` 变成 `...149500`，
  后续"删除 / 编辑"带着错 ID 回后端就是 404 或误改。修法：**ID 出网一律字符串**。
- **授权聚合漏过滤绑定表的 `del_flag`**：角色授权改一次 = 软删旧绑定 + 插新绑定，而聚合只过滤了菜单自身的
  `del_flag` → **"取消授权等于没取消"**，把菜单授权清空后重新登录照样拿到权限串。
- **软删行也占唯一索引**：唯一键建在业务键上，软删行 `del_flag=1` 依旧命中 → "删除后再建同名"这个运维天天做的
  动作被翻译成 500（duplicate key），表象与真因毫无关系。修法：**复活原行**。这个坑在本项目里**独立出现过三次**。
- **投影写入必须容忍乱序**：消息入队后可能**立刻**被消费完，结果投影先于登记落库，登记随后把状态刷回
  `pending` —— 任务永远停在"待处理"。约三分之一概率复现。
- **观测系统必须排除观测自身**：慢 SQL 落库本身也可能慢，被采集器自己采到就是**正反馈**——几秒写满表且
  全是自己的 INSERT。

对后来者来说，这份记录比代码本身更稀缺。

### 2.5 验证标准是"硬证据"，不是"接口返回 200"

端到端验证的口径写死在项目里：**能看磁盘字节就不看返回值，能连库核行数就不看列表长度**。

- 加密存储：**grep 磁盘文件**确认不含明文、密文长度 > 明文、下载回来逐字节比对等于原文；
- 导入导出：**磁盘字节数 == 库里的 `file_size`**，xlsx 共享字符串里真有表头；
- 跨库 Saga：直连**两个真实数据库**核对行数，补偿干净时主库账本必须为空；
- 幂等重投：投两次，**行数不翻倍**；
- 权限：直接摘掉 `sys_role_menu` 绑定（`del_flag=1`）看是否 403，恢复看是否 200；
- 传输加密：测篡改 / 伪造 / 张冠李戴（A 的票传 B 的 key）三种攻击全部被拒。

再加上 `scripts/check-docs.py` 把**文档一致性**也做成了门禁（表名字段名 / 内链 / 章节引用 / crate 依赖白名单）。

---

## 3. 已实现的功能

### 3.1 权限域（M1，13 项）

- **六类资源完整 CRUD**：用户 / 部门 / 岗位 / 角色 / 菜单 / 客户端，含软删联动、启停、踢下线
- **RBAC 鉴权中间件**：`auth_middleware` + `require_permission` + `CurrentUser` 提取器，支持 `*` 通配
- **数据权限引擎**（`miko-datascope`）：五档基础 + 1 档扩展，并集合并；靠函数签名强制注入，JOIN / COUNT 不漏条件
- **动态路由下发**：`GET /auth/routes` 下发菜单树（`M`/`C`）；按钮级权限点走登录态 `permissions`，不混进路由树
- **JWT 会话**：多端登录、动态 Token 时效（`sliding` / `absolute`）、按 `client_key` 隔离踢人；会话层毫秒、对外秒

### 3.2 账号安全（M2，11 项全部收口）

密码策略引擎（多策略 **`merge_all` 更严格者胜出**）· 登录失败锁定 · 敏感操作二验 ·
**TOTP MFA + 备份码** · 个人中心（改密 / 找回 / 换绑双阶段）· **字段加解密 + HMAC 检索列** ·
**数据脱敏** · **接口传输加密** · **密钥管理（KEK/DEK 轮换 + 重加密）** ·
操作日志 / 登录日志 / 在线用户三件套

### 3.3 框架能力（M3，10 项全部收口）

| 模块 | crate | 说明 |
|---|---|---|
| 多数据源 | `miko-datasource` | 路由三级决策（上下文 > 注解 > 方法名约定 > 主库）、读写分离、事务传播四档、`MasterOnlyGuard` 进事务即钉主库 |
| 动态数据源 | `miko-datasource` | 热增删；**连续 3 次失败才降级**（一次成功即恢复）；配置指纹没变不重建连接池；**连接串永不回显** |
| Saga 编排 | `miko-datasource` | 不引 XA；失败**严格逆序**补偿；只有 503 / 超时才重试；`compensated`（可安全重投）与 `failed`（有残留需人工）**分开** |
| 对象存储 | `miko-storage` | 本地 / 内存 / S3（**手写 SigV4，不引 SDK**）；预签名直传、代理上传、**应用层流式加密**、上传票据（HMAC + 一次性 + AAD 绑 object_key） |
| 异步队列 | `miko-mq` | 内存与 Redis Stream 双形态同语义；DLQ、延迟任务、崩溃回收；**重试次数记在任务身上**（按 `msg_id` 记会永远归零） |
| 定时任务 | `miko-job` | **自研 cron 解析**（分钟级五段、闰年月末、`?`）；嵌入式执行器 + 心跳；misfire 策略；选主端口（RAII 释放） |
| 字典 / 参数 / 公告 | `miko-system` | 参数里的密钥走字段保险箱加密、列表只回 `***`；公告富文本用**零依赖自研白名单净化**（覆盖实体编码绕过） |
| 导入导出 | `miko-excel` | xlsx 流式写 + **20 万行自动分 sheet**；CSV 带 BOM；**按魔数判文件类型**（不看扩展名）；五道校验 + 错误行明细；导出复用指纹含格式 |
| 接口文档 | `miko-web` | utoipa 全量注解 + Scalar UI；`cargo run --bin gen-openapi` 产快照，CI `--check` 比对防漂移 |
| 可观测性 | `miko-monitor` | 服务指标（sysinfo + 节点心跳）、缓存监控（命令埋点包装层）、**慢 SQL 采样**（自噬防护 + 指纹聚合 + 降采样）、SSE 日志流 |

### 3.4 研发提效与扩展（M4，T1–T8 收口）

- **工作流引擎**（`miko-flow`）：DSL 图校验（一次报全部问题）、会签 / 或签（全整数运算）、
  转办 / 委派 / 加签 / 退回 / 撤回 / 跳转 / 终止 / 催办 / 抄送、乐观锁防双提交
- **流程设计器**（前端自研 DOM + SVG 画布，**不引 `@vue-flow/core`**）：画布模型就是 DSL，
  `toDsl()` 直出后端能吃的 JSON；**前端校验与后端同判据**（14 张故意画坏的图同时喂给两边，逐一比对错误码集合）
- **消息中心 + WebSocket 网关**（`miko-message`）：本节点直投 + Redis Pub/Sub 跨节点路由；
  ticket 60 秒取出即失效；未读数**只覆盖不累加**
- **代码生成器**（`miko-gen`）：元数据 UI + 11 套 Askama 模板 + 三种写策略（覆盖 / 标记块内改 / 只建一次）+
  **生成后自动 `cargo check` / `vue-tsc`，不通过才回滚**；显式报"假绿灯"（没进编译图 = 根本没编过）
- **多租户字段预留**（`miko-tenant`）：`inject_tenant` 绑定参数注入 + 写入侧 `stamp`；
  **负控探针**（没注入的必须被判漏）+ 覆盖扫描报表
- **黑名单**（`miko-security`）：IP / 客户端 / UA 维度、CIDR 集合、两级缓存
  （本地快照 + 共享版本号，**正确性不依赖轮询**）、登录锁定命中 IP 维度时自动拉黑

### 3.5 前端（[独立仓库](https://gitee.com/oldauntu/miko-frontend)）

Vue3 + TypeScript + Ant Design Vue + Vite + Pinia，**40 个 `.vue`**（39 个页面 + 自研流程设计器）覆盖上述全部模块；
动态路由、按钮级权限指令、传输加密拦截器、脱敏展示（**掩码绝不回填编辑框**）。

---

## 4. 架构

### 4.1 分层：四层 + 端口适配器

刻意**不照搬 Java 的 Controller / Service / Mapper**，而是按 Rust 的模块语义重新组织：

```
L1 接入层    Axum Router · Handler · Extractor · OpenAPI     参数绑定、调用用例、序列化
L2 应用层    用例编排、事务边界、跨聚合协调、领域事件            一个 UseCase = 一个完整业务动作
L3 领域层    实体 / 值对象 / 领域规则（纯 Rust，无 IO）         业务不变量，可单测，不依赖框架
L4 基础设施  SeaORM 仓储 · Redis · S3 · MQ · HTTP 客户端       通过 trait（端口）向上提供能力
```

依赖方向只能向下；第三方库**不允许**直接出现在领域层，必须包一层 trait。

### 4.2 请求全链路（中间件洋葱）

```
MW1  Trace(trace_id) → MW2 RequestId / 访问日志 → MW3 Timeout / Concurrency / BodyLimit
  → MW4  CORS + Security Headers
  → MW5  TransportCrypto    解信封、验时间窗与 nonce 防重放
  → MW6  黑名单拦截          挂在鉴权之外（爆破流量本来就没有令牌）
  → MW7  Auth               验令牌 → 构造 LoginUser → 注入 Extension
  → MW8  Authorization      RBAC 权限点比对
  → MW9  租户 / 脱敏         绑定 task-local 上下文
  → MW10 Audit              操作日志（挂在鉴权之内，才能归属到人）
  → MW11 DataScope          按角色推导可见部门集合
  → Handler → UseCase → Repository(SeaORM)
  → 脱敏序列化 → 响应加密（可选）→ ApiResult<T>
```

顺序不是随便排的，几条硬约束：Trace 必须最早（后面所有日志都要挂 trace_id）；
**传输加密必须早于鉴权**（签名 / nonce 可能在加密 body 里）；**审计必须晚于鉴权**（否则归属不到人，
代价是被鉴权短路的请求不进操作日志——失去归属的操作日志本就没有审计价值）；
RBAC 早于 DataScope（数据范围由角色推导）。

### 4.3 crate 地图

```
装配       miko-boot（产出两个二进制：miko-boot / miko-runner）
业务       miko-system · miko-ops · miko-client · miko-gen
能力       miko-core   miko-config  miko-web      miko-auth     miko-security
（框架）    miko-datascope  miko-tenant  miko-datasource  miko-cache  miko-storage
            miko-mq     miko-job    miko-flow     miko-message  miko-excel  miko-monitor
```

---

## 5. 快速开始

**前置**：Rust ≥ 1.88、PostgreSQL（或 MySQL 8.0）、可选 Redis（缓存 / 队列 / 跨节点网关）。

> 当前**实测验证**用的是 PostgreSQL 18.4；文档的生产口径是 MySQL 8.0（DDL 方言跟随连接后端）。

```bash
# 0) 取代码
git clone https://gitee.com/oldauntu/miko-backend.git
cd miko-backend/server

# 1) 跑迁移（35 个迁移：建表 + 菜单 + 权限点 + 管理员角色绑定）
MIKO_DATABASE__URL='postgres://user:pwd@127.0.0.1:5432/miko_admin' \
  cargo run --bin miko-boot -- migrate

# 2) 启动后端
export MIKO_DATABASE__URL='postgres://user:pwd@127.0.0.1:5432/miko_admin'
export MIKO_CONFIG_DIR="$(pwd)/config"                    # 关键：不设会读不到 config/*.toml（D82）
export MIKO_REDIS__URL='redis://:pwd@127.0.0.1:6379/0'    # 可选
cargo run --bin miko-boot
```

启动后：

| 地址 | 说明 |
|---|---|
| `http://localhost:8080/api/v1/doc/scalar` | 接口文档（Scalar UI，内嵌规范） |
| `http://localhost:8080/api/v1/summary` | 冒烟接口，响应体与响应头都带 `trace_id` |
| `http://localhost:9090/healthz` | 存活探针（另有 `/readyz` `/startupz` `/metrics`） |

> **没有 `/livez`**（早期草稿笔误，已废除）；端口只有 **8080**（业务）与 **9090**（运维）两个。

### 密钥管理（字段加密 / 传输加密的前置）

```bash
cargo run --bin miko-boot -- key gen-kek             # 生成一把 KEK，放进 MIKO_KEK_BASE64
cargo run --bin miko-boot -- key status              # 查看密钥环
cargo run --bin miko-boot -- key rotate              # 轮换（旧代次保留，旧密文仍可解）
cargo run --bin miko-boot -- key reencrypt           # 分批重加密（只重写密文列，不动检索摘要）
cargo run --bin miko-boot -- field-crypto backfill   # 把存量明文回填成密文（幂等，可重跑）
```

### 改了配置没反应？

`MIKO_CONFIG_DIR` 是**运行时**指定的，默认值指向编译期 crate 内的路径——
**`server/config/*.toml` 默认根本不会被读**（全部生效值来自内置默认与环境变量）。
本地开发请显式设成 `$(pwd)/config`。

---

## 6. 目录结构

```
miko-backend/
├── server/
│   ├── crates/
│   │   ├── miko-boot/               装配层 + 两个二进制 + gen-openapi
│   │   ├── modules/
│   │   │   ├── miko-system/         业务主模块（权限域 / 安全域 / 各框架能力编排）
│   │   │   │   ├── src/migration/   35 个迁移
│   │   │   │   └── src/entity/      SeaORM 实体
│   │   │   ├── miko-ops/            运维域（在线用户 / 监控 / 接口文档）
│   │   │   ├── miko-client/         客户端与授权方式管理
│   │   │   └── miko-gen/            代码生成器
│   │   └── miko-*/                  能力层 crate（见 4.3 crate 地图）
│   ├── config/                      default.toml / production.toml（**不含任何凭据**）
│   └── openapi.json                 OpenAPI 快照（CI 用 --check 校验一致性，**需要入库**）
├── docs/                            20 篇开发手册 + 任务清单 + 决策记录
├── scripts/                         文档校验 / 代码生成 / 迁移 / 端到端验证脚本
├── skills/                          项目技能库（约定 / 踩坑判据 / 验证与发布规程）
├── deploy/                          Dockerfile / docker-compose / nginx / prometheus / k8s
└── .github/workflows/ci.yml         CI（⚠️ 见第 8 节「已知缺口」）
```

---

## 7. 质量门禁

```bash
cd server

cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings     # 零告警
cargo test --workspace                                     # 1127 用例 / 51 套件
cargo run --bin gen-openapi -- --check                     # OpenAPI 快照无漂移

python3 scripts/check-docs.py                              # 文档一致性（表名 / 内链 / 章节 / 依赖白名单）
```

端到端脚本在 [`scripts/`](./scripts/)，需要真库 / 真 Redis，**连接串一律从环境变量读取**：

```bash
export MIKO_E2E_DSN='postgres://user:pwd@host:5432/miko_admin'
export MIKO_SAGA_LAB_URL='postgres://user:pwd@host:5432/miko_saga_lab'   # 跨库 Saga 用
node scripts/tmp-e2e-blacklist.mjs
```

覆盖范围举例：黑名单 42 项、账号安全 30 项、传输加密 22 项、密钥管理 23 项、Saga 27 项、
队列 25 项、定时任务 44 项、导入导出 61 项、代码生成 49 项、监控 56 项、租户 23 项——
另有配套的 `*-db.py` 做**库内硬证据**核对（表 / 列 / 索引 / 权限点 method+pattern / 审计流水）。

---

## 8. 已知缺口

诚实列出还没做的部分，避免误判完成度：

| 项 | 状态 |
|---|---|
| 水印管理、i18n、大屏报表 | 未开工（`docs/18` §4–6） |
| 运行期多租户隔离 | 一期只做**字段预留 + 注入器 + 防漏测试**，不认租户码 |
| 系统版本 & 升级管理 | 未开工（`docs/18` §2） |
| 分片上传 | 未做（大文件走代理上传 + 单次 HTTP） |
| S3 后端 | 签名与接口适配完成，**未接真实 MinIO 联调** |
| `miko-runner` 独立进程执行器 | 未做（当前是嵌入式执行器） |
| 代码生成器 CLI 模式 | 未做（只有 Web 界面） |
| 动态 SQL 字典 | 未做（依赖 `sqlparser`，不在离线依赖里；**创建时即拒绝**，而不是存进去后永远不生效） |
| 国密 Provider | 未做（`TransportCipher` trait 已留位） |
| M5 压测 / 渗透测试 / `cargo audit`·`deny` 清零 | 未开始 |

---

## 9. 凭据约定

**仓内不含任何凭据**，全部走环境变量：

```bash
MIKO_DATABASE__URL      # 主库连接串
MIKO_REDIS__URL         # Redis
MIKO_MQ__URL            # 队列（复用 Redis 时可同值）
MIKO_KEK_BASE64         # 密钥加密密钥（推荐；也可用 MIKO_KEK_FILE 走 Secret 挂载）
MIKO_E2E_DSN            # 端到端脚本用的真库连接串
```

`server/config/*.toml` 里的 `jwt_secret` / `storage.ticket_key` 等是**带 `dev-only` 字样的本地默认值**，
生产必须用环境变量覆盖（配置注释里逐条写明）。

推送到公开仓库前请先自查：

```bash
git grep --cached -E "<真实口令>|<内网IP>"
```

---

## 10. 文档

从 [`docs/README.md`](./docs/README.md) 进入。几篇值得先看的：

| 文档 | 为什么看 |
|---|---|
| [01 架构总览](./docs/01-架构总览.md) | 20 分钟建立整体心智模型 |
| [02 技术选型](./docs/02-技术选型.md) | 不只写"用什么"，还写"为什么是它 / 放弃了什么 / 有什么坑" |
| [05 认证授权与安全](./docs/05-认证授权与安全.md) | 安全域的全部设计口径 |
| [20 开发任务清单](./docs/20-开发任务清单.md) | **进度 + 160 条工程决策记录**——最值得读的一篇 |

## 11. 项目技能库

[`skills/`](./skills/README.md) 把开发中反复用到的**约定、踩坑判据与验证规程**固化成了技能，
供 AI 助手（拷到工作区的 `.workbuddy/skills/` 即可被自动加载）与新人直接取用：

| 技能 | 什么时候读 |
|---|---|
| [miko-overview](./skills/miko-overview/SKILL.md) | 第一次接触项目 / 要跑起来 |
| [miko-backend-conventions](./skills/miko-backend-conventions/SKILL.md) | 写任何后端代码、接口、迁移 |
| [miko-security-domain](./skills/miko-security-domain/SKILL.md) | 改登录 / 口令 / 加密 / 脱敏 / 传输 / 黑名单 |
| [miko-infra-modules](./skills/miko-infra-modules/SKILL.md) | 改多数据源 / Saga / 存储 / 队列 / 定时 / 监控 / 导入导出 |
| [miko-workflow-engine](./skills/miko-workflow-engine/SKILL.md) | 改工作流（引擎 / 运行时 / 设计器 / 消息） |
| [miko-frontend-dev](./skills/miko-frontend-dev/SKILL.md) | 改前端页面 / 路由 / 请求层 |
| [miko-verify-and-gates](./skills/miko-verify-and-gates/SKILL.md) | 改完代码要验证、要写 e2e |
| [miko-release-and-repos](./skills/miko-release-and-repos/SKILL.md) | 要提交 / 推送 / 发布 |

与 `docs/` 的分工：**`docs/` 是设计与需求文档，`skills/` 是操作手册与踩坑判据**。
两者冲突时以 [`docs/20-开发任务清单.md`](./docs/20-开发任务清单.md)（决策唯一权威表）为准。