lehuo/docs/03_ARCHITECTURE.md

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 模块建议

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. 分层规则

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

响应：

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

错误：

{
  "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。

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