280 lines
4.5 KiB
Markdown
280 lines
4.5 KiB
Markdown
# 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`。
|
||
|
||
备份成功≠可恢复，必须验证恢复。
|