mirror of https://gitee.com/ulthon/ulthon_information.git synced 2026-07-01 14:52:48 +08:00

Files

augushong 0e8944bc7f docs: 为 category-api 和 apikey-article-api 添加项目笔记文件

- 添加 category-api 的 problems、decisions、learnings、issues 文档
- 添加 apikey-article-api 的 issues、decisions、learnings 文档
- 包含架构决策、问题记录和学习总结

2026-04-28 21:03:15 +08:00

54 KiB

Raw Blame History

API Key 管理与文章/附件 API

TL;DR

Quick Summary: 为现有 ThinkPHP 6 CMS 添加 API Key 认证机制，后台管理员可管理自己的 API Key，通过 API Key 调用 RESTful 接口完成文章完整 CRUD 和附件完整管理（上传/列表/删除）。

Deliverables:

数据库迁移文件：ul_api_key 表

ApiKey 模型

ApiKeyAuth 中间件（Header 认证）

文章 API 控制器（列表/详情/创建/编辑/删除）

附件 API 控制器（上传/列表/删除）

后台 API Key 管理控制器 + layui 视图

API 中间件注册文件

Estimated Effort: Medium Parallel Execution: YES - 3 waves Critical Path: 迁移+模型 → 中间件 → API控制器 → 后台管理

Context

Original Request

后台可以管理 API Key，使用 API Key 可以管理文章（列表、发表文章、上传附件等）。

Interview Summary

Key Discussions:

API Key 粒度：每个管理员一个 API Key
权限控制：拥有 Key 即有全部文章管理权限，无需分级
过期策略：永不过期，手动禁用/启用
文章操作：列表+详情(所有Key); 创建+编辑自己(can_write_own=1); 编辑后台(can_write_other=1); 删除(can_delete控制)
附件管理：列表(所有Key); 上传(can_write_own=1); 删除(can_delete控制)
数据查询：所有数据不分来源
权限模型：三字段（can_write_own/can_write_other/can_delete），每个Key独立控制
有删除接口，删除权限由 can_delete 字段控制
source 字段用于权限判断和数据隔离
测试策略：不需要搭建测试基础设施

Research Findings:

现有 API 控制器（3个）均无认证，继承 BaseController
API 路由完全依赖 TP6 自动路由 /api/{controller}/{action}
不存在 app/api/middleware.php，需新建
Post 模型使用 SoftDelete + AutoClearCache，关联 categorys/tags/comments
文件上传使用 app/UploadFiles.php 静态服务类
响应格式：{ code: 0/500, msg: '', data: {} } 通过 json_message()
迁移使用 ColumnFormat 辅助类，时间戳 int(10)

Metis Review

Identified Gaps (addressed):

API Key 安全存储：数据库中存储 md5 哈希而非明文，仅在创建时展示一次原文
管理员被删除时的 API Key 处理：通过 admin_id 外键关联，管理员删除时 API Key 自动禁用
现有 API 控制器不受影响：中间件仅应用于需要认证的路由/控制器
防止重复提交：创建文章时生成 uid 防止重复
附件类型校验：复用现有 UploadFiles::fileScan() 安全扫描

Work Objectives

Core Objective

为 CMS 系统增加 API Key 认证体系，使外部客户端可以通过 API Key 认证后调用 RESTful API 管理文章和附件。

Concrete Deliverables

database/migrations/ 新增 ul_api_key 表迁移 + post/upload_files 表加 source 字段迁移
app/model/ApiKey.php - API Key 模型
app/middleware/ApiKeyAuth.php - API Key 认证中间件
app/api/middleware.php - API 应用中间件注册
app/api/controller/Articles.php - 文章 API（列表/详情/创建/编辑，无删除）
app/api/controller/Attachments.php - 附件管理 API（上传/列表，无删除，数据隔离）
app/admin/controller/ApiKey.php - 后台 API Key 管理控制器
view/admin/api_key/ - 后台 API Key 管理 layui 视图（index.html）

Definition of Done

php think migrate:run 成功创建 ul_api_key 表（含 can_write_own/can_write_other/can_delete 字段）
后台可以查看/生成/重新生成/禁用/启用 API Key，以及设置三个权限字段
使用有效 API Key 可以查询所有文章和附件
can_write_own=1 时可以创建文章和上传附件，编辑/删除 source='api' 的数据
can_write_other=1 时可以编辑 source='admin' 的数据
can_delete=0 时不能删除任何数据
can_delete=1 时只能删除 source='api' 的数据
can_delete=2 时可以删除所有数据
使用无效/禁用的 API Key 返回 401 错误

Must Have

API Key 数据库存储 md5 哈希，创建时仅返回一次明文
所有 API 响应使用 json_message() 格式
每个 API Key 有三个独立权限字段:
- can_write_own (0/1): 能否创建和编辑 source='api' 的数据
- can_write_other (0/1): 能否编辑 source='admin' 的数据
- can_delete (0/1/2): 0=不能删除, 1=只能删API创建的, 2=可删所有
API 可以查询所有数据（文章列表/详情、附件列表），不区分来源
创建文章时自动标记 source='api'
上传附件时自动标记 source='api'
编辑文章时根据 source 和权限字段判断是否允许
删除时根据 can_delete 和 source 判断是否允许
文件上传复用现有 UploadFiles::save() 及安全扫描
后台管理界面沿用现有 layui 风格，可设置三个权限
中间件仅保护需要认证的 API 控制器
post 表和 upload_files 表添加 source 字段（默认 'admin'，API 创建时设为 'api'）

Must NOT Have (Guardrails)

不修改现有控制器或模型（只新增）
不改变现有 Session 认证体系
不引入 Rate Limiting
不引入 API Key 过期时间
不修改现有 app/UploadFiles.php 文件
不引入新前端库
不使用 $fillable 白名单

Verification Strategy (MANDATORY)

ZERO HUMAN INTERVENTION - ALL verification is agent-executed. No exceptions.

Test Decision

Infrastructure exists: NO
Automated tests: None
Framework: none
Verification method: Agent-executed QA via curl commands

QA Policy

Every task MUST include agent-executed QA scenarios. Evidence saved to .sisyphus/evidence/task-{N}-{scenario-slug}.{ext}.

API/Backend: Use Bash (curl) - Send requests, assert status + response fields
Admin UI: Use Playwright (playwright skill) - Navigate, interact, assert DOM, screenshot

Execution Strategy

Parallel Execution Waves

Wave 1 (Start Immediately - 基础设施层):
├── Task 1: 数据库迁移 - ul_api_key 表 [quick]
├── Task 2: ApiKey 模型 [quick]
└── Task 3: ApiKeyAuth 认证中间件 [quick]

Wave 2 (After Wave 1 - API 接口层，MAX PARALLEL):
├── Task 4: 文章 API 控制器 (depends: 1, 2, 3) [unspecified-high]
├── Task 5: 附件 API 控制器 (depends: 1, 2, 3) [unspecified-high]
├── Task 6: 后台 API Key 管理控制器 + 视图 (depends: 1, 2) [unspecified-high]
├── Task 7: API Key 权限查询接口 (depends: 2, 3) [quick]
└── Task 8: 前台 API 文档页面 (depends: 4, 5, 7) [unspecified-high]

Wave FINAL (After ALL tasks — 4 parallel reviews):
├── Task F1: Plan compliance audit (oracle)
├── Task F2: Code quality review (unspecified-high)
├── Task F3: Real manual QA (unspecified-high)
└── Task F4: Scope fidelity check (deep)
-> Present results -> Get explicit user okay

Critical Path: Task 1 → Task 3 → Task 4 → Task 8 → F1-F4 → user okay
Parallel Speedup: ~60% faster than sequential
Max Concurrent: 5 (Wave 2)

Dependency Matrix

Task	Depends On	Blocks	Wave
1	-	2,3,4,5,6	1
2	1	3,4,5,6,7	1
3	1,2	4,5,7	1
4	1,2,3	8,F1-F4	2
5	1,2,3	8,F1-F4	2
6	1,2	F1-F4	2
7	2,3	8	2
8	4,5,7	F1-F4	2
F1-F4	4,5,6,8	-	FINAL

Agent Dispatch Summary

Wave 1: 3 tasks - T1 → quick, T2 → quick, T3 → quick
Wave 2: 5 tasks - T4 → unspecified-high, T5 → unspecified-high, T6 → unspecified-high, T7 → quick, T8 → unspecified-high
FINAL: 4 tasks - F1 → oracle, F2 → unspecified-high, F3 → unspecified-high, F4 → deep

TODOs

1. 数据库迁移 - ul_api_key 表 + post/upload_files 表 source 字段

What to do:
- 创建迁移文件 database/migrations/{timestamp}_create_table_api_key.php
- 参照现有迁移结构（如 create_table_admin.php），使用 ColumnFormat 辅助类
- 表名: api_key（Phinx 自动加 ul_ 前缀 → ul_api_key）
- 字段设计:
  - id: 自增主键
  - admin_id: int(10) unsigned，关联管理员 ID（NOT NULL）
  - api_key: string(64)，存储 md5 哈希值（NOT NULL, UNIQUE）
  - name: stringNormal(100)，API Key 名称/备注
  - status: integerTypeStatus()，0=禁用，1=启用，默认1
  - can_write_own: integerTypeStatus()，0=不可, 1=可，默认0（能否创建和编辑API数据）
  - can_write_other: integerTypeStatus()，0=不可, 1=可，默认0（能否编辑后台数据）
  - can_delete: integerTypeStatus()，0=不可删除, 1=仅删API数据, 2=可删所有，默认0
  - create_time: timestamp，创建时间
  - update_time: timestamp，更新时间
  - delete_time: timestamp，软删除时间
- 添加索引: admin_id（普通索引）, api_key（唯一索引）
- 仅实现 change() 方法（不可逆迁移，遵循项目惯例）
- 创建迁移文件 database/migrations/{timestamp}_add_source_to_post_and_upload_files.php
- 给 post 表添加 source 字段: stringShort(30)，默认值 'admin'
- 给 upload_files 表添加 source 字段: stringShort(30)，默认值 'admin'
- source 字段用于标记数据来源：'admin'=后台创建，'api'=API创建
- 仅实现 change() 方法
Must NOT do:
- 不添加外键约束（项目无此惯例）
- 不修改现有字段
Recommended Agent Profile:
- Category: quick
  - Reason: 单个迁移文件，结构清晰，参照现有模板即可
- Skills: []
- Skills Evaluated but Omitted:
  - 无需特殊技能
Parallelization:
- Can Run In Parallel: YES (with nothing - this is the foundation)
- Parallel Group: Wave 1 (with Tasks 2)
- Blocks: Tasks 2, 3, 4, 5, 6
- Blocked By: None (can start immediately)
References:

Pattern References:
- database/migrations/20190822043811_create_table_admin.php - Admin 表迁移结构，参照此文件的迁移类结构
- database/migrations/20200418120809_create_table_post.php - Post 表迁移，参照字段定义方式
- app/common/ColumnFormat.php - 列定义辅助类，了解 stringNormal()/timestamp()/integerTypeStatus() 等方法
Why Each Reference Matters:
- Admin 迁移文件展示了本项目的标准迁移写法：类名、命名空间、change() 方法、ColumnFormat 用法
- Post 迁移展示了字段类型选择惯例
- ColumnFormat 是必用的辅助类，必须使用它定义列
Acceptance Criteria:

QA Scenarios (MANDATORY):
```
Scenario: 迁移文件创建成功并执行
  Tool: Bash
  Preconditions: 项目根目录，数据库配置正确
  Steps:
    1. 运行 `php think migrate:run`
    2. 检查输出无错误
    3. 使用 SQLite 命令检查 ul_api_key 表结构
    4. 验证字段存在: admin_id, api_key, name, status, create_time, update_time, delete_time
    5. 验证 api_key 字段有 UNIQUE 约束
    6. 检查 ul_post 表是否有 source 字段，默认值是否为 'admin'
    7. 检查 ul_upload_files 表是否有 source 字段，默认值是否为 'admin'
  Expected Result: ul_api_key 表创建成功含所有字段；post 和 upload_files 表新增 source 字段
  Failure Indicators: migrate:run 报错，或表/字段缺失
  Evidence: .sisyphus/evidence/task-1-migration-success.txt

Scenario: 回滚后重新迁移
  Tool: Bash
  Preconditions: 迁移已执行
  Steps:
    1. 运行 `php think migrate:rollback`
    2. 确认 ul_api_key 表不存在，source 字段已移除
    3. 运行 `php think migrate:run`
    4. 确认表和字段恢复
  Expected Result: 回滚后表/字段消失，重新迁移后恢复
  Failure Indicators: 回滚失败或重新迁移失败
  Evidence: .sisyphus/evidence/task-1-migration-rollback.txt
```
Commit: YES (groups with Task 2)
- Message: feat(api-key): add api_key table, model and auth middleware
- Files: database/migrations/*_create_table_api_key.php
- Pre-commit: php -l database/migrations/*_create_table_api_key.php
2. ApiKey 模型

What to do:
- 创建 app/model/ApiKey.php 模型
- 继承 app\common\model\Base（项目模型基类）
- 使用 SoftDelete trait，$defaultSoftDelete = 0
- 使用 AutoClearCache trait（项目惯例）
- 定义表名: $name = 'api_key'
- 定义关联: belongsTo(Admin::class, 'admin_id') 关联到管理员
- 添加静态方法:
  - generateKey($admin_id, $name = '', $can_write_own = 0, $can_write_other = 0, $can_delete = 0): 生成随机 API Key（32位 hex），存储 md5 哈希，返回明文 Key（仅此一次返回明文）
  - verifyKey($raw_key): 根据 md5 哈希查找 Key，检查 status=1，返回 ApiKey 模型或 null
  - regenerateKey($id): 重新生成 Key（旧 Key 失效），返回新明文 Key
- 添加实例方法:
  - canWriteOwn(): 返回 $this->can_write_own == 1
  - canWriteOther(): 返回 $this->can_write_other == 1
  - canDelete($source = null): 判断能否删除指定来源的数据
    - can_delete=0: 返回 false
    - can_delete=1: 仅当 $source=='api' 时返回 true
    - can_delete=2: 返回 true
- API Key 明文格式: ak_ + 32位随机 hex（如 ak_a1b2c3d4e5f6...），便于识别
Must NOT do:
- 不修改 Admin 模型
- 不在模型中存储明文 API Key
Recommended Agent Profile:
- Category: quick
  - Reason: 单个模型文件，逻辑简单，参照现有模型即可
- Skills: []
Parallelization:
- Can Run In Parallel: YES (with Task 1 - 可并行编写，但执行需等待迁移)
- Parallel Group: Wave 1 (with Task 1)
- Blocks: Tasks 3, 4, 5, 6
- Blocked By: Task 1 (迁移必须先执行)
References:

Pattern References:
- app/model/Admin.php - 管理员模型结构，参照模型定义、SoftDelete 用法
- app/common/model/Base.php - 模型基类，了解继承方式
- app/model/Post.php - SoftDelete + AutoClearCache trait 的使用方式（use SoftDelete; protected $defaultSoftDelete = 0;）
API/Type References:
- app/model/Admin.php - Admin 模型，用于 belongsTo 关联定义
Why Each Reference Matters:
- Admin 模型展示了本项目标准模型写法
- Base 模型展示了基类功能（AutoClearCache 已在 Base 中还是需要单独 use）
- Post 模型展示了 SoftDelete 的具体用法
Acceptance Criteria:

QA Scenarios (MANDATORY):
```
Scenario: ApiKey 模型 CRUD 和 Key 生成/验证
  Tool: Bash (php think)
  Preconditions: Task 1 迁移已执行
  Steps:
    1. 运行 php -r 测试脚本:
       "require 'vendor/autoload.php'; $app = new think\App(); $app->initialize();
       $raw = app\model\ApiKey::generateKey(1, 'test-key');
       echo 'Raw key format: ' . (preg_match('/^ak_[a-f0-9]{32}$/', $raw) ? 'OK' : 'FAIL') . PHP_EOL;
       $verified = app\model\ApiKey::verifyKey($raw);
       echo 'Verify valid: ' . ($verified ? 'OK' : 'FAIL') . PHP_EOL;
       $verified2 = app\model\ApiKey::verifyKey('ak_invalid0000000000000000000000000');
       echo 'Verify invalid: ' . ($verified2 === null ? 'OK' : 'FAIL') . PHP_EOL;"
    2. 检查输出全部为 OK
  Expected Result: Key 生成格式正确（ak_ + 32位hex），验证有效 Key 返回模型，无效 Key 返回 null
  Failure Indicators: 格式不匹配，验证逻辑错误
  Evidence: .sisyphus/evidence/task-2-model-qa.txt

Scenario: 禁用状态的 Key 无法验证
  Tool: Bash (php think)
  Preconditions: Task 1 迁移已执行
  Steps:
    1. 创建 ApiKey 并设置为 status=0
    2. 调用 verifyKey()
    3. 确认返回 null
  Expected Result: 禁用的 Key 验证失败
  Failure Indicators: 禁用 Key 仍然验证通过
  Evidence: .sisyphus/evidence/task-2-model-disabled.txt
```
Commit: YES (groups with Task 1)
- Message: feat(api-key): add api_key table, model and auth middleware
- Files: app/model/ApiKey.php
- Pre-commit: php -l app/model/ApiKey.php
3. ApiKeyAuth 认证中间件 + API 中间件注册

What to do:
- 创建 app/middleware/ApiKeyAuth.php 中间件
- 参照现有 ConfigInit.php 的 handle 签名
- 认证逻辑:
  1. 从 HTTP Header Authorization: Bearer {key} 提取 API Key
  2. 若无 Bearer 头，尝试从 X-API-Key 头获取
  3. 调用 ApiKey::verifyKey($raw_key) 验证
  4. 验证成功: 将 admin_id、api_key_id 和三个权限字段存入 Request attribute
    - $request->admin_id = $api_key->admin_id
    - $request->api_key_id = $api_key->id
    - $request->can_write_own = $api_key->can_write_own
    - $request->can_write_other = $api_key->can_write_other
    - $request->can_delete = $api_key->can_delete
  5. 验证失败: 返回 JSON {"code": 401, "msg": "API Key 无效或已禁用", "data": null}，HTTP 状态码 401
- 写操作检查在控制器中实现（不在中间件中，因为不同操作的权限逻辑不同）
- 创建 app/api/middleware.php 注册文件:
  - 注意: 仅对需要认证的控制器生效。TP6 支持在控制器中通过 $middleware 属性指定中间件
  - 方案: 在 Articles 和 Attachments 控制器中通过 protected $middleware = [ApiKeyAuth::class]; 挂载
  - 这样现有 API 控制器（Files/Captcha/WxOpen）不受影响
- 创建空的 app/api/middleware.php（为将来预留，内容为 return [];）
Must NOT do:
- 不修改现有中间件
- 不影响现有无认证的 API 控制器（Files/Captcha/WxOpen）
- 不使用 Session 进行 API 认证
Recommended Agent Profile:
- Category: quick
  - Reason: 单个中间件文件 + 一个空的注册文件，逻辑简单
- Skills: []
Parallelization:
- Can Run In Parallel: NO (需要 Task 1, 2 完成)
- Parallel Group: Wave 1 (with Tasks 1, 2，但依赖它们)
- Blocks: Tasks 4, 5
- Blocked By: Tasks 1, 2
References:

Pattern References:
- app/middleware/ConfigInit.php - 现有中间件，参照 handle($request, \Closure $next) 签名和返回格式
- app/middleware.php - 全局中间件注册格式
- app/admin/middleware.php - 应用级中间件注册格式（了解 TP6 应用中间件注册方式）
API/Type References:
- app/model/ApiKey.php (Task 2 产出) - 调用 ApiKey::verifyKey() 方法
External References:
- ThinkPHP 6 中间件文档: 控制器中间件 $middleware 属性用法
Why Each Reference Matters:
- ConfigInit 展示了本项目的标准中间件写法
- middleware.php 展示了中间件注册格式
- 需要理解 TP6 控制器级中间件挂载方式（而非全局中间件）
Acceptance Criteria:

QA Scenarios (MANDATORY):
```
Scenario: 无 API Key 请求被拒绝
  Tool: Bash (curl)
  Preconditions: 服务器运行在 127.0.0.1:8010
  Steps:
    1. curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:8010/index.php/api/articles/index
    2. 检查返回 HTTP 状态码
  Expected Result: HTTP 401, 响应体 {"code":401,"msg":"API Key 无效或已禁用","data":null}
  Failure Indicators: 返回 200 或其他非 401 状态码
  Evidence: .sisyphus/evidence/task-3-auth-nokey.txt

Scenario: 无效 API Key 被拒绝
  Tool: Bash (curl)
  Preconditions: 服务器运行中
  Steps:
    1. curl -s -H "Authorization: Bearer ak_invalid0000000000000000000000000" http://127.0.0.1:8010/index.php/api/articles/index
    2. 检查响应
  Expected Result: HTTP 401, {"code":401,"msg":"API Key 无效或已禁用","data":null}
  Failure Indicators: 返回 200
  Evidence: .sisyphus/evidence/task-3-auth-invalid.txt

Scenario: 有效 API Key 通过认证
  Tool: Bash (curl)
  Preconditions: 已通过后台或直接在数据库创建有效 API Key
  Steps:
    1. 使用有效 API Key 请求: curl -s -H "Authorization: Bearer {valid_key}" http://127.0.0.1:8010/index.php/api/articles/index
    2. 检查响应
  Expected Result: HTTP 200, {"code":0,"msg":"","data":{...}}
  Failure Indicators: 返回 401
  Evidence: .sisyphus/evidence/task-3-auth-valid.txt
```
Commit: YES (groups with Tasks 1, 2)
- Message: feat(api-key): add api_key table, model and auth middleware
- Files: app/middleware/ApiKeyAuth.php, app/api/middleware.php
- Pre-commit: php -l app/middleware/ApiKeyAuth.php

4. 文章 API 控制器（Articles）— 列表/详情/创建/编辑/删除，权限控制

What to do:

创建 app/api/controller/Articles.php，继承 app\BaseController
通过 protected $middleware = [\app\middleware\ApiKeyAuth::class]; 挂载认证中间件
实现以下方法（全部返回 json_message() 格式 JSON）:

index() - 文章列表:
- 接收 GET 参数: page(页码), limit(每页数量,默认15), type(文章类型), category_id(分类筛选), keyword(标题搜索)
- 查询: Post::with(['categorys.category', 'tags.tag']) + 条件过滤
- 按 id desc 排序，分页
- 可查看所有文章（不按 source 过滤）
- 返回: { code: 0, data: { list: [...], total: N, page: N } }
read() - 文章详情:
- 接收参数: id（文章 ID）
- 查询: Post::with(['categorys.category', 'tags.tag'])->find($id)
- 可查看所有文章详情（不按 source 过滤）
- 返回: { code: 0, data: { post: {...}, categories: [...], tags: [...] } }
- 不存在时返回: { code: 500, msg: "文章不存在" }
save() - 创建文章:
- 接收 POST JSON 数据: title(必填), content, content_html, desc, poster, type(默认"1"), status(默认0), publish_time, is_top, categorys(数组), tags(数组), author_name
- 权限检查: $request->can_write_own == 1，否则返回 403
- 自动生成 uid = uniqid()
- 设置 create_time = time(), update_time = time()
- 设置 source = 'api'（标记为 API 创建）
- 从数据中提取 categorys[] 和 tags[]，创建 PostCategory/PostTag 关联
- 返回: { code: 0, msg: "创建成功", data: { id: N, uid: "..." } }
update() - 编辑文章:
- 接收 POST JSON 数据 + id(必填)
- 查找文章，不存在返回错误
- 权限检查（根据 source 判断）:
  - 文章 source='api' → 需要 $request->can_write_own == 1
  - 文章 source='admin' → 需要 $request->can_write_other == 1
  - 无权限返回 403
- 提取 categorys[] 和 tags[]，diff 更新关联（参照 admin/Post 的 update 逻辑）
- $model_post->save($post_data)
- 返回: { code: 0, msg: "更新成功" }
delete() - 删除文章:
- 接收参数: id
- 查找文章，不存在返回错误
- 权限检查（根据 source 和 can_delete 判断）:
  - 文章 source='api' → 需要 $request->can_delete >= 1
  - 文章 source='admin' → 需要 $request->can_delete == 2
  - 无权限返回 403
- 软删除: $model_post->delete()
- 删除关联: PostCategory::where('post_id', $id)->delete() + PostTag::where('post_id', $id)->delete()
- 返回: { code: 0, msg: "删除成功" }
输入验证:
- 创建时 title 必填
- id 参数必须为正整数
- 使用 $this->validate() 或手动检查（参照项目现有风格）

Must NOT do:

不使用 Session 认证
不返回视图/HTML（纯 JSON）
不修改 Post 模型
不使用 $fillable（遵循项目惯例）
无权限时返回 403 而非静默失败

Recommended Agent Profile:

Category: unspecified-high
- Reason: 涉及完整 CRUD 逻辑，需要仔细参照现有 admin/Post 控制器的业务逻辑，中等复杂度
Skills: []

Parallelization:

Can Run In Parallel: YES (with Tasks 5, 6)
Parallel Group: Wave 2
Blocks: F1-F4
Blocked By: Tasks 1, 2, 3

References:

Pattern References:

app/admin/controller/Post.php - 核心参考，完整的文章 CRUD 实现，特别是:
- save() 方法: uid 生成、categorys/tags 提取、ModelPost::create() 流程
- update() 方法: categorys/tags diff 更新逻辑
- delete() 方法: 软删除 + 关联删除流程
- index() 方法: with 预加载、条件过滤、分页
app/api/controller/Files.php - API 控制器格式，参照继承方式和 JSON 返回

API/Type References:

app/model/Post.php - Post 模型，所有字段、关系、获取器
app/model/PostCategory.php - 文章分类关联模型
app/model/PostTag.php - 文章标签关联模型
app/model/Category.php - 分类模型
app/model/Tag.php - 标签模型
app/common.php - json_message() 函数签名和使用方式

Why Each Reference Matters:

admin/Post 控制器是本任务的蓝本，API 版本需要复用相同的业务逻辑但改为 JSON 响应
Files 控制器展示了 API 控制器的标准写法
Post 模型定义了可用字段和关系
json_message() 是统一的响应格式

Acceptance Criteria:

QA Scenarios (MANDATORY):

Scenario: 文章列表 - 正常请求
  Tool: Bash (curl)
  Preconditions: 有效 API Key，数据库中有文章数据
  Steps:
    1. curl -s -H "Authorization: Bearer {key}" "http://127.0.0.1:8010/index.php/api/articles/index?page=1&limit=5"
    2. 解析 JSON 响应
  Expected Result: {"code":0,"data":{"list":[...],"total":N,"page":1}}
  Failure Indicators: code 非 0，缺少 list/total 字段
  Evidence: .sisyphus/evidence/task-4-articles-list.txt

Scenario: 创建文章 - 完整数据
  Tool: Bash (curl)
  Preconditions: 有效 API Key
  Steps:
    1. curl -s -X POST -H "Authorization: Bearer {key}" -H "Content-Type: application/json" \
       -d '{"title":"API测试文章","content":"# Test","content_html":"<h1>Test</h1>","status":1,"categorys":[1],"tags":[1]}' \
       "http://127.0.0.1:8010/index.php/api/articles/save"
    2. 解析 JSON，记录返回的 id 和 uid
  Expected Result: {"code":0,"msg":"创建成功","data":{"id":N,"uid":"..."}}
  Failure Indicators: code 非 0，缺少 id/uid
  Evidence: .sisyphus/evidence/task-4-articles-create.txt

Scenario: 文章详情
  Tool: Bash (curl)
  Preconditions: 已创建文章，知道其 id
  Steps:
    1. curl -s -H "Authorization: Bearer {key}" "http://127.0.0.1:8010/index.php/api/articles/read?id={id}"
  Expected Result: {"code":0,"data":{"post":{...},"categories":[...],"tags":[...]}}
  Failure Indicators: code 非 0，缺少 post 字段
  Evidence: .sisyphus/evidence/task-4-articles-detail.txt

Scenario: 编辑文章
  Tool: Bash (curl)
  Preconditions: 已创建文章
  Steps:
    1. curl -s -X POST -H "Authorization: Bearer {key}" -H "Content-Type: application/json" \
       -d '{"id":{id},"title":"API测试文章-已编辑","status":1}' \
       "http://127.0.0.1:8010/index.php/api/articles/update"
  Expected Result: {"code":0,"msg":"更新成功"}
  Failure Indicators: code 非 0
  Evidence: .sisyphus/evidence/task-4-articles-update.txt

Scenario: 创建文章 - source 字段标记
  Tool: Bash (curl + SQLite)
  Preconditions: 有效 API Key
  Steps:
    1. 创建一篇文章（同上 Scenario）
    2. 查询数据库检查该文章的 source 字段值
  Expected Result: source = 'api'
  Failure Indicators: source 字段缺失或值不为 'api'
  Evidence: .sisyphus/evidence/task-4-articles-source.txt

Scenario: 删除接口不存在
  Tool: Bash (curl)
  Preconditions: 有效 API Key
  Steps:
    1. curl -s -X POST -H "Authorization: Bearer {key}" "http://127.0.0.1:8010/index.php/api/articles/delete?id=1"
  Expected Result: 返回 404 或控制器无此方法的错误（不是成功删除）
  Failure Indicators: {"code":0,"msg":"删除成功"}（如果删除成功了就错了）
  Evidence: .sisyphus/evidence/task-4-articles-no-delete.txt

Scenario: can_write_own=0 时无法创建文章
  Tool: Bash (curl)
  Preconditions: 有效 API Key 且 can_write_own=0
  Steps:
    1. curl -s -X POST -H "Authorization: Bearer {key}" -H "Content-Type: application/json" \
       -d '{"title":"不应成功"}' \
       "http://127.0.0.1:8010/index.php/api/articles/save"
  Expected Result: {"code":403,"msg":"无权操作"}
  Failure Indicators: code 为 0（创建成功）
  Evidence: .sisyphus/evidence/task-4-articles-no-create.txt

Scenario: can_write_own=1, can_write_other=0 时无法编辑后台文章
  Tool: Bash (curl)
  Preconditions: 有效 API Key 且 can_write_own=1, can_write_other=0，存在 source='admin' 的文章
  Steps:
    1. curl -s -X POST -H "Authorization: Bearer {key}" -H "Content-Type: application/json" \
       -d '{"id":{admin_article_id},"title":"不应成功"}' \
       "http://127.0.0.1:8010/index.php/api/articles/update"
  Expected Result: {"code":403,"msg":"无权操作"}
  Failure Indicators: code 为 0（编辑成功）
  Evidence: .sisyphus/evidence/task-4-articles-no-edit-other.txt

Scenario: can_write_other=1 时可以编辑后台文章
  Tool: Bash (curl)
  Preconditions: 有效 API Key 且 can_write_other=1，存在 source='admin' 的文章
  Steps:
    1. curl -s -X POST -H "Authorization: Bearer {key}" -H "Content-Type: application/json" \
       -d '{"id":{admin_article_id},"title":"可以编辑"}' \
       "http://127.0.0.1:8010/index.php/api/articles/update"
  Expected Result: {"code":0,"msg":"更新成功"}
  Failure Indicators: code 为 403
  Evidence: .sisyphus/evidence/task-4-articles-edit-other.txt

Scenario: can_delete=0 时不能删除任何文章
  Tool: Bash (curl)
  Preconditions: 有效 API Key 且 can_delete=0
  Steps:
    1. curl -s -X POST -H "Authorization: Bearer {key}" "http://127.0.0.1:8010/index.php/api/articles/delete?id={id}"
  Expected Result: {"code":403,"msg":"无权删除"}
  Failure Indicators: code 为 0（删除成功）
  Evidence: .sisyphus/evidence/task-4-articles-no-delete.txt

Scenario: can_delete=1 时只能删除 API 创建的文章
  Tool: Bash (curl)
  Preconditions: 有效 API Key 且 can_delete=1，存在 source='api' 和 source='admin' 的文章
  Steps:
    1. 删除 source='api' 的文章 → 应成功
    2. 删除 source='admin' 的文章 → 应返回 403
  Expected Result: API 文章删除成功，后台文章拒绝
  Failure Indicators: 后台文章也被删除
  Evidence: .sisyphus/evidence/task-4-articles-delete-own.txt

Scenario: can_delete=2 时可以删除所有文章
  Tool: Bash (curl)
  Preconditions: 有效 API Key 且 can_delete=2
  Steps:
    1. 删除任意文章 → 应成功
  Expected Result: {"code":0,"msg":"删除成功"}
  Failure Indicators: 返回 403
  Evidence: .sisyphus/evidence/task-4-articles-delete-all.txt

Scenario: 创建文章 - 缺少标题
  Tool: Bash (curl)
  Preconditions: 有效 API Key
  Steps:
    1. curl -s -X POST -H "Authorization: Bearer {key}" -H "Content-Type: application/json" \
       -d '{"content":"no title"}' \
       "http://127.0.0.1:8010/index.php/api/articles/save"
  Expected Result: {"code":500,"msg":"标题不能为空"}
  Failure Indicators: code 为 0（创建成功）
  Evidence: .sisyphus/evidence/task-4-articles-create-notitle.txt

Scenario: 查询不存在的文章
  Tool: Bash (curl)
  Preconditions: 有效 API Key
  Steps:
    1. curl -s -H "Authorization: Bearer {key}" "http://127.0.0.1:8010/index.php/api/articles/read?id=99999"
  Expected Result: {"code":500,"msg":"文章不存在"}
  Failure Indicators: code 为 0
  Evidence: .sisyphus/evidence/task-4-articles-detail-404.txt

Commit: YES

Message: feat(api): add article CRUD API endpoints
Files: app/api/controller/Articles.php
Pre-commit: php -l app/api/controller/Articles.php

5. 附件 API 控制器（Attachments）— 上传/列表/删除，权限控制