Преглед изворни кода

docs: 登记DOA接口+统一能登录/不能登录用户口径规范

Sisyphus пре 1 месец
родитељ
комит
98db1253fa
3 измењених фајлова са 27 додато и 1 уклоњено
  1. 6 0
      AGENTS.md
  2. 6 0
      cfc-backend/AGENTS.md
  3. 15 1
      docs/superpowers/api/API_REFERENCE.md

+ 6 - 0
AGENTS.md

@@ -90,6 +90,12 @@ opencode web --port 4090 --hostname 127.0.0.1
 - **环境自适应:** 小程序 `config.js` 通过 `uni.getAccountInfoSync()` 自动切换 develop/trial/release 的 API 地址
 - **测试模式:** `wechat.test-mode: true` 跳过微信 API,使用模拟数据
 
+## 用户模型统一口径
+
+- **能登录用户**:`family_members.userId` 非空且关联 User 有 openid(VO 层 `memberType=login`)
+- **不能登录用户**(历史称"孩子"):`family_members.userId` 为空或关联 User 无 openid(VO 层 `memberType=local`),由同家庭能登录用户代管其数据(任务/健康/DOA 等)
+- 新功能禁止再引入"孩子"概念,统一用"能登录用户/不能登录用户"表述
+
 ## cfclub 新特性
 
 - 家庭邀请二维码(小程序码+令牌+落地页)

+ 6 - 0
cfc-backend/AGENTS.md

@@ -51,6 +51,12 @@ Spring Boot 2.7.18 后端服务,MyBatis-Plus ORM,JWT 认证。
 - **Bean名冲突检查:** 新增 Controller/Service 时,确保类名不与其他包中的类重名(Spring 默认 Bean Name 为类名首字母小写)
 - **身份标识:** `userId`=登录账号(`users.id`)、`memberId`/`familyMemberId`/`currentMemberId`=家庭成员(`family_members.id`)、`childId`=遗留表(`children.id`);账号自身/交易/权限判断用 userId,成员/孩子数据(任务/健康/成长/关系/五维能量)用 memberId;`JwtInterceptor` 按 `userId+familyId` 自动反查 `currentMemberId`(始终是登录账号自己),**切换视角不改变 currentMemberId**,靠前端显式传 `memberId` 参数覆盖;新功能禁止新增 `childId` 引用(详见 `docs/architecture/userid-vs-memberid-usage-guide.md`)
 
+## 用户模型统一口径
+
+- **能登录用户**:`family_members.userId` 非空且关联 User 有 openid(VO 层 `memberType=login`)
+- **不能登录用户**(历史称"孩子"):`family_members.userId` 为空或关联 User 无 openid(VO 层 `memberType=local`),由同家庭能登录用户代管其数据(任务/健康/DOA 等)
+- 新功能禁止再引入"孩子"概念,统一用"能登录用户/不能登录用户"表述
+
 ## ANTI-PATTERNS (本项目禁止)
 
 - **DO NOT** 在 Controller 直接操作 Mapper

+ 15 - 1
docs/superpowers/api/API_REFERENCE.md

@@ -1196,6 +1196,20 @@ interactionType 取值:`PHONE` / `WECHAT` / `MEETING` / `OTHER`。
 
 > **已记录关键人拓展 API 端点 — 禁止重复注册。**
 
+### 4.41 DOA 个人目标(家庭打卡个人目标模块)
+
+| 路径 | 说明 |
+|------|------|
+| `POST /api/doa/stage/create` | 创建阶段(memberId?+title+durationWeeks+goals[1-3]) |
+| `POST /api/doa/overview` | 家庭总览:各成员当前 active 阶段 |
+| `POST /api/doa/stage/detail` | 阶段详情:stage + goals + weeks |
+| `POST /api/doa/stage/cancel` | 取消阶段(仅 active 可取消) |
+| `POST /api/doa/week/plan` | 提交周计划(A表周行动宣告) |
+| `POST /api/doa/week/review` | 提交周复盘(B表五问) |
+| `POST /api/doa/week/list` | 周记录列表(按阶段查周记录) |
+
+> **已记录 DOA 个人目标 API 端点 — 禁止重复注册。**
+
 ## 六、待清理的废弃接口
 
 | Controller | 废弃接口 | 替代方案 | 当前状态 | 清理条件 |
@@ -1265,4 +1279,4 @@ interactionType 取值:`PHONE` / `WECHAT` / `MEETING` / `OTHER`。
 
 ---
 
-*文档最后更新:2026-09-09*
+*文档最后更新:2026-09-13*