2979 lines
53 KiB
Markdown
2979 lines
53 KiB
Markdown
<!-- FILE: 00_README_FIRST.md -->
|
||
|
||
# 乐活公益·暖心服务平台 —— Codex 开发文档包
|
||
|
||
> 版本：V1.0
|
||
> 文档用途：作为 Codex / AI 编程智能体的长期开发上下文、项目规则和验收依据。
|
||
> 最高原则：任何代码实现不得偏离本目录文档。发生冲突时，按本文档规定的优先级处理。
|
||
|
||
---
|
||
|
||
## 1. 项目一句话定义
|
||
|
||
“乐活公益·暖心服务平台”不是公益宣传页，而是一套以微信小程序为公众入口、Web 管理后台为工作人员入口、以“需求申请 → 受理评估 → 建档 → 派单 → 服务 → 反馈 → 回访 → 持续关爱”为核心闭环的公益服务数字化平台。
|
||
|
||
主要服务领域：
|
||
|
||
1. 关爱老年人、为老服务；
|
||
2. 困境妇女慈善帮扶；
|
||
3. 困境儿童关爱与帮扶；
|
||
4. 残疾人爱心救助与帮扶；
|
||
5. 其他困难群体服务；
|
||
6. 志愿者组织、公益活动、公益资源和社会参与。
|
||
|
||
---
|
||
|
||
## 2. Codex 每次开始工作前必须执行
|
||
|
||
按顺序阅读：
|
||
|
||
1. `00_README_FIRST.md`
|
||
2. `01_PROJECT_CONSTITUTION.md`
|
||
3. `02_PRODUCT_PRD_V1.md`
|
||
4. `03_ARCHITECTURE.md`
|
||
5. `04_DATA_MODEL.md`
|
||
6. `05_API_AND_WORKFLOW.md`
|
||
7. `06_SECURITY_PRIVACY.md`
|
||
8. `07_UI_UX.md`
|
||
9. `08_ENGINEERING_RULES.md`
|
||
10. `09_TEST_ACCEPTANCE.md`
|
||
11. `10_TASK_STATE.md`
|
||
12. `11_DECISIONS.md`
|
||
|
||
如果只是小范围修复，也至少必须阅读：
|
||
|
||
- `01_PROJECT_CONSTITUTION.md`
|
||
- `10_TASK_STATE.md`
|
||
- 与修改模块相关的文档
|
||
- `11_DECISIONS.md`
|
||
|
||
不得仅根据聊天中最近一句话修改项目。
|
||
|
||
---
|
||
|
||
## 3. 开发结束后必须回写
|
||
|
||
每完成一个任务，必须：
|
||
|
||
1. 更新 `10_TASK_STATE.md`；
|
||
2. 若产生架构/技术/业务决策，更新 `11_DECISIONS.md`；
|
||
3. 若接口变化，更新 API 文档；
|
||
4. 若表结构变化，更新数据模型与 migration；
|
||
5. 增加或更新自动化测试；
|
||
6. 执行 lint、typecheck、unit test、integration test、build；
|
||
7. 输出本次变更摘要、影响范围、风险、回滚方式。
|
||
|
||
禁止“只改代码、不改文档”。
|
||
|
||
---
|
||
|
||
## 4. 冲突处理优先级
|
||
|
||
从高到低：
|
||
|
||
1. 数据安全、隐私、法律合规；
|
||
2. `01_PROJECT_CONSTITUTION.md` 中的硬约束；
|
||
3. 已确认的产品业务规则；
|
||
4. 数据一致性和可审计性；
|
||
5. API 契约；
|
||
6. UI/UX 规范；
|
||
7. 工程偏好；
|
||
8. Codex 自己认为“更先进”的方案。
|
||
|
||
如果 Codex 认为有更好的方案，但会改变既有边界，必须记录到 `11_DECISIONS.md` 的“待确认建议”，不能擅自实施。
|
||
|
||
---
|
||
|
||
## 5. 代码仓库建议结构
|
||
|
||
```text
|
||
lehuo-public-service/
|
||
├─ apps/
|
||
│ ├─ miniprogram/ # 微信小程序
|
||
│ ├─ admin-web/ # Web 管理后台
|
||
│ └─ api/ # 后端 API
|
||
├─ packages/
|
||
│ ├─ contracts/ # DTO / enum / schema / API 契约
|
||
│ ├─ shared/ # 无业务副作用的共享代码
|
||
│ ├─ eslint-config/
|
||
│ └─ tsconfig/
|
||
├─ infra/
|
||
│ ├─ docker/
|
||
│ ├─ nginx/
|
||
│ ├─ scripts/
|
||
│ └─ backup/
|
||
├─ docs/
|
||
│ ├─ 本文档包
|
||
│ └─ diagrams/
|
||
├─ migrations/
|
||
├─ .env.example
|
||
├─ pnpm-workspace.yaml
|
||
├─ package.json
|
||
├─ AGENTS.md
|
||
└─ README.md
|
||
```
|
||
|
||
---
|
||
|
||
## 6. AGENTS.md 必须包含
|
||
|
||
仓库根目录 `AGENTS.md` 应复制以下核心规则：
|
||
|
||
- 先读 `docs/00_README_FIRST.md` 与 `docs/01_PROJECT_CONSTITUTION.md`。
|
||
- 不擅自改变产品定位、技术栈、数据库类型、认证方式。
|
||
- 不删除既有功能来“简化实现”。
|
||
- 不通过 mock 假装功能完成。
|
||
- 不将敏感信息写入日志。
|
||
- 每个业务状态变化必须可审计。
|
||
- 所有表结构变化必须 migration。
|
||
- 所有 API 变更必须同步 contracts。
|
||
- 完成任务必须更新 `docs/10_TASK_STATE.md`。
|
||
- 任何架构决策必须更新 `docs/11_DECISIONS.md`。
|
||
- 不因“AI认为更合理”而推翻已经批准的业务规则。
|
||
|
||
<!-- FILE: 01_PROJECT_CONSTITUTION.md -->
|
||
|
||
# 01 项目开发宪法（不可随意修改）
|
||
|
||
## 1. 产品定位硬约束
|
||
|
||
本项目必须始终是：
|
||
|
||
> 公益服务数字化平台，而不是宣传网站、商城、社交平台或复杂互联网平台。
|
||
|
||
V1.0 第一目标：让真实服务闭环跑通。
|
||
|
||
主链路：
|
||
|
||
```text
|
||
服务对象/代申请人提交需求
|
||
→ 工作人员受理
|
||
→ 需求评估
|
||
→ 建立/关联服务对象档案
|
||
→ 创建服务工单
|
||
→ 分配工作人员/志愿者
|
||
→ 执行服务
|
||
→ 留痕
|
||
→ 服务对象确认/反馈
|
||
→ 回访
|
||
→ 必要时继续跟进
|
||
```
|
||
|
||
任何新功能都必须回答：“是否增强这条主链路？”
|
||
|
||
---
|
||
|
||
## 2. 用户体验硬约束
|
||
|
||
1. 小程序优先服务普通群众、老人和低数字技能用户。
|
||
2. 主要操作不得依赖复杂手势。
|
||
3. 核心按钮大、清楚、可理解。
|
||
4. 服务申请尽量在 3~4 个步骤内完成。
|
||
5. 表单遵循“少填、可选、可拍、可说、可代办”。
|
||
6. 不在前端暴露技术术语、内部状态码。
|
||
7. 不为了视觉炫技牺牲加载速度和可理解性。
|
||
8. 所有失败状态必须给普通人能看懂的说明与下一步动作。
|
||
9. 适老化不是“放大字体”这么简单，必须包含点击区域、对比度、信息密度、步骤数量、错误恢复能力。
|
||
10. 功能完成度优先于动画和装饰。
|
||
|
||
---
|
||
|
||
## 3. 技术硬约束
|
||
|
||
1. 国内网络环境可稳定开发、构建、部署和访问。
|
||
2. 微信小程序作为公众端。
|
||
3. Web 管理后台作为机构工作人员端。
|
||
4. 后端采用模块化单体优先，V1.0 禁止为了“先进”拆微服务。
|
||
5. MySQL 为核心关系数据库。
|
||
6. Redis 只用于缓存、限流、短期状态等可恢复数据，不作为业务事实唯一存储。
|
||
7. 文件不保存到应用容器本地磁盘；生产环境使用对象存储。
|
||
8. 必须 Docker 化。
|
||
9. 环境分 dev / test / staging / prod。
|
||
10. 配置必须环境变量化，禁止把密钥提交 Git。
|
||
11. 所有数据库修改必须 migration。
|
||
12. 生产部署必须有备份、恢复、日志、监控和健康检查。
|
||
13. 对外部供应商能力必须封装 Adapter，不让业务层直接绑定云厂商 SDK。
|
||
14. V1.0 不引入 Kubernetes。
|
||
15. V1.0 不引入复杂事件总线，必要异步任务先使用可靠 Job/Queue 模式。
|
||
|
||
---
|
||
|
||
## 4. 安全硬约束
|
||
|
||
平台会处理老人、困境妇女、儿童、残疾人、困难家庭等敏感服务信息。
|
||
|
||
必须做到：
|
||
|
||
- 默认最小权限；
|
||
- 后台 RBAC；
|
||
- 资源级权限校验；
|
||
- 敏感字段脱敏；
|
||
- 操作审计；
|
||
- 不允许越权查询；
|
||
- 不允许通过 ID 枚举他人服务记录；
|
||
- 数据导出必须受控；
|
||
- 文件下载必须鉴权；
|
||
- 上传文件做类型、大小、扩展名、MIME 校验；
|
||
- Token、手机号、身份证件、地址、儿童信息不得写入普通日志；
|
||
- 删除业务数据优先软删除/归档，禁止随意物理删除；
|
||
- 关键状态变更保留历史；
|
||
- 不满 14 周岁相关信息按监护人授权与更严格权限原则处理；
|
||
- 不把真实生产数据复制到开发环境；
|
||
- 测试数据必须脱敏或生成。
|
||
|
||
---
|
||
|
||
## 5. 可靠性硬约束
|
||
|
||
1. 所有写请求应支持幂等或防重复提交。
|
||
2. 重要状态迁移必须使用数据库事务。
|
||
3. 不允许“接口成功但数据库只写了一半”。
|
||
4. 异步任务失败必须可重试、可查询。
|
||
5. 外部服务失败不能拖垮主业务。
|
||
6. 外部短信、订阅消息、对象存储失败应有降级和补偿。
|
||
7. 服务工单状态必须经过状态机校验，不能任意改字符串。
|
||
8. 每个关键实体保留 `created_at / updated_at / created_by / updated_by`。
|
||
9. 每个关键业务操作有 audit log。
|
||
10. 任何“已完成”都必须有可验证结果，不能只靠前端显示。
|
||
|
||
---
|
||
|
||
## 6. 易维护硬约束
|
||
|
||
- 避免自研基础组件；
|
||
- 避免魔法数字；
|
||
- 枚举集中管理；
|
||
- DTO 与数据库 Entity 分离；
|
||
- Controller 不写复杂业务；
|
||
- Service 不直接散落第三方 SDK；
|
||
- Repository 层负责数据访问；
|
||
- 公共错误码统一；
|
||
- 日志统一；
|
||
- 配置集中；
|
||
- 每个模块有 README 或模块说明；
|
||
- 复杂逻辑写测试；
|
||
- 删除代码前检查是否有业务依赖；
|
||
- 依赖升级必须经过测试，不追新版本。
|
||
|
||
---
|
||
|
||
## 7. V1.0 禁止范围
|
||
|
||
除非后续明确批准，V1.0 禁止：
|
||
|
||
- 在线公开募捐核心交易系统；
|
||
- 复杂社交/朋友圈；
|
||
- 即时 IM 聊天系统自研；
|
||
- AI 自动作出救助资格决定；
|
||
- 人脸识别；
|
||
- 未经必要性论证收集身份证完整信息；
|
||
- 微服务/K8s；
|
||
- 大数据平台；
|
||
- 区块链；
|
||
- 自研工作流引擎；
|
||
- 复杂积分商城；
|
||
- 过度游戏化；
|
||
- 对外开放 API 平台；
|
||
- 多租户 SaaS 架构。
|
||
|
||
---
|
||
|
||
## 8. AI 功能原则
|
||
|
||
AI 是效率工具，不是 V1.0 主角。
|
||
|
||
后续 AI 必须：
|
||
|
||
- 默认建议、不自动做高风险决定；
|
||
- AI 结果明确标记；
|
||
- 工作人员确认后才写入正式业务记录；
|
||
- 不把敏感数据发送到未经批准的外部模型；
|
||
- 能关闭；
|
||
- 业务流程不依赖 AI 才能运行。
|
||
|
||
<!-- FILE: 02_PRODUCT_PRD_V1.md -->
|
||
|
||
# 02 V1.0 产品需求文档（PRD）
|
||
|
||
## 1. V1.0 目标
|
||
|
||
交付可真实投入公益服务的第一版：
|
||
|
||
- 群众能找到服务、提交申请、看进度、给反馈；
|
||
- 家属/社区/志愿者能代申请；
|
||
- 工作人员能受理、建档、派单、留痕、回访；
|
||
- 志愿者能注册、报名活动；
|
||
- 管理员能管理项目、内容、人员、权限和统计。
|
||
|
||
---
|
||
|
||
## 2. 用户角色
|
||
|
||
### 2.1 PUBLIC
|
||
|
||
普通公众。浏览公益项目、活动、组织介绍、参与入口。
|
||
|
||
### 2.2 APPLICANT
|
||
|
||
申请人。可以是服务对象本人，也可以是代申请人。
|
||
|
||
### 2.3 BENEFICIARY
|
||
|
||
服务对象。老人、困境妇女、困境儿童、残疾人及其他困难群体。
|
||
|
||
### 2.4 VOLUNTEER
|
||
|
||
志愿者。
|
||
|
||
### 2.5 STAFF
|
||
|
||
公益工作人员。
|
||
|
||
### 2.6 PROJECT_MANAGER
|
||
|
||
公益项目负责人。
|
||
|
||
### 2.7 ADMIN
|
||
|
||
系统管理员。
|
||
|
||
### 2.8 SUPER_ADMIN
|
||
|
||
仅限极少数技术/管理人员，用于系统级配置，日常不使用。
|
||
|
||
---
|
||
|
||
## 3. 小程序信息架构
|
||
|
||
底部 Tab 建议：
|
||
|
||
1. 首页
|
||
2. 服务
|
||
3. 公益
|
||
4. 我的
|
||
|
||
### 首页
|
||
|
||
- Logo/品牌语
|
||
- 我需要帮助
|
||
- 帮他人申请
|
||
- 为老服务
|
||
- 妇女帮扶
|
||
- 儿童关爱
|
||
- 残疾人帮扶
|
||
- 最新公益项目
|
||
- 最新活动
|
||
- 我要做公益
|
||
|
||
### 服务
|
||
|
||
- 服务分类
|
||
- 服务申请
|
||
- 我的申请
|
||
- 服务进度
|
||
- 我的反馈
|
||
- 联系乐活
|
||
|
||
### 公益
|
||
|
||
- 公益项目
|
||
- 公益动态
|
||
- 公益活动
|
||
- 志愿者招募
|
||
- 企业/资源合作
|
||
- 乐活公益介绍
|
||
|
||
### 我的
|
||
|
||
根据身份动态显示：
|
||
|
||
- 微信登录/绑定手机号
|
||
- 我的资料
|
||
- 我的服务申请
|
||
- 我的活动
|
||
- 志愿者资料
|
||
- 我的志愿服务
|
||
- 消息
|
||
- 隐私设置
|
||
- 联系客服
|
||
|
||
---
|
||
|
||
## 4. 服务申请
|
||
|
||
### 4.1 申请类型
|
||
|
||
- OLD_AGE：老年关爱/为老服务
|
||
- WOMEN：困境妇女
|
||
- CHILD：困境儿童
|
||
- DISABILITY：残疾人帮扶
|
||
- LIFE_DIFFICULTY：生活困难
|
||
- OTHER：其他
|
||
|
||
### 4.2 申请身份
|
||
|
||
- SELF：本人申请
|
||
- FAMILY：家属代申请
|
||
- COMMUNITY：社区/机构代申请
|
||
- VOLUNTEER：志愿者代申请
|
||
- OTHER：其他
|
||
|
||
### 4.3 最小字段
|
||
|
||
- 服务类别
|
||
- 申请人与服务对象关系
|
||
- 服务对象姓名或称呼
|
||
- 联系方式
|
||
- 所在区域（不默认要求精确门牌）
|
||
- 需求描述
|
||
- 隐私授权确认
|
||
|
||
### 4.4 可选字段
|
||
|
||
- 图片/附件
|
||
- 期望联系时间
|
||
- 是否行动不便
|
||
- 是否需要上门
|
||
- 紧急程度（用户只能表达，最终等级由工作人员评估）
|
||
- 语音描述（二期可增强）
|
||
|
||
### 4.5 提交
|
||
|
||
提交后：
|
||
|
||
- 生成不可预测的业务编号；
|
||
- 显示“已收到”；
|
||
- 明确说明后续由工作人员联系；
|
||
- 不承诺超出机构能力的即时救援；
|
||
- 若用户选择明显紧急风险，应提示联系 110/120 等适当公共紧急服务，但具体文案由运营审核。
|
||
|
||
---
|
||
|
||
## 5. 服务申请状态机
|
||
|
||
```text
|
||
SUBMITTED
|
||
↓
|
||
PENDING_CONTACT
|
||
↓
|
||
ASSESSING
|
||
├─→ REJECTED/OUT_OF_SCOPE
|
||
├─→ REFERRED
|
||
↓
|
||
ACCEPTED
|
||
↓
|
||
SERVICE_PLANNED
|
||
↓
|
||
IN_SERVICE
|
||
↓
|
||
SERVICE_COMPLETED
|
||
↓
|
||
FOLLOW_UP_PENDING
|
||
↓
|
||
CLOSED
|
||
```
|
||
|
||
可增加：
|
||
|
||
- CANCELLED
|
||
- SUSPENDED
|
||
|
||
规则：
|
||
|
||
- 状态变化必须记录历史；
|
||
- 不可跳过关键节点，除管理员执行带原因的纠正操作；
|
||
- 关闭后再次产生需求，应创建新申请/跟进记录，而不是覆盖旧记录。
|
||
|
||
---
|
||
|
||
## 6. 服务对象档案
|
||
|
||
每个 Beneficiary 一人一档。
|
||
|
||
核心字段：
|
||
|
||
- 基础身份
|
||
- 联系信息
|
||
- 联系人/监护人
|
||
- 所属服务类别
|
||
- 地址分级信息
|
||
- 风险/关爱标签
|
||
- 备注
|
||
- 是否重点关爱
|
||
- 档案状态
|
||
|
||
严禁把所有信息塞入一个 JSON 字段。
|
||
|
||
儿童、残疾、健康、家庭困难等敏感字段应按实际必要性分表/分域并控制权限。
|
||
|
||
---
|
||
|
||
## 7. 工单
|
||
|
||
服务申请被接受后创建 Service Case / Work Order。
|
||
|
||
字段：
|
||
|
||
- 工单编号
|
||
- beneficiary_id
|
||
- application_id
|
||
- project_id（可空）
|
||
- 服务类别
|
||
- 负责人
|
||
- 计划日期
|
||
- 服务地点
|
||
- 服务说明
|
||
- 当前状态
|
||
- 优先级
|
||
- 完成时间
|
||
- 结果摘要
|
||
- 后续计划
|
||
|
||
工单可关联多个执行人/志愿者，但只有一个责任负责人。
|
||
|
||
---
|
||
|
||
## 8. 服务记录
|
||
|
||
一次工单可有多次服务记录。
|
||
|
||
记录：
|
||
|
||
- 服务时间
|
||
- 服务类型
|
||
- 服务人员
|
||
- 服务内容
|
||
- 服务结果
|
||
- 图片附件
|
||
- 服务对象确认情况
|
||
- 后续建议
|
||
- 创建人
|
||
|
||
服务记录创建后若修改，必须保留修订痕迹或审计日志。
|
||
|
||
---
|
||
|
||
## 9. 回访
|
||
|
||
回访任务来源：
|
||
|
||
- 服务完成自动创建；
|
||
- 重点关爱对象周期任务；
|
||
- 工作人员手工创建。
|
||
|
||
回访结果：
|
||
|
||
- SATISFIED
|
||
- GENERALLY_SATISFIED
|
||
- UNSATISFIED
|
||
- NEED_MORE_HELP
|
||
- UNREACHABLE
|
||
- OTHER
|
||
|
||
若 `NEED_MORE_HELP`：
|
||
|
||
- 必须支持一键创建后续申请/工单；
|
||
- 不能只保存文字然后无人处理。
|
||
|
||
---
|
||
|
||
## 10. 志愿者
|
||
|
||
注册字段遵循最小必要：
|
||
|
||
- 姓名
|
||
- 手机
|
||
- 所在区域
|
||
- 可服务时间
|
||
- 技能标签
|
||
- 感兴趣领域
|
||
- 紧急联系人（仅确有管理需要时）
|
||
- 志愿者状态
|
||
|
||
状态：
|
||
|
||
- APPLIED
|
||
- APPROVED
|
||
- REJECTED
|
||
- SUSPENDED
|
||
- INACTIVE
|
||
|
||
志愿者默认不能查看完整服务对象档案。
|
||
|
||
---
|
||
|
||
## 11. 公益活动
|
||
|
||
活动：
|
||
|
||
- 标题
|
||
- 封面
|
||
- 项目
|
||
- 时间
|
||
- 地点
|
||
- 招募人数
|
||
- 报名截止时间
|
||
- 说明
|
||
- 状态
|
||
|
||
状态：
|
||
|
||
- DRAFT
|
||
- PUBLISHED
|
||
- REGISTRATION_CLOSED
|
||
- IN_PROGRESS
|
||
- COMPLETED
|
||
- CANCELLED
|
||
|
||
报名：
|
||
|
||
- 用户
|
||
- 志愿者身份
|
||
- 报名时间
|
||
- 审核状态
|
||
- 签到状态
|
||
- 服务时长
|
||
|
||
---
|
||
|
||
## 12. 公益项目
|
||
|
||
项目用于：
|
||
|
||
- 展示；
|
||
- 归集服务工单；
|
||
- 统计服务成果；
|
||
- 后续政府购买服务项目管理。
|
||
|
||
V1 字段：
|
||
|
||
- 项目名称
|
||
- 项目类别
|
||
- 简介
|
||
- 详细介绍
|
||
- 封面
|
||
- 项目周期
|
||
- 状态
|
||
- 是否公开
|
||
- 负责人
|
||
- 目标人数（可空）
|
||
- 排序
|
||
|
||
---
|
||
|
||
## 13. 内容管理
|
||
|
||
内容类型：
|
||
|
||
- 机构介绍
|
||
- 公益动态
|
||
- 服务故事
|
||
- 通知公告
|
||
- 常见问题
|
||
|
||
内容必须支持草稿和发布，不允许编辑即立即对外。
|
||
|
||
涉及服务对象故事：
|
||
|
||
- 必须有内容审核流程；
|
||
- 展示前脱敏；
|
||
- 未授权不得公开身份性信息。
|
||
|
||
---
|
||
|
||
## 14. 消息通知
|
||
|
||
V1：
|
||
|
||
- 站内消息
|
||
- 微信订阅消息（按微信平台能力和用户授权使用）
|
||
|
||
事件：
|
||
|
||
- 申请提交
|
||
- 申请状态变化
|
||
- 服务安排
|
||
- 服务完成
|
||
- 待评价/回访
|
||
- 活动报名结果
|
||
|
||
通知失败不能回滚主交易。
|
||
|
||
---
|
||
|
||
## 15. Web 后台
|
||
|
||
一级菜单：
|
||
|
||
- 工作台
|
||
- 服务申请
|
||
- 服务工单
|
||
- 服务对象
|
||
- 回访管理
|
||
- 公益项目
|
||
- 公益活动
|
||
- 志愿者
|
||
- 内容管理
|
||
- 数据统计
|
||
- 用户与权限
|
||
- 系统设置
|
||
- 审计日志（高权限）
|
||
|
||
工作台至少展示：
|
||
|
||
- 新申请
|
||
- 待联系
|
||
- 评估中
|
||
- 服务中
|
||
- 待回访
|
||
- 今日服务
|
||
- 超期任务
|
||
- 重点关爱提醒
|
||
|
||
---
|
||
|
||
## 16. 数据统计 V1
|
||
|
||
统计以真实业务数据计算：
|
||
|
||
- 申请数
|
||
- 受理数
|
||
- 完成服务数
|
||
- 服务人次
|
||
- 去重服务对象数
|
||
- 各服务类别数量
|
||
- 志愿者数量
|
||
- 活动数量
|
||
- 志愿服务时长
|
||
|
||
不得用手工填写数字覆盖真实统计结果。
|
||
|
||
<!-- FILE: 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 模块建议
|
||
|
||
```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`。
|
||
|
||
备份成功≠可恢复，必须验证恢复。
|
||
|
||
<!-- FILE: 04_DATA_MODEL.md -->
|
||
|
||
# 04 数据模型
|
||
|
||
## 1. 通用字段规范
|
||
|
||
核心表统一包含：
|
||
|
||
- id: bigint/uuid（二选一后固定；建议 bigint 内部主键 + public_id 随机ID）
|
||
- public_id: varchar，外部暴露，禁止连续可枚举
|
||
- created_at
|
||
- updated_at
|
||
- created_by（后台业务表适用）
|
||
- updated_by
|
||
- deleted_at（需要软删除的表）
|
||
|
||
时间统一数据库 UTC 存储，展示按 Asia/Shanghai。
|
||
|
||
---
|
||
|
||
## 2. 核心实体
|
||
|
||
### users
|
||
|
||
微信/后台统一用户主体，避免重复身份系统。
|
||
|
||
- id
|
||
- public_id
|
||
- status
|
||
- user_type
|
||
- mobile（加密/脱敏策略）
|
||
- nickname
|
||
- avatar_url
|
||
- last_login_at
|
||
|
||
### wechat_identities
|
||
|
||
- user_id
|
||
- openid
|
||
- unionid nullable
|
||
- appid
|
||
- created_at
|
||
唯一索引 `(appid, openid)`。
|
||
|
||
### staff_profiles
|
||
|
||
- user_id
|
||
- employee_no nullable
|
||
- display_name
|
||
- department
|
||
- status
|
||
|
||
### roles / permissions / user_roles / role_permissions
|
||
|
||
标准 RBAC。
|
||
|
||
---
|
||
|
||
## 3. beneficiary_profiles
|
||
|
||
服务对象档案：
|
||
|
||
- id
|
||
- public_id
|
||
- display_name
|
||
- gender nullable
|
||
- birth_year nullable
|
||
- mobile nullable
|
||
- region_code
|
||
- address_detail_encrypted nullable
|
||
- primary_category
|
||
- key_care_flag
|
||
- status
|
||
- notes_encrypted nullable
|
||
- created_by
|
||
- timestamps
|
||
|
||
不要默认收集完整身份证。
|
||
|
||
---
|
||
|
||
## 4. beneficiary_contacts
|
||
|
||
- beneficiary_id
|
||
- name
|
||
- relation
|
||
- mobile
|
||
- is_guardian
|
||
- is_emergency_contact
|
||
- consent_record_id nullable
|
||
|
||
---
|
||
|
||
## 5. beneficiary_tags / tags
|
||
|
||
标签：
|
||
|
||
- 独居
|
||
- 高龄
|
||
- 行动不便
|
||
- 定期探访
|
||
- 困境儿童
|
||
等。
|
||
|
||
标签只能帮助服务，不应成为歧视性画像。
|
||
|
||
---
|
||
|
||
## 6. service_applications
|
||
|
||
- id
|
||
- public_id
|
||
- application_no
|
||
- applicant_user_id nullable
|
||
- beneficiary_id nullable
|
||
- apply_mode
|
||
- service_category
|
||
- description
|
||
- region_code
|
||
- contact_name
|
||
- contact_mobile
|
||
- preferred_contact_time nullable
|
||
- urgency_self_report nullable
|
||
- evaluated_priority nullable
|
||
- status
|
||
- assigned_staff_id nullable
|
||
- source
|
||
- submitted_at
|
||
- accepted_at nullable
|
||
- closed_at nullable
|
||
- rejection_reason nullable
|
||
- referral_note nullable
|
||
- timestamps
|
||
|
||
索引：
|
||
|
||
- application_no unique
|
||
- status
|
||
- assigned_staff_id + status
|
||
- created_at
|
||
- service_category + created_at
|
||
|
||
---
|
||
|
||
## 7. service_application_status_history
|
||
|
||
- application_id
|
||
- from_status
|
||
- to_status
|
||
- operator_user_id
|
||
- reason
|
||
- created_at
|
||
|
||
不可更新，只追加。
|
||
|
||
---
|
||
|
||
## 8. service_cases
|
||
|
||
- id
|
||
- public_id
|
||
- case_no
|
||
- application_id
|
||
- beneficiary_id
|
||
- project_id nullable
|
||
- owner_staff_id
|
||
- category
|
||
- priority
|
||
- status
|
||
- planned_start_at nullable
|
||
- planned_end_at nullable
|
||
- service_location_encrypted nullable
|
||
- summary
|
||
- result_summary nullable
|
||
- follow_up_plan nullable
|
||
- completed_at nullable
|
||
- timestamps
|
||
|
||
---
|
||
|
||
## 9. case_assignees
|
||
|
||
支持多人协作：
|
||
|
||
- case_id
|
||
- user_id
|
||
- assignee_type STAFF/VOLUNTEER
|
||
- role
|
||
- assigned_at
|
||
- removed_at nullable
|
||
|
||
---
|
||
|
||
## 10. service_records
|
||
|
||
- id
|
||
- public_id
|
||
- case_id
|
||
- beneficiary_id
|
||
- service_start_at
|
||
- service_end_at nullable
|
||
- service_type
|
||
- content
|
||
- result
|
||
- follow_up_suggestion nullable
|
||
- beneficiary_confirm_status nullable
|
||
- created_by
|
||
- timestamps
|
||
|
||
---
|
||
|
||
## 11. follow_up_tasks
|
||
|
||
- id
|
||
- public_id
|
||
- beneficiary_id
|
||
- case_id nullable
|
||
- owner_staff_id
|
||
- due_at
|
||
- follow_up_type
|
||
- status
|
||
- result_code nullable
|
||
- result_note nullable
|
||
- completed_at nullable
|
||
- source
|
||
- timestamps
|
||
|
||
索引：
|
||
|
||
- owner_staff_id + status + due_at
|
||
- beneficiary_id + due_at
|
||
|
||
---
|
||
|
||
## 12. volunteers / volunteer_skills
|
||
|
||
volunteers：
|
||
|
||
- user_id
|
||
- real_name
|
||
- mobile
|
||
- region_code
|
||
- availability_note
|
||
- status
|
||
- approved_by nullable
|
||
- approved_at nullable
|
||
|
||
skills：
|
||
|
||
- volunteer_id
|
||
- skill_code
|
||
|
||
---
|
||
|
||
## 13. projects
|
||
|
||
- id
|
||
- public_id
|
||
- name
|
||
- category
|
||
- summary
|
||
- content
|
||
- cover_file_id
|
||
- manager_user_id
|
||
- start_date
|
||
- end_date
|
||
- target_people nullable
|
||
- status
|
||
- is_public
|
||
- sort_order
|
||
- timestamps
|
||
|
||
---
|
||
|
||
## 14. activities
|
||
|
||
- id
|
||
- public_id
|
||
- project_id nullable
|
||
- title
|
||
- summary
|
||
- content
|
||
- cover_file_id
|
||
- start_at
|
||
- end_at
|
||
- registration_deadline
|
||
- location_text
|
||
- capacity nullable
|
||
- status
|
||
- published_at nullable
|
||
- timestamps
|
||
|
||
---
|
||
|
||
## 15. activity_registrations
|
||
|
||
- activity_id
|
||
- user_id
|
||
- status
|
||
- registered_at
|
||
- checked_in_at nullable
|
||
- service_minutes nullable
|
||
|
||
唯一 `(activity_id,user_id)` 防重复报名。
|
||
|
||
---
|
||
|
||
## 16. content_posts
|
||
|
||
- id
|
||
- public_id
|
||
- type
|
||
- title
|
||
- summary
|
||
- content
|
||
- cover_file_id nullable
|
||
- status DRAFT/REVIEW/PUBLISHED/ARCHIVED
|
||
- author_user_id
|
||
- reviewer_user_id nullable
|
||
- published_at nullable
|
||
- timestamps
|
||
|
||
---
|
||
|
||
## 17. files
|
||
|
||
只保存元数据：
|
||
|
||
- id
|
||
- public_id
|
||
- storage_provider
|
||
- bucket
|
||
- object_key
|
||
- original_filename
|
||
- mime_type
|
||
- size
|
||
- sha256
|
||
- business_type
|
||
- uploader_user_id
|
||
- status
|
||
- created_at
|
||
|
||
前端不得直接拼接永久公网 URL。
|
||
|
||
---
|
||
|
||
## 18. consents
|
||
|
||
- id
|
||
- public_id
|
||
- user_id nullable
|
||
- beneficiary_id nullable
|
||
- consent_type
|
||
- version
|
||
- granted_by
|
||
- granted_at
|
||
- revoked_at nullable
|
||
- evidence_json（仅保存必要证明）
|
||
- ip_hash nullable
|
||
- created_at
|
||
|
||
---
|
||
|
||
## 19. audit_logs
|
||
|
||
只追加：
|
||
|
||
- id
|
||
- request_id
|
||
- actor_user_id
|
||
- actor_role
|
||
- action
|
||
- resource_type
|
||
- resource_public_id
|
||
- result
|
||
- metadata_json（不得含敏感明文）
|
||
- ip_hash
|
||
- user_agent_summary
|
||
- created_at
|
||
|
||
---
|
||
|
||
## 20. notifications / notification_deliveries
|
||
|
||
通知实体与发送记录分开，支持重试和追踪。
|
||
|
||
---
|
||
|
||
## 21. 数据库规则
|
||
|
||
1. 必须使用 FK 或由 ORM/服务保证等价完整性；禁止无约束“凭感觉关联”。
|
||
2. 唯一业务编号必须 unique。
|
||
3. 常查字段建组合索引。
|
||
4. 禁止对大文本字段滥建索引。
|
||
5. 金额如未来出现用 decimal，禁止 float。
|
||
6. 所有枚举在 contracts 中有单一事实来源。
|
||
7. migration 不允许 destructive change 直接上线。
|
||
8. 删除列采用“停用 → 迁移 → 验证 → 后续版本删除”。
|
||
|
||
<!-- FILE: 05_API_AND_WORKFLOW.md -->
|
||
|
||
# 05 API 与业务流程规范
|
||
|
||
## 1. API 命名
|
||
|
||
REST 为主。
|
||
|
||
示例：
|
||
|
||
- POST `/api/v1/auth/wechat/login`
|
||
- GET `/api/v1/me`
|
||
- POST `/api/v1/service-applications`
|
||
- GET `/api/v1/service-applications/:publicId`
|
||
- POST `/api/v1/admin/service-applications/:publicId/transition`
|
||
- POST `/api/v1/admin/service-cases`
|
||
- POST `/api/v1/admin/service-cases/:publicId/records`
|
||
- POST `/api/v1/admin/follow-ups/:publicId/complete`
|
||
|
||
不使用：
|
||
|
||
- `/getAllXXX`
|
||
- `/doSomething2`
|
||
- `/updateStatusDirectly`
|
||
|
||
---
|
||
|
||
## 2. 服务申请提交事务
|
||
|
||
伪代码：
|
||
|
||
```text
|
||
validate input
|
||
check idempotency key
|
||
resolve applicant user
|
||
create or leave beneficiary unlinked
|
||
create service_application
|
||
create initial status history
|
||
create audit log
|
||
commit
|
||
enqueue notification
|
||
return public_id + application_no
|
||
```
|
||
|
||
禁止在事务中等待第三方消息服务。
|
||
|
||
---
|
||
|
||
## 3. 受理
|
||
|
||
工作人员：
|
||
|
||
1. 打开申请；
|
||
2. 权限检查；
|
||
3. 联系服务对象；
|
||
4. 评估；
|
||
5. 可关联已有档案或建立档案；
|
||
6. ACCEPTED；
|
||
7. 创建 service_case；
|
||
8. 指定负责人；
|
||
9. 创建后续任务；
|
||
10. 通知用户。
|
||
|
||
“关联已有档案”必须防止同名误合并，至少依据手机号+人工确认等多个条件。
|
||
|
||
---
|
||
|
||
## 4. 服务执行
|
||
|
||
- 工单 `SERVICE_PLANNED → IN_SERVICE`
|
||
- 新增 service_record
|
||
- 上传附件
|
||
- 可多次服务
|
||
- 完成时填写 result_summary
|
||
- `IN_SERVICE → SERVICE_COMPLETED`
|
||
- 自动生成 follow_up_task
|
||
|
||
---
|
||
|
||
## 5. 回访
|
||
|
||
完成回访时：
|
||
|
||
- 写结果；
|
||
- 标记任务完成；
|
||
- 如果需要继续帮助，创建 linked application/case；
|
||
- 记录来源关系；
|
||
- 写 audit。
|
||
|
||
---
|
||
|
||
## 6. 文件上传
|
||
|
||
推荐流程：
|
||
|
||
1. 客户端申请上传凭证；
|
||
2. 后端检查业务权限和文件约束；
|
||
3. 生成短期上传签名或后端代理上传；
|
||
4. 上传完成后回调/确认；
|
||
5. 后端校验 object metadata；
|
||
6. files 表记录；
|
||
7. 业务表关联 file_id。
|
||
|
||
安全约束：
|
||
|
||
- 文件大小限制；
|
||
- MIME 白名单；
|
||
- 扩展名白名单；
|
||
- object key 随机；
|
||
- 禁止使用原始文件名作路径；
|
||
- 图片需要时进行安全转码；
|
||
- 下载使用短时签名 URL；
|
||
- 私有 Bucket 默认。
|
||
|
||
---
|
||
|
||
## 7. 分页
|
||
|
||
统一 cursor 或 page/pageSize。V1 可使用：
|
||
|
||
- page >= 1
|
||
- pageSize 默认 20，最大 100
|
||
|
||
返回：
|
||
|
||
```json
|
||
{
|
||
"items": [],
|
||
"page": 1,
|
||
"pageSize": 20,
|
||
"total": 120
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 搜索
|
||
|
||
后台允许按：
|
||
|
||
- 业务编号
|
||
- 姓名/称呼
|
||
- 脱敏手机号后四位（视实现）
|
||
- 服务类别
|
||
- 状态
|
||
- 时间
|
||
- 项目
|
||
- 负责人
|
||
|
||
敏感全文搜索能力应谨慎开放。
|
||
|
||
---
|
||
|
||
## 9. 导出
|
||
|
||
任何导出：
|
||
|
||
- 必须权限校验；
|
||
- 记录审计；
|
||
- 限制数据范围；
|
||
- 大数据量异步生成；
|
||
- 文件有过期时间；
|
||
- 默认脱敏；
|
||
- 导出儿童等敏感信息需要更高权限。
|
||
|
||
---
|
||
|
||
## 10. 错误码
|
||
|
||
至少：
|
||
|
||
- AUTH_REQUIRED
|
||
- FORBIDDEN
|
||
- RESOURCE_NOT_FOUND
|
||
- VALIDATION_ERROR
|
||
- DUPLICATE_REQUEST
|
||
- INVALID_STATE_TRANSITION
|
||
- APPLICATION_NOT_FOUND
|
||
- CASE_NOT_FOUND
|
||
- VOLUNTEER_NOT_APPROVED
|
||
- ACTIVITY_FULL
|
||
- REGISTRATION_CLOSED
|
||
- FILE_TYPE_NOT_ALLOWED
|
||
- FILE_TOO_LARGE
|
||
- RATE_LIMITED
|
||
- INTERNAL_ERROR
|
||
|
||
用户端错误文案必须友好，日志保留 requestId 便于排障。
|
||
|
||
<!-- FILE: 06_SECURITY_PRIVACY.md -->
|
||
|
||
# 06 安全、隐私与合规基线
|
||
|
||
> 本文是工程基线，不替代正式法律意见。上线前应由运营主体根据实际收集信息、服务范围和微信平台规则完成隐私政策、用户协议和必要合规审核。
|
||
|
||
## 1. 数据分类
|
||
|
||
### L1 公开
|
||
|
||
公益项目公开介绍、公开活动、组织联系方式。
|
||
|
||
### L2 内部
|
||
|
||
普通内部运营信息、非敏感统计。
|
||
|
||
### L3 敏感业务
|
||
|
||
服务申请详情、家庭困难、住址、联系方式、服务记录。
|
||
|
||
### L4 高敏感
|
||
|
||
儿童个人信息、监护信息、健康/残疾相关详细信息、证件、特殊风险记录。
|
||
|
||
默认 L3/L4 不得公开。
|
||
|
||
---
|
||
|
||
## 2. 最小收集
|
||
|
||
每个字段进入系统前必须回答：
|
||
|
||
- 为什么需要？
|
||
- 不收集是否仍能提供服务？
|
||
- 保存多久？
|
||
- 谁能看？
|
||
- 是否可脱敏？
|
||
- 是否真的需要精确地址/证件？
|
||
|
||
没有明确目的不得新增收集项。
|
||
|
||
---
|
||
|
||
## 3. 未成年人
|
||
|
||
不满 14 周岁相关个人信息必须采用更严格保护：
|
||
|
||
- 明确监护人角色；
|
||
- 记录同意；
|
||
- 限制访问人员；
|
||
- 默认不公开案例身份；
|
||
- 不允许志愿者看到与任务无关的信息；
|
||
- 定期审计访问；
|
||
- 允许合法更正、删除/撤回等请求按规则处理。
|
||
|
||
---
|
||
|
||
## 4. 加密
|
||
|
||
传输：
|
||
|
||
- 全站 HTTPS/TLS。
|
||
|
||
存储：
|
||
|
||
- 云盘/数据库基础加密按环境开启；
|
||
- 极敏感字段应用层加密；
|
||
- 密钥不与数据库同库；
|
||
- 密钥通过云 KMS/Secret Manager 或安全环境变量管理。
|
||
|
||
密码：
|
||
|
||
- Argon2id 或 bcrypt 强哈希；
|
||
- 禁止 MD5/SHA1 直接存密码。
|
||
|
||
---
|
||
|
||
## 5. 手机号和地址
|
||
|
||
显示：
|
||
|
||
- 普通列表默认脱敏，例如 138****1234；
|
||
- 详细查看必须权限。
|
||
|
||
查询：
|
||
|
||
- 如需精确匹配可存 HMAC/hash 辅助索引；
|
||
- 明文/密文设计需避免为搜索而降低保护。
|
||
|
||
---
|
||
|
||
## 6. 日志
|
||
|
||
禁止记录：
|
||
|
||
- 身份证完整号码
|
||
- 完整手机号
|
||
- openid
|
||
- access token
|
||
- session token
|
||
- 详细住址
|
||
- 儿童档案内容
|
||
- 服务描述全文
|
||
- 上传文件原文
|
||
|
||
允许：
|
||
|
||
- public_id
|
||
- requestId
|
||
- action code
|
||
- status
|
||
- 耗时
|
||
- 脱敏 actor 信息
|
||
|
||
---
|
||
|
||
## 7. OWASP 基线
|
||
|
||
必须防：
|
||
|
||
- SQL injection
|
||
- XSS
|
||
- CSRF（后台 Cookie 认证时）
|
||
- SSRF
|
||
- IDOR/BOLA
|
||
- path traversal
|
||
- unrestricted upload
|
||
- mass assignment
|
||
- brute force
|
||
- credential stuffing
|
||
- rate abuse
|
||
- insecure direct object reference
|
||
|
||
每个资源 API 后端都做授权，不相信前端按钮是否隐藏。
|
||
|
||
---
|
||
|
||
## 8. 限流
|
||
|
||
按场景设置：
|
||
|
||
- 登录
|
||
- 验证码
|
||
- 服务申请
|
||
- 文件上传
|
||
- 搜索
|
||
- 导出
|
||
- 微信登录 exchange
|
||
|
||
不能只按 IP，必要时组合 user/device/IP。
|
||
|
||
---
|
||
|
||
## 9. 审计事件
|
||
|
||
至少审计：
|
||
|
||
- 登录成功/失败
|
||
- 角色权限修改
|
||
- 查看高敏感档案
|
||
- 新增/修改服务对象
|
||
- 服务申请状态变化
|
||
- 工单分配
|
||
- 服务记录修改
|
||
- 导出
|
||
- 删除/归档
|
||
- 隐私同意变化
|
||
- 系统配置变化
|
||
|
||
---
|
||
|
||
## 10. 数据保留
|
||
|
||
不要永久保留所有数据。
|
||
|
||
必须由运营方定义：
|
||
|
||
- 服务档案保存期限；
|
||
- 未成年人数据期限；
|
||
- 日志期限；
|
||
- 导出文件期限；
|
||
- 已取消授权后的处理；
|
||
- 项目验收要求。
|
||
|
||
程序上把保留策略做成可配置任务，而不是散落代码。
|
||
|
||
---
|
||
|
||
## 11. 权限矩阵核心原则
|
||
|
||
### Volunteer
|
||
|
||
只能：
|
||
|
||
- 看自己被分配任务；
|
||
- 看完成服务所需的最小信息；
|
||
- 提交服务记录；
|
||
不能：
|
||
- 搜索全体服务对象；
|
||
- 导出名单；
|
||
- 看完整历史档案。
|
||
|
||
### Staff
|
||
|
||
按负责范围访问。
|
||
|
||
### Project Manager
|
||
|
||
按项目访问。
|
||
|
||
### Admin
|
||
|
||
跨项目业务管理，但高敏感导出仍可要求额外权限。
|
||
|
||
### Super Admin
|
||
|
||
系统维护，不等于默认业务数据无限查看；高敏感读取同样审计。
|
||
|
||
---
|
||
|
||
## 12. 安全发布门禁
|
||
|
||
上线前必须：
|
||
|
||
- npm/pnpm dependency audit
|
||
- secret scan
|
||
- SAST 基础扫描
|
||
- API 权限测试
|
||
- 越权测试
|
||
- 文件上传测试
|
||
- SQL 注入/XSS 测试
|
||
- 弱密码/暴力登录测试
|
||
- 备份恢复测试
|
||
- staging 冒烟测试
|
||
|
||
发现 Critical/High 安全问题不得上线。
|
||
|
||
<!-- FILE: 07_UI_UX.md -->
|
||
|
||
# 07 UI/UX 与适老化规范
|
||
|
||
## 1. 视觉原则
|
||
|
||
关键词：
|
||
|
||
- 温暖
|
||
- 可信
|
||
- 简洁
|
||
- 清楚
|
||
- 不商业化
|
||
- 不花哨
|
||
|
||
不得做：
|
||
|
||
- 密集 Banner
|
||
- 过多卡片
|
||
- 首页十几个同级入口
|
||
- 小字号说明堆叠
|
||
- 复杂渐变和强动画
|
||
- 倒计时/诱导点击式设计
|
||
|
||
---
|
||
|
||
## 2. 小程序首页优先级
|
||
|
||
P0：
|
||
|
||
1. 我需要帮助
|
||
2. 帮他人申请
|
||
|
||
P1：3. 四大服务类别 4. 我的服务进度
|
||
|
||
P2：5. 公益项目 6. 公益活动 7. 我要做公益
|
||
|
||
宣传内容不能挤压服务入口。
|
||
|
||
---
|
||
|
||
## 3. 适老规范
|
||
|
||
建议基线：
|
||
|
||
- 正文字号尽量 >= 16px 等效视觉；
|
||
- 主要按钮文字 >= 17px 等效视觉；
|
||
- 主要点击区域高度约 48px 以上；
|
||
- 按钮间距足够；
|
||
- 一屏只做一个主要决定；
|
||
- 错误提示紧贴字段；
|
||
- 表单支持保存草稿（较长时）；
|
||
- 不用颜色作为唯一状态表达；
|
||
- 图标同时配文字；
|
||
- 返回动作清晰；
|
||
- 网络失败可重试；
|
||
- 提交后明确“已成功”。
|
||
|
||
具体像素可在设计系统中统一，不以本建议替代微信设备适配。
|
||
|
||
---
|
||
|
||
## 4. 表单原则
|
||
|
||
一页最多 5~7 个核心输入。
|
||
复杂申请拆步骤：
|
||
|
||
1. 需要什么帮助
|
||
2. 帮谁申请
|
||
3. 联系方式与地区
|
||
4. 需求描述
|
||
5. 确认提交
|
||
|
||
可选信息放“补充信息”。
|
||
|
||
---
|
||
|
||
## 5. 文案
|
||
|
||
使用：
|
||
|
||
- “我需要帮助”
|
||
- “帮家人申请”
|
||
- “工作人员正在联系您”
|
||
- “还需要继续帮助”
|
||
- “重新提交”
|
||
|
||
避免：
|
||
|
||
- “创建工单”
|
||
- “状态流转”
|
||
- “Beneficiary”
|
||
- “Record Not Found”
|
||
- “非法参数”
|
||
|
||
---
|
||
|
||
## 6. 空状态
|
||
|
||
例如没有服务申请：
|
||
“您还没有提交过服务申请。如果您或家人需要帮助，可以从这里开始。”
|
||
|
||
提供明确按钮。
|
||
|
||
---
|
||
|
||
## 7. 错误恢复
|
||
|
||
提交失败不能清空已填表单。
|
||
上传失败允许单文件重试。
|
||
网络失败保持本地草稿。
|
||
重复点击提交不应生成多个申请。
|
||
|
||
---
|
||
|
||
## 8. 管理后台
|
||
|
||
后台目标：让工作人员每天打开工作台就知道做什么。
|
||
|
||
表格：
|
||
|
||
- 默认显示业务必要列；
|
||
- 手机、地址默认脱敏；
|
||
- 常用筛选固定；
|
||
- 详情采用清晰分区；
|
||
- 状态颜色+文字；
|
||
- 危险操作二次确认并说明影响。
|
||
|
||
禁止为了“企业感”做过密 Dashboard。
|
||
|
||
---
|
||
|
||
## 9. 无障碍
|
||
|
||
- 合理对比度；
|
||
- 图片提供语义说明（可用场景）；
|
||
- 表单 label 明确；
|
||
- 键盘操作兼容后台；
|
||
- focus 可见；
|
||
- 不用仅 hover 才出现核心操作。
|
||
|
||
<!-- FILE: 08_ENGINEERING_RULES.md -->
|
||
|
||
# 08 工程开发规则
|
||
|
||
## 1. Monorepo
|
||
|
||
推荐 pnpm workspace。
|
||
|
||
根命令：
|
||
|
||
```bash
|
||
pnpm install
|
||
pnpm lint
|
||
pnpm typecheck
|
||
pnpm test
|
||
pnpm build
|
||
```
|
||
|
||
必须保证 CI 与本地命令一致。
|
||
|
||
---
|
||
|
||
## 2. 包管理
|
||
|
||
- 锁定 package manager 版本；
|
||
- 提交 lockfile；
|
||
- 不混 npm/yarn/pnpm；
|
||
- 国内开发可配置可靠 npm 镜像，但源码不得依赖私有个人镜像；
|
||
- CI 应支持官方源回退。
|
||
|
||
---
|
||
|
||
## 3. TypeScript
|
||
|
||
- strict: true
|
||
- 禁止大面积 any
|
||
- 禁止 `@ts-ignore` 掩盖错误；特殊情况写原因
|
||
- API contracts 明确类型
|
||
- 日期统一 ISO 8601
|
||
|
||
---
|
||
|
||
## 4. Git
|
||
|
||
分支：
|
||
|
||
- main
|
||
- develop（可选）
|
||
- feature/*
|
||
- fix/*
|
||
- chore/*
|
||
|
||
Commit 建议 Conventional Commits。
|
||
|
||
每个 PR：
|
||
|
||
- 变更摘要
|
||
- 测试结果
|
||
- 截图（UI）
|
||
- migration 说明
|
||
- 风险
|
||
- 回滚方案
|
||
|
||
---
|
||
|
||
## 5. 环境变量
|
||
|
||
`.env.example` 只能放占位符。
|
||
|
||
示例：
|
||
|
||
```env
|
||
APP_ENV=development
|
||
DATABASE_URL=
|
||
REDIS_URL=
|
||
WECHAT_APP_ID=
|
||
WECHAT_APP_SECRET=
|
||
COS_BUCKET=
|
||
COS_REGION=
|
||
COS_SECRET_ID=
|
||
COS_SECRET_KEY=
|
||
SESSION_SECRET=
|
||
FIELD_ENCRYPTION_KEY=
|
||
```
|
||
|
||
真实密钥不得入 Git。
|
||
|
||
---
|
||
|
||
## 6. 数据库 Migration
|
||
|
||
规则：
|
||
|
||
- 每次 schema 修改一份 migration；
|
||
- migration 可审查；
|
||
- 生产不允许 ORM 自动 `synchronize=true`；
|
||
- 大表变更考虑锁；
|
||
- destructive migration 分阶段。
|
||
|
||
---
|
||
|
||
## 7. 代码质量
|
||
|
||
函数：
|
||
|
||
- 单一职责；
|
||
- 复杂度高就拆；
|
||
- 业务规则命名表达含义；
|
||
- 不写 1000 行 service；
|
||
- 不复制粘贴权限逻辑。
|
||
|
||
必须有：
|
||
|
||
- lint
|
||
- format
|
||
- typecheck
|
||
- unit test
|
||
- integration test
|
||
|
||
---
|
||
|
||
## 8. 错误处理
|
||
|
||
后端：
|
||
|
||
- 业务错误使用统一 Domain/Application Error；
|
||
- 未预期错误不把 stack 返回用户；
|
||
- requestId 贯穿。
|
||
|
||
前端：
|
||
|
||
- 业务错误直接友好提示；
|
||
- 网络错误可重试；
|
||
- 401 统一重新登录；
|
||
- 403 明确无权限；
|
||
- 5xx 提供 requestId。
|
||
|
||
---
|
||
|
||
## 9. 第三方依赖
|
||
|
||
新增依赖前：
|
||
|
||
1. 是否真有必要？
|
||
2. 是否长期维护？
|
||
3. License 是否可用？
|
||
4. 是否显著增大 bundle？
|
||
5. 是否国内网络可获取？
|
||
6. 能否用现有依赖实现？
|
||
|
||
避免“为了 10 行代码引入一个包”。
|
||
|
||
---
|
||
|
||
## 10. Codex 禁止行为
|
||
|
||
- 不读文档直接重构；
|
||
- 看到旧代码就全量重写；
|
||
- 为通过测试删除测试；
|
||
- 用 mock 替代真实功能后宣称完成；
|
||
- 注释掉权限；
|
||
- 关闭类型检查；
|
||
- `catch {}` 吞错误；
|
||
- 生产环境 hardcode；
|
||
- 把敏感值写 fixtures；
|
||
- 删除 migration 历史；
|
||
- 改 API 不更新前端和 contracts；
|
||
- 自己决定产品删减。
|
||
|
||
---
|
||
|
||
## 11. Definition of Done
|
||
|
||
一个任务只有同时满足以下条件才算完成：
|
||
|
||
- 功能实现；
|
||
- 正常路径测试；
|
||
- 异常路径测试；
|
||
- 权限测试；
|
||
- 数据 migration 完成；
|
||
- 文档更新；
|
||
- lint 通过；
|
||
- typecheck 通过；
|
||
- test 通过；
|
||
- build 通过；
|
||
- 无新 High/Critical 漏洞；
|
||
- `10_TASK_STATE.md` 已回写。
|
||
|
||
<!-- FILE: 09_TEST_ACCEPTANCE.md -->
|
||
|
||
# 09 测试与验收
|
||
|
||
## 1. 测试金字塔
|
||
|
||
### Unit
|
||
|
||
业务规则、状态机、权限策略、计算。
|
||
|
||
### Integration
|
||
|
||
API + DB，重点测试事务、唯一约束、权限和状态流转。
|
||
|
||
### E2E
|
||
|
||
关键业务闭环。
|
||
|
||
---
|
||
|
||
## 2. P0 E2E 场景
|
||
|
||
### E2E-001 本人申请
|
||
|
||
用户登录 → 选择老年服务 → 填写需求 → 提交 → 获得编号 → 我的申请可见。
|
||
|
||
### E2E-002 防重复
|
||
|
||
用户连续点击提交两次 → 只能产生一个业务申请。
|
||
|
||
### E2E-003 代申请
|
||
|
||
家属为老人申请 → 正确保存申请人与服务对象关系。
|
||
|
||
### E2E-004 工作人员受理
|
||
|
||
工作人员登录 → 查看待处理 → 联系/评估 → 建档 → 受理 → 创建工单。
|
||
|
||
### E2E-005 服务执行
|
||
|
||
负责人 → 开始服务 → 添加两条服务记录 → 完成 → 自动生成回访任务。
|
||
|
||
### E2E-006 回访继续帮扶
|
||
|
||
回访选择“需要继续帮助” → 生成关联后续任务/申请，原历史不丢失。
|
||
|
||
### E2E-007 越权
|
||
|
||
志愿者 A 访问志愿者 B 的工单 → 403。
|
||
|
||
### E2E-008 用户越权
|
||
|
||
用户 A 猜测用户 B 的 public_id → 404/403，不泄露存在性。
|
||
|
||
### E2E-009 活动报名
|
||
|
||
报名 → 重复报名被唯一约束阻止 → 人数达到上限后不可继续报名。
|
||
|
||
### E2E-010 文件
|
||
|
||
允许图片上传；exe/php/html 等危险类型拒绝；超限拒绝；私有文件无授权无法下载。
|
||
|
||
---
|
||
|
||
## 3. 安全验收
|
||
|
||
必须测试：
|
||
|
||
- IDOR
|
||
- broken access control
|
||
- mass assignment
|
||
- SQLi
|
||
- stored/reflected XSS
|
||
- CSRF（后台）
|
||
- upload bypass
|
||
- rate limit
|
||
- brute force
|
||
- token expiry
|
||
- session fixation
|
||
- sensitive log leakage
|
||
|
||
---
|
||
|
||
## 4. 可靠性验收
|
||
|
||
模拟：
|
||
|
||
- Redis 不可用；
|
||
- COS 暂时失败；
|
||
- 微信消息发送失败；
|
||
- 数据库瞬时错误；
|
||
- 客户端重复请求；
|
||
- 网络超时。
|
||
|
||
要求：
|
||
|
||
- 主业务不产生半状态；
|
||
- 可重试；
|
||
- 失败可追踪；
|
||
- UI 不假成功。
|
||
|
||
---
|
||
|
||
## 5. 性能目标（V1 建议基线）
|
||
|
||
不是大型互联网项目，不盲目追极限。
|
||
|
||
建议：
|
||
|
||
- 常规 API P95 < 500ms（不含第三方和大文件）
|
||
- 后台列表首屏合理数据量 < 2s
|
||
- 小程序首页优先内容快速可见
|
||
- 100 并发常规请求下无明显错误率上升
|
||
- 数据库常用列表避免 N+1
|
||
|
||
具体目标可根据云资源实测调整。
|
||
|
||
---
|
||
|
||
## 6. UAT 验收人员
|
||
|
||
至少模拟：
|
||
|
||
- 65+ 老年服务对象
|
||
- 家属代申请
|
||
- 普通工作人员
|
||
- 项目负责人
|
||
- 志愿者
|
||
- 管理员
|
||
|
||
UAT 不只让开发人员自测。
|
||
|
||
---
|
||
|
||
## 7. V1 上线门槛
|
||
|
||
必须全部满足：
|
||
|
||
- P0 E2E 全通过；
|
||
- 无 Critical/High 已知安全漏洞；
|
||
- 备份成功；
|
||
- 恢复演练通过；
|
||
- staging 走完整闭环；
|
||
- 隐私政策/授权页面就绪；
|
||
- 微信小程序审核所需材料就绪；
|
||
- 监控和告警正常；
|
||
- 可回滚上一版本。
|
||
|
||
<!-- FILE: 10_TASK_STATE.md -->
|
||
|
||
# 10 任务状态（Codex 每次必须维护）
|
||
|
||
> 这是项目“长记忆”的核心文件之一。禁止删除历史，仅更新状态并添加记录。
|
||
|
||
## 当前阶段
|
||
|
||
`PHASE_0 - 仓库初始化与技术基线`
|
||
|
||
## 当前版本目标
|
||
|
||
`V1.0 MVP：跑通公益服务主闭环`
|
||
|
||
---
|
||
|
||
## 阶段任务
|
||
|
||
### Phase 0：工程初始化
|
||
|
||
- [ ] 建立 monorepo
|
||
- [ ] 建立 miniprogram
|
||
- [ ] 建立 admin-web
|
||
- [ ] 建立 api
|
||
- [ ] 建立 shared contracts
|
||
- [ ] Docker Compose 本地环境
|
||
- [ ] MySQL / Redis / MinIO
|
||
- [ ] ESLint / Prettier / TSConfig
|
||
- [ ] CI
|
||
- [ ] health check
|
||
- [ ] 环境变量模板
|
||
- [ ] AGENTS.md
|
||
|
||
### Phase 1：认证与权限
|
||
|
||
- [ ] 微信登录
|
||
- [ ] 后台登录
|
||
- [ ] user
|
||
- [ ] RBAC
|
||
- [ ] resource policy
|
||
- [ ] audit baseline
|
||
|
||
### Phase 2：服务申请
|
||
|
||
- [ ] 服务分类
|
||
- [ ] 本人申请
|
||
- [ ] 代申请
|
||
- [ ] 我的申请
|
||
- [ ] 状态历史
|
||
- [ ] 防重复提交
|
||
- [ ] 后台申请列表/详情
|
||
|
||
### Phase 3：服务对象与工单
|
||
|
||
- [ ] beneficiary 档案
|
||
- [ ] 联系人/监护人
|
||
- [ ] 标签
|
||
- [ ] 工单
|
||
- [ ] 分配工作人员
|
||
- [ ] 志愿者协作
|
||
- [ ] 服务记录
|
||
- [ ] 附件
|
||
|
||
### Phase 4：回访闭环
|
||
|
||
- [ ] 回访任务
|
||
- [ ] 自动创建
|
||
- [ ] 完成回访
|
||
- [ ] 继续帮扶
|
||
- [ ] 工作台待办
|
||
|
||
### Phase 5：公益项目/活动/志愿者
|
||
|
||
- [ ] 项目 CRUD/发布
|
||
- [ ] 活动
|
||
- [ ] 活动报名
|
||
- [ ] 志愿者申请/审核
|
||
- [ ] 服务时长
|
||
|
||
### Phase 6：内容与通知
|
||
|
||
- [ ] 公益动态
|
||
- [ ] 机构介绍
|
||
- [ ] 内容审核状态
|
||
- [ ] 站内消息
|
||
- [ ] 微信订阅通知 Adapter
|
||
|
||
### Phase 7：统计、安全与上线
|
||
|
||
- [ ] 基础统计
|
||
- [ ] 导出
|
||
- [ ] 权限扫描
|
||
- [ ] 安全测试
|
||
- [ ] 备份恢复
|
||
- [ ] staging
|
||
- [ ] UAT
|
||
- [ ] production deployment
|
||
|
||
---
|
||
|
||
## 当前正在处理
|
||
|
||
暂无。Codex 第一次执行时填写。
|
||
|
||
---
|
||
|
||
## 最近完成记录
|
||
|
||
格式：
|
||
|
||
```text
|
||
YYYY-MM-DD
|
||
任务：
|
||
完成：
|
||
测试：
|
||
涉及 migration：
|
||
文档变化：
|
||
遗留问题：
|
||
```
|
||
|
||
---
|
||
|
||
## 已知问题
|
||
|
||
首次开发为空。任何未解决问题必须写这里，禁止只留在聊天上下文。
|
||
|
||
---
|
||
|
||
## 下一步
|
||
|
||
从 Phase 0 依次执行。禁止跳到 AI、地图、复杂报表等后续功能。
|
||
|
||
<!-- FILE: 11_DECISIONS.md -->
|
||
|
||
# 11 架构与产品决策日志（ADR 简化版）
|
||
|
||
> Codex 不得删除已批准决策。新决策追加。
|
||
|
||
## D-001 产品架构
|
||
|
||
状态：ACCEPTED
|
||
|
||
决定：
|
||
V1 使用“微信小程序 + Web 管理后台 + 单体 API + MySQL + Redis + 对象存储”。
|
||
|
||
原因：
|
||
低复杂度、易部署、易维护、适合当前组织规模。
|
||
|
||
---
|
||
|
||
## D-002 后端架构
|
||
|
||
状态：ACCEPTED
|
||
|
||
决定：
|
||
模块化单体，不采用微服务。
|
||
|
||
触发重新评估条件：
|
||
|
||
- 单体部署已形成明确性能瓶颈；
|
||
- 团队规模显著扩大；
|
||
- 某模块有独立扩容/安全隔离的客观需求。
|
||
|
||
---
|
||
|
||
## D-003 主技术语言
|
||
|
||
状态：ACCEPTED
|
||
|
||
决定：
|
||
优先 TypeScript 全栈。
|
||
|
||
原因：
|
||
前后端共享类型、Codex 开发一致性高、维护人员切换成本较低。
|
||
|
||
---
|
||
|
||
## D-004 数据库
|
||
|
||
状态：ACCEPTED
|
||
|
||
决定：
|
||
MySQL 作为业务事实数据库。
|
||
Redis 不保存不可恢复的唯一业务事实。
|
||
|
||
---
|
||
|
||
## D-005 文件
|
||
|
||
状态：ACCEPTED
|
||
|
||
决定：
|
||
生产文件进入私有对象存储，通过授权临时访问；不持久化在应用容器本地盘。
|
||
|
||
---
|
||
|
||
## D-006 V1 范围
|
||
|
||
状态：ACCEPTED
|
||
|
||
决定：
|
||
V1 首先实现服务闭环、志愿者、项目活动、内容和基础统计，不做复杂 AI、地图、公开募捐、自研 IM。
|
||
|
||
---
|
||
|
||
## D-007 隐私
|
||
|
||
状态：ACCEPTED
|
||
|
||
决定：
|
||
个人敏感信息采取最小收集、最小权限、默认脱敏、操作审计；儿童相关信息更严格。
|
||
|
||
---
|
||
|
||
## D-008 UI
|
||
|
||
状态：ACCEPTED
|
||
|
||
决定：
|
||
优先普通群众与适老使用，不追求炫技。
|
||
|
||
---
|
||
|
||
## 待确认建议
|
||
|
||
Codex 若有会改变已批准架构的建议，只能写在这里，不得直接实施：
|
||
|
||
```text
|
||
[PENDING]
|
||
日期：
|
||
建议：
|
||
原因：
|
||
收益：
|
||
风险：
|
||
迁移成本：
|
||
需要用户确认：
|
||
```
|
||
|
||
<!-- FILE: 12_CODEX_MASTER_PROMPT.md -->
|
||
|
||
# 12 可直接交给 Codex 的总指令
|
||
|
||
你现在是“乐活公益·暖心服务平台”的主开发工程师、架构维护者和测试负责人。
|
||
|
||
你的目标不是一次生成大量代码，而是在整个项目周期中持续、准确、可验证地完成系统。
|
||
|
||
## 一、第一原则
|
||
|
||
在写任何代码之前，必须完整阅读 `docs/` 中的项目文档，特别是：
|
||
|
||
- 00_README_FIRST.md
|
||
- 01_PROJECT_CONSTITUTION.md
|
||
- 10_TASK_STATE.md
|
||
- 11_DECISIONS.md
|
||
|
||
项目文档是当前事实来源。聊天上下文只能补充，不能覆盖已批准规则，除非用户明确要求修改。
|
||
|
||
## 二、记忆协议
|
||
|
||
每次任务开始：
|
||
|
||
1. 读取项目开发宪法；
|
||
2. 读取当前任务状态；
|
||
3. 读取决策日志；
|
||
4. 检查 Git diff；
|
||
5. 确定任务属于哪个 Phase；
|
||
6. 输出本次实现范围，不扩大范围。
|
||
|
||
每次任务结束：
|
||
|
||
1. 运行 lint；
|
||
2. 运行 typecheck；
|
||
3. 运行 unit tests；
|
||
4. 运行 integration tests；
|
||
5. 运行 build；
|
||
6. 需要时运行 E2E；
|
||
7. 更新 `10_TASK_STATE.md`；
|
||
8. 更新 `11_DECISIONS.md`（如有）；
|
||
9. 更新 API/DB 文档；
|
||
10. 汇报“完成内容 / 未完成内容 / 测试结果 / 风险 / 下一步”。
|
||
|
||
如果上下文不足：
|
||
优先从仓库文档和代码中恢复，而不是凭空假设。
|
||
|
||
## 三、禁止行为
|
||
|
||
你绝对不能：
|
||
|
||
- 擅自改产品方向；
|
||
- 删除业务需求来降低开发难度；
|
||
- 重写整个项目只因为你更喜欢另一套技术；
|
||
- 擅自换数据库；
|
||
- 擅自改认证方案；
|
||
- 跳过权限；
|
||
- 跳过 migration；
|
||
- 跳过测试；
|
||
- 用 mock 冒充生产功能；
|
||
- 写死生产密钥；
|
||
- 把敏感信息写日志；
|
||
- 把所有业务逻辑堆在 Controller；
|
||
- 让前端权限判断代替后端鉴权；
|
||
- 使用连续 ID 作为面向用户的资源标识；
|
||
- 对服务对象数据做无授权公开；
|
||
- 开发未批准的 AI 自动决策能力。
|
||
|
||
## 四、编码优先级
|
||
|
||
顺序永远是：
|
||
|
||
1. 正确性
|
||
2. 安全
|
||
3. 数据一致性
|
||
4. 用户可理解
|
||
5. 可维护
|
||
6. 可测试
|
||
7. 性能
|
||
8. 开发速度
|
||
9. 技术“先进程度”
|
||
|
||
## 五、实现策略
|
||
|
||
不要一次开发所有功能。
|
||
|
||
严格按 `10_TASK_STATE.md` Phase 执行。
|
||
|
||
一个 Phase 的 P0 测试不通过，不进入下一个 Phase。
|
||
|
||
## 六、发生冲突时
|
||
|
||
如果新需求与项目宪法冲突：
|
||
|
||
- 不静默修改；
|
||
- 说明冲突点；
|
||
- 在 `11_DECISIONS.md` 建 PENDING 项；
|
||
- 等用户明确批准后再改变。
|
||
|
||
如果是不会改变边界的小实现细节，可自行采用最简单可靠方案，并记录重要决定。
|
||
|
||
## 七、安全要求
|
||
|
||
本项目处理弱势群体和未成年人相关信息。
|
||
|
||
任何时候都按：
|
||
|
||
- 最小收集
|
||
- 最小权限
|
||
- 默认脱敏
|
||
- 完整审计
|
||
- 私有文件
|
||
- 后端鉴权
|
||
- 不信任客户端
|
||
- 不信任用户输入
|
||
- 不信任第三方回调
|
||
- 不信任 AI 输出
|
||
|
||
执行。
|
||
|
||
## 八、完成标准
|
||
|
||
“页面能打开”不是完成。
|
||
“接口返回 200”不是完成。
|
||
“我写了代码但没运行测试”不是完成。
|
||
|
||
完成必须符合 `08_ENGINEERING_RULES.md` 的 Definition of Done 和 `09_TEST_ACCEPTANCE.md`。
|
||
|
||
## 九、第一次任务
|
||
|
||
请从 Phase 0 开始：
|
||
|
||
1. 初始化 monorepo；
|
||
2. 创建 `apps/miniprogram`；
|
||
3. 创建 `apps/admin-web`；
|
||
4. 创建 `apps/api`；
|
||
5. 创建 `packages/contracts`；
|
||
6. 建立本地 Docker Compose：MySQL、Redis、MinIO；
|
||
7. 建立统一 lint/typecheck/test/build；
|
||
8. 创建 `/health`；
|
||
9. 创建 `.env.example`；
|
||
10. 创建根目录 `AGENTS.md`；
|
||
11. 创建 CI；
|
||
12. 运行全部命令并修复问题；
|
||
13. 更新 `docs/10_TASK_STATE.md`；
|
||
14. 不开发业务功能，等待 Phase 1。
|
||
|
||
完成后只汇报：
|
||
|
||
- 新增/修改文件
|
||
- 本地启动方式
|
||
- 测试命令和结果
|
||
- 已知问题
|
||
- 下一步 Phase 1 计划
|
||
|
||
不要自行开始 Phase 1。
|
||
|
||
<!-- FILE: 13_DEPLOYMENT_CHINA.md -->
|
||
|
||
# 13 国内环境部署与运维
|
||
|
||
## 1. 目标
|
||
|
||
- 中国大陆访问稳定；
|
||
- 微信小程序合法域名可配置；
|
||
- TLS；
|
||
- 低维护成本；
|
||
- 可迁移；
|
||
- 可备份；
|
||
- 可回滚。
|
||
|
||
---
|
||
|
||
## 2. 推荐生产拓扑（初期）
|
||
|
||
```text
|
||
微信小程序
|
||
│ HTTPS
|
||
▼
|
||
Nginx / API Domain
|
||
│
|
||
▼
|
||
NestJS API (Docker)
|
||
├── MySQL
|
||
├── Redis
|
||
└── Tencent COS
|
||
|
||
管理后台
|
||
│ HTTPS
|
||
└────────► Nginx / API
|
||
```
|
||
|
||
管理后台静态资源可由 Nginx 或对象存储/CDN 托管。
|
||
|
||
---
|
||
|
||
## 3. 云厂商
|
||
|
||
优先腾讯云并非代码强绑定要求，而是微信生态和国内运维便利性考虑。
|
||
|
||
代码必须通过 Adapter 保持：
|
||
|
||
- COS 可替换 S3 兼容存储；
|
||
- Redis 可替换其他标准 Redis；
|
||
- MySQL 可迁移标准 MySQL；
|
||
- Nginx/Docker 不绑定专有 PaaS。
|
||
|
||
---
|
||
|
||
## 4. 国内依赖获取
|
||
|
||
开发机可根据实际环境配置：
|
||
|
||
- npm 国内镜像；
|
||
- Docker 镜像加速；
|
||
- 操作系统软件源镜像。
|
||
|
||
但：
|
||
|
||
- lockfile 必须提交；
|
||
- CI 至少验证标准 registry 可构建；
|
||
- 不依赖个人私服；
|
||
- 不在代码写死镜像地址。
|
||
|
||
---
|
||
|
||
## 5. 环境
|
||
|
||
### dev
|
||
|
||
开发者本机 Docker Compose。
|
||
|
||
### test
|
||
|
||
CI 自动化测试。
|
||
|
||
### staging
|
||
|
||
与生产拓扑尽量一致，使用测试小程序/测试账号。
|
||
|
||
### prod
|
||
|
||
真实用户。
|
||
|
||
严禁 dev 直连 prod 数据库。
|
||
|
||
---
|
||
|
||
## 6. 发布
|
||
|
||
建议：
|
||
|
||
1. CI build；
|
||
2. 生成 immutable image tag；
|
||
3. staging deploy；
|
||
4. migration precheck；
|
||
5. smoke test；
|
||
6. production backup；
|
||
7. production deploy；
|
||
8. health check；
|
||
9. E2E smoke；
|
||
10. 观察；
|
||
11. 出现严重问题回滚应用版本。
|
||
|
||
数据库 migration 必须设计可前后兼容，避免应用回滚后数据库不兼容。
|
||
|
||
---
|
||
|
||
## 7. 监控
|
||
|
||
至少：
|
||
|
||
- API availability
|
||
- 5xx rate
|
||
- P95 latency
|
||
- CPU/memory
|
||
- disk
|
||
- MySQL connection
|
||
- Redis connectivity
|
||
- job failures
|
||
- backup failures
|
||
|
||
告警进入实际有人查看的渠道。
|
||
|
||
---
|
||
|
||
## 8. 容灾
|
||
|
||
初期无需昂贵双活，但必须：
|
||
|
||
- 自动数据库备份；
|
||
- 异地/云端备份；
|
||
- IaC/部署脚本；
|
||
- Docker 镜像可重建；
|
||
- 文档化恢复；
|
||
- 定期演练。
|
||
|
||
---
|
||
|
||
## 9. 微信小程序上线准备
|
||
|
||
实际申请和上线阶段需要根据微信公众平台最新规则核对：
|
||
|
||
- 小程序主体
|
||
- 服务类目
|
||
- 隐私保护指引
|
||
- 用户信息/手机号等接口使用说明
|
||
- request/download/upload 合法域名
|
||
- HTTPS 证书
|
||
- 备案/域名要求
|
||
- 订阅消息模板
|
||
- 审核材料
|
||
|
||
微信平台规则可能变化，因此上线前必须重新查官方文档，不得只依赖本文件。
|
||
|
||
<!-- FILE: 14_RELEASE_CHECKLIST.md -->
|
||
|
||
# 14 发布检查清单
|
||
|
||
## 代码
|
||
|
||
- [ ] main branch clean
|
||
- [ ] lockfile committed
|
||
- [ ] lint pass
|
||
- [ ] typecheck pass
|
||
- [ ] unit pass
|
||
- [ ] integration pass
|
||
- [ ] E2E P0 pass
|
||
- [ ] build pass
|
||
|
||
## 数据库
|
||
|
||
- [ ] migration reviewed
|
||
- [ ] backup done
|
||
- [ ] rollback compatibility checked
|
||
- [ ] indexes reviewed
|
||
|
||
## 安全
|
||
|
||
- [ ] secrets scan
|
||
- [ ] dependency scan
|
||
- [ ] auth test
|
||
- [ ] IDOR test
|
||
- [ ] export permission test
|
||
- [ ] file upload test
|
||
- [ ] logs checked for PII
|
||
|
||
## 隐私
|
||
|
||
- [ ] privacy policy version correct
|
||
- [ ] consent flow correct
|
||
- [ ] children/guardian flow checked
|
||
- [ ] sensitive list fields masked
|
||
- [ ] retention configuration checked
|
||
|
||
## 微信
|
||
|
||
- [ ] legal domains
|
||
- [ ] HTTPS
|
||
- [ ] privacy declarations
|
||
- [ ] API permissions
|
||
- [ ] subscribe message handling
|
||
- [ ] real device test
|
||
|
||
## 运维
|
||
|
||
- [ ] health
|
||
- [ ] monitor
|
||
- [ ] alert
|
||
- [ ] backup
|
||
- [ ] restore procedure
|
||
- [ ] rollback image available
|
||
|
||
## UAT
|
||
|
||
- [ ] 本人申请
|
||
- [ ] 代申请
|
||
- [ ] 受理
|
||
- [ ] 建档
|
||
- [ ] 派单
|
||
- [ ] 服务
|
||
- [ ] 回访
|
||
- [ ] 继续帮扶
|
||
- [ ] 志愿者
|
||
- [ ] 活动报名
|
||
|
||
<!-- FILE: AGENTS_TEMPLATE.md -->
|
||
|
||
# AGENTS.md
|
||
|
||
Before coding, read:
|
||
|
||
1. docs/00_README_FIRST.md
|
||
2. docs/01_PROJECT_CONSTITUTION.md
|
||
3. docs/10_TASK_STATE.md
|
||
4. docs/11_DECISIONS.md
|
||
5. task-related docs
|
||
|
||
Rules:
|
||
|
||
- Do not change approved product scope or architecture without explicit approval.
|
||
- Do not bypass authorization, migrations, tests, or audit requirements.
|
||
- Do not log sensitive beneficiary data.
|
||
- Do not expose sequential internal IDs.
|
||
- Update docs/10_TASK_STATE.md after every task.
|
||
- Update docs/11_DECISIONS.md for architecture/product decisions.
|
||
- Run lint, typecheck, tests and build before marking work complete.
|