# 03 技术架构

## 1. 总体选择

优先采用“TypeScript 全栈 + 模块化单体 + MySQL + Redis + 对象存储 + Docker”。

推荐：

### 微信小程序

- 微信小程序原生框架
- TypeScript
- TDesign Miniprogram（优先复用成熟组件）
- 自建 API Client
- 不使用重量级跨端框架作为 V1 默认方案

### 管理后台

- Vue 3
- TypeScript
- Vite
- Pinia
- Vue Router
- TDesign Vue Next 或成熟国内 UI 组件库
- ECharts（仅统计图表需要时）

### API

- Node.js LTS
- NestJS
- TypeScript
- REST API
- Prisma 或 TypeORM 二选一；建议 Prisma，但一旦项目启动后不得混用
- OpenAPI/Swagger
- Zod/class-validator 统一选一种 DTO 校验体系，NestJS 默认可使用 class-validator

### 数据

- MySQL 8.x
- Redis 7.x
- 对象存储：腾讯云 COS 为生产默认实现
- 本地开发：MinIO 兼容 S3 API

### 部署

- Docker
- Docker Compose
- Nginx
- 腾讯云 CVM / 轻量云服务器可作为早期部署载体
- 数据库生产优先托管 MySQL；预算有限时也可独立数据库容器，但必须有可靠备份
- HTTPS
- 国内域名和备案按实际上线要求办理

---

## 2. 为什么不做微服务

当前机构规模和 V1 业务复杂度不需要微服务。

模块化单体优点：

- 部署简单；
- 成本低；
- 调试简单；
- 事务一致性容易保证；
- Codex 更容易保持全局一致；
- 后续真有规模需求时可按模块拆分。

模块边界仍必须清晰。

---

## 3. API 模块建议

```text
auth
users
profiles
beneficiaries
service-applications
service-cases
service-records
follow-ups
projects
activities
volunteers
content
files
notifications
statistics
audit
permissions
system
```

每模块：

- controller
- service
- repository
- dto
- entities/model
- policy/permission
- tests

---

## 4. 分层规则

```text
Controller
  ↓
Application Service
  ↓
Domain Rules / Policy
  ↓
Repository / Adapter
  ↓
Database / External Service
```

禁止：

- Controller 直接访问 ORM；
- 页面直接写 SQL；
- 业务层直接调用 COS/微信 SDK；
- 前端自己判断权限代替后端校验。

---

## 5. 外部 Adapter

必须封装：

- WeChatAuthAdapter
- WeChatSubscribeMessageAdapter
- ObjectStorageAdapter
- SmsAdapter（若以后使用）
- AIAdapter（二期）
- GeocodingAdapter（二期）

这样可更换供应商。

---

## 6. API 规范

统一前缀：

`/api/v1`

响应：

```json
{
  "success": true,
  "data": {},
  "requestId": "..."
}
```

错误：

```json
{
  "success": false,
  "error": {
    "code": "APPLICATION_NOT_FOUND",
    "message": "未找到该服务申请"
  },
  "requestId": "..."
}
```

HTTP 状态码必须正确使用，不得永远 200。

---

## 7. 认证

### 小程序端

- wx.login 获取 code；
- 后端换取微信身份；
- 服务端创建自己的 session/token；
- token 轮换/过期；
- 手机号绑定按微信开放能力和实际授权流程实现；
- openid/unionid 绝不作为前端授权依据。

### 后台

推荐：

- 用户名/手机号 + 强密码；
- 生产可增加 MFA；
- HttpOnly Secure Cookie 优先；
- 管理后台不把长期 Token 放 localStorage。

---

## 8. 权限

RBAC + 资源级 Policy。

示例：

- STAFF 可以看自己负责的工单；
- PROJECT_MANAGER 可以看自己项目范围；
- ADMIN 可跨项目；
- VOLUNTEER 只能查看分配给自己的最小必要任务信息；
- 普通小程序用户只能查看自己提交或合法关联的申请。

---

## 9. 状态机

服务申请、工单、活动、志愿者审批必须采用明确状态机。

所有 transition：

- 验证当前状态；
- 验证目标状态；
- 验证权限；
- 事务写入；
- 写 history；
- 写 audit；
- 事务提交后再触发通知。

---

## 10. 幂等

以下必须防重复：

- 服务申请提交
- 活动报名
- 状态变更
- 服务记录提交
- 回访提交
- 文件关联
- 微信回调（若未来有）

方案：

- clientRequestId / idempotencyKey
- 数据库唯一索引
- 事务
- 必要时 Redis 短锁

---

## 11. 可观测性

必须：

- requestId
- structured logging
- error tracking
- health endpoint
- readiness/liveness
- 慢接口日志
- 数据库慢查询
- 关键任务状态

日志中禁止敏感数据。

---

## 12. 备份

至少：

- MySQL 每日自动备份；
- 保留 7/30 天策略可配置；
- 对象存储版本/生命周期按预算配置；
- 每季度至少做一次恢复演练；
- 恢复步骤写入 `infra/backup/README.md`。

备份成功≠可恢复，必须验证恢复。